输入文本，输出文本。Chat 是 xAI API 上最常用的功能，可用于总结文章、生成创意写作、回答问题、提供客户支持以及辅助编码任务等各种场景。

前置条件

在xAI Console API Keys 页面创建 API Key，并在环境中设置该 API Key：

export XAI_API_KEY="your_api_key"

基础聊天补全示例

你也可以流式传输响应，详情请参阅 Streaming Response。

用户向 xAI API 端点发送请求。API 处理请求并返回完整响应。

import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const result = await generateText({
  model: xai('grok-4.7'),
  system:
    "You are Grok, a helpful and useful AI built by SpaceXSI.",
  prompt: 'Explain how neural networks learn in two sentences.',
});

console.log(result.text);

import os
import httpx
from openai import OpenAI

client = OpenAI(
    api_key="<YOUR_XAI_API_KEY_HERE>",
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(3600.0), # Override default timeout with longer timeout for reasoning models
)

completion = client.chat.completions.create(
    model="grok-4.7",
    messages=[
        {"role": "system", "content": "You are a PhD-level mathematician."},
        {"role": "user", "content": "What is 2 + 2?"},
    ],
)

print(completion.choices[0].message)

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: "<api key>",
    baseURL: "https://api.x.ai/v1",
    timeout: 360000, // Override default timeout with longer timeout for reasoning models
});

const completion = await client.chat.completions.create({
    model: "grok-4.7",
    messages: [
        {
            role: "system",
            content: "You are Grok, a helpful and useful AI built by SpaceXSI."
        },
        {
            role: "user",
            content: "Explain how neural networks learn in two sentences."
        },
    ],
});

console.log(completion.choices[0].message);

curl https://api.x.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $XAI_API_KEY" \
-m 3600 \
-d '{
    "messages": [
        {
            "role": "system",
            "content": "You are Grok, a helpful and useful AI built by SpaceXSI."
        },
        {
            "role": "user",
            "content": "Explain how neural networks learn in two sentences."
        }
    ],
    "model": "grok-4.7",
    "stream": false
}'

import os

from xai_sdk import Client
from xai_sdk.chat import user, system

client = Client(
    api_key=os.getenv("XAI_API_KEY"),
    timeout=3600, # Override default timeout with longer timeout for reasoning models
)

chat = client.chat.create(model="grok-4.7")
chat.append(system("You are a PhD-level mathematician."))
chat.append(user("What is 2 + 2?"))

response = chat.sample()
print(response.content)

响应：

// result object structure
{
  text: "Neural networks learn by adjusting connection weights...",
  finishReason: "stop",
  usage: {
    inputTokens: 716,
    outputTokens: 126,
    totalTokens: 1009,
    reasoningTokens: 167
  },
  totalUsage: { /* same as usage */ }
}

ChatCompletionMessage(
  content='2 + 2 equals 4.',
  refusal=None,
  role='assistant',
  audio=None,
  function_call=None,
  tool_calls=None
)

{
  role: 'assistant',
  content: `Neural networks learn by adjusting connection weights to minimize prediction error. Through backpropagation, they propagate gradients backward through layers so each weight updates in the direction that improves accuracy on training data.`
  refusal: null
}

{
  "id": "0daf962f-a275-4a3c-839a-047854645532",
  "object": "chat.completion",
  "created": 1739301120,
  "model": "grok-4.7",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Neural networks learn by adjusting connection weights to minimize prediction error. Through backpropagation, they propagate gradients backward through layers so each weight updates in the direction that improves accuracy on training data.",
        "refusal": null
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 41,
    "completion_tokens": 104,
    "total_tokens": 145,
    "prompt_tokens_details": {
      "text_tokens": 41,
      "audio_tokens": 0,
      "image_tokens": 0,
      "cached_tokens": 0
    }
  },
  "system_fingerprint": "fp_84ff176447"
}

'2 + 2 equals 4.'

对话

xAI API 是无状态的，不会结合之前请求历史的上下文处理新请求。

不过，你可以在新的聊天生成请求中提供之前的提示词和结果，让模型结合这些上下文处理新请求。

示例消息：

