GPT-4o Image Generation
Generate images using GPT-4o model, supporting text-to-image and image editing
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-imagemodel - 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
AuthorizationstringheaderrequiredAll endpoints require Bearer Token authentication
Get your API Key from the API Key Management Page
Add to request header:
Authorization: Bearer YOUR_API_KEYBody
modelstringbodyrequireddefault: gpt-4o-imageImage generation model name
Example: "gpt-4o-image"
promptstringbodyrequiredText description for image generation
Maximum 1000 characters
sizestringbodydefault: 1:1Image aspect ratio
Supported formats:
1:1- Square (default)2:3- Portrait3:2- Landscape
nintegerbodydefault: 1Number 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[]bodyReference 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_urlstringbodyMask image URL (for image editing)
- Must be PNG format
- Size must match the reference image
- Maximum 4MB
Response
idstringUnique task identifier for status queries
objectstringObject type, always generation.task
modelstringModel name used
statusstringTask status
queued- Queued for processingin_progress- Processingcompleted- Successfully completedfailed- Failed
progressintegerTask progress percentage (0-100)
created_atintegerTask creation timestamp (Unix timestamp)
metadataobjectTask 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"
}
}