使用 Grok Imagine 模型根据文本 prompt 生成图像。API 支持批量生成多张图像，并可控制宽高比、分辨率和质量。

快速开始

通过一次 API 调用生成图像：

import { xai } from "@ai-sdk/xai";
import { generateImage } from "ai";

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

console.log(image.base64);

from openai import OpenAI

client = OpenAI(
    base_url="https://api.x.ai/v1",
    api_key="YOUR_API_KEY",
)

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

print(response.data[0].url)

curl -X POST 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(response.data[0].url);

import xai_sdk

client = xai_sdk.Client()

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

print(response.url)

图像默认以 URL 形式返回。URL 是临时的，因此请及时下载或处理。你也可以请求 base64 输出，以便直接嵌入图像。

配置

多张图像

通过 n 参数（1–10）在单次请求中生成多张图像。在 REST API 和兼容 OpenAI 的 SDK 中，n 为可选参数，默认值为 1。xAI Python SDK 使用 sample() 生成单张图像，使用 sample_batch(n=...) 生成多张图像——n 必须提供给 sample_batch()。

import { xai } from "@ai-sdk/xai";
import { generateImage } from "ai";

const { images } = await generateImage({
    model: xai.image("grok-imagine-image-2.0"),
    prompt: "A futuristic city skyline at night",
    n: 4,
});

images.forEach((image, i) => {
    console.log(`Variation ${i + 1}: ${image.base64.slice(0, 50)}...`);
});

from openai import OpenAI

client = OpenAI(
    base_url="https://api.x.ai/v1",
    api_key="YOUR_API_KEY",
)

response = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="A futuristic city skyline at night",
    n=4,
)

for i, image in enumerate(response.data):
    print(f"Variation {i + 1}: {image.url}")

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 futuristic city skyline at night",
    n: 4,
});

response.data.forEach((image, i) => {
    console.log(`Variation ${i + 1}: ${image.url}`);
});

curl -X POST 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 futuristic city skyline at night",
    "n": 4
  }'

import xai_sdk

client = xai_sdk.Client()

responses = client.image.sample_batch(
    prompt="A futuristic city skyline at night",
    model="grok-imagine-image-2.0",
    n=4,
)

for i, image in enumerate(responses):
    print(f"Variation {i + 1}: {image.url}")

宽高比

使用 aspect_ratio 参数。省略时默认为 auto，由模型根据 prompt 选择最佳宽高比。

比例	用例
`1:1`	社交媒体、缩略图
`16:9` / `9:16`	宽屏、移动端、故事
`4:3` / `3:4`	演示文稿、人像
`3:2` / `2:3`	摄影
`2:1` / `1:2`	横幅、页眉
`19.5:9` / `9:19.5`	现代智能手机屏幕（iPhone）
`20:9` / `9:20`	现代智能手机屏幕（Android）
`21:9`	电影宽银幕
`5:2`	宽幅横幅
`auto`	模型自动为提示词选择最佳比例

import { xai } from "@ai-sdk/xai";
import { generateImage } from "ai";

const { image } = await generateImage({
    model: xai.image("grok-imagine-image-2.0"),
    prompt: "Mountain landscape at sunrise",
    aspectRatio: "16:9",
});

console.log(image.base64);

from openai import OpenAI

client = OpenAI(
    base_url="https://api.x.ai/v1",
    api_key="YOUR_API_KEY",
)

response = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="Mountain landscape at sunrise",
    extra_body={"aspect_ratio": "16:9"},
)

print(response.data[0].url)

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: "Mountain landscape at sunrise",

    aspect_ratio: "16:9",
});

console.log(response.data[0].url);

curl -X POST 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": "Mountain landscape at sunrise",
    "aspect_ratio": "16:9"
  }'

import xai_sdk

client = xai_sdk.Client()

response = client.image.sample(
    prompt="Mountain landscape at sunrise",
    model="grok-imagine-image-2.0",
    aspect_ratio="16:9",
)

print(response.url)

分辨率

你可以通过 resolution 参数指定输出图像的分辨率。目前支持的图像分辨率包括：

1k（省略时的默认值）
2k

import { xai } from "@ai-sdk/xai";
import { generateImage } from "ai";

const { image } = await generateImage({
    model: xai.image("grok-imagine-image-2.0"),
    prompt: "An astronaut performing EVA in LEO.",
    providerOptions: {
        xai: { resolution: "2k" },
    },
});

console.log(image.base64);

from openai import OpenAI

client = OpenAI(
    base_url="https://api.x.ai/v1",
    api_key="YOUR_API_KEY",
)

response = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="An astronaut performing EVA in LEO.",
    extra_body={"resolution": "2k"},
)

print(response.data[0].url)

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: "An astronaut performing EVA in LEO.",

    resolution: "2k",
});

console.log(response.data[0].url);

curl -X POST 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": "An astronaut performing EVA in LEO.",
    "resolution": "2k"
}'

import xai_sdk

client = xai_sdk.Client()

response = client.image.sample(
    prompt="An astronaut performing EVA in LEO.",
    model="grok-imagine-image-2.0",
    resolution="2k"
)

print(response.url)

使用可选的 quality 参数控制生成质量。允许的值为 low、medium 和 auto。省略时默认值为 auto，由服务为每次请求选择质量。目前 Auto 使用 low 生成图像，并使用 medium 进行图像编辑。图像按实际提供的质量计费（参阅价格）。传入 low 或 medium 可固定使用特定质量。该参数仅支持 grok-imagine-image-2.0。

curl -X POST 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 watercolor painting of a lighthouse at dawn",
    "quality": "low"
  }'

import xai_sdk

client = xai_sdk.Client()

response = client.image.sample(
    prompt="A watercolor painting of a lighthouse at dawn",
    model="grok-imagine-image-2.0",
    quality="low",
)

print(response.url)

base64 输出

使用以下参数控制输出格式：response_format 参数。省略时默认为 url，返回临时托管 URL。如需直接嵌入图像而无需下载，请请求 base64：

import { xai } from "@ai-sdk/xai";
import { generateImage } from "ai";
import fs from "fs";

const { image } = await generateImage({
    model: xai.image("grok-imagine-image-2.0"),
    prompt: "A serene Japanese garden",
});

// Save to file (AI SDK returns base64 by default)
const imageBuffer = Buffer.from(image.base64, "base64");
fs.writeFileSync("garden.jpg", imageBuffer);

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://api.x.ai/v1",
    api_key="YOUR_API_KEY",
)

response = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="A serene Japanese garden",
    response_format="b64_json",
)

# Save to file
image_bytes = base64.b64decode(response.data[0].b64_json)
with open("garden.jpg", "wb") as f:
    f.write(image_bytes)

import OpenAI from "openai";
import fs from "fs";

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 serene Japanese garden",
    response_format: "b64_json",
});

// Save to file
const imageBuffer = Buffer.from(response.data[0].b64_json, "base64");
fs.writeFileSync("garden.jpg", imageBuffer);

curl -X POST 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 serene Japanese garden",
    "response_format": "b64_json"
  }'

import xai_sdk

client = xai_sdk.Client()

response = client.image.sample(
    prompt="A serene Japanese garden",
    model="grok-imagine-image-2.0",
    image_format="base64",
)

# Save to file
with open("garden.jpg", "wb") as f:
    f.write(response.image)

延迟生成

图像生成通常在单次请求内完成。对于耗时较长的批次，或希望避免长时间保持连接时，可以设置 deferred: true，适用端点为 /v1/images/generations 或 /v1/images/edits。请求会立即返回 request_id；随后轮询 GET /v1/images/{request_id} 以获取结果。延迟请求仅支持 response_format: "url"（默认值）。结果与延迟聊天补全的结果一同存储，保留 24 小时。

轮询响应中包含 status：

pending（HTTP 202）：仍在生成
done（HTTP 200）：data 和 usage 已填充，结构与同步响应一致
failed（HTTP 200）：error 包含一个 code 和 message

import os
import time
import requests

headers = {
    "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
    "Content-Type": "application/json",
}

# Step 1: Start generation
response = requests.post(
    "https://api.x.ai/v1/images/generations",
    headers=headers,
    json={
        "model": "grok-imagine-image-2.0",
        "prompt": "A serene Japanese garden",
        "deferred": True,
    },
)
request_id = response.json()["request_id"]

# Step 2: Poll for the result
while True:
    result = requests.get(
        f"https://api.x.ai/v1/images/{request_id}",
        headers={"Authorization": headers["Authorization"]},
    )
    data = result.json()

    if data["status"] == "done":
        print(f"Image URL: {data['data'][0]['url']}")
        break
    elif data["status"] == "failed":
        print(f"Generation failed: {data['error']['message']}")
        break
    else:
        print("Still processing...")
        time.sleep(5)

# Step 1: Start generation
curl -X POST 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 serene Japanese garden",
    "deferred": true
  }'
# => {"request_id": "..."}

# Step 2: Poll for the result
curl https://api.x.ai/v1/images/<request_id> \
  -H "Authorization: Bearer $XAI_API_KEY"
# => 202 {"request_id": "...", "status": "pending"}
# => 200 {"request_id": "...", "status": "done", "data": [{"url": "...", "mime_type": "image/jpeg"}], "usage": {...}}

也可以注册 webhook 来接收 image.generation.completed、image.generation.failed、image.edit.completed 和 image.edit.failed 事件，无需轮询。

响应详情

除图像 URL 或 Base64 数据外，xAI SDK 还会在响应对象上提供额外元数据。

内容审核：检查生成的图像是否通过内容审核：

if response.respect_moderation:
    print(response.url)
else:
    print("Image filtered by moderation")

模型：获取实际使用的模型（解析所有别名）：

print(f"Model: {response.model}")

并发请求

当你需要使用不同的提示词，例如并行生成互不相关的图像时，请使用 AsyncClient 搭配 asyncio.gather 并发发起请求。这比逐一发起请求快得多。

import asyncio
import xai_sdk

async def generate_concurrently():
    client = xai_sdk.AsyncClient()

    # Each request uses a different prompt
    prompts = [
        "A futuristic city skyline at sunset",
        "A serene Japanese garden in winter",
        "An astronaut floating above Earth",
        "A medieval castle on a misty mountain",
    ]

    # Fire all requests concurrently
    tasks = [
        client.image.sample(
            prompt=prompt,
            model="grok-imagine-image-2.0",
        )
        for prompt in prompts
    ]

    results = await asyncio.gather(*tasks)

    for prompt, result in zip(prompts, results):
        print(f"{prompt}: {result.url}")

asyncio.run(generate_concurrently())

模型：可用的图像模型
图像编辑：使用自然语言编辑图像
图像提示词指南：编写提示词，使主体保持可辨识
图像生成工具：让 Grok 在对话中生成和编辑图像
视频生成：根据文本提示词生成视频
API 参考：完整的端点文档
Imagine API 主页：展示 Imagine API 的实际效果

最后更新：2026 年 10 月 8 日

从写代码，到创作下一幕

Agent Plan & Coding Plan

Seedance 2.5

模型能力

图像生成

快速开始

配置

多张图像

宽高比

分辨率

质量

base64 输出

延迟生成

响应详情

并发请求