Text-to-Image API Reference
Use the Gate.AI text-to-image endpoint to call image models from OpenAI, Qwen, Seedream, and other providers. This endpoint uses a JSON request body and synchronously returns image URLs and billing details, with no job_id polling or webhook.
| Field | Value |
|---|---|
| Base URL | https://api.gate.ai/openai/v1 |
| Auth | Authorization: Bearer <API_KEY> |
| Format | OpenAI-compatible; uses a JSON request body |
Image endpoints live under /openai/v1. Generated data[].url values are short-lived S3 presigned URLs, so download or persist them promptly. Stored objects have a 30-day TTL.
Generate Images from Text
POST
/images/generationsGenerate images synchronously from a text prompt. Successful responses use the OpenAI-compatible image result shape, with data[].url pointing to the generated image.
Request Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Authorization | header | string | Yes | Gate.AI API Key. Format: Bearer <API_KEY> |
| Content-Type | header | string | Yes | Request body format: application/json |
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Image model ID, such as gpt-image-1, qwen-image-2.0-pro, or seedream-4.0. Missing model returns 400 model is required |
| prompt | string | Yes | Image text prompt. gpt-image-1 allows up to 32000 characters |
| n | integer | No | Number of images to generate, 1-10, default 1. Multiple images are billed per image |
| size | string | No | Output size. gpt-image-1 supports 1024x1024, 1536x1024, 1024x1536, or auto, and this is used for cost estimation |
| response_format | string | No | url or b64_json. gpt-image-1 does not support this parameter and may reject it upstream |
| stream | boolean | No | Pass-through field. The current image path is synchronous and does not route by this value |
Example
json
1{2 "model": "gpt-image-1",3 "prompt": "A golden retriever running on a sunny beach, cinematic",4 "n": 1,5 "size": "1024x1024"6}Response Fields
| Name | Type | Description |
|---|---|---|
| created | integer | Generation timestamp in seconds |
| data | array | Result array, length equals n |
| data[].url | string | Image S3 presigned URL, short-lived, with a 30-day stored object TTL |
| usage | object | Usage. OpenAI models return token details; Qwen models return width, height, and image_count |
| model_extend.cost | string | Actual billed amount in USD; billing is based on this value |
| model_extend.line_items | array | Billing line items. Token billing includes input/output/cache; per-image billing includes billing_unit, rate_usd_per_image, and resolution_tier |
| model_extend.provider | string | Actual upstream provider, such as openai or qwen |
| size / quality / output_format / background | string | Input fields echoed by some models |
| model | string | Only echoed at the top level for Qwen models |
Response Example
json
1{2 "created": 1781604363,3 "data": [4 {5 "url": "https://ai-gateway-file.s3.ap-northeast-1.amazonaws.com/multimodal/image/2026/06/16/example-0.png?X-Amz-Expires=600&X-Amz-Signature=..."6 }7 ],8 "size": "1024x1024",9 "quality": "low",10 "output_format": "png",11 "background": "opaque",12 "usage": {13 "input_tokens": 10,14 "output_tokens": 196,15 "total_tokens": 206,16 "output_tokens_details": {17 "image_tokens": 196,18 "text_tokens": 019 }20 },21 "model_extend": {22 "cost": "0.006322",23 "provider": "openai",24 "total_tokens": "206",25 "line_items": [26 {27 "kind": "uncached_input",28 "tokens": 10,29 "rate_usd_per_million": "5.0000000000",30 "amount_usd": "0.0000500000"31 },32 {33 "kind": "output",34 "tokens": 196,35 "rate_usd_per_million": "32.0000000000",36 "amount_usd": "0.0062720000"37 }38 ]39 }40}Response
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Success. Returns image results and billing information synchronously. | ImageResponse |
| 400 | Bad Request | Malformed request body, invalid JSON, or missing model / prompt. | OpenAIErrorResponse |
| 401 | Unauthorized | API key is invalid or missing. | OpenAIErrorResponse |
| 402 | Payment Required | Insufficient balance. Response includes current balance and estimated cost. | InsufficientBalanceResponse |
| 404 | Not Found | Model not found, or the image endpoint is not enabled. | OpenAIErrorResponse |
| 413 | Payload Too Large | Request body too large. Default limit is 8 MiB. | OpenAIErrorResponse |
| 429 | Too Many Requests | Too many requests. Please slow down. | OpenAIErrorResponse |
| 500 | Internal Server Error | Internal server error. | OpenAIErrorResponse |
| 502 | Bad Gateway | Upstream image service failed. | OpenAIErrorResponse |