​
Prefer asynchronous generation

For new integrations, use:
Create the job, save its ID, and poll for the result. This is the recommended flow for web pages, mobile clients, serverless functions, batch jobs, and reference-image editing because it avoids holding one synchronous request open for a long time. Synchronous compatibility requests use:
The multipart image edit endpoint is retained for legacy clients:
New integrations should use the asynchronous JSON endpoint with image or images for URL or base64 reference images.

​
Text-to-image

​
Reference images

For remote images, put public OSS or CDN URLs in the asynchronous JSON request:
Resize large images before submission and make sure their URLs remain accessible while the job is running.

​
Reading results

An image request may return an image URL, b64_json, or an asynchronous task ID. Do not hard-code only one response field. Save results that need long-term access to your own object storage.

​
Polling jobs

  1. Create a job with POST /v1/images/generations/jobs.
  2. Save the returned id and current status.
  3. Poll GET /v1/images/generations/jobs/{job_id} every two to three seconds initially.
  4. Continue while the status is queued or running.
  5. Read data when the status is succeeded.
  6. Read error.message when the status is failed.
Stop polling only at a terminal state. On a temporary network failure, retry the next polling interval instead of creating a duplicate job.