Image Edit

Fast image editing API reference. Edit photos with a text instruction and choose the model per request. OAI Swift v1 returns edits in about 7–12 seconds.

Edit Image

POST

/v1/images/edit/

Edit one or more images with a text instruction. One endpoint for several editing models: pick one with the model field. Built for speed: with OAI Swift v1 a typical edit is ready in about 7–12 seconds from submit to result. Like every endpoint, it returns a task_id; poll the status endpoint for the image.

Request

# Edit a photo with the default model
curl -X POST https://api.3daistudio.com/v1/images/edit/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "images": ["data:image/jpeg;base64,/9j/4AAQ..."],
    "prompt": "Replace the background with a clean white studio backdrop."
  }'

# Choose the model, size and output format
curl -X POST https://api.3daistudio.com/v1/images/edit/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "oai-swift-v1",
    "images": ["data:image/jpeg;base64,/9j/4AAQ..."],
    "prompt": "Make the jacket red. Keep everything else unchanged.",
    "size": "1024x1536",
    "output_format": "png"
  }'

Response

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-11-05T14:00:00Z"
}

Parameters

Parameter	Type	Required	Description
images	array	Yes	1 to 10 base64-encoded images (data:image/...;base64,...), PNG, JPEG or WebP. The first image is the one being edited; the others are references. Images larger than 2,048 px on the longest side are downscaled automatically.
prompt	string	Yes	Edit instruction, up to 32,000 characters. Say what to change and what to keep (e.g. "Make the jacket red. Keep everything else unchanged.").
model	string	No	Editing model, see Models. Default: "oai-swift-v1".
size	string	No	"auto" (about 1 megapixel in the shape of the first image) or "WIDTHxHEIGHT", e.g. "1024x1536": multiples of 16, aspect ratio at most 3:1, 655,360 to 2,200,000 pixels. Largest sizes: 1472x1472 (1:1), 1712x1280 (4:3), 1808x1200 (3:2), 1968x1104 (16:9), 2544x848 (3:1), and the same flipped for portrait. An invalid size is rejected with the reason and the closest valid size. Smaller sizes are slightly faster. Default: "auto".
output_format	string	No	"jpeg" (fastest), "png" or "webp". Default: "jpeg".
background	string	No	"auto", "opaque" or "transparent" (requires png or webp). Default: "auto".
markup	string	No	A transparent PNG (base64) with circles, arrows or sketches marking what to change, exactly the size of the first image. Describe the change in the prompt and ask to remove the marks.
options	object	No	Model-specific settings. {"planning": "fast" \| "balanced" \| "thorough"}: how much the model plans before rendering. Same price; "fast" (default) suits most edits.

Models

Model	Typical time	Notes
oai-swift-v1 (OAI Swift v1)	~7–12 s	Default. Our fastest editor. Strong at keeping faces, outfits and accessories; supports markup.

Checking Status

GET

/v1/generation-request/<task_id>/status/

Poll with the task_id from the submit response. Edits finish in seconds, so polling every 0.5–1 seconds is fine. When status is "FINISHED", results contains the edited image; its metadata lists the model and the output size. Results expire after 24 hours.

Request

curl https://api.3daistudio.com/v1/generation-request/YOUR_TASK_ID/status/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "status": "FINISHED",
  "progress": 100,
  "failure_reason": null,
  "results": [
    {
      "asset": "https://storage.3daistudio.com/assets/9f2c3a.jpg",
      "asset_type": "EDITED_IMAGE",
      "metadata": { "model": "oai-swift-v1", "width": 832, "height": 1248 }
    }
  ]
}

Credit Costs

8 credits per edit plus 2 credits per input image. A typical one-photo edit costs 10 credits. Failed edits are refunded automatically.

Input images	Credits
1	10
2	12
4	16
10	28

Processing Times

With OAI Swift v1 a typical edit takes about 7–12 seconds end to end, most of it in the model. For the fastest results send JPEG photos no larger than about 2,048 px, keep size at "auto" (or a smaller size such as "816x816"), and run several edits in parallel instead of one after another.

Errors

Common errors for the image edit endpoint.

Status	Error Code	Description
400	VALIDATION_FAILED	Missing or invalid parameters (the response lists the fields). Nothing is charged.
402	INSUFFICIENT_CREDITS	Not enough credits. Purchase more credits.
429	RATE_LIMITED	Rate limit exceeded. Wait and retry.
503	INPUT_STAGING_FAILED	The input images could not be processed. Nothing was charged; retry after a short delay.
503	DISPATCH_FAILED	The edit could not be started. Credits were refunded; retry after a short delay.