/v1/images/generations

Generate an image based on a prompt. This is the endpoint for making generation requests to image generation models.

Request Body

Response Body

data

array

A list of generated image objects.

POST

/v1/images/generations

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XAI_API_KEY"],
    base_url="https://api.x.ai/v1",
)

response = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="A collage of London landmarks in a stenciled street‑art style",
)

print(response.model_dump_json(indent=2))

curl -s https://api.x.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "A collage of London landmarks in a stenciled street‑art style"
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: "https://api.x.ai/v1",
});

const response = await client.images.generate({
  model: "grok-imagine-image-2.0",
  prompt: "A collage of London landmarks in a stenciled street‑art style",
});

console.log(JSON.stringify(response, null, 2));

{
  "prompt": "A cat in a tree",
  "model": "grok-imagine-image",
  "response_format": "url",
  "n": 2
}

Output

JSON

{
  "created": null,
  "background": null,
  "data": [
    {
      "b64_json": null,
      "revised_prompt": "",
      "url": "https://imgen.x.ai/xai-imgen/xai-tmp-imgen-e721d078-dd94-4440-8b25-9836f1eb5afa.jpeg",
      "mime_type": "image/jpeg"
    }
  ],
  "output_format": null,
  "quality": null,
  "size": null,
  "usage": {
    "input_tokens": null,
    "input_tokens_details": null,
    "output_tokens": null,
    "total_tokens": null,
    "cost_in_usd_ticks": 200000000
  }
}

Image edit

/v1/images/edits

Edit an image based on a prompt. This is the endpoint for making edit requests to image generation models.

Request Body

prompt

string

required

Prompt for image editing.

Response Body

data

array

A list of generated image objects.

POST

/v1/images/edits

curl -s https://api.x.ai/v1/images/edits \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "Render this as a pencil sketch with detailed shading",
    "image": {
      "url": "https://docs.x.ai/assets/api-examples/images/style-realistic.png",
      "type": "image_url"
    }
  }'

const response = await fetch("https://api.x.ai/v1/images/edits", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.XAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "grok-imagine-image-2.0",
    prompt: "Render this as a pencil sketch with detailed shading",
    image: {
      url: "https://docs.x.ai/assets/api-examples/images/style-realistic.png",
      type: "image_url",
    },
  }),
});

console.log(JSON.stringify(await response.json(), null, 2));

import json
import os

import requests

response = requests.post(
    "https://api.x.ai/v1/images/edits",
    headers={
        "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "grok-imagine-image-2.0",
        "prompt": "Render this as a pencil sketch with detailed shading",
        "image": {
            "url": "https://docs.x.ai/assets/api-examples/images/style-realistic.png",
            "type": "image_url",
        },
    },
)

print(json.dumps(response.json(), indent=2))

{
  "prompt": "Add a hat to this cat.",
  "image": {
    "url": "..."
  },
  "model": "grok-imagine-image"
}

Output

JSON

{
  "data": [
    {
      "url": "https://imgen.x.ai/xai-imgen/xai-tmp-imgen-82f06097-a9ad-4db4-9c8d-8197c74eebd1.jpeg",
      "mime_type": "image/jpeg",
      "revised_prompt": ""
    }
  ],
  "usage": {
    "cost_in_usd_ticks": 220000000
  }
}

Get deferred image results

/v1/images/{request_id}

GET /v1/images/{request_id}: 202 while pending, 200 with data when done or with error when failed (a failed generation is a body, not an HTTP error, so pollers do not retry-storm).

Path parameters

request_id

string

required

The deferred request id returned by a previous image request.

Response Body

request_id

string

The polled request id.

status

string

"pending", "done" or "failed".

GET

/v1/images/{request_id}

curl -s "https://api.x.ai/v1/images/$IMAGE_REQUEST_ID" \
  -H "Authorization: Bearer $XAI_API_KEY"

const response = await fetch(
  `https://api.x.ai/v1/images/${process.env.IMAGE_REQUEST_ID}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.XAI_API_KEY}`,
    },
  },
);

console.log(JSON.stringify(await response.json(), null, 2));

import json
import os

import requests

request_id = os.environ["IMAGE_REQUEST_ID"]

response = requests.get(
    f"https://api.x.ai/v1/images/{request_id}",
    headers={
        "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
    },
)

print(json.dumps(response.json(), indent=2))

No parameters.

Output

JSON

{
  "request_id": "572d62a8-c2ae-47f6-9c60-21ed08bdcd30",
  "status": "done",
  "data": [
    {
      "url": "https://imgen.x.ai/xai-imgen/xai-tmp-imgen-572d62a8-c2ae-47f6-9c60-21ed08bdcd30-4ba414e5.jpeg",
      "mime_type": "image/jpeg"
    }
  ],
  "usage": {
    "cost_in_usd_ticks": 200000000
  }
}

Last updated: October 2, 2026

Inference API

Images

Image generation

Request Body

Response Body

Image edit

Request Body

Response Body

Get deferred image results

Path parameters

Response Body