Reframe Video

Reframe Video (product reframe_video) changes a video's aspect ratio and paints in the areas the new frame adds, optionally guided by up to 2 reference images. One task makes one video, priced from the source video's length and resolution.

Create a task

Use the shared create endpoint with model: "reframe-video". It usually responds in under 1 second; the source video is read and the cost frozen in the background within a few seconds. Get the result once the task has finished.

Headers

Body

Turn a clip of at most 15 seconds into 9:16, with a reference image for the new areas:

curl https://api.nanoapi.ai/v1/tasks \
  -H "Authorization: Bearer $NANOAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f6a8c2e-0b3d-4d9f-9a7e-2c5b1f8d6e30" \
  -d '{
    "model": "reframe-video",
    "video_url": "https://example.com/clip.mp4",
    "aspect_ratio": "9:16",
    "image_urls": ["https://example.com/background.jpg"]
  }'

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 source video is longer than 15 seconds with image_urls): go by what retrieving the task or the webhook tells you.

{
  "code": 200,
  "message": "success",
  "data": {
    "object": "task",
    "id": "tk_01jbm7f9h2k5m8p1t4w7z0d3e6",
    "model": "reframe-video",
    "status": "queued",
    "error": null,
    "created_at": "2026-11-03T08:30:00Z"
  }
}

Get the result

Measured from creation to the end: 5–10 minutes, about 7 for a 10-second video, slower when the generation service is busy. 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} with data.id at most once every 15 seconds until status is succeeded or failed. Check several tasks at once with ids in List tasks.

The request above, once it has succeeded (other fields left out):

{
  "status": "succeeded",
  "input": {
    "video_url": "https://example.com/clip.mp4",
    "aspect_ratio": "9:16",
    "image_urls": ["https://example.com/background.jpg"]
  },
  "num_outputs": 1,
  "outputs": [
    {
      "index": 0,
      "type": "video",
      "url": "https://cdn.nanoapi.ai/h/tk_01jbm7f9h2k5m8p1t4w7z0d3e6_1_1793694600.mp4",
      "preview_url": "https://cdn.nanoapi.ai/h/tk_01jbm7f9h2k5m8p1t4w7z0d3e6_1_1793694600_compressed.mp4"
    }
  ],
  "billing": {
    "currency": "USD",
    "frozen": "…", // worked out from the source video, see Pricing
    "charged": "…", // the same, occasionally a little less
    "refunded": "0.00",
    "billed_seconds": null
  }
}

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

All media is passed as public http(s) URLs. There's no upload endpoint: host the files yourself. URLs are at most 4096 characters, must download directly and can't point to localhost or private, loopback or reserved addresses.

Keep every link reachable until the task finishes, including links that expire.

Pricing

cost = per-task amount + price per second (source resolution) × seconds of the source video

Loading the current prices…

• Seconds: the source video's length, rounded to the nearest second.
• Price per second: by the source video's resolution tier, 480p, 720p or 1080p, set by the generation service when it reads the source video. For example, a 640×360 video is billed as 480p, and a short side above 1080 pixels counts as 1080p. aspect_ratio and reference images don't change it.
• Within a few seconds of creating the task, the source video is read, the cost worked out and frozen. When the task succeeds, the frozen amount is charged, occasionally a little less (some videos are processed again during generation, for example hidden frames left by phone editing, or re-encoding), never more. When it fails, all of it is returned. How freezing and charging work in general: Billing.
• billing.billed_seconds is always null.

Example: if the source video of the request above is a 10-second 720p clip, the task costs the per-task amount plus 10 × the 720p price per second.

To show a price before submitting, read the video's length and resolution on your side and apply the current prices from GET /v1/products: the reframe_video product has one prices row per source resolution, with the per-task amount in base_price. Prices change, so don't hard-code them. It's an estimate, since the tier is set only when the source video is read: 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.

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.

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.