Merge Audio Video
Replace the sound of a video with an audio file and get an mp4, priced by the length of the video.
Merge Audio Video (product merge_audio_video) replaces the sound of a video with an audio file and returns an mp4. It runs on FFmpeg, not a generation model, and usually finishes within seconds to tens of seconds. One task makes one video, priced by the length of the video picture, whatever the audio.
Create a task
https://api.nanoapi.ai/v1/tasksUse the shared create endpoint with model: "merge-audio-video". It usually responds in under 1 second; the video is read and the cost frozen in the background within a few seconds. Get the result once the task has finished.
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <API key>, see Authentication. |
Content-Type | Yes | application/json |
Idempotency-Key | No | A unique string for every new task, ideally a UUID (1–255 characters). See Preventing duplicate tasks. |
Body
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | merge-audio-video. |
video_url | string | Yes | The video, 1–60 seconds: mp4, mov, m4v, webm or mkv (gif isn't supported yet). See Media. |
audio_url | string | Yes | The audio: mp3, wav, m4a, aac, ogg or flac. A video with an audio track works too; its first audio track is used. See Media. |
start_offset | number | No | Where in the video the audio starts, in seconds (decimals allowed); it's silent before that. Without it the audio starts at the beginning (0). Can't be below 0 and must be less than the video's length (so under 60). |
webhook_url | string | No | Notified when the task succeeds or fails: https, up to 2048 characters, not a private, loopback or reserved address. See Webhooks. |
Put a voice-over on a clip, starting 1.5 seconds in:
curl https://api.nanoapi.ai/v1/tasks \
-H "Authorization: Bearer $NANOAPI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c3a9e-2b7d-4e58-9a0c-d4e8b2f71c35" \
-d '{
"model": "merge-audio-video",
"video_url": "https://example.com/clip.mp4",
"audio_url": "https://example.com/voice.mp3",
"start_offset": 1.5
}'Response: 200 OK. data is the newly created task, with only these fields; each one is described in Create a task: Response. Keep data.id to get the result. The cost is frozen within a few seconds of creation, and the task may fail at that point (for example if the video is longer than 60 seconds): go by what retrieving the task or the webhook tells you.
{
"code": 200,
"message": "success",
"data": {
"object": "task",
"id": "tk_01jb8z5q4w3e2r1t0y9u8i7o6p",
"model": "merge-audio-video",
"status": "queued",
"error": null,
"created_at": "2026-11-15T08:30:00Z"
}
}Get the result
It usually finishes within seconds to tens of seconds, most of it spent downloading the files. Once the task has finished (succeeded or failed), get the result either way:
- Webhook (recommended in production): if you passed
webhook_url, the full task is pushed to it once when the task finishes. See Webhooks. - Polling: call
GET /v1/tasks/{task_id}withdata.idat most once every 15 seconds untilstatusissucceededorfailed. Check several tasks at once withidsin List tasks.
The request above, once it has succeeded (other fields left out):
{
"status": "succeeded",
"input": {
"video_url": "https://example.com/clip.mp4",
"audio_url": "https://example.com/voice.mp3",
"start_offset": 1.5
},
"num_outputs": 1,
"outputs": [
{
"index": 0,
"type": "video",
"url": "https://cdn.nanoapi.ai/h/tk_01jb8z5q4w3e2r1t0y9u8i7o6p_1_1792658900.mp4",
"preview_url": null
}
],
"billing": {
"currency": "USD",
"frozen": "…", // worked out from the length of the video, see Pricing
"charged": "…", // the same
"refunded": "0.00",
"billed_seconds": null
}
}| Field | Merge Audio Video |
|---|---|
outputs | One item. |
outputs[0].type | video. |
outputs[0].url | The merged video, an mp4 as long as the video picture. h264 and HEVC pictures are kept as they are, not re-encoded, so the quality doesn't change; other codecs (VP9, AV1 and so on) are converted to h264. The sound is always AAC. |
outputs[0].preview_url | Always null: this model has no preview, use url. |
billing.billed_seconds | Always null: the cost is worked out from the length of the video, see Pricing. |
input | The parameters you sent. |
- Audio longer than the video is cut off at the end of the video; shorter audio is followed by silence. You don't need to trim the audio yourself.
- The video's own sound is removed, not mixed with the new audio.
- Result files are kept for 15 days: download the ones you need to keep, see Outputs.
On failure the frozen amount is returned in full and the reason is in data.error.type, see Errors. Every field is described in The task object.
Media
The video and the audio are passed as public http(s) URLs in video_url and audio_url. There's no upload endpoint: host the files yourself. URLs are at most 4096 characters, must download directly (not a web page) and can't point to localhost or private, loopback or reserved addresses.
Video (video_url) | Audio (audio_url) | |
|---|---|---|
| Format | mp4, mov, m4v, webm or mkv; gif isn't supported yet | mp3, wav, m4a, aac, ogg or flac; or a video with an audio track (its first audio track is used) |
| Length | 1–60 seconds (limits.min_source_video_seconds and max_source_video_seconds in GET /v1/products) | Cut off or followed by silence to match the length of the video picture |
| When it's read | Within a few seconds of creating the task (to work out the price): if it can't be read, the task fails with invalid_media; over 60 seconds or under 1 second, with video_too_long / video_too_short. Nothing is frozen. Downloaded again for processing: if that fails, the task fails with invalid_media and the frozen amount is returned in full. | Only when processing: if it can't be downloaded, isn't a supported format, or is a video without an audio track, the task fails with invalid_media and the frozen amount is returned in full. |
Keep the links reachable until the task finishes, including links that expire. Use direct links to files on your own storage rather than links to third-party sites: a slow or rate-limited host can make the download during processing fail.
Pricing
cost = round(video seconds × price per second ÷ 0.00039) × 0.00039Loading the current prices…
- Seconds: the length of the video picture (the video track), known only once the platform reads the video. The audio and
start_offsetdon't change it. - The total is rounded to the nearest whole multiple of $0.00039. This step isn't in
GET /v1/products:price_stepon themerge_audio_videorow isnull. Compute in integer micro-dollars (amount × 1,000,000), not floats. - Within a few seconds of creating the task, the video is read, the cost worked out and frozen. When the task succeeds, the frozen amount is charged; when it fails, all of it is returned. How freezing and charging work in general: Billing.
billing.billed_secondsis alwaysnull.
To show a price before submitting, read the video's length on your side and apply the current price from GET /v1/products: the merge_audio_video product has one prices row, with billing_unit second and the price per second in unit_price. Prices change, so don't hard-code them. It's an estimate: billing.frozen on the retrieved task is what counts (it's frozen within a few seconds of creation).
Errors
Errors and failure reasons specific to this model. Every error of the create endpoint: Create a task → Errors; every failure reason: Failure reasons.
Create request errors: the request fails with an HTTP error and no task is created. param names the parameter.
| Status | error.type | When | What to do |
|---|---|---|---|
400 | invalid_request | video_url or audio_url is missing (Field required, param names it). | Send both. |
400 | invalid_request | start_offset is below 0, 60 or more, or not a number (param "start_offset"); video_url or audio_url isn't a public http(s) URL of at most 4096 characters; or num_outputs isn't 1. | Fix the parameter param names. |
400 | invalid_request | A parameter this model doesn't take, such as audio_urls or prompt (Extra inputs are not permitted). | Remove it. |
Other errors of the create endpoint (401, 402, 429 and so on): Create a task → Errors.
Task failures: the create request succeeded (200) and the task later turned failed. There's no HTTP status: the reason is the task's error.type, from retrieving the task or the webhook.
error.type | When | What to do |
|---|---|---|
invalid_media | The video can't be read: it can't be downloaded, isn't a supported format, or has no picture (gifs too); message says which. Within a few seconds of creating the task, nothing frozen. | Use a public, directly downloadable video in a supported format and create the task again. |
video_too_long | The video is longer than 60 seconds (The video duration must be at most 60 seconds.). Within a few seconds of creating the task, nothing frozen. | Trim the video to 60 seconds or less and create the task again. |
video_too_short | The video is shorter than 1 second (The video duration must be at least 1 second.). Within a few seconds of creating the task, nothing frozen. | Use a longer video. |
invalid_request | start_offset isn't less than the video's length (start_offset must be less than the duration of the video.). Within a few seconds of creating the task, nothing frozen. | Use a smaller start_offset and create the task again. |
insufficient_balance | Your available balance can't cover the cost worked out from the video. Within a few seconds of creating the task, nothing frozen. | Top up, then create the task again. |
spend_limit_exceeded | This task's cost would go over one of the key's spend limits. Within a few seconds of creating the task, nothing frozen. | Raise the limit in Console → API keys, or wait for it to reset, then create the task again. |
invalid_media | The audio can't be used: it can't be downloaded, isn't a supported format, or is a video without an audio track (The audio could not be used. Make sure audio_url is a publicly downloadable audio file, or a video with an audio track.). Or the video couldn't be downloaded again for processing. After freezing: all of it is returned. | Use stable, public, direct links (for example on your own storage) and create the task again. |
content_policy | The video didn't pass content review. | Resubmitting it as is fails again: use a different video. |
generation_failed | Processing failed. | Create it again later. |
queue_timeout / internal_error | Not started within 30 minutes / an error on our side. | Create it again later. |
Every failed task has its frozen amount returned in full and billing.charged "0.00". Branch on error.type: the quoted messages are for display and may change, see Messages.