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

Request Body

aspect_ratio ("1:1" | "3:4" | "4:3" | "9:16" | "16:9" | "2:3" | "3:2" | "9:19.5" | "19.5:9" | "9:20" | "20:9" | "1:2" | "2:1" | "auto")
model (string | null) — Model to be used.
n (integer | null) — Number of images to be generated
prompt (string) — Prompt for image generation.
resolution ("1k" | "2k")
response_format (string | null) — Response format to return the image in. Can be url or b64_json. If b64_json is specified, the image will be returned as a base64-encoded string instead of a url to the generated image file.
storage_options (object)
- expires_after (integer | null) — Seconds from now until the file auto-expires. Maximum 2592000 (30 days). If omitted, the file does not expire.
- filename (string, required) — Filename for the stored file.
- public_url (boolean | object)
user (string | null) — A unique identifier representing your end-user, which can help xAI to monitor and detect abuse.

Response Body

data (array<object>, required) — A list of generated image objects.
- b64_json (string | null) — A base64-encoded string representation of the generated image (without the data-URI prefix), if `b64_json` is specified as `response_format` in the request.
- file_output (object)
  - expires_at (integer | null) — Unix timestamp (seconds) when the stored file expires and will be automatically deleted. Only present when the file has an expiration.
  - file_id (string, required) — Files API file_id of the stored file.
  - filename (string, required) — Filename of the stored file.
  - public_url (string | null) — Public URL for the stored file. Only present when the request included `storage_options.public_url` and creation succeeded.
  - public_url_error (string | null) — Human-readable error when `storage_options.public_url` was set but public URL creation failed. The file was stored successfully.
  - public_url_expires_at (integer | null) — Unix timestamp (seconds) when the public URL expires. Present when the public URL has an expiry, either from an explicit `expires_after` in the request or inherited from the file's TTL.
- mime_type (string | null) — The MIME type of the generated image (e.g. `image/png`, `image/jpeg`, `image/webp`).
- storage_error (string | null) — Human-readable error when `storage_options` was set but the upload failed. Absent on success or when storage was not requested.
- url (string | null) — A url to the generated image, if `response_format` is not specified or with `url` in the request.
usage (object)
- cost_in_usd_ticks (integer, required) — The cost of this request expressed in USD ticks. One USD cent equals 100,000,000 ticks, so one US dollar equals 10,000,000,000 ticks.

Code Examples

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-quality",
    "prompt": "A collage of London landmarks in a stenciled street‑art style"
  }'

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-quality",
    prompt="A collage of London landmarks in a stenciled street‑art style",
)

print(response.model_dump_json(indent=2))

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-quality",
  prompt: "A collage of London landmarks in a stenciled street‑art style",
});

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

**Response example:**

{
  "data": [
    {
      "url": "..."
    },
    {
      "url": "..."
    }
  ]
}

POST /v1/images/edits

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

Request Body

aspect_ratio ("1:1" | "3:4" | "4:3" | "9:16" | "16:9" | "2:3" | "3:2" | "9:19.5" | "19.5:9" | "9:20" | "20:9" | "1:2" | "2:1" | "auto")
image (object)
- file_id (string | null) — File ID from the xAI Files API. Mutually exclusive with `url`. The file must be an image (JPEG, PNG, or WebP) and fully uploaded.
- url (string) — Public URL or base64-encoded data URL of the image (JPEG, PNG, or WebP). Also accepts `image_url` for compatibility. Required when `file_id` is not set.
images (array<object>) — List of input images for multi-reference editing. Mutually exclusive with `image`. When multiple images are provided, refer to them as \<IMAGE_0\>, \<IMAGE_1\>, etc. in the prompt.
- file_id (string | null) — File ID from the xAI Files API. Mutually exclusive with `url`. The file must be an image (JPEG, PNG, or WebP) and fully uploaded.
- url (string) — Public URL or base64-encoded data URL of the image (JPEG, PNG, or WebP). Also accepts `image_url` for compatibility. Required when `file_id` is not set.
model (string | null) — Model to be used.
n (integer | null) — Number of image edits to be generated.
prompt (string, required) — Prompt for image editing.
resolution ("1k" | "2k")
response_format (string | null) — Response format to return the image in. Can be `url` or `b64_json`. If `b64_json` is specified, the image will be returned as a base64-encoded string instead of a url to the generated image file.
storage_options (object)
- expires_after (integer | null) — Seconds from now until the file auto-expires. Maximum 2592000 (30 days). If omitted, the file does not expire.
- filename (string, required) — Filename for the stored file.
- public_url (boolean | object)
user (string | null) — A unique identifier representing your end-user, which can help xAI to monitor and detect abuse.

Response Body

data (array<object>, required) — A list of generated image objects.
- b64_json (string | null) — A base64-encoded string representation of the generated image (without the data-URI prefix), if `b64_json` is specified as `response_format` in the request.
- file_output (object)
  - expires_at (integer | null) — Unix timestamp (seconds) when the stored file expires and will be automatically deleted. Only present when the file has an expiration.
  - file_id (string, required) — Files API file_id of the stored file.
  - filename (string, required) — Filename of the stored file.
  - public_url (string | null) — Public URL for the stored file. Only present when the request included `storage_options.public_url` and creation succeeded.
  - public_url_error (string | null) — Human-readable error when `storage_options.public_url` was set but public URL creation failed. The file was stored successfully.
  - public_url_expires_at (integer | null) — Unix timestamp (seconds) when the public URL expires. Present when the public URL has an expiry, either from an explicit `expires_after` in the request or inherited from the file's TTL.
- mime_type (string | null) — The MIME type of the generated image (e.g. `image/png`, `image/jpeg`, `image/webp`).
- storage_error (string | null) — Human-readable error when `storage_options` was set but the upload failed. Absent on success or when storage was not requested.
- url (string | null) — A url to the generated image, if `response_format` is not specified or with `url` in the request.
usage (object)
- cost_in_usd_ticks (integer, required) — The cost of this request expressed in USD ticks. One USD cent equals 100,000,000 ticks, so one US dollar equals 10,000,000,000 ticks.

Code Examples

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-quality",
    "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-quality",
    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-quality",
        "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))

**Response example:**

{
  "data": [
    {
      "url": "..."
    }
  ]
}

Inference API

Images

POST /v1/images/generations

Request Body

Response Body

Code Examples

POST /v1/images/edits

Request Body

Response Body

Code Examples