xAI 文档

外观

关键信息 ​

成本追踪 ​

来自 xAI API 的每个推理响应都包含该请求的确切费用，通过聊天完成、Responses API、图像生成和视频生成响应中的 usage 对象内的 cost_in_usd_ticks 字段返回。

成本是按请求计算的：每个调用返回该单个请求的费用，无论是简单的完成、流式响应，还是使用服务器端工具的代理循环。这是应用所有适用折扣（包括 提示缓存 减少）后的实际计费金额，并包含所有 token 成本和服务器端工具调用成本。无需估算或事后账单查询。

工作原理 ​

成本以 ticks 表示，其中 1 美元 = 10,000,000,000 ticks (10^10)。转换为美元：

text
cost_usd = cost_in_usd_ticks / 10,000,000,000

例如，"cost_in_usd_ticks": 37756000 的响应成本为 $0.0038。"cost_in_usd_ticks": 200000000 的图像生成成本为 $0.02。

Ticks 的存在是为了精确性：它们表示到美分以下的小数部分成本，没有浮点数舍入，当您处理数千个请求且需要总金额累加准确时，这一点很重要。

从响应中读取成本 ​

xAI SDK ​

xAI SDK 提供了一个 cost_usd 便捷属性，可以自动将 ticks 转换为美元。如果您需要整数精度，也可以通过 response.usage.cost_in_usd_ticks 访问原始 ticks：

python
import os
from xai_sdk import Client
from xai_sdk.chat import user

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

chat = client.chat.create(
    model="grok-4.5",
    messages=[user("Say hello")],
)
response = chat.sample()

# Convenience property — ticks converted to dollars.
print(f"Cost: ${response.cost_usd:.6f}")

# Raw ticks for integer-precision accounting.
print(f"Cost (ticks): {response.usage.cost_in_usd_ticks}")

聊天完成和 Responses API ​

每个 REST 完成和响应中的 usage 对象都包含 cost_in_usd_ticks：

json
"usage": {
    "input_tokens": 199,
    "output_tokens": 1,
    "total_tokens": 200,
    "cost_in_usd_ticks": 158500
}
bash
curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "input": "Say hello"
  }' | jq '.usage.cost_in_usd_ticks'
python
import os
from openai import OpenAI

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

completion = client.chat.completions.create(
    model="grok-4.5",
    messages=[{"role": "user", "content": "Say hello"}],
)

# cost_in_usd_ticks is available directly on the usage object.
cost_ticks = completion.usage.cost_in_usd_ticks
cost_usd = cost_ticks / 1e10
print(f"Cost: ${cost_usd:.6f}")
javascript
import OpenAI from "openai";

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

const completion = await client.chat.completions.create({
  model: "grok-4.5",
  messages: [{ role: "user", content: "Say hello" }],
});

const costTicks = completion.usage.cost_in_usd_ticks;
const costUsd = costTicks / 1e10;
console.log(`Cost: ${costUsd.toFixed(6)}`);

NOTE

Vercel AI SDK (@ai-sdk/xai) 目前在其响应元数据中不显示 cost_in_usd_ticks。要访问它，请使用 OpenAI SDK 或直接使用原始 REST API。

流式响应 ​

当使用 xAI SDK 进行流式响应时，每个块都携带一个运行中的 cost_in_usd_ticks 总计；最后一个块反映请求的最终成本。组装的 Response 对象会自动携带此信息。

当使用 OpenAI SDK 或 REST API 时，在请求中设置 stream_options: { include_usage: true }。成本仅包含在最后一个块（空的 choices）中；中间块不包含使用数据。

python
import os
from xai_sdk import Client
from xai_sdk.chat import user

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

chat = client.chat.create(
    model="grok-4.5",
    messages=[user("Tell me a joke")],
)

for response, chunk in chat.stream():
    print(chunk.content, end="", flush=True)
print()

# After the stream completes, cost is on the final response.
print(f"Cost: ${response.cost_usd:.6f}")
python
import os
from openai import OpenAI

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

stream = client.chat.completions.create(
    model="grok-4.5",
    messages=[{"role": "user", "content": "Tell me a joke"}],
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.usage:
        cost_ticks = chunk.usage.cost_in_usd_ticks
        print(f"\nCost: ${cost_ticks / 1e10:.6f}")
    elif chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)

跨对话追踪成本 ​

cost_in_usd_ticks 是按请求计算的；它不会在多个轮次中累积。在多轮对话中，需要您自己累加成本：

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

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

chat = client.chat.create(
    model="grok-4.5",
    messages=[system("You are a helpful assistant.")],
)

total_cost_usd = 0.0
while True:
    prompt = input("You: ")
    if prompt.lower() == "exit":
        break

    chat.append(user(prompt))
    response = chat.sample()
    print(f"Grok: {response.content}")
    chat.append(response)

    total_cost_usd += response.cost_usd or 0.0
    print(f"  (this turn: ${response.cost_usd or 0:.6f})")

print(f"Total session cost: ${total_cost_usd:.4f}")
python
import os
from openai import OpenAI

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

messages = [{"role": "system", "content": "You are a helpful assistant."}]
total_cost_usd = 0.0

while True:
    prompt = input("You: ")
    if prompt.lower() == "exit":
        break

    messages.append({"role": "user", "content": prompt})
    completion = client.chat.completions.create(
        model="grok-4.5",
        messages=messages,
    )

    reply = completion.choices[0].message.content
    print(f"Grok: {reply}")
    messages.append({"role": "assistant", "content": reply})

    cost_ticks = completion.usage.cost_in_usd_ticks
    cost_usd = cost_ticks / 1e10
    total_cost_usd += cost_usd
    print(f"  (this turn: ${cost_usd:.6f})")

print(f"Total session cost: ${total_cost_usd:.4f}")

服务器端工具 ​

当请求使用服务器端工具（网络搜索、X 搜索、代码执行）时，模型在返回最终答案之前可能会进行多次内部调用。返回的 cost_in_usd_ticks 以单个值涵盖该请求中的所有 token 成本和所有工具调用。无需单独累加。

python
import os
from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import web_search, x_search

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

chat = client.chat.create(
    model="grok-4.5",
    tools=[web_search(), x_search()],
)
chat.append(user("What are people saying about xAI's latest announcement?"))

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

# Shows which server-side tools were invoked and how many times.
print(f"Tools used: {response.server_side_tool_usage}")
# Cost covers all model decodes + every tool call in the agentic loop.
print(f"Cost: ${response.cost_usd:.4f}")
python
import os
from openai import OpenAI

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

response = client.responses.create(
    model="grok-4.5",
    input="What are people saying about xAI's latest announcement?",
    tools=[
        {"type": "web_search"},
        {"type": "x_search"},
    ],
)

print(response.output_text)

# Cost covers all model decodes + every tool call in the agentic loop.
cost_ticks = response.usage.cost_in_usd_ticks
print(f"Cost: ${cost_ticks / 1e10:.4f}")
bash
curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "tools": [{"type": "web_search"}, {"type": "x_search"}],
    "input": "What are people saying about xAI'\''s latest announcement?"
  }' | jq '{tools_used: .usage.num_server_side_tools_used, cost_in_usd_ticks: .usage.cost_in_usd_ticks}'

图像和视频生成 ​

图像和视频响应在其 usage 对象中包含相同的 cost_in_usd_ticks 字段：

bash
# Image generation
curl https://api.x.ai/v1/images/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-quality",
    "prompt": "A cat on a rocket"
  }' | jq '.usage.cost_in_usd_ticks'
# => 200000000 ($0.02)
python
import os
from xai_sdk import Client

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

# Image generation
image = client.image.sample(
    model="grok-imagine-image-quality",
    prompt="A cat on a rocket",
)
print(f"Image cost: ${image.cost_usd:.4f}")

# Video generation
video = client.video.generate(
    model="grok-imagine-video-1.5",
    prompt="A cat floating in space",
)
print(f"Video cost: ${video.cost_usd:.4f}")
python
import os
from openai import OpenAI

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

response = client.images.generate(
    model="grok-imagine-image-quality",
    prompt="A cat on a rocket",
)

cost_ticks = response.usage.cost_in_usd_ticks
print(f"Image cost: ${cost_ticks / 1e10:.4f}")

Batch API ​

Batch 结果包含每项请求的成本。您可以将它们相加以获得总批次成本，或者读取批次对象本身的 cost_breakdown。有关详细信息，请参阅 Batch API。

本文档为 docs.x.ai 全站中文翻译，由 AI 自动翻译生成。代码示例请以原文为准。

xAI 文档中文版 · 仅供学习参考