Skip to main content

​
Image Studio — Edit Live

POST /v1/images/studio/edit
Edit one or more input images with a text instruction. The endpoint is always async — it accepts your job and returns immediately with a job_id. Retrieve the result by polling the status_url or by supplying a callback_url to receive a webhook when the job completes.

​
Request body

ParameterTypeRequiredDescription
promptstringYesEditing instructions. 1-2,000 characters.
image_urlsarray of stringsYes1-5 reference image URLs to edit. Some models use only the first image — see the model catalog.
modelstringYesEdit model to use. The API defaults to standard if omitted, but integrations should send this explicitly. Full list in the model catalog.
callback_urlstringNoWebhook URL that will receive the final result.
additional_settingsobjectNoModel-specific settings (e.g., resolution, quality, aspect_ratio). Refer to the model catalog for accepted values per model.
enable_fallbackbooleanNoDefaults to true. Accepted for forward compatibility; image edit fallback behavior is model-dependent.

​
Model support

Default model: standard. The API can default model when omitted, but production integrations should send it explicitly so the selected edit model is clear. common means callback_url, additional_settings, and enable_fallback. Model-specific knobs are passed in additional_settings.
Model IDDisplay nameRequired paramsOptional supported paramsCostETA
standardGemini 2.5 Flashprompt, image_urls, modelcommon; image_urls 1-5$0.10~8s
proGemini 3 Proprompt, image_urls, modelcommon; image_urls 1-5$0.20~10s
qwen-image/edit-2511Qwen Image Edit 2511prompt, image_urls, modelcommon; image_urls 1-3$0.10~15s
Seedream-4.5-uncensoredSeedream v4.5prompt, image_urls, modelcommon + seed; image_urls 1-5$0.10~15s
Wan-2.6Wan 2.6prompt, image_urls, modelcommon + seed, negative_prompt; image_urls 1-5$0.10~20s
Wan-2.6-image-editWan 2.6 Image Editprompt, image_urls, modelcommon + seed, negative_prompt; image_urls 1-5$0.10~15s
group-editQwen Group Photoprompt, image_urls, modelcommon + seed; image_urls 1-5$0.10~20s
xai/grok-imagine-image/editGrok Imagine Editprompt, image_urls, modelcommon + seed; provider uses the first image$0.10~15s
seedream-v5Seedream v5 Liteprompt, image_urls, modelcommon; image_urls 1-5$0.10~15s
nano-banana-2/editNano Banana 2 Editprompt, image_urls, modelcommon + resolution (0.5k, 1k, 2k, 4k), aspect_ratio, output_format (png, jpeg), enable_web_search, enable_image_search; image_urls 1-50.5k/1k/2k $0.10, 4k $0.20~20s
nano-banana-2/edit-fastNano Banana 2 Edit Fastprompt, image_urls, modelcommon + resolution (2k, 4k), aspect_ratio, output_format (png, jpeg); image_urls 1-5$0.10~12s
seedream-v4.5/edit-sequentialSeedream v4.5 Edit Sequentialprompt, image_urls, modelcommon + seed, max_images (1-15); image_urls 1-5$0.10~25s
seedream-v5.0-lite/edit-sequentialSeedream v5 Lite Edit Sequentialprompt, image_urls, modelcommon + max_images (1-15); image_urls 1-5$0.10~25s
wan-2.7-image-editWan 2.7 Image Editprompt, image_urls, modelcommon + seed; image_urls 1-5$0.10~15s
wan-2.7-image-edit-proWan 2.7 Image Edit Proprompt, image_urls, modelcommon + seed; image_urls 1-5$0.10~20s
gpt-image-2/editGPT Image 2 Editprompt, image_urls, modelcommon + quality (low, medium, high), resolution (1k, 2k), aspect_ratio, output_format (png, jpeg, webp); image_urls 1-5low/medium $0.10, high 1k $0.30, high 2k $0.40~20s

​
Example request

curl --request POST "https://api.uncensored.com/api/v1/images/studio/edit" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "prompt": "Add a vibrant sunset background and warm lighting",
    "image_urls": ["https://example.com/photo.jpg"],
    "model": "pro",
    "callback_url": "https://your-server.com/webhook"
  }'

​
Submit response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "status_url": "https://api.uncensored.com/api/v1/images/studio/edit/jobs/550e8400-e29b-41d4-a716-446655440000",
  "mode": "edit",
  "webhook_url": "https://your-server.com/webhook",
  "created_at": "2026-05-17T10:30:00Z"
}

​
Get job status

GET /v1/images/studio/edit/jobs/{job_id}
Poll every 2-5 seconds. Most jobs complete in 10-90 seconds depending on the model. 
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "image_url": "https://media.lesscensored.com/images/abc123.png",
  "model": "pro",
  "is_fallback": false,
  "error": null,
  "created_at": "2026-05-17T10:30:00Z",
  "completed_at": "2026-05-17T10:30:15Z",
  "processing_time": 15.2
}

​
Response fields

FieldDescription
job_idID of the job.
statusprocessing, completed, or failed.
image_urlURL of the edited image when status is completed.
modelThe model that produced the result.
is_fallbacktrue if the requested model was temporarily unavailable and a substitute produced the result. The model field reports which one.
errorError message when status is failed; otherwise null.
processing_timeTotal time in seconds the job took to complete.

​
Webhook payload

If you supplied callback_url, the same JSON shape as the status response is POSTed to your webhook once the job reaches a terminal state (completed or failed).

​
Multi-image edits

Pass up to 5 image URLs in image_urls. The first image is typically the primary subject; additional images are treated as references. Not every model supports multi-image — the model catalog marks which models do.

​
Variable pricing

Models such as nano-banana-2/edit and gpt-image-2/edit price the request based on resolution and/or quality. Pass these in additional_settings: 
{
  "prompt": "Replace the background with a snowy mountain scene",
  "image_urls": ["https://example.com/photo.jpg"],
  "model": "gpt-image-2/edit",
  "additional_settings": {
    "quality": "medium",
    "resolution": "2k",
    "aspect_ratio": "16:9"
  }
}
See the model catalog for each model’s accepted values.

​
Status codes

Status codeDescription
202Job accepted and queued.
400Invalid request (e.g., missing image_urls, unknown model).
402Insufficient funds.
403Content moderation failed, or your API key’s scope does not permit this model.
429Rate limit exceeded.
500Internal server error.