/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

dataarray<object>

A list of generated image objects.

Code Examples

**Response example:**

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
}

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

promptstring

Prompt for image editing.

Response Body

dataarray<object>

A list of generated image objects.

Code Examples

**Response example:**

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

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

The deferred request id returned by a previous image request.

Response Body

request_idstring

The polled request id.

statusstring

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

Code Examples

**Response example:**

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.

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

Code Examples

Image edit

Request Body

Response Body

Code Examples

Get deferred image results

Path Parameters

Response Body

Code Examples