ToAPIsToAPIs
GPT-4o-image

GPT-4o Image Generation

Generate images using GPT-4o model, supporting text-to-image and image editing

POST
/v1/images/generations

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.

  • Unified image generation API
  • Use model parameter to select gpt-4o-image model
  • Supports text-to-image, image-to-image, and image editing
  • Async task management, query results by task ID

Important Change: For better performance and cost control, we no longer support passing base64 image data directly in image_urls. Please use the Upload Image API first to upload images and get URLs, then call this endpoint.

Authorizations

Authorizationstringheaderrequired

All endpoints require Bearer Token authentication

Get your API Key from the API Key Management Page

Add to request header:

Authorization: Bearer YOUR_API_KEY

Body

modelstringbodyrequireddefault: gpt-4o-image

Image generation model name

Example: "gpt-4o-image"

promptstringbodyrequired

Text description for image generation

Maximum 1000 characters

sizestringbodydefault: 1:1

Image aspect ratio

Supported formats:

  • 1:1 - Square (default)
  • 2:3 - Portrait
  • 3:2 - Landscape
nintegerbodydefault: 1

Number of images to generate

Supports 1, 2, 4. Charges will be pre-deducted based on the number

Default: 1

⚠️ Note: Must enter a plain number (e.g., 1), do not use quotes or it will cause an error

image_urlsstring[]body

Reference image URL list for image-to-image or image editing

⚠️ URL format only (base64 no longer supported)

  • Publicly accessible image URL (http:// or https://)
  • You can use the Upload Image API to upload local images and get URLs

Limitations:

  • Maximum 5 images
  • Single image up to 10MB
  • Supported formats: jpeg, jpg, png, webp
mask_urlstringbody

Mask image URL (for image editing)

  • Must be PNG format
  • Size must match the reference image
  • Maximum 4MB

Response

idstring

Unique task identifier for status queries

objectstring

Object type, always generation.task

modelstring

Model name used

statusstring

Task status

  • queued - Queued for processing
  • in_progress - Processing
  • completed - Successfully completed
  • failed - Failed
progressinteger

Task progress percentage (0-100)

created_atinteger

Task creation timestamp (Unix timestamp)

metadataobject

Task metadata

requestExample

curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-4o-image",
    "prompt": "An ancient castle under the starry sky",
    "size": "1:1",
    "n": 1
  }'
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-4o-image",
    "prompt": "Transform this image into an ancient castle under the starry sky",
    "size": "1:1",
    "n": 1,
    "image_urls": [
      "https://example.com/castle.jpg"
    ]
  }'
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-4o-image",
    "prompt": "Add fireworks above the castle",
    "size": "1:1",
    "n": 1,
    "image_urls": [
      "https://example.com/castle.jpg"
    ],
    "mask_url": "https://example.com/mask.png"
  }'
import requests

response = requests.post(
    "https://toapis.com/v1/images/generations",
    headers={
        "Authorization": "Bearer your-ToAPIs-key",
        "Content-Type": "application/json"
    },
    json={
        "model": "gpt-4o-image",
        "prompt": "An ancient castle under the starry sky",
        "size": "1:1",
        "n": 1
    }
)

task = response.json()
print(f"Task ID: {task['id']}")
print(f"Status: {task['status']}")
import requests

response = requests.post(
    "https://toapis.com/v1/images/generations",
    headers={
        "Authorization": "Bearer your-ToAPIs-key",
        "Content-Type": "application/json"
    },
    json={
        "model": "gpt-4o-image",
        "prompt": "Transform this image into an ancient castle under the starry sky",
        "size": "1:1",
        "n": 1,
        "image_urls": ["https://example.com/castle.jpg"]
    }
)

task = response.json()
print(f"Task ID: {task['id']}")
print(f"Status: {task['status']}")
const response = await fetch('https://toapis.com/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-ToAPIs-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4o-image',
    prompt: 'An ancient castle under the starry sky',
    size: '1:1',
    n: 1
  })
});

const task = await response.json();
console.log(`Task ID: ${task.id}`);
console.log(`Status: ${task.status}`);
const response = await fetch('https://toapis.com/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-ToAPIs-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4o-image',
    prompt: 'Transform this image into an ancient castle under the starry sky',
    size: '1:1',
    n: 1,
    image_urls: ['https://example.com/castle.jpg']
  })
});

const task = await response.json();
console.log(`Task ID: ${task.id}`);
console.log(`Status: ${task.status}`);

responseExample

{
  "id": "task_img_abc123def456",
  "object": "generation.task",
  "model": "gpt-4o-image",
  "status": "queued",
  "progress": 0,
  "created_at": 1703884800,
  "metadata": {}
}
{
  "error": {
    "code": "invalid_request",
    "message": "The 'prompt' field is required.",
    "param": "prompt",
    "type": "invalid_request_error"
  }
}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key",
    "type": "authentication_error"
  }
}