Quick Answer
- Use POST /v1/images/generations with model=gpt-image-2.
- Supports prompt generation and reference_images URL inputs for guided generation.
- Reference images must be URLs, so local files must be uploaded first instead of passing base64 directly.
- The endpoint returns an async task id for later status polling.
- Official public pricing is roughly $0.22 / $0.50 / $1.30 per image for 1K / 2K / 4K; ToAPIs currently shows $0.015 / $0.020 / $0.025 per image on the landing comparison, with final billing based on account pricing.
- At the ToAPIs 1K listed rate of $0.015 per image, a $10 top-up is roughly 600+ additional 1K images; at the 4K listed rate of $0.025 per image, it is roughly 400 4K images.
Key Parameters
- model | string | required | gpt-image-2 | - | Use gpt-image-2 as the exact model id.
- prompt | string | required | - | - | Primary prompt for image generation or editing.
- size | string | optional | 1:1 | 1K: 1:1 | 3:2 | 2:3; 2K: 1:1 | 3:2 | 2:3 | 4:3 | 3:4 | 5:4 | 4:5 | 16:9 | 9:16 | 2:1 | 1:2 | 21:9 | 9:21; 4K: 4:3 | 3:4 | 16:9 | 9:16 | 2:1 | 1:2 | 21:9 | 9:21 | Output aspect ratio; supported values depend on the selected resolution tier.
- resolution | string | optional | 1K | 1K | 2K | 4K | Output resolution tier; must match a supported size combination.
- reference_images | string[] | optional | - | URL array | Reference image URL array. Local files must be uploaded first; no direct base64 references.
- image_urls | string[] | optional | - | URL array (compat field) | Compatibility field; prefer reference_images for new integrations.
- response_format | string | optional | url | url | b64_json | Response format; current ToAPIs docs recommend url.
Common Errors
- 400 invalid_request_error: trigger=Missing required fields or invalid size-resolution combinations.; fix=Validate model, prompt, size, resolution, and response_format against docs.; retry=Retry only after correcting the payload.
- 400 invalid_reference_images: trigger=Passing base64, local paths, or non-URL reference_images values.; fix=Upload the image first and pass the resulting URL in reference_images.; retry=Retry after fixing the reference image input.
- 401 authentication_error: trigger=Missing Authorization header or invalid API key.; fix=Verify bearer token format and key scope.; retry=Retry after fixing authentication.
- 429 rate_limit_exceeded: trigger=Request rate, concurrency, or current quota hits upstream rate limiting.; fix=Apply exponential backoff first, then review request rate, concurrency, and quota usage.; retry=Use 1s/2s/4s backoff with jitter; if it persists, reduce submission pressure.
