gptimg.co gptimg.co DocumentationCreate images
Turn a prompt into a production-ready image with the gpt-image-2 API. One POST with a Bearer token, up to four reference URLs, 45-second round trip.
Create images
POST /api/v1/images/generateSubmits an image generation task and immediately returns a task ID.
The task runs asynchronously — poll
GET /api/v1/images/task/{id} for status and
results.
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <YOUR_API_KEY> |
Content-Type | Yes | application/json |
Request body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
prompt | string | Yes | — | Natural-language description of the desired image |
aspect_ratio | string | No | "1:1" | One of the 13 values listed below |
n | integer | No | 1 | Number of images to generate, 1–4. Credits scale linearly. |
reference_images | string[] | No | [] | Up to 4 https URLs. If non-empty, the task runs as image-to-image. |
Supported aspect ratios
1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 5:4, 4:5, 2:1, 1:2, 21:9, 9:21Mode: text-to-image
Prompt only, no reference images.
{
"prompt": "A cinematic wide shot of a lone lighthouse on a cliff at sunset, oil painting style",
"aspect_ratio": "16:9",
"n": 1
}Mode: image-to-image
Pass 1–4 reference image URLs. The model uses them as visual references — for example, the subject's identity, an outfit, a color palette, or a composition to follow.
{
"prompt": "Restyle the subject as a watercolor painting with soft pastel tones",
"reference_images": [
"https://example.com/portrait.jpg"
],
"aspect_ratio": "3:4",
"n": 2
}URL requirements
All reference_images URLs must:
- Use the
https://scheme (http anddata:URIs are rejected) - Point to a publicly reachable resource that the upstream generator can download
Base64 payloads are explicitly rejected — they bloat logs, DB rows, and upstream requests. Upload your image to your own storage (or any public host) and pass the resulting URL.
Response
200 OK
{
"success": true,
"data": {
"id": "kUtpnus8fXpDKkuEjayG3",
"task_id": "gpt-image-2-kUtpnus8fXpDKkuEjayG3",
"status": "processing",
"provider": "gpt-image-2",
"model": "gpt-image-2",
"type": "text-to-image",
"media_url": null,
"images": [],
"created_at": "2026-04-22T00:12:03.456Z"
}
}| Field | Description |
|---|---|
data.id | Internal row ID. Use data.task_id for polling. |
data.task_id | Task identifier. Format: gpt-image-2-<21-char id>. Pass this to GET /api/v1/images/task/{id}. |
data.status | Always "processing" at creation. |
data.type | "text-to-image" if reference_images was empty, otherwise "image-to-image". |
data.created_at | ISO 8601 creation timestamp. |
Error responses
See the Errors page for the full reference. Common errors for this endpoint:
400 INVALID_REQUEST— body failed validation (empty prompt, unsupported aspect ratio,nout of range, reference URL nothttps://)401 UNAUTHORIZED— missing/invalid API key, or key leaked through a query string402 INSUFFICIENT_CREDITS— balance below2 × n. The response body includesrequiredandavailablefields for context.500 INTERNAL_ERROR— unexpected server-side failure. The credit charge is refunded automatically.
Complete example
curl -X POST https://gptimg.co/api/v1/images/generate \
-H "Authorization: Bearer $GPTIMG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A minimalist product shot of a ceramic coffee cup, top-down view, soft shadow",
"aspect_ratio": "1:1",
"n": 2
}'