Skip to main content
POST
/
v1
/
images
/
generations
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2",
    "prompt": "A ginger cat sitting on a windowsill watching the sunset, watercolor style",
    "n": 1,
    "size": "16:9"
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA"
    }
  ]
}

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2",
    "prompt": "A ginger cat sitting on a windowsill watching the sunset, watercolor style",
    "n": 1,
    "size": "16:9"
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA"
    }
  ]
}

​
Authorizations

​
Authorization
string
required
All endpoints require Bearer Token authenticationGet your API Key:Visit the API Key management page to get your API KeyInclude it in the request header:
Authorization: Bearer YOUR_API_KEY

​
Body

​
model
string
default:"gpt-image-2"
required
Image generation model nameFixed to gpt-image-2
​
prompt
string
required
Text description for image generation
  • Supports English and Chinese, detailed descriptions recommended
  • Pre-submission content moderation / safety review — violations are rejected immediately
​
n
integer
default:"1"
Number of images to generateRange: 1
Must be a pure number (e.g., 1), do not wrap in quotes
​
size
string
default:"1:1"
Image aspect ratio13 supported ratios:
  • 1:1 - Square (default)
  • 16:9 / 9:16 - Widescreen landscape / portrait
  • 4:3 / 3:4 - Standard landscape / portrait
  • 3:2 / 2:3 - Classic landscape / portrait
  • 5:4 / 4:5 - Near-square landscape / portrait
  • 2:1 / 1:2 - Wide landscape / tall portrait
  • 21:9 / 9:21 - Ultra-wide landscape / ultra-tall portrait
Only ratio notation is supported. Passing pixel sizes like 1024x1024 returns build_request_failed: invalid size
​
image_urls
array
Reference image array (OpenAI standard field). Switches to image-to-image mode when provided.
Other OpenAI standard fields (response_format, quality, style) are not supported and will be ignored. Task results only return url — please download and convert to base64 yourself if needed.

​
Usage Examples

Text-to-image (minimal request) 
{
  "model": "gpt-image-2",
  "prompt": "A ginger cat sitting on a windowsill watching the sunset, watercolor style"
}
Text-to-image (with ratio) 
{
  "model": "gpt-image-2",
  "prompt": "a corgi astronaut on the moon, cinematic, 8k",
  "size": "16:9",
  "n": 1
}
Image-to-image (reference = URL) 
{
  "model": "gpt-image-2",
  "prompt": "Turn this photo into a watercolor painting",
  "size": "1:1",
  "image_urls": [
    "https://example.com/photo.jpg"
  ]
}
Image-to-image (reference = base64) 
{
  "model": "gpt-image-2",
  "prompt": "Turn this photo into a watercolor painting",
  "image_urls": [
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ]
}
Image-to-image (multi-reference fusion, URL + base64 mixed) 
{
  "model": "gpt-image-2",
  "prompt": "Fuse these two photos into a single poster",
  "size": "4:3",
  "image_urls": [
    "https://example.com/photo-a.jpg",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ]
}

​
Response

​
code
integer
Response status code
​
data
array
Response data array

​
Querying Task Results

After successful submission, a task_id is returned. Poll the task status via GET /v1/tasks/{task_id}, see Task Query API for details.

​
Success Response Example

{
  "code": 200,
  "data": {
    "id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA",
    "status": "completed",
    "progress": 100,
    "created": 1776748674,
    "completed": 1776748726,
    "actual_time": 52,
    "estimated_time": 100,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/xxxxxxxx-gpt_image_2_task_xxx_0.png"
          ],
          "expires_at": 1776835126
        }
      ]
    }
  }
}
Image access: data.result.images[0].url[0]

​
Task Status

StatusMeaning
pendingSubmitted / queued
processingBeing processed upstream
completedSuccess, result.images available
failedFailed, check error.message

​
Polling Recommendations

  • Initial query delay: Wait 10~20 seconds after submission before first query
  • Query interval: 3~5 seconds recommended, avoid millisecond-level polling
  • Timeout reference: A single image typically completes in 3060 seconds (observed actual_time 4452s)
  • Batch query: To query multiple tasks at once, use POST /v1/tasks/batch with body {"task_ids": ["task_xxx", "task_yyy"]}

​
Notes

  1. Asynchronous processing: Submission returns task_id, poll /v1/tasks/{task_id} to get the final image URL
  2. Content moderation: prompt is reviewed first — violations are rejected with no billing
  3. Result URL: The platform mirrors upstream temporary signed links to its own R2 object storage, returning a stable link that clients can access directly
  4. URL validity: expires_at = completed + 24h in the response is a hint field, please download or mirror to your own CDN promptly
  5. Ratio conflict: Use the size field for aspect ratio — avoid repeating it in prompt to prevent upstream ambiguity
  6. Billing: Billed per successful image, no charge on failure or moderation rejection
  7. Task retention: task_id is retained in the database for several days by default (configured by TASK_RETENTION_DAYS) — expired queries return “task does not exist or has expired”