Skip to main content
POST
GPT-Image-2.5 Image Generation
The standard tier creates an image task through POST /v1/images/generations and returns a task ID. After the task finishes, retrieve the image URL through the status endpoint. Both models use the same request format: gpt-image-2.5 is the series name. Always pass the full model name from the table.
This page covers the standard tier. To pay by actual token usage, use the separate GPT-Image-2.5 VIP documentation. Both tiers run as async tasks; the main differences are the size format and the billing model.
Note for users in mainland China: Please use https://toapis.cn as the API endpoint (Base URL). Replace https://toapis.com with https://toapis.cn in the examples in this document.
Create an API Key in the console.

Quick Start

Set your ToAPIs API Key as the TOAPIS_API_KEY environment variable, then submit the task:
Example submit response:
Save the returned id, replace TASK_ID below with that value, and query the result:
A task moves through pending, queued, and in_progress, and finally reaches completed or failed. On completed, read the image URL from result.data; on failed, read error. Poll every few seconds. The full set of fields is documented in Image Task Status. A successful submit only means the task was created. Wait until completed before downloading the image, and keep polling the same task ID while you wait.

Request Parameters

string
required
Authenticate with Bearer YOUR_TOAPIS_API_KEY.
string
required
gpt-image-2.5-flare or gpt-image-2.5-sunburst.
string
required
Description of the image. When you use reference images, describe the subject to keep and the content to change.
string
default:"high"
The standard tier currently pins W8X channels to high, so you can omit this parameter. Any other string value is ignored and high is used instead. The Playground does not expose a quality option.The standard tier is currently priced by resolution.
string
default:"1:1"
Aspect ratio, for example 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 21:9.We recommend using a ratio and passing resolution explicitly. The service calculates the output pixel dimensions from both values. The standard tier uses ratios, while the VIP tier uses pixel dimensions.
string
default:"1K"
Resolution tier. 1K, 2K, and 4K are supported, and lowercase values are also accepted. This field determines the pricing tier for the standard tier.
string
Optional background setting. Set "transparent" to generate an image with a transparent background. Omit this field for normal image generation.Works with both text-to-image requests and requests containing reference_images.
integer
default:1
Use 1 per request to generate one image.
string[]
Optional list of reference image URLs. The images must be reachable by the server. For local images, obtain a URL first through the Upload Image API.image_urls is also accepted. Use one of the two fields. The examples on this page use reference image URLs; to upload local files directly for editing, see Reference Image Editing.

Ratio and Resolution Examples

4K is a resolution tier; the actual width and height depend on the aspect ratio. A square 4K output, for example, is 2880x2880.

Generation with Reference Images

Use the same generation endpoint and add reference_images. The example below uses Sunburst and still returns an async task:
Replace https://example.com/otter.png with your own reference image URL, then query the result with the returned task ID.

Pricing

The prices below are standard prices verified on 2026-09-09, for one generated image per request. Both standard models cost the same: All three prices apply to low, medium, high, xhigh, and max. Reference image input currently has no additional per-image fee. Account-specific pricing or discounts may differ; check the model pricing page and your account configuration for the latest prices.

Differences from the VIP Tier

When switching to VIP, change the model name and the parameters together. See GPT-Image-2.5 VIP for details.