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-1-official",
    "prompt": "An ancient castle under a starry sky",
    "size": "1:1",
    "quality": "auto",
    "n": 1
  }'

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

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-1-official",
    "prompt": "An ancient castle under a starry sky",
    "size": "1:1",
    "quality": "auto",
    "n": 1
  }'

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

​
Supported Models

ModelDescriptionModesImage-to-ImageMax ImagesBilling
gpt-image-1-officialStability-first, suitable for general image generationText-to-Image / Image-to-ImageSupported4Size x Quality
gpt-image-1.5-officialNew version, suitable for higher quality and complex editingText-to-Image / Image-to-ImageSupported4Size x Quality

​
Authorizations

​
Authorization
string
required
All API requests require Bearer Token authenticationGet your API Key:Visit the API Key management page to obtain your API KeyAdd the following to your request headers:
Authorization: Bearer YOUR_API_KEY

​
Body

​
model
string
required
Model name
  • gpt-image-1-official - Stability-first, suitable for general image generation
  • gpt-image-1.5-official - New version, suitable for higher quality and complex editing
​
prompt
string
required
Text description for image generation, supports both Chinese and English
​
size
string
default:"1:1"
Aspect ratioSupported ratios:
  • 1:1 - Square (default)
  • 3:2 - Landscape
  • 2:3 - Portrait
​
n
integer
default:"1"
Number of images to generateRange: 1-4
  • Values ≤ 0 will be treated as 1
  • Values > 4 will be treated as 4
Warning: Must be a plain number (e.g. 1), do not add quotes, otherwise it will cause an error
​
quality
string
default:"auto"
Image quality
  • auto - Auto quality selection (default)
  • low - Faster, more economical
  • medium - Balance between quality and cost
  • high - Higher quality, higher cost
​
background
string
default:"auto"
Background mode
  • auto - Auto background (default)
  • opaque - Opaque background
  • transparent - Transparent background, recommended with png output format
background: transparent cannot be used with output_format: jpeg simultaneously
​
moderation
string
default:"auto"
Moderation level
  • auto - Default moderation level
  • low - More lenient moderation
​
output_format
string
default:"png"
Output format
  • png - Default format, suitable for transparent backgrounds
  • jpeg - Smaller file size, suitable for general image output
background: transparent cannot be used with output_format: jpeg simultaneously
​
output_compression
integer
Output compression level, range 0-100
  • Recommended only for jpeg
  • Not recommended for png
​
image_urls
array
Array of reference image URLs, enables image-to-image mode when providedLimit: Up to 15 reference images
​
mask_url
string
Mask image URL for inpainting
  • Must be used together with image_urls
  • Will be submitted via the official editing API
  1. Before uploading the mask image, please confirm that the image Alpha channel is “Yes”.
  2. The mask image size must match the first reference image.

​
Size Reference

Aspect ratios are used externally; the system automatically maps them to official dimensions internally.
RatioActual SizeDescription
1:11024x1024Square
2:31024x1536Portrait
3:21536x1024Landscape

​
Usage Examples

Text-to-Image (minimal) 
{
  "model": "gpt-image-1-official",
  "prompt": "An ancient castle under a starry sky"
}
Text-to-Image (full parameters) 
{
  "model": "gpt-image-1-official",
  "prompt": "A flat icon of a glass bottle with no background",
  "size": "2:3",
  "quality": "high",
  "background": "transparent",
  "moderation": "low",
  "output_format": "png",
  "n": 1
}
Image-to-Image (single reference) 
{
  "model": "gpt-image-1.5-official",
  "prompt": "Convert the reference image to illustration style, preserving the main outline",
  "size": "1:1",
  "quality": "auto",
  "image_urls": [
    "https://your-cdn.com/input.png"
  ],
  "n": 1
}
Image-to-Image (multi-reference fusion) 
{
  "model": "gpt-image-1.5-official",
  "prompt": "Merge two reference images into an illustration poster, preserving the main outlines",
  "size": "1:1",
  "quality": "auto",
  "background": "transparent",
  "image_urls": [
    "https://your-cdn.com/input-a.png",
    "https://your-cdn.com/input-b.png"
  ],
  "moderation": "low",
  "output_format": "png",
  "n": 1
}
Multiple images (n > 1) 
{
  "model": "gpt-image-1-official",
  "prompt": "Four minimalist poster variations of a red fox",
  "size": "1:1",
  "quality": "low",
  "output_format": "png",
  "n": 4
}

​
Response

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

​
Notes

  1. Asynchronous processing: After submission, a task_id is returned. Poll /v1/tasks/{task_id} to get results
  2. Model selection: Use gpt-image-1-official for general image generation; use gpt-image-1.5-official for high-quality editing and complex image-to-image tasks
  3. Image URL requirements: For image-to-image, use publicly accessible and stable image URLs
  4. Billing: Charged per successfully generated image; no charge for failures