Edit an audio file

Trim, reorder, repeat, or fade an existing MP3 or WAV. Supply a public audio URL and the segments you want; get one edited audio file. To create new music, use Suno.

The endpoint follows the standard Task model: authenticate with x-api-key, submit JSON, receive a task descriptor, and poll GET /api/v1/tasks/{taskId} until terminal. Creation requires task:create; Task reads require task:read. Optional webhookUrl completion notifications use the shared Webhook contract.

Save one idempotency key per logical edit and reuse it only for retries of that exact request. Use this dedicated endpoint; generic Task creation does not accept audio-editing models.

---

The standard charge is 5 credits per started output minute. Set maxCredits to bound the charge. See pricing for examples.

POST /api/v1/audio/renders

Creates one asynchronous audio edit. Successful acceptance returns HTTP 202. If rendering is unavailable, new task creation returns 503 AUDIO_RENDER_UNAVAILABLE before charging credits. A saved request key can still recover a previously accepted receipt.

Examples

Set and save a fresh REQUEST_KEY once for each new logical edit. Reuse that key and the original body to recover a lost response. Use a different saved key when trying another example or output format.

export REQUEST_KEY="$(uuidgen)"

Crop and fade

curl -X POST https://api.omnapi.com/api/v1/audio/renders \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceUrl": "https://media.example.com/song.wav",
    "segments": [
      {"startSeconds": 10, "endSeconds": 40, "fadeInSeconds": 0.5, "fadeOutSeconds": 1}
    ],
    "output": {"format": "mp3"},
    "maxCredits": 5
  }'

Keeps seconds 10–40 as a 30-second MP3. Standard charge: 5 credits.

Reorder and repeat

curl -X POST https://api.omnapi.com/api/v1/audio/renders \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceUrl": "https://media.example.com/song.wav",
    "segments": [
      {"startSeconds": 30, "endSeconds": 45, "repeat": 2, "fadeInSeconds": 0.2},
      {"startSeconds": 0, "endSeconds": 10, "fadeOutSeconds": 1}
    ],
    "output": {"format": "wav", "sampleRate": 48000, "channels": 2},
    "maxCredits": 5
  }'

Plays seconds 30–45 twice, followed by seconds 0–10: 40 seconds total. Standard charge: 5 credits.

Replace the illustrative source with a publicly reachable audio file. Keep it readable until the service captures it. A successful 202 means the task was accepted; media decoding, actual duration, and selection bounds can still fail during processing. Once captured, recovery uses that fixed source.

Response (202 Accepted)

HTTP 202 · Complete response example

{
  "taskId": "01995900-0000-7000-8000-000000000001",
  "status": "PENDING",
  "creditsRequired": 5,
  "pollUrl": "/api/v1/tasks/01995900-0000-7000-8000-000000000001"
}

Field	Meaning
taskId	Save this identifier to query the accepted edit.
status	Task status recorded at acceptance.
creditsRequired	Accepted charge, including any customer pricing.
pollUrl	Relative Task read path; resolve against https://api.omnapi.com.

---

GET /api/v1/tasks/{taskId}

Set TASK_ID to the taskId in the create receipt. Poll using an API key with task:read authorized for the same OmnAPI user:

curl "https://api.omnapi.com/api/v1/tasks/$TASK_ID" \
  -H "x-api-key: $OMNAPI_KEY"

Result shape (when COMPLETED)

The following is an illustrative excerpt for the 40-second WAV example. The output is one MUSIC resource; download it from resources[].url.

HTTP 200 · Response excerpt

{
  "status": "COMPLETED",
  "resources": [
    {
      "id": "01995900-0000-7000-8000-000000000002",
      "type": "MUSIC",
      "url": "https://media.example.com/edited.wav?signature=example",
      "duration": 40,
      "assetId": "01995900-0000-7000-8000-000000000002",
      "assetStatus": "READY",
      "retainedUntil": "2026-10-04T12:00:00.000Z",
      "urlExpiresAt": "2026-09-20T13:00:00.000Z",
      "metadata": {
        "format": "wav",
        "sampleRate": 48000,
        "channels": 2,
        "sampleCount": 1920000,
        "durationSeconds": 40,
        "bytes": 7680078,
        "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      }
    }
  ]
}

metadata.durationSeconds is the precise edited duration; duration is rounded to an integer for compatibility. bytes and sha256 describe the delivered file; use the returned values to verify your download.

Downloads and retention

Outputs are retained for 14 days. Signed download URLs last at most one hour and never extend beyond retainedUntil. Query the Task for a fresh URL during retention. Download and store files you need longer. After retention ends, url is null and assetStatus is EXPIRED; Task metadata remains readable.

Only API keys authorized for the Task owner can query the Task and obtain fresh download URLs. Anyone holding a valid signed URL can download until it expires; treat the complete URL as private. The download itself does not require your OmnAPI API key.

---

Pricing

Audio Editing uses your OmnAPI credit balance. The standard price is 5 credits per started output minute, charged once for the combined edit before any customer-specific pricing is applied.

Endpoint	Standard credits	Billing unit
POST /api/v1/audio/renders	5	Per started requested output minute

Read the cacheable GET /api/v1/pricing/catalog catalog for current standard pricing; see Credits & Billing. The create receipt’s creditsRequired is authoritative. Set maxCredits to reject a quote above your budget before a task is created or credits are deducted.

Billable duration is the sum of (endSeconds − startSeconds) × repeat, using requested decimal times before sample rounding. Fades do not change duration. The standard charge is 5 × ceil(totalSeconds / 60).

Requested output	Standard charge
More than 0 and up to 60 seconds	5 credits
More than 60 and up to 120 seconds	10 credits
1800 seconds	150 credits

Credits are deducted when the task is accepted. Automatic recovery stays within the same task and does not create another charge. Final failure or cancellation uses the standard refund process; inspect the Task’s settlement fields before starting a new edit.

---

Parameters

Body

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

Only the listed fields are accepted in this object.

• Request · segmentsRequired

  array<object>

  Segments in playback order; at most 64 copies after repetition and 30 minutes total output.

  Minimum items: 1. Maximum items: 64.

  1 field

  • Request · segments[]Each item

    object

    Only the listed fields are accepted in this object.

    5 fields

    • Request · segments[].endSecondsRequired

      number

      Exclusive end in source seconds; must exceed the start and fit the decoded source.

      Maximum: 900. Exclusive lower bound: 0.

    • Request · segments[].startSecondsRequired

      number

      Inclusive start in source seconds, rounded to the nearest output sample (half up).

      Minimum: 0. Maximum: 900.

    • Request · segments[].fadeInSecondsOptional

      number

      Linear fade-in duration. A positive fade must span at least two output samples.

      Minimum: 0. Maximum: 900. Default: 0.

    • Request · segments[].fadeOutSecondsOptional

      number

      Linear fade-out duration. Both fades combined must fit the segment.

      Minimum: 0. Maximum: 900. Default: 0.

    • Request · segments[].repeatOptional

      string | integer

      Total copies of this segment; fades apply to every copy.

      Minimum: 1. Maximum: 64. Default: 1. Use a complete option below; the value must satisfy at least one option.

      2 options

      • Request · Option 1 — stringOption

        string

        Numeric string accepted by coercion; the converted value must satisfy the numeric constraints (minimum 1, maximum 64). Prefer a JSON number.

        Format: integer. Default: "1".

      • Request · Option 2 — integerOption

        integer

        Total copies of this segment; fades apply to every copy.

        Minimum: 1. Maximum: 64. Default: 1.

• Request · sourceUrlRequired

  string

  Public HTTP(S) URL of one MP3 or uncompressed PCM WAV source.

  Maximum characters: 8192. Format: uri.

• Request · maxCreditsOptional

  number

  Maximum authorized credit charge; a higher quote rejects creation before debit.

  Minimum: 0.

• Request · outputOptional

  object

  Output settings; defaults to WAV PCM16, 48 kHz, stereo.

  Only the listed fields are accepted in this object.

  3 fields

  • Request · output.channelsOptional

    1 | 2

    Output channels: 1 for mono or 2 for stereo.

    Default: 2.

  • Request · output.formatOptional

    "wav" | "mp3"

    Output encoding: WAV PCM16 or MP3 at 192 kbps.

    Default: "wav".

  • Request · output.sampleRateOptional

    44100 | 48000

    Output sample rate in Hz.

    Default: 48000.

• Request · webhookUrlOptional

  string

  Optional HTTPS destination for standard Task completion notifications.

  Maximum characters: 2048. Format: uri.

webhookUrl and maxCredits are top-level fields. This endpoint does not accept a product config envelope or a model field.

Segment rules

Field	Type	Required	Limit / default
startSeconds	number	Required	Inclusive start from the beginning of the source; at least 0
endSeconds	number	Required	Exclusive end; greater than start, at most 900, and within the decoded source
repeat	integer	Optional	Total copies, 1–64; default 1
fadeInSeconds	number	Optional	Linear fade from silence at the beginning of each copy; default 0
fadeOutSeconds	number	Optional	Linear fade toward silence at the end of each copy; default 0

One segment crops the source. Array order determines playback order. repeat copies a segment after its fades are applied, so every copy receives the same fade. Segments concatenate without overlap or automatic crossfades.

Times round to the nearest output sample; an exact half sample rounds upward. A segment must contain at least one output sample. Positive fades must span at least two samples, and their combined length must fit the segment. Out-of-range selections are rejected instead of silently shortened.

Output settings

Field	Type	Supported values	Default
output.format	string	wav (16-bit PCM), mp3 (192 kbps)	wav
output.sampleRate	integer	44100, 48000 Hz	48000
output.channels	integer	1 (mono), 2 (stereo)	2

Limits and request allowances

Setting	Supported values
Source	One public HTTP(S) MP3 or uncompressed PCM WAV file
Source size and duration	At most 200 MiB and 15 minutes
Source audio	One audio stream; 44,100 or 48,000 Hz; mono or stereo
Expanded segment count	At most 64, including repetitions
Output duration	At most 30 minutes

Private addresses, credential-protected URLs, unsupported formats, and expired source URLs may fail validation. M4A is not a supported input: for a Suno song, first obtain a completed MP3 or WAV export and use its current download URL.

See Rate Limits for shared request allowances. Capacity limits can return 429; retry the original body with the same saved request key.

---

Recovery

Response or Task error	What to do
400 VALIDATION_ERROR	Fix missing fields, field types, or schema limits before submitting a new logical edit.
409 with a conflicting idempotency request	Recover with the original body and key. Use a new key for a changed edit.
429	Wait and replay the original body with the same key.
503 AUDIO_RENDER_UNAVAILABLE	Rendering is temporarily unavailable; retry later with the saved key.
AUDIO_INVALID_EDIT	Check segment ranges, repeat count, and fade lengths.
AUDIO_SOURCE_INVALID	Check source accessibility, media format, sample rate, channels, and duration.
AUDIO_RESOURCE_LIMIT	Reduce the media or edit to fit processing limits.
AUDIO_PROCESSING_FAILED	Processing or decoding failed; check for damaged media and inspect the Task’s error and settlement fields.

For a network failure or 5xx without a receipt, replay the original request key; a task may already exist. If a response identifies a task, poll it. Media errors can appear on an accepted Task; they are not limited to the initial HTTP response.

For terminal failures, inspect refund/settlement fields before submitting a new edit. Include the Task ID when contacting support. Cancellation follows the Task lifecycle and does not guarantee interruption of an in-progress render.

See Error recovery for shared error handling.