Outpaint Image

Outpaint Image (product outpaint_image) extends an image to a new aspect ratio: the original is scaled down into the middle of the frame and everything around it is painted in, rather than a strip added along the edges. One task makes one image, at a fixed price per task.

Create a task

Use the shared create endpoint with model: "outpaint-image". It usually responds in under 1 second, and the price is frozen within a few seconds. Get the result once the task has finished.

Headers

Body

Extend a room photo to 16:9:

curl https://api.nanoapi.ai/v1/tasks \
  -H "Authorization: Bearer $NANOAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7a2f4c9e-1d6b-4b3a-8e5f-0c9d3a6b2e71" \
  -d '{
    "model": "outpaint-image",
    "image_url": "https://example.com/room.jpg",
    "aspect_ratio": "16:9"
  }'

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 task can still fail after it's created (for example if your balance can't cover it), so go by what retrieving the task or the webhook tells you.

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

Get the result

Measured from creation to the end: about 1–1.5 minutes, 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": {
    "image_url": "https://example.com/room.jpg",
    "aspect_ratio": "16:9"
  },
  "num_outputs": 1,
  "outputs": [
    {
      "index": 0,
      "type": "image",
      "url": "https://cdn.nanoapi.ai/h/tk_01jbm4c6e9g2j5k8q1t4w7y0a3_1_1793694600.png",
      "preview_url": "https://cdn.nanoapi.ai/h/tk_01jbm4c6e9g2j5k8q1t4w7y0a3_1_1793694600_compressed.jpg"
    }
  ],
  "billing": {
    "currency": "USD",
    "frozen": "…", // the price per task
    "charged": "…", // the same
    "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

The image is passed as a public http(s) URL in image_url. There's no upload endpoint: host the file yourself. URLs are at most 4096 characters, must download directly and can't point to localhost or private, loopback or reserved addresses.

The image is read only when generation runs, after the price was frozen: if it can't be downloaded, isn't an image or can't be opened, the task fails with invalid_media and the frozen amount is returned in full. Keep the link reachable until the task finishes, including links that expire.

Pricing

cost = price per task

Loading the current prices…

• aspect_ratio and the size of the original don't change the price.
• It's frozen within a few seconds of creating the task and charged when the task succeeds; when the task fails, all of it is returned. How freezing and charging work in general: Billing.

Read the current price from GET /v1/products (the outpaint_image product has one prices row, billing_unit task). Prices change, so don't hard-code them; billing.frozen on the retrieved task is what counts.

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.