Trim Video
Cut a part out of a video without re-encoding and get an MP4, priced by the length you cut.
Trim Video (product trim_video) cuts a part out of a video and returns an MP4. It runs on FFmpeg, not a generation model, and doesn't re-encode: the video and audio are copied as they are, so the quality doesn't change. One task makes one video, priced by the length you cut.
Create a task
https://api.nanoapi.ai/v1/tasksUse the shared create endpoint with model: "trim-video".
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 | trim-video |
video_url | string | Yes | The video: H.264 or HEVC, with AAC or MP3 audio or no audio, at most 500 MB. See Media. |
start_time | number | Yes | Where the cut starts, in seconds from the beginning of the video (decimals allowed). 0 or more, and less than the video's length. The cut actually starts at the keyframe before it, see Where the cut starts. |
end_time | number | Conditional | One of end_time / duration is required, not both. Where the cut ends, in seconds from the beginning of the video, at least 1 second after start_time. Past the end of the video, the cut ends there. |
duration | number | Conditional | One of end_time / duration is required, not both. How many seconds to cut from start_time, at least 1. Past the end of the video, the cut ends there. |
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. |
Cut seconds 10 to 15 out of a clip:
curl https://api.nanoapi.ai/v1/tasks \
-H "Authorization: Bearer $NANOAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "trim-video",
"video_url": "https://example.com/clip.mp4",
"start_time": 10,
"end_time": 15
}'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": "trim-video",
"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 video. 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_url": "https://example.com/clip.mp4",
"start_time": 10,
"end_time": 15
},
"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 length cut, see Pricing
"charged": "…", // the same
"refunded": "0.00",
"billed_seconds": null
}
}| Field | Trim Video |
|---|---|
outputs | One item |
outputs[0].type | video |
outputs[0].url | The cut, 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 length cut, see Pricing. |
input | The parameters you sent |
Result files are kept for 15 days, see Outputs.
Where the cut starts
Without re-encoding, a cut can only start on a keyframe. The result starts at the last keyframe before start_time, so it begins earlier than start_time, by up to one keyframe interval (often 2–5 seconds in AI-generated videos). The end is close to end_time (a video with B-frames may end a few frames early). The extra part at the start isn't charged.
Media
The video goes in video_url as a public http(s) URL that downloads 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.
Video (video_url) | |
|---|---|
| Format | H.264 or HEVC video; AAC or MP3 audio, or no audio |
| Size | At most 500 MB |
| Length | At least 1 second must be left after start_time (limits.min_duration_seconds in GET /v1/products). |
| When it's read | Within a few seconds of creating the task (to work out the price): if it can't be read, isn't a supported format or is over 500 MB, the task fails with invalid_media; if less than 1 second is left after start_time, with 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. |
Use a direct link to a file on your own storage rather than a link to a third-party site: a slow or rate-limited host can make the download during processing fail.
Pricing
cost = round(seconds cut × price per second ÷ 0.00039) × 0.00039Loading the current prices…
- Seconds cut:
end_time−start_time(anend_timepast the end of the video counts up to the end), orduration. The extra part beforestart_time(see Where the cut starts) isn't counted. - The total is rounded to the nearest whole multiple of $0.00039. This step isn't in
GET /v1/products:price_stepon thetrim_videorow isnull. Compute in integer micro-dollars, see Amounts.
Current prices, to show the cost of the seconds you cut before submitting (an estimate when end_time or duration goes past the end of the video): GET /v1/products (the trim_video 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_url",
"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": "video_too_short",
"message": "The trimmed video must be at least 1 second long. Make sure start_time is at least 1 second before the end of the video."
}
}error.type | Description |
|---|---|
invalid_media | The 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 | Less than 1 second is left after start_time |
invalid_request | start_time isn't less than the video's length |
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.