ToAPIsToAPIs
Grok Image

Grok 이미지 생성

Grok 모델로 이미지 생성, 텍스트-이미지 및 참조 이미지 생성 지원

POST
/v1/images/generations

중국 본토 사용자 안내: 중국 본토 사용자는 https://toapis.cn 를 API 엔드포인트(Base URL)로 사용해 주세요. 본 문서의 예시에서 https://toapis.com 을 https://toapis.cn 로 바꿔 주세요.

  • 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

Authorizationstring헤더필수

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

modelstring본문필수

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"

promptstring본문필수

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_ratiostring본문기본값: 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
resolutionstring본문기본값: 1k

Output resolution tier

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

qualitystring본문기본값: 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.

ninteger본문기본값: 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_formatstring본문기본값: url

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

image_urlsstring[]본문

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

요청 예시

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}`);

응답 예시

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