ToAPIsToAPIs
Grok Image

Grok Image Generation

Generate images using Grok models, supporting text-to-image and reference-image generation

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 grok-image or grok-image-2.0 model
  • 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

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

modelstringbodyrequired

Image generation model name

Supported models:

  • grok-image - Standard Grok image generation model
  • grok-image-2.0 - Grok 2.0 image generation model, supports the quality parameter

Example: "grok-image"

promptstringbodyrequired

Text 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:1

Image aspect ratio

Supported formats:

  • 1:1 - Square (default)
  • 2:3 - Portrait
  • 3:4 - Portrait
  • 3:2 - Landscape
  • 4:3 - Landscape
  • 16:9 - Widescreen landscape
  • 9:16 - Widescreen portrait
resolutionstringbodydefault: 1k

Output resolution tier

Currently only 1k is supported (roughly 1 megapixel output).

qualitystringbodydefault: low

Output 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: 1

Number 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: url

Result delivery format. Only url is supported — results are returned as image URLs.

image_urlsstring[]body

Reference 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

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": "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"
  }
}