beatra文档

处理音频

Creates an asynchronous deterministic audio editing task (`beatra-audio-v1` or `auto`, up to 15 minutes and 100 MiB) for `trim`, `loop`, `fade`, `normalize_loudness`, or `convert_format`, with optional fade, loudness, and format finishing in the same call. Charged per task (up to 50 calls per account per UTC day). When the task succeeds, `output` contains `{operation, outputs: [{role: "processed", artifact_id, url, mime_type, duration_ms, size_bytes}]}`.

下方的接口说明（参数、请求和响应）是英文原文，字段名与接口完全一致。

POST
/v1/audio/process

Request Body

application/jsonRequired
metadataMetadata

Caller-supplied metadata; ≤16 keys, key ≤64 chars, value ≤512 chars

callback_urlCallback Url

HTTPS URL Beatra will POST the final Task envelope to when the Task reaches a terminal state

callback_signing_key_idCallback Signing Key Id

Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided.

operation
Required
Operation

Local audio processing operation (trim, loop, fade, normalize_loudness, convert_format).

Value in: "trim" | "loop" | "fade" | "normalize_loudness" | "convert_format"
source
Required
Source

Source audio (artifact_id or HTTPS url). Accepts source or audio.

modelModel

Audio processing model identifier, or 'auto' for automatic selection.

Default: "auto"Value in: "auto" | "beatra-audio-v1"
start_msStart Ms

Trim start in milliseconds.

end_msEnd Ms

Trim end in milliseconds.

target_duration_msTarget Duration Ms

Target output duration in milliseconds (trim or loop).

loop_countLoop Count

Exact loop repeat count (loop; 2-100, mutually exclusive with target_duration_ms).

loop_start_msLoop Start Ms

Loop region start in ms.

loop_end_msLoop End Ms

Loop region end in ms.

crossfade_msCrossfade Ms

Seamless loop boundary crossfade in milliseconds (50-3000).

end_with_fadeEnd With Fade

Apply fade-out at the end of a looped clip.

fade_in_msFade In Ms

Fade-in duration in ms (0-30000).

fade_out_msFade Out Ms

Fade-out duration in ms (0-30000).

fade_curveFade Curve

Fade curve (tri, exp, log, qsin).

loudness_lufsLoudness Lufs

Target integrated loudness in LUFS (-30 to -9).

true_peak_dbTrue Peak Db

Target true-peak ceiling in dBTP (-9 to 0).

formatFormat

Output audio format (required for convert_format).

sample_rateSample Rate

Output sample rate in Hz.

bitrate_kbpsBitrate Kbps

Lossy bitrate in kbps.

channelsChannels

Output channel count (1 or 2).

Header Parameters

X-Request-Idstring

Optional client request id echoed in the response.

Idempotency-Key
Required
Idempotency-Key
Minimum length: 1Maximum length: 128
Authorization
Required
string

Bearer API key.

curl -X POST "https://api.beatra.ai/v1/audio/process" \
  -H "X-Request-Id: string" \
  -H "Idempotency-Key: string" \
  -H "Authorization: string" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "property1": "string",
      "property2": "string"
    },
    "callback_url": "string",
    "callback_signing_key_id": "string",
    "operation": "trim",
    "source": {
      "type": "url",
      "url": "string"
    },
    "model": "auto",
    "start_ms": 3600000,
    "end_ms": 100,
    "target_duration_ms": 100,
    "loop_count": 2,
    "loop_start_ms": 3600000,
    "loop_end_ms": 100,
    "crossfade_ms": 50,
    "end_with_fade": true,
    "fade_in_ms": 30000,
    "fade_out_ms": 30000,
    "fade_curve": "tri",
    "loudness_lufs": -30,
    "true_peak_db": -9,
    "format": "wav",
    "sample_rate": 8000,
    "bitrate_kbps": 64,
    "channels": 1
  }'

Task accepted

{
  "object": "task",
  "task_id": "string",
  "status": "queued",
  "capability": "string",
  "workload_type": "model",
  "model": "string",
  "resolved_model": "string",
  "model_selection_reason": null,
  "social": {
    "platform": "string",
    "operation_key": "string",
    "operation_name": "string",
    "schema_hash": "string"
  },
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "input": {},
  "progress": {
    "percent": 100,
    "stage": "string",
    "message": "string"
  },
  "output": {},
  "warnings": [
    {
      "code": "string",
      "message": "string",
      "field": "string"
    }
  ],
  "error": {
    "code": "string",
    "type": "string",
    "message": "string",
    "retryable": true,
    "param": "string",
    "details": {},
    "request_id": "string"
  },
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "cache_read_tokens": 0,
    "cache_creation_tokens": 0,
    "reasoning_tokens": 0,
    "image_count": 0,
    "image_pixels": 0,
    "video_seconds": 0,
    "input_video_seconds": 0,
    "output_video_seconds": 0,
    "audio_seconds": 0,
    "characters": 0,
    "lines": [
      {
        "meter": "string",
        "quantity": "string",
        "unit": "string",
        "billed_amount_credits": "string"
      }
    ],
    "credits": "string"
  },
  "billing": {
    "charged_credits": "string",
    "refunded_credits": "string",
    "granted_credits": "string",
    "grant_source": "string",
    "net_charged_credits": "string"
  },
  "callback": {
    "url": "string",
    "status": "pending",
    "attempt_count": 0,
    "delivered_at": "2019-08-24T14:15:22Z",
    "last_error": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "started_at": "2019-08-24T14:15:22Z",
  "deadline_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "cancel_requested_at": "2019-08-24T14:15:22Z",
  "links": {
    "self": "string",
    "cancel": "string",
    "assets": "string"
  }
}

最后更新