Grok Image Generation
Generate images using Grok models, supporting text-to-image and reference-image generation
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
grok-imageorgrok-image-2.0model - Supports text-to-image and reference-image generation (up to 5 reference images)
- 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
modelstringbodyrequiredImage generation model name
Supported models:
grok-image- Standard Grok image generation modelgrok-image-2.0- Grok 2.0 image generation model, supports thequalityparameter
Example: "grok-image"
promptstringbodyrequiredText description for image generation
Maximum 1000 characters. When image_urls is provided, the prompt should explicitly describe how the reference images should be used (e.g., "generate an image based on the reference image"), otherwise the references may be ignored.
aspect_ratiostringbodydefault: 1:1Image aspect ratio
Supported formats:
1:1- Square (default)2:3- Portrait3:4- Portrait3:2- Landscape4:3- Landscape16:9- Widescreen landscape9:16- Widescreen portrait
resolutionstringbodydefault: 1kOutput resolution tier
Currently only 1k is supported (roughly 1 megapixel output).
qualitystringbodydefault: lowOutput quality tier. Only supported by grok-image-2.0
Supported values:
low- Low quality (default)medium- Medium quality
The two tiers are billed at different rates, see the Pricing page.
nintegerbodydefault: 1Number of images to generate
Currently only 1 is supported
Default: 1
⚠️ Note: Must enter a plain number (e.g., 1), do not use quotes or it will cause an error
response_formatstringbodydefault: urlResult delivery format. Only url is supported — results are returned as image URLs.
image_urlsstring[]bodyReference image URL list for reference-image generation
⚠️ 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
Each reference image is billed as an input image in addition to the per-request price.
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": "grok-image-2.0",
"prompt": "A cyberpunk futuristic city at night",
"aspect_ratio": "16:9",
"quality": "medium",
"n": 1
}'curl --request POST \
--url https://toapis.com/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "grok-image",
"prompt": "Generate an image based on the reference image, transforming it into watercolor painting style",
"aspect_ratio": "1:1",
"n": 1,
"image_urls": [
"https://example.com/photo.jpg"
]
}'import requests
response = requests.post(
"https://toapis.com/v1/images/generations",
headers={
"Authorization": "Bearer your-ToAPIs-key",
"Content-Type": "application/json"
},
json={
"model": "grok-image",
"prompt": "A cyberpunk futuristic city at night",
"aspect_ratio": "16:9",
"n": 1
}
)
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: 'grok-image',
prompt: 'A cyberpunk futuristic city at night',
aspect_ratio: '16:9',
n: 1
})
});
const task = await response.json();
console.log(`Task ID: ${task.id}`);
console.log(`Status: ${task.status}`);responseExample
{
"id": "tsk_img_abc123def456",
"object": "generation.task",
"model": "grok-image",
"status": "queued",
"progress": 0,
"created_at": 1768380224,
"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"
}
}