Reference Image API Reference
Use the Gate.AI image-to-image endpoint to upload a reference image and generate or edit an image. This endpoint uses multipart/form-data and synchronously returns image URLs and billing details; usage.input_tokens includes image_tokens counted from the reference image.
| Field | Value |
|---|---|
| Base URL | https://api.gate.ai/openai/v1 |
| Auth | Authorization: Bearer <API_KEY> |
| Format | OpenAI-compatible; uses a multipart/form-data 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 a Reference Image
POST
/images/editsUpload a reference image with multipart/form-data to synchronously generate or edit an image. usage.input_tokens includes image_tokens counted from the reference 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: multipart/form-data |
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 |
| image | file | Yes | Reference image file. gpt-image-1 requires PNG, under 4 MB, square; without mask, it must include an alpha channel as the mask |
| mask | file | No | PNG mask. Transparent areas are edited, and dimensions must match image |
| prompt | string | Yes | Edit prompt, up to 1000 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 256x256, 512x512, or 1024x1024, 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 |
Example
text
1model=gpt-image-12prompt=Add a yellow border and a small sun in the corner3size=1024x10244image=@./input.pngResponse 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": 1781604390,3 "data": [4 {5 "url": "https://ai-gateway-file.s3.ap-northeast-1.amazonaws.com/multimodal/image/2026/06/16/example-edit-0.png?X-Amz-Expires=600&X-Amz-Signature=..."6 }7 ],8 "size": "1024x1024",9 "quality": "low",10 "output_format": "png",11 "usage": {12 "input_tokens": 220,13 "input_tokens_details": {14 "image_tokens": 194,15 "text_tokens": 2616 },17 "output_tokens": 272,18 "total_tokens": 49219 },20 "model_extend": {21 "cost": "0.009804",22 "provider": "openai",23 "total_tokens": "492"24 }25}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 |