aisplice

API reference

Images: async tasks

Models on this endpoint (12)

gpt-image-2.5-extgpt-image-2seedream-5-0-flashgpt-image-2.5-flare+8
Try it in the Workbench
POST/v1/images/tasks
GET/v1/images/tasks/{task_id}
GET/v1/images/tasks/{task_id}/content

Async image generation — the route every image model in the catalogue uses. Submit returns a task_id; poll the status endpoint, then read persistent result URLs from /content — or register a webhook and skip polling.

#Request parameters

  • modelstringrequired

    An async image model ID, e.g. gpt-image-2. Sync-only models reject this endpoint.

  • promptstringrequired

    What to draw.

  • sizestringoptional

    Aspect-ratio preset such as "16:9" — what most image models take; the model card lists the exact values. Some older models also accept WIDTHxHEIGHT.

  • resolutionstringoptional

    Output resolution tier such as "1K", "2K" or "4K", where the model card lists it — also a pricing-tier dimension.

  • qualitystringoptional

    Vendor quality level (e.g. standard / hd) — also a pricing-tier dimension.

  • nintegeroptional

    Number of images (billing multiplies per image).

  • imagesarrayoptional

    Reference images to edit or follow, as URLs or data URIs. The model card lists how many each model takes.

  • maskstringoptional

    Repaint one area of the first reference image — see "Edit part of an image" below. Only models whose model card lists mask take it; mask_url is accepted as the same field.

  • webhook_urlstringoptional

    HTTPS URL called once the task reaches a terminal state — see the video guide for the callback contract.

  • webhook_secretstringoptional

    If set, deliveries carry X-Xiaoxiang-Signature: sha256=hex(HMAC-SHA256(body, secret)).

Parameters differ by model

Check the model card for the fields and values each model takes. gpt-image-2.5-ext takes size as a ratio plus resolution; a pixel size such as 2560x1088 is mapped to the nearest ratio and resolution (21:9 at 2K). It has no background control: "auto" is ignored, other values are rejected. It makes one picture per request and has no version choice: leave version out or send "flare".

Field names may vary by model family

Task status payloads mirror what the upstream vendor reports; treat your actual responses as authoritative and rely on task_id, status and the /content endpoint, which are stable across vendors.

#Edit part of an image

Send the picture in images and a mask: only the masked area is redrawn and the rest of the picture stays as it is. Say in prompt what should appear there. Today gpt-image-2.5-flare and gpt-image-2.5-sunburst take a mask; the model card shows it as the mask field.

curl https://www.aisplice.store/v1/images/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Replace the mug with a glass of orange juice; keep everything else",
    "images": ["https://example.com/desk.png"],
    "mask": "https://example.com/desk-mask.png",
    "resolution": "1K"
  }'

How to make the mask

A PNG with an alpha channel: fully transparent pixels mark the area to redraw, the rest is kept. It must be exactly the pixel size of the first reference image (not of the output), under 4 MB. One mask per request; with several reference images it applies to the first. On the gpt-image-2.5 models, leave size out so the result keeps the picture's shape.
  • 400 invalid_requestmask was sent without a reference image, or to a model that takes none (gpt-image-2.5-ext answers "mask is not supported on Ext").

Full error-code table →

#Related errors

  • 404 not_foundUnknown path, unknown model name, or an expired / foreign task_id.
  • 401Invalid or missing bearer token. No error.code on this path — match the status.
  • 402 insufficient_user_quotaWallet balance cannot cover the pre-reserved estimate.
  • 429Per-key throttle. Empty body; wait for Retry-After. A 429 that does carry insufficient_user_quota is a daily spend cap instead.
  • 503 model_not_foundUnknown model, or no healthy channel serves it right now.

Full error-code table →

#Request example

# 1. submit
curl https://www.aisplice.store/v1/images/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.5-ext", "prompt": "A red paper crane on a desk", "size": "16:9", "resolution": "1K"}'

# 2. poll every 3s until a terminal status
curl https://www.aisplice.store/v1/images/tasks/$TASK_ID -H "Authorization: Bearer sk-YOUR_KEY"

# 3. fetch persistent result URLs
curl https://www.aisplice.store/v1/images/tasks/$TASK_ID/content -H "Authorization: Bearer sk-YOUR_KEY"

#Response

response.json
// POST /v1/images/tasks
{"task_id": "task_xxx", "status": "queued"}

// GET /v1/images/tasks/{task_id}
{"task_id": "task_xxx", "status": "in_progress", "progress": "60%"}

// GET /v1/images/tasks/{task_id}/content — after completion
{"created": 1720000000, "data": [{"url": "https://…"}]}

Still stuck?

Send us the request ID or the error message and we will look into it.

PreviousMessages (Anthropic format)NextVideos