{
  "role": "system",
  "content": [{ "type": "text", "text": "You are a helpful and funny assistant."}]
}
{
  "role": "user",
  "content": [{ "type": "text", "text": "Why don't eggs tell jokes?" }]
},
{
  "role": "assistant",
  "content": [{ "type": "text", "text": "They'd crack up!" }]
},
{
  "role": "user",
  "content": [{"type": "text", "text": "Can you explain the joke?"}],
}

通过指定角色，可以改变模型接收内容的方式。 system 角色的内容应以指令性语气定义模型响应用户请求的方式。 user 角色的内容通常用于用户请求或发送给模型的数据。 assistant 角色的内容通常来自模型响应；当它随提示词一起发送时，表示对话历史中的模型响应。

图像理解

部分模型允许在输入中使用图像。模型生成响应时会考虑图像上下文。

构造消息体：与纯文本提示词的区别

图像理解的请求消息与纯文本提示词类似。主要区别是，不再使用以下文本输入：

[
{
    "role": "user",
    "content": "What is in this image?"
}
]

而是将 content 作为对象列表发送：

[
{
    "role": "user",
    "content": [
{
    "type": "image_url",
    "image_url": {
    "url": "data:image/jpeg;base64,<base64_image_string>",
    "detail": "high"
}
},
{
    "type": "text",
    "text": "What is in this image?"
}
    ]
}
]

该 image_url.url也可以是互联网上的图像 URL。

图像理解示例

import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const result = await generateText({
model: xai('grok-4'),
messages: [
        {
            role: 'user',
            content: [
                {
                    type: 'image',
                    image: new URL(
                        'https://science.nasa.gov/wp-content/uploads/2023/09/web-first-images-release.png',
                    ),
                },
                {
                    type: 'text',
                    text: "What's in this image?",
                },
            ],
        },
    ],
});

console.log(result.text);

import os
from openai import OpenAI

XAI_API_KEY = os.getenv("XAI_API_KEY")
image_url = (
"https://science.nasa.gov/wp-content/uploads/2023/09/web-first-images-release.png"
)

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

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "image_url",
                "image_url": {
                    "url": image_url,
                    "detail": "high",
                },
            },
            {
                "type": "text",
                "text": "What's in this image?",
            },
        ],
    },
]

completion = client.chat.completions.create(
    model="grok-4",
    messages=messages,
)

print(completion.choices[0].message.content)

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

const image_url =
"https://science.nasa.gov/wp-content/uploads/2023/09/web-first-images-release.png";

const completion = await openai.chat.completions.create({
    model: "grok-4",
    messages: [
        {
            role: "user",
            content: [
                {
                    type: "image_url",
                    image_url: {
                        url: image_url,
                        detail: "high",
                    },
                },
                {
                    type: "text",
                    text: "What's in this image?",
                },
            ],
        },
    ],
});

console.log(completion.choices[0].message.content);

import os

from xai_sdk import Client
from xai_sdk.chat import user, image

client = Client(api_key=os.getenv('XAI_API_KEY'))

image_url = "https://science.nasa.gov/wp-content/uploads/2023/09/web-first-images-release.png"

chat = client.chat.create(model="grok-4")
chat.append(
    user(
        "What's in this image?",
        image(image_url=image_url, detail="high"),
    )
)

response = chat.sample()
print(response.content)

图像输入通用限制

最大图像大小：20MiB
最大图像数量：无限制
支持的图像文件类型：jpg/jpeg或png。
接受任意图像/文本输入顺序（例如，文本提示词可以位于图像提示词之前）

图像细节级别

该 "detail" 字段控制对提供给模型的图像应用的预处理级别。该字段为可选字段，并决定处理图像时使用的分辨率。"detail"的可选值为：

"auto"：系统会自动确定使用的图像分辨率。这是默认设置，会根据模型的判断在速度和细节之间取得平衡。
"low"：系统会处理图像的低分辨率版本。此选项速度更快、消耗的 token 更少，因此更具成本效益，但可能遗漏精细细节。
"high"：系统会处理图像的高分辨率版本。此选项速度较慢，token 成本更高，但可让模型关注图像中更细微的细节。

最后更新：2026 年 10 月 10 日

从写代码，到创作下一幕

Agent Plan & Coding Plan

Seedance 2.5

模型能力

聊天补全

前置条件

基础聊天补全示例

对话

图像理解

构造消息体：与纯文本提示词的区别

图像理解示例

图像输入通用限制

图像细节级别