模型能力

图像生成

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

快速开始

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

python

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

print(response.url)

bash

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

python

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

print(response.data[0].url)

javascript

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

javascript

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

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

console.log(image.base64);

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

配置

多张图像

使用 sample_batch() 方法和 n 参数在一次请求中生成多张图像。这将返回一个 ImageResponse 对象列表。

python

import xai_sdk

client = xai_sdk.Client()

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

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

python

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-quality",
    prompt="A futuristic city skyline at night",
    n=4,
)

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

javascript

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

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

javascript

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

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

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

bash

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-quality",
    "prompt": "A futuristic city skyline at night",
    "n": 4
  }'

宽高比

使用 aspect_ratio 参数控制图像尺寸。这适用于单张和多张图像的生成和编辑。对于单张图像的编辑，输出宽高比会遵循输入图像的宽高比。

Ratio	Use case
`1:1`	社交媒体、缩略图
`16:9` / `9:16`	宽屏、移动设备、故事
`4:3` / `3:4`	演示文稿、肖像
`3:2` / `2:3`	摄影
`2:1` / `1:2`	横幅、页眉
`19.5:9` / `9:19.5`	现代智能手机显示屏
`20:9` / `9:20`	超宽显示屏
`auto`	模型自动选择最适合提示的宽高比

python

import xai_sdk

client = xai_sdk.Client()

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

print(response.url)

python

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-quality",
    prompt="Mountain landscape at sunrise",
    extra_body={"aspect_ratio": "16:9"},
)

print(response.data[0].url)

javascript

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

    aspect_ratio: "16:9",
});

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

javascript

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

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

console.log(image.base64);

bash

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

分辨率

您可以指定输出图像的不同分辨率。当前支持的图像分辨率有：

python

import xai_sdk

client = xai_sdk.Client()

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

print(response.url)

python

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-quality",
    prompt="An astronaut performing EVA in LEO.",
    extra_body={"resolution": "2k"},
)

print(response.data[0].url)

javascript

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

    resolution: "2k",
});

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

javascript

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

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

console.log(image.base64);

bash

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

Base64 输出

为了在不下载的情况下直接嵌入图像，请求 base64：

python

import xai_sdk

client = xai_sdk.Client()

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

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

python

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

javascript

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

javascript

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

const { image } = await generateImage({
    model: xai.image("grok-imagine-image-quality"),
    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);

bash

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-quality",
    "prompt": "A serene Japanese garden",
    "response_format": "b64_json"
  }'

响应详情

xAI SDK 在响应对象上暴露了除图像 URL 或 base64 数据之外的附加元数据。

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

python

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

模型 — 获取实际使用的模型（解析任何别名）：

python

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

并发请求

当您需要使用不同的提示生成多张图像时，例如并行生成不相关的图像，请使用 AsyncClient 和 asyncio.gather 来并发发送请求。这比一次一个地发送请求要快得多。

TIP

如果您想从同一个提示获得多个变体，请改用 sample_batch() 和 n 参数`。这会在单个请求中生成所有图像，是同提示生成最有效的方法。

python

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

模型能力 ​

图像生成 ​

快速开始 ​

配置 ​

多张图像 ​

宽高比 ​

分辨率 ​

Base64 输出 ​

响应详情 ​

并发请求 ​

相关 ​

模型能力

图像生成

快速开始

配置

多张图像

宽高比

分辨率

Base64 输出

响应详情

并发请求

相关