POST/api/v1/gpt-image-2/generate

Generate Image (GPT-2)

High-quality image generation with GPT Image 2. Supports multiple sizes up to 4K, quality tiers, and output formats.

Request Parameters

Parameter	Type	Required	Description
`prompt`	string	Yes	The text prompt describing the image
`size`	string	No	"1024x1024" (default), "1536x1024", "1024x1536", "2048x2048", "2048x1152", "3840x2160", "2160x3840", or "auto". On an edit, omit this or pass "auto" to keep the input image proportions.
`quality`	string	No	"low", "medium", "high", or "auto" (default). Affects detail level and cost.
`outputFormat`	string	No	"png" (default), "jpeg", or "webp".
`outputCompression`	number	No	Compression level 0-100 (JPEG/WebP only).
`moderation`	string	No	"auto" (default) or "low". Controls content moderation strictness.
`imageBase64`	array	No	Array of base64-encoded reference images (up to 14).
`imageUrls`	array	No	Array of reference image URLs (up to 14).
`callbackUrl`	string	No	Webhook URL for async callback mode. Returns 202 immediately.

Quality & Size Pricing

Quality	Image Size	Cost per Image
Low	1K (1024x1024, 1536x1024, 1024x1536)	$0.015
Low	2K (2048x2048, 2048x1152)	$0.025
Low	4K (3840x2160, 2160x3840)	$0.05
Medium	1K (1024x1024, 1536x1024, 1024x1536) (default)	$0.045
Medium	2K (2048x2048, 2048x1152)	$0.05
Medium	4K (3840x2160, 2160x3840)	$0.09
High	1K (1024x1024, 1536x1024, 1024x1536)	$0.18
High	2K (2048x2048, 2048x1152)	$0.20
High	4K (3840x2160, 2160x3840)	$0.35

Async Mode (Recommended)

Recommended for production

GPT Image 2 is the slowest model on the platform — large or high-quality generations routinely take 1-5+ minutes. We strongly recommend async mode for it: include a callbackUrl (or poll the job status endpoint) so the API returns a 202 response instantly and delivers the result via webhook, instead of holding a long synchronous connection that some clients or proxies may drop. Sync mode still works and will wait for the result, but async is more reliable for slow generations.

bash

curl -X POST https://eccoapi.com/api/v1/gpt-image-2/generate \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A photorealistic product photo of a silver espresso machine",
    "size": "2048x2048",
    "quality": "high",
    "callbackUrl": "https://your-server.com/webhook"
  }'

Returns 202 Accepted with a jobId. Poll /api/v1/jobs/:jobId for status, or receive the result at your callbackUrl.

Sync Request

Sync mode waits for the image and returns it directly. Best for quick generations under 60 seconds.

bash

curl -X POST https://eccoapi.com/api/v1/gpt-image-2/generate \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A photorealistic product photo of a silver espresso machine",
    "size": "1024x1024",
    "quality": "high",
    "outputFormat": "png"
  }'

Response

json

{
  "code": 200,
  "msg": "Success",
  "data": {
    "assetUrl": "https://<signed-url>",
    "assetKey": "user/<userId>/gpt-image-2/....png",
    "mimeType": "image/png",
    "bytes": 2097152
  },
  "meta": {
    "model": "gpt-image-2",
    "cost": 0.12,
    "remaining_credits": 9.88,
    "settings": {
      "size": "1024x1024",
      "quality": "high",
      "outputFormat": "png",
      "moderation": "auto"
    }
  }
}

Status Codes

Code	Description
`200`	Success - image generated
`202`	Accepted - async job queued (when callbackUrl is provided)
`400`	Bad request - invalid parameters
`401`	Unauthorized - invalid or missing API key
`402`	Payment required - insufficient credits
`429`	Rate limited - too many requests
`500`	Internal server error