Audio Editing API — Crop, Reorder, Repeat, and Fade

The Audio Editing API combines cropping, reordering, repetition, and linear fades in one asynchronous render. Submit one public audio URL and an ordered list of segments, then retrieve the finished file through the standard Task API.

Availability is controlled by the service rollout. When rendering is unavailable, creation returns 503 AUDIO_RENDER_UNAVAILABLE before accepting a new task.

Submit an edit

Set a fresh request key once for each logical edit. Save it with the request body and reuse both when recovering a lost response.

export REQUEST_KEY="$(uuidgen)"

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://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
  }'

Replace the source with a publicly reachable audio file. This example plays seconds 30–45 twice, followed by seconds 0–10: 40 seconds of output in total.

The response has HTTP status 202:

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

Creation requires task:create; task reads require task:read. You can also send webhookUrl for completion notifications. Use this dedicated endpoint to create an edit; the generic Task creation endpoints do not accept audio-editing models.

Segment rules

Field	Meaning
startSeconds	Inclusive start measured from the beginning of the source, at least 0.
endSeconds	Exclusive end; greater than the start and within the decoded source.
repeat	Total number of copies, from 1 to 64; defaults to 1.
fadeInSeconds	Linear fade from silence at the beginning of each copy; defaults to 0.
fadeOutSeconds	Linear fade toward silence at the end of each copy; defaults to 0.

One segment crops the source. Changing the array order rearranges sections. repeat copies a segment after applying its fades, so every copy receives the same fade. Segments are concatenated 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. The service rejects out-of-range selections instead of silently shortening them.

Formats and limits

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 all repetitions
Output duration	At most 30 minutes
output.format	wav (default, 16-bit PCM) or mp3 (192 kbps)
output.sampleRate	48000 (default) or 44100
output.channels	2 (default) or 1

Keep the source readable until the service captures it. Private addresses, credential-protected URLs, unsupported formats, and expired source URLs may fail validation. Once captured, the task uses that fixed source for recovery.

Credits

The standard price is 5 credits per started output minute, charged once for the combined edit. Output duration for billing is the sum of (endSeconds − startSeconds) × repeat, using the requested decimal times before sample rounding. Fades do not change the duration.

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

Customer pricing can change the final quote. creditsRequired records the accepted price; maxCredits prevents acceptance above your budget. Automatic recovery stays within the same task and does not create another charge. A final failed or cancelled task uses the standard refund process; inspect the task’s settlement fields before starting a new edit.

Retrieve and retain the result

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

Wait for COMPLETED, then download the audio from resources[].url. The resource includes assetId, assetStatus, retainedUntil, and urlExpiresAt. Its metadata contains the format, sample rate, channels, sample count, precise durationSeconds, file size in bytes, and sha256 checksum. The integer duration field is rounded for compatibility.

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

Only the task owner can retrieve its private result. API keys authorized for the same OmnAPI user can access the task; another user’s key cannot. A valid public source URL can be used without a music-provider account binding.

Recovery

• For 429, wait and retry the original body with the same saved request key.
• For a network failure or 5xx without a receipt, replay that same request key; a task may already exist. If a response identifies a task, poll it.
• A conflicting request body under an existing key returns 409. Use a new key only for a new logical edit.
• Invalid selections use AUDIO_INVALID_EDIT; unsupported or unreadable input uses AUDIO_SOURCE_INVALID. Correct the source or selection before resubmitting.
• AUDIO_RESOURCE_LIMIT means the media exceeded processing limits; AUDIO_PROCESSING_FAILED means the render could not be completed. Inspect the terminal task and refund fields, and include its task ID when contacting support.
• Cancellation follows the existing Task lifecycle; this endpoint does not add an in-progress cancellation guarantee.

See Task model, Webhooks, and Error recovery for the shared integration behavior.