Merge Videos
Join 2–10 videos end to end without re-encoding and get an MP4, priced by their total length.
Merge Videos (product merge_videos) joins 2–10 videos end to end, in the order you list them, and returns an MP4. It runs on FFmpeg, not a generation model, and doesn't re-encode, so the quality doesn't change; the videos must therefore match (see Media). One task makes one video, priced by the total length of the videos.
Create a task
https://api.nanoapi.ai/v1/tasksUse the shared create endpoint with model: "merge-videos".
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-videos |
video_urls | string[] | Yes | 2–10 videos, joined in this order. They must match each other: H.264 or HEVC, with AAC or MP3 audio or no audio, at most 500 MB each. See Media. |
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. |
Join three clips:
curl https://api.nanoapi.ai/v1/tasks \
-H "Authorization: Bearer $NANOAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "merge-videos",
"video_urls": [
"https://example.com/1.mp4",
"https://example.com/2.mp4",
"https://example.com/3.mp4"
]
}'Response: 200 OK, the new task (fields). Keep data.id to get the result; the task can still fail, see Errors.
{
"code": 200,
"message": "success",
"data": {
"object": "task",
"id": "tk_01jb8z5q4w3e2r1t0y9u8i7o6p",
"model": "merge-videos",
"status": "queued",
"error": null,
"created_at": "2026-11-17T08:30:00Z"
}
}Get the result
It usually finishes within seconds to tens of seconds, most of it spent downloading the videos. Get the result through the webhook if you sent webhook_url, or poll GET /v1/tasks/{task_id} at most once every 15 seconds until status is succeeded or failed (several tasks at once: ids in List tasks).
The request above once it has succeeded (other fields omitted; all fields: The task object):
{
"status": "succeeded",
"input": {
"video_urls": [
"https://example.com/1.mp4",
"https://example.com/2.mp4",
"https://example.com/3.mp4"
]
},
"num_outputs": 1,
"outputs": [
{
"index": 0,
"type": "video",
"url": "https://cdn.nanoapi.ai/h/tk_01jb8z5q4w3e2r1t0y9u8i7o6p_1_1792831800.mp4",
"preview_url": null
}
],
"billing": {
"currency": "USD",
"frozen": "…", // worked out from the total length of the videos, see Pricing
"charged": "…", // the same
"refunded": "0.00",
"billed_seconds": null
}
}| Field | Merge Videos |
|---|---|
outputs | One item |
outputs[0].type | video |
outputs[0].url | The joined video, an MP4 with the video and audio copied as they are (not re-encoded). |
outputs[0].preview_url | Always null: use url. |
billing.billed_seconds | Always null: the cost is worked out from the total length of the videos, see Pricing. |
input | The parameters you sent |
Result files are kept for 15 days, see Outputs.
Media
The videos go in video_urls as public http(s) URLs that download directly (not a web page): at most 4096 characters, not localhost or a private, loopback or reserved address, and valid until the task finishes (including signed URLs that expire). There's no upload endpoint.
Videos (video_urls) | |
|---|---|
| Count | 2–10 (limits.min_videos and max_videos in GET /v1/products) |
| Format | H.264 or HEVC video; AAC or MP3 audio, or no audio |
| Size | At most 500 MB each |
| Length | At least 1 second all together (limits.min_duration_seconds) |
| When they're read | Within a few seconds of creating the task (to work out the price): if one can't be read, isn't a supported format or is over 500 MB, the task fails with invalid_media; if they don't match, with invalid_request. Nothing is frozen. Downloaded again for processing: if that fails, or a mismatch shows up only then, the task fails and the frozen amount is returned in full. |
The videos must match, because they're joined without re-encoding:
- the same video codec, resolution, frame rate, pixel format and rotation;
- the same audio codec, sample rate and channels, and either all of them have audio or none do.
Videos made by the same model with the same settings usually match, and clips cut with Trim Video can be joined back. Clips cut in a phone's gallery app may not work.
When they don't match, the task fails with invalid_request, see Errors. Only the first mismatch is reported: fix it and create the task again to find the next one.
When a failure (invalid_media or invalid_request) is known to come from one video, its message ends with The problem is with video_urls[N]. (N counts from 0).
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(total seconds of all videos × price per second ÷ 0.00039) × 0.00039Loading the current prices…
- Seconds: the lengths of all the videos added together, known only once they are read.
- The total is rounded to the nearest whole multiple of $0.00039. This step isn't in
GET /v1/products:price_stepon themerge_videosrow isnull. Compute in integer micro-dollars, see Amounts.
Current prices, to estimate from the videos' lengths before submitting: GET /v1/products (the merge_videos product has one prices row, with billing_unit second and the price per second in unit_price). The task's billing.frozen is the amount that counts; freezing and charging: Billing.
Errors
Request errors
A request that fails returns an HTTP error, and no task is created:
{
"code": 400,
"message": "Field required",
"error": {
"type": "invalid_request",
"param": "video_urls",
"details": null
},
"request_id": "rq_01jb8z9x2c4v6b8n0m1q3w5e7r"
}| HTTP status | error.type | Description |
|---|---|---|
| 400 | invalid_request | A required parameter is missing, a value breaks the rules in the parameter table, or a parameter isn't accepted; param names it |
| 401 | invalid_api_key | The API key is invalid, deleted or has been reset |
| 402 | insufficient_balance | Your available balance is 0 |
| 402 | spend_limit_exceeded | One of the API key's spend limits is used up |
| 403 | account_suspended | Your account has been suspended |
| 409 | idempotency_key_reused | The Idempotency-Key was already used with a different request body |
| 429 | rate_limited | Too many requests |
| 500 | internal_error | A server error; the task may have been created |
details and how to handle each error: Create a task → Errors.
Task failures
A created task can still fail: its status turns failed and the reason is in error, with no HTTP status. A failed task is never charged; anything frozen is returned in full.
{
"status": "failed",
"error": {
"type": "invalid_media",
"message": "The video file is too large. Each video must be at most 500 MB. The problem is with video_urls[2]."
}
}error.type | Description |
|---|---|
invalid_media | A video can't be downloaded, isn't H.264 or HEVC with AAC or MP3 audio or no audio, or is over 500 MB |
video_too_short | The videos are shorter than 1 second all together |
invalid_request | The videos don't match (see Media); a clip cut in a phone's gallery app can also have hidden frames at its start that don't match |
insufficient_balance | Your available balance can't cover this task |
spend_limit_exceeded | This task would go over one of the API key's spend limits |
generation_failed | Generation failed |
queue_timeout | Not started within 30 minutes of being queued |
internal_error | An internal error |
Branch on error.type; message is an English explanation for developers and may change. When each reason can happen, whether anything was frozen, and the message texts: Failure reasons.