Extract Frame
Save the first, middle or last frame of a video as a full-size JPEG, priced by the length of the video.
Extract Frame (product extract_frame) takes one frame of a video, the first, the middle or the last, and returns it as a JPEG at the video's full size, turned upright to the video's rotation. It runs on FFmpeg, not a generation model. One task makes one image, priced by the length of the video, whichever frame you take.
Create a task
https://api.nanoapi.ai/v1/tasksUse the shared create endpoint with model: "extract-frame".
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 | extract-frame |
video_url | string | Yes | The video: MP4, MOV, M4V, WebM or MKV, at most 500 MB. See Media. |
frame_type | string | Yes | first (the first frame), middle (the frame halfway through the video) or last (the last frame). |
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. |
Take the last frame of a clip, for example to start the next clip from it:
curl https://api.nanoapi.ai/v1/tasks \
-H "Authorization: Bearer $NANOAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "extract-frame",
"video_url": "https://example.com/clip.mp4",
"frame_type": "last"
}'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": "extract-frame",
"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",
"frame_type": "last"
},
"num_outputs": 1,
"outputs": [
{
"index": 0,
"type": "image",
"url": "https://cdn.nanoapi.ai/h/tk_01jb8z5q4w3e2r1t0y9u8i7o6p_1_1792831800.jpg",
"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 | Extract Frame |
|---|---|
outputs | One item |
outputs[0].type | image |
outputs[0].url | The frame, a JPEG at the video's full size, turned upright to the video's rotation. |
outputs[0].preview_url | Always null: 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 |
Result files are kept for 15 days, see Outputs.
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 | MP4, MOV, M4V, WebM or MKV |
| Size | At most 500 MB |
| Length | At least 1 second (limits.min_source_video_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 (GIF included) or is over 500 MB, the task fails with invalid_media; under 1 second, 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(video seconds × price per second ÷ 0.00039) × 0.00039Loading the current prices…
- Seconds: the length of the whole video, whichever frame you take, known only once the video is read.
- The total is rounded to the nearest whole multiple of $0.00039. This step isn't in
GET /v1/products:price_stepon theextract_framerow isnull. Compute in integer micro-dollars, see Amounts.
Current prices, to estimate from the video's length before submitting: GET /v1/products (the extract_frame 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 video duration must be at least 1 second."
}
}error.type | Description |
|---|---|
invalid_media | The video can't be downloaded, isn't a supported format (GIF included), or is over 500 MB |
video_too_short | The video is shorter than 1 second |
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.