# @apicity/xai 中文文档

规范地址：https://npmcn.com/package/%40apicity/xai/

版本：0\.26\.0
npm 元数据更新时间：2026-11-04T19:41:46.152Z
中文译文更新时间：2026-11-06T10:11:34.597Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40apicity/xai
原文对照：https://npmcn.com/package/%40apicity/xai/?lang=original
项目主页：https://github.com/justintanner/apicity#readme
源码仓库：https://github.com/justintanner/apicity

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：487 kB，55 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：2 个
- 首次发布：2026-05-11T02:17:38.390Z
- 最新版本发布：2026-11-04T19:41:45.973Z
- 近 30 天下载量：4050（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：89（近 12 个月 89 个）

## 中文简介

X.AI / Grok 提供商进行聊天和搜索.

## 安装

```sh
npm install @apicity/xai
```

也可以使用：`pnpm add @apicity/xai`、`yarn add @apicity/xai`、`bun add @apicity/xai`

## README

# @apicity/xai (英语)

[![npm](https://img.shields.io/npm/v/@apicity/xai?color=cb0000)](https://www.npmjs.com/package/@apicity/xai) [![dependencies](https://img.shields.io/badge/dependencies-2-blue)](https://npmcn.com/package/%40apicity/xai/package.json) [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue?logo=typescript&logoColor=white)](https://npmcn.com/package/%40apicity/xai/tsconfig.json)

X.AI / Grok 提供商进行聊天和搜索.

运行时间依赖性 :

-   `ws@^8.21.0` ——认证服务器 WebSocket 运出自 `@apicity/xai/realtime`
-   `zod@^4.6.6` - 请求在每一个 POST 端点上附加计划 `.schema`

## 安装

```bash
npm install @apicity/xai
# or
pnpm add @apicity/xai
```

## 快速启动

```typescript
import { createXai } from "@apicity/xai";

const xai = createXai({ apiKey: process.env.XAI_API_KEY! });
```

## 现实世界的例子:与Grok-4进行结构化的远景分析

手Grok -4 一张肖像, 系统提示 钉下输出计划, 财务报告和审定财务报表 `text.format.type: "json_object"` - 准备复制 JSON描述带有决定性的射击/有词汇. 以下流量 逐字记录 [`tests/integration/xai-vision-json.test.ts`](https://npmcn.com/tests/integration/xai-vision-json.test.ts) 并重玩对 [`tests/recordings/xai_3613880225/vision-analysis-json_243984103/recording.har`](https://npmcn.com/tests/recordings/xai_3613880225/vision-analysis-json_243984103/recording.har), (中文(简体) ), 因此反应形状符合xAI实际返回的内容.

```typescript
import { readFile } from "node:fs/promises";
import { createXai } from "@apicity/xai";

const xai = createXai({ apiKey: process.env.XAI_API_KEY! });

// 1. Load the image and inline it as a data URL. xAI also accepts
//    https:// URLs, but inlining keeps the call self-contained and
//    works against private hosts.
const image = await readFile("./portrait.jpg");
const base64 = image.toString("base64");

// 2. The system prompt enumerates the legal vocabulary for `shot` and
//    constrains `pose` to body geometry only. Combined with
//    `text.format.type: "json_object"` this gives Grok no room to drift
//    off-schema — temperature 0 keeps the result reproducible.
const SYSTEM_PROMPT = [
  "You are an expert image-to-prompt analyst.",
  "Return only a JSON object with keys prompt, shot, and pose.",
  "prompt: a single-paragraph reproduction-ready image prompt, 1900 characters or fewer, with no line breaks.",
  'shot: exactly "<size>, <angle>" where size is one of extreme close-up, close-up, medium close-up, medium shot, medium long shot, long shot, or extreme long shot, and angle is one of eye-level, low-angle, high-angle, overhead, or dutch.',
  "pose: only body geometry for human figures, with no clothing, hair, background, or lighting details.",
].join(" ");

// 3. Multimodal Responses request: system turn + a user turn whose
//    content is an array of `input_image` + `input_text` parts.
const result = await xai.post.v1.responses({
  model: "grok-4",
  input: [
    { role: "system", content: SYSTEM_PROMPT },
    {
      role: "user",
      content: [
        {
          type: "input_image",
          image_url: `data:image/jpeg;base64,${base64}`,
          detail: "high",
        },
        {
          type: "input_text",
          text: 'Analyze this image and produce a reproduction-ready JSON description with keys "prompt", "shot", and "pose".',
        },
      ],
    },
  ],
  text: { format: { type: "json_object" } },
  store: false,
  temperature: 0,
  max_output_tokens: 300,
});

// 4. The Responses API wraps output in a typed item array. Find the
//    assistant message, then the first `output_text` part inside it.
//    Discriminated unions narrow `item.type === "message"` so
//    `item.content` is statically typed.
const message = result.output.find((item) => item.type === "message");
const outputText =
  message?.type === "message"
    ? message.content.find((part) => part.type === "output_text")?.text
    : undefined;

if (!outputText) throw new Error("Grok did not return output_text");

const analysis = JSON.parse(outputText) as {
  prompt: string;
  shot: string;
  pose: string;
};

console.log(analysis.shot);
// → "medium close-up, eye-level"

console.log(analysis.pose);
// → "upright torso facing forward, head straight and centered, shoulders squared, arms relaxed downward (implied)"

// 5. Reasoning-token accounting. Grok-4 spent 623 of its 728 output
//    tokens reasoning before emitting the 105-token JSON answer —
//    surfaced in `usage.output_tokens_details.reasoning_tokens`.
console.log(result.usage);
// → {
//     input_tokens: 2684,
//     input_tokens_details: { cached_tokens: 679 },
//     output_tokens: 728,
//     output_tokens_details: { reasoning_tokens: 623 },
//     total_tokens: 3412,
//   }
```

**页:1**

-   `store: false` 不让XAI的历史表面出现反应。 翻转到 `true` 链式后续 `previous_response_id` - 用于 多回转改进 ("现在描述衣柜") 不重装 每次图像.
-   反应输出阵列还包含推理项目和工具调用 当在现相. 总是歧视 `item.type` 读取内容之前; TypeScript的收缩 让你诚实.
-   用于原始聊天方式,而不使用响应包,使用 `xai.post.v1.chat.completions` 换句话说,同样的认证,同样的模型目录, 只是OpenAI兼容的请求/响应形状.
-   表面错误为 `XaiError` 与 `status` 与附着的经文, 这样 `try { ... } catch (e) { if (e instanceof XaiError) ... }` 给你 直接发生上游错误.

## 想象文件 API 集成

xAI 想象图像和视频端点可以参考私有文件 API 资产,并且可以将生成的资产持续到文件存储.

-   输入: 任何地方 想象接受一个公共 URL 或 base64 图像/视频, 通过存储 `file_id` 换句话说 Apicity 接受原始 REST 形状 (单位:千美元)`image: { file_id }`, (中文(简体) ), `images: [{ file_id }]`, (中文(简体) ), `last_frame: { file_id }`, (中文(简体) ), `video: { file_id }`, (中文(简体) ), `reference_images: [{ file_id }]`\+ 方便别名 (单位:千美元)`image_file_id`, (中文(简体) ), `image_file_ids`, (中文(简体) ), `last_frame_file_id`, (中文(简体) ), `video_file_id`,以及 `reference_image_file_ids`页:1 在 HTTP 请求之前.
-   产出:通过 `storage_options` 附有所需 `filename` 坚持下去 生成的图像或视频。 奥米 `public_url` 或设定为 `false` 用于私有文件; 设置 `public_url: true` 或者说 `public_url: { expires_after: 86400 }` 创建可共享的 URL.
-   答复中仍然包括默认电平 `imgen.x.ai` 或者说 `vidgen.x.ai` 生成 URL。 当请求存储时 ưμ㼯A `file_output` 编辑 生成图像或完成的视频.

### 参考到视频、被绑框和预设声音

`xai.post.v1.videos.generations` 支持使用 最多14个参考图像 `grok-imagine-video-1.5` 家庭(7个 `grok-imagine-video`),一到三个预设的声音,或者两者兼有. 图像 引用可能使用公共 HTTPS URL、 数据 URI 或 文件 API ID 混合剂。 预设语音使用开放式的,对大小写不敏感的xAI语音标识; 3; 辣度保存每个 `voice_id` 语音识别留给 xAI. 预设的声音和被绑框要求 `grok-imagine-video-1.5` 经济、社会、文化权利委员会 `-preview` 和日期别名。 无型号请求 带有引用、 最后一个框或密钥框默认为条形 `grok-imagine-video-1.5` 型号.

```typescript
const video = await xai.post.v1.videos.generations({
  prompt: "The person from <IMAGE_0> speaks the line with the voice from <AUDIO_0>",
  model: "grok-imagine-video-1.5",
  reference_images: [{ url: "https://example.com/character.png" }],
  reference_audios: [{ voice_id: "eve" }],
  duration: 15,
});
```

在1.5个家庭里,一个请求也可以指针框. `image` (或 `image_file_id`)是第一个框架,单独或附带参考; `last_frame` (或 `last_frame_file_id`)是最后一个框架;和 `keyframes` 在剪辑内刻出四张图像 每个键框 `timestamp_s` 必须 大于 0 并小于 `duration` (省略时为8秒). 页:1 将键框按到一分之三秒的网格,所以有两个键框绕到 同一档次被否决. `prompt` 当一个框架被固定时是可选的; 文本到视频和仅引用请求仍然需要。 先被钉住 帧取取 `<IMAGE_0>`,然后从 `<IMAGE_1>`。 。 。 .

```typescript
const timeLapse = await xai.post.v1.videos.generations({
  model: "grok-imagine-video-1.5",
  image: { url: "https://example.com/dawn.png" },
  keyframes: [
    { image: { url: "https://example.com/noon.png" }, timestamp_s: 3.5 },
    { image: { url: "https://example.com/dusk.png" }, timestamp_s: 6.5 },
  ],
  last_frame: { url: "https://example.com/night.png" },
  duration: 10,
  resolution: "720p",
});
```

相同的可调用程序接受只使用图像和音频的参考请求. 空引用和键框数组不活动 。 源视频( A)`video` 或者说 `video_file_id`)不包括每个模型的参考文献和被标注的框架, 财务报告和审定财务报表 `grok-imagine-video` 也拒绝 `image` 除了参考书目 提示 标记,例如 `<IMAGE_0>` 财务报告和审定财务报表 `<AUDIO_0>` 未经修改.

### 存储输入字段映射

当图像或视频已经存在于 xAI 文件时使用这些字段 存储。 辣度将方便化的别名化为REST `file_id` 发送请求前的对象形状.

| 异想天开 | 存储输入字段 | 发送到xAI |
| --- | --- | --- |
| `xai.post.v1.images.edits` | `image_file_id` | `image: { file_id }` |
| `xai.post.v1.images.edits` | `image_file_ids` | `images: [{ file_id }]` |
| `xai.post.v1.videos.generations` | `image_file_id` | `image: { file_id }` |
| `xai.post.v1.videos.generations` | `last_frame_file_id` | `last_frame: { file_id }` |
| `xai.post.v1.videos.generations` | `reference_image_file_ids` | `reference_images: [{ file_id }]` |
| `xai.post.v1.videos.generations.imageToVideo` | `image_file_id` | `image: { file_id }` |
| `xai.post.v1.videos.edits` | `video_file_id` | `video: { file_id }` |
| `xai.post.v1.videos.extensions` | `video_file_id` | `video: { file_id }` |

也可以直接通过原始的 REST 字段. `images` 财务报告和审定财务报表 `reference_images` 条目可以混合 `{ file_id }` 财务报告和审定财务报表 `{ url }` 条目,仅在一些引用时有用 已经是私有文件资产 。 存储的图像必须是 PNG, JPEG, 或 WebP; 存储的视频必须是 MP4; 文件上传必须是 在以“想象”结尾引用之前完成.

```typescript
const gen = await xai.post.v1.images.generations({
  prompt: "A futuristic city skyline at night",
  model: "grok-imagine-image-2.0",
  quality: "low",
  storage_options: { filename: "city.jpg" },
});
const city = gen.data[0].file_output!.file_id!;

const edit = await xai.post.v1.images.edits({
  prompt: "Add neon signs to the buildings",
  model: "grok-imagine-image-2.0",
  quality: "low",
  image_file_id: city,
  storage_options: { filename: "city-neon.jpg" },
});
const neonCity = edit.data[0].file_output!.file_id!;

const video = await xai.post.v1.videos.generations({
  prompt: "A camera pulls back through the city",
  model: "grok-imagine-video",
  duration: 5,
  image_file_id: neonCity,
  storage_options: {
    filename: "city-loop.mp4",
    public_url: true,
  },
});

const done = await xai.get.v1.videos(video.request_id);
console.log(done.video?.url);
console.log(done.video?.file_output?.public_url);
```

见xAI的 [想象文件 API 集成](https://docs.x.ai/developers/model-capabilities/imagine/files), (中文(简体) ), [引用文件为输入](https://docs.x.ai/developers/model-capabilities/imagine/files/inputs), (中文(简体) ), [持续生成输出](https://docs.x.ai/developers/model-capabilities/imagine/files/outputs), (中文(简体) ), [管理文件](https://docs.x.ai/developers/files/managing-files), (中文(简体) ), 财务报告和审定财务报表 [文件 公开 URL](https://docs.x.ai/developers/files/public-urls) 用于上传、过期和公共 URL 生命周期细节的文件.

## 文件 公开 URL

上传到xAI存储的文件默认是私有的. 使用 `xai.post.v1.files.publicUrl(fileId)` 创建共享 用于已有文件的 xAI CDN URL, 然后独立撤销该 URL 与 `xai.post.v1.files.publicUrl.revoke(fileId)` 共享时 应该停止。 撤销公用URL让私用文件完好无损.

```typescript
const file = await xai.post.v1.files(
  new Blob(["diagram"], { type: "image/png" }),
  "diagram.png",
  "assistants"
);

const created = await xai.post.v1.files.publicUrl(file.id, {
  expires_after: 86400,
});
console.log(created.public_url);
console.log(created.expires_at);

const withPublicUrls = await xai.get.v1.files({
  filter: "public_url != null",
});
console.log(withPublicUrls.data[0]?.public_url);

await xai.post.v1.files.publicUrl.revoke(file.id);
```

**公共 URL 生命周期**

-   空创建机构使用 xAI 默认 。 过 `expires_after` 以秒计 在1小时到30天后自动翻转 URL.
-   公共 URL 无法超过其文件 。 如果文件有自己的文件 `expires_at`,省略的公共 URL 过期继承文件过期; 明确 `expires_after` 必须装入剩余文件 一辈子.
-   创建为 idempotent , 而一个文件已经有一个活动的公共 URL : 重复调用返回相同的 URL 令牌,并可以更新其过期 .
-   `get.v1.files(fileId)` 财务报告和审定财务报表 `get.v1.files({ filter })` 保护 `public_url` 财务报告和审定财务报表 `public_url_expires_at` 元数据,所以呼叫者可以 审计当前公开的文件.

见xAI的 [文件 公开 URL](https://docs.x.ai/developers/files/public-urls), (中文(简体) ), [管理文件](https://docs.x.ai/developers/files/managing-files), (中文(简体) ), 财务报告和审定财务报表 [想象文件 API 集成](https://docs.x.ai/developers/model-capabilities/imagine/files) 用于支持的内容类型、大小限制和 `storage_options.public_url` 生成路径.

## 实时服务器传输

`@apicity/xai/realtime` 出口 `connectXaiRealtime`,一个 WebSocket 服务器侧语音会话的传输基于 `ws`发送到您的 作为 API 密钥 `Authorization: Bearer` 头,所以保留在服务器上; 浏览器应该与来自 `xai.post.v1.realtime.clientSecrets` 换句话说.

```typescript
import { connectXaiRealtime } from "@apicity/xai/realtime";

const connection = await connectXaiRealtime({
  apiKey: process.env.XAI_API_KEY!,
  model: "grok-voice-latest",
  onEvent: (event) => console.log(event.type),
});

connection.send({
  type: "session.update",
  session: { voice: "eve", audio: { output: { speed: 1.1 } } },
});

// Speak a scripted line without model inference. The force_message
// item is the whole turn, so do not follow it with response.create.
connection.send({
  type: "conversation.item.create",
  item: {
    type: "force_message",
    role: "assistant",
    interruptible: false,
    content: [{ type: "output_text", text: "This call is being recorded." }],
  },
});

connection.close();
await connection.closed;
```

-   过 `callId` 改为 `model` 附加到一个入境的SIP电话.
-   `audio.output.speed` 是从0.7到1.5的回放乘数 (默认 1. 0).
-   `interruptible: false` 将调用器音频发送到强制消息 完成播放( 默认) `true`) (中文(简体) ).
-   `timeout` 限制握手( 默认 15 s) 和 `signal` 终止它 或开口连接. 一个被拒绝的握手拒绝 `XaiError` 带有HTTP状态并解析出体.
-   一个不是 JSON 文本框架的服务器事件 `type` 关闭 联系和报告 `Invalid Realtime event` 结束 `onError`。 。 。 .

见xAI的 [对发言的发言](https://docs.x.ai/developers/model-capabilities/audio/speech-to-speech) 用于会话参数和活动的文件.

## API 参考

55个端点横跨18个组. 每个方法都映射出上游的 URL 路径 .

### 键

`GET` **`xai.v1.apiKey`**

`GET [https://api.x.ai/v1/api-key](https://api.x.ai/v1/api-key)`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/developers/rest-api-reference/inference/other)

```typescript
const res = await xai.get.v1.apiKey();
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

### 批号

`GET` **`xai.v1.batches`**

`GET https://api.x.ai/v1/batches/{paramsOrIdOrSignal}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.get.v1.batches({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`GET` **`xai.v1.batches.requests`**

`GET https://api.x.ai/v1/batches/{batchId}/requests{query}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.get.v1.batches.requests({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`GET` **`xai.v1.batches.results`**

`GET https://api.x.ai/v1/batches/{batchId}/results{query}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.get.v1.batches.results({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.v1.batches`**

`POST [https://api.x.ai/v1/batches](https://api.x.ai/v1/batches)`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.post.v1.batches({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.v1.batches.cancel`**

`POST https://api.x.ai/v1/batches/{batchId}:cancel`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.post.v1.batches.cancel({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.v1.batches.requests`**

`POST https://api.x.ai/v1/batches/{batchId}/requests`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.post.v1.batches.requests({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

### 聊天

`GET` **`xai.v1.chat.deferredCompletion`**

`GET https://api.x.ai/v1/chat/deferred-completion/{requestId}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.get.v1.chat.deferredCompletion({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.v1.chat.completions`**

`POST [https://api.x.ai/v1/chat/completions](https://api.x.ai/v1/chat/completions)`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.post.v1.chat.completions({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

### 自定义声音

`DELETE` **`xai.v1.customVoices`**

`DELETE https://api.x.ai/v1/custom-voices/{voiceId}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/developers/model-capabilities/audio/custom-voices)

```typescript
const res = await xai.delete.v1.customVoices({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`GET` **`xai.v1.customVoices`**

`GET https://api.x.ai/v1/custom-voices/{paramsOrVoiceIdOrSignal}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/developers/model-capabilities/audio/custom-voices)

```typescript
const res = await xai.get.v1.customVoices({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`GET` **`xai.v1.customVoices.audio`**

`GET https://api.x.ai/v1/custom-voices/{voiceId}/audio`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/developers/model-capabilities/audio/custom-voices)

```typescript
const res = await xai.get.v1.customVoices.audio({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`PATCH` **`xai.v1.customVoices`**

`PATCH https://api.x.ai/v1/custom-voices/{voiceId}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/developers/model-capabilities/audio/custom-voices)

```typescript
const res = await xai.patch.v1.customVoices({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.v1.customVoices`**

`POST [https://api.x.ai/v1/custom-voices](https://api.x.ai/v1/custom-voices)`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/developers/model-capabilities/audio/custom-voices)

```typescript
const res = await xai.post.v1.customVoices({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

### 文档

`POST` **`xai.v1.documents.search`**

`POST [https://api.x.ai/v1/documents/search](https://api.x.ai/v1/documents/search)`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.post.v1.documents.search({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

### 文件

`DELETE` **`xai.v1.files`**

`DELETE https://api.x.ai/v1/files/{fileId}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.delete.v1.files({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`GET` **`xai.v1.files`**

`GET https://api.x.ai/v1/files/{paramsOrFileIdOrSignal}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.get.v1.files({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`GET` **`xai.v1.files.content`**

`GET https://api.x.ai/v1/files/{fileId}/content`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.get.v1.files.content({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.v1.files`**

`POST [https://api.x.ai/v1/files](https://api.x.ai/v1/files)`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.post.v1.files({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.v1.files.publicUrl`**

`POST https://api.x.ai/v1/files/{fileId}/public-url`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/developers/files/public-urls)

```typescript
const res = await xai.post.v1.files.publicUrl({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.v1.files.publicUrl.revoke`**

`POST https://api.x.ai/v1/files/{fileId}/public-url/revoke`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/developers/files/public-urls)

```typescript
const res = await xai.post.v1.files.publicUrl.revoke({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

### 图像模式

`GET` **`xai.v1.imageGenerationModels`**

`GET https://api.x.ai/v1/image-generation-models/{modelIdOrSignal}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.get.v1.imageGenerationModels({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

### 图像

`GET` **`xai.v1.images`**

`GET https://api.x.ai/v1/images/{requestId}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/developers/rest-api-reference/inference/images)

```typescript
const res = await xai.get.v1.images({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.v1.images.edits`**

`POST [https://api.x.ai/v1/images/edits](https://api.x.ai/v1/images/edits)`

成本等级 : `prohibitive`

[上游区域](https://docs.x.ai/developers/rest-api-reference/inference/images)

```typescript
const res = await xai.post.v1.images.edits({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.v1.images.generations`**

`POST [https://api.x.ai/v1/images/generations](https://api.x.ai/v1/images/generations)`

成本等级 : `prohibitive`

[上游区域](https://docs.x.ai/developers/rest-api-reference/inference/images)

```typescript
const res = await xai.post.v1.images.generations({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

### 语言模型

`GET` **`xai.v1.languageModels`**

`GET https://api.x.ai/v1/language-models/{modelIdOrSignal}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.get.v1.languageModels({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

### 管理辅助

`DELETE` **`xai.managementApi.v1.collections`**

`DELETE https://management-api.x.ai/v1/collections/{collectionId}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.delete.managementApi.v1.collections({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`DELETE` **`xai.managementApi.v1.collections.documents`**

`DELETE https://management-api.x.ai/v1/collections/{collectionId}/documents/{fileId}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.delete.managementApi.v1.collections.documents({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`GET` **`xai.managementApi.auth.teams.apiKeys`**

`GET https://management-api.x.ai/auth/teams/{teamId}/api-keys{query}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/developers/rest-api-reference/management/auth)

```typescript
const res = await xai.get.managementApi.auth.teams.apiKeys({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`GET` **`xai.managementApi.v1.billing.teams.postpaid.invoice.preview`**

`GET https://management-api.x.ai/v1/billing/teams/{teamId}/postpaid/invoice/preview`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/developers/rest-api-reference/management/billing)

```typescript
const res = await xai.get.managementApi.v1.billing.teams.postpaid.invoice.preview({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`GET` **`xai.managementApi.v1.billing.teams.postpaid.spendingLimits`**

`GET https://management-api.x.ai/v1/billing/teams/{teamId}/postpaid/spending-limits`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/developers/rest-api-reference/management/billing)

```typescript
const res = await xai.get.managementApi.v1.billing.teams.postpaid.spendingLimits({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`GET` **`xai.managementApi.v1.billing.teams.prepaid.balance`**

`GET https://management-api.x.ai/v1/billing/teams/{teamId}/prepaid/balance`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/developers/rest-api-reference/management/billing)

```typescript
const res = await xai.get.managementApi.v1.billing.teams.prepaid.balance({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`GET` **`xai.managementApi.v1.collections`**

`GET https://management-api.x.ai/v1/collections/{paramsOrIdOrSignal}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.get.managementApi.v1.collections({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`GET` **`xai.managementApi.v1.collections.documents`**

`GET https://management-api.x.ai/v1/collections/{collectionId}/documents/{paramsOrFileId}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.get.managementApi.v1.collections.documents({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`GET` **`xai.managementApi.v1.collections.documents.batchGet`**

`GET https://management-api.x.ai/v1/collections/{collectionId}/documents:batchGet{query}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.get.managementApi.v1.collections.documents.batchGet({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`PATCH` **`xai.managementApi.v1.collections.documents`**

`PATCH https://management-api.x.ai/v1/collections/{collectionId}/documents/{fileId}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.patch.managementApi.v1.collections.documents({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.managementApi.v1.billing.teams.usage`**

`POST https://management-api.x.ai/v1/billing/teams/{teamId}/usage`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/developers/rest-api-reference/management/billing)

```typescript
const res = await xai.post.managementApi.v1.billing.teams.usage({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.managementApi.v1.collections`**

`POST [https://management-api.x.ai/v1/collections](https://management-api.x.ai/v1/collections)`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.post.managementApi.v1.collections({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.managementApi.v1.collections.documents`**

`POST https://management-api.x.ai/v1/collections/{collectionId}/documents/{fileId}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.post.managementApi.v1.collections.documents({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`PUT` **`xai.managementApi.v1.collections`**

`PUT https://management-api.x.ai/v1/collections/{collectionId}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.put.managementApi.v1.collections({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

### 模型

`GET` **`xai.v1.models`**

`GET https://api.x.ai/v1/models/{modelIdOrSignal}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.get.v1.models({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

### 实时

`POST` **`xai.v1.realtime.clientSecrets`**

`POST [https://api.x.ai/v1/realtime/client_secrets](https://api.x.ai/v1/realtime/client_secrets)`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.post.v1.realtime.clientSecrets({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

### 答复

`DELETE` **`xai.v1.responses`**

`DELETE https://api.x.ai/v1/responses/{id}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.delete.v1.responses({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`GET` **`xai.v1.responses`**

`GET https://api.x.ai/v1/responses/{id}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.get.v1.responses({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.v1.responses`**

`POST [https://api.x.ai/v1/responses](https://api.x.ai/v1/responses)`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.post.v1.responses({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.v1.responses.compact`**

`POST [https://api.x.ai/v1/responses/compact](https://api.x.ai/v1/responses/compact)`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.post.v1.responses.compact({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

### 标准

`POST` **`xai.v1.stt`**

`POST [https://api.x.ai/v1/stt](https://api.x.ai/v1/stt)`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.post.v1.stt({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

### 标记文字

`POST` **`xai.v1.tokenizeText`**

`POST [https://api.x.ai/v1/tokenize-text](https://api.x.ai/v1/tokenize-text)`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.post.v1.tokenizeText({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

### 吨数

`POST` **`xai.v1.tts`**

`POST [https://api.x.ai/v1/tts](https://api.x.ai/v1/tts)`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.post.v1.tts({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

### 视频模式

`GET` **`xai.v1.videoGenerationModels`**

`GET https://api.x.ai/v1/video-generation-models/{modelIdOrSignal}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.get.v1.videoGenerationModels({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

### 视频

`GET` **`xai.v1.videos`**

`GET https://api.x.ai/v1/videos/{requestId}`

成本等级 : `expensive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.get.v1.videos({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.v1.videos.edits`**

`POST [https://api.x.ai/v1/videos/edits](https://api.x.ai/v1/videos/edits)`

成本等级 : `prohibitive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.post.v1.videos.edits({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.v1.videos.extensions`**

`POST [https://api.x.ai/v1/videos/extensions](https://api.x.ai/v1/videos/extensions)`

成本等级 : `prohibitive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.post.v1.videos.extensions({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.v1.videos.generations`**

`POST [https://api.x.ai/v1/videos/generations](https://api.x.ai/v1/videos/generations)`

成本等级 : `prohibitive`

[上游区域](https://docs.x.ai/docs/api-reference)

```typescript
const res = await xai.post.v1.videos.generations({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

`POST` **`xai.v1.videos.generations.imageToVideo`**

`POST [https://api.x.ai/v1/videos/generations](https://api.x.ai/v1/videos/generations)`

成本等级 : `prohibitive`

[上游区域](https://docs.x.ai/developers/model-capabilities/video/image-to-video)

```typescript
const res = await xai.post.v1.videos.generations.imageToVideo({ /* ... */ });
```

资料来源: [`packages/provider/xai/src/xai.ts`](https://npmcn.com/package/%40apicity/xai/src/xai.ts)

## 中间软件

```typescript
import { createXai, withRetry } from "@apicity/xai";

const xai = createXai({ apiKey: process.env.XAI_API_KEY! });
const models = withRetry(xai.get.v1.models, { retries: 3 });
```

## 限制费率

客户端速率限制队列请求停留在xAI API限制范围内.

```typescript
import {
  createXai,
  withRateLimit,
  withRetry,
  createRateLimiter,
  XAI_RATE_LIMITS,
} from "@apicity/xai";

const xai = createXai({ apiKey: process.env.XAI_API_KEY! });
```

### 使用 xAI 级预设

```typescript
// Use built-in tier presets (free, tier1, tier2, tier3, tier4)
const limiter = createRateLimiter(XAI_RATE_LIMITS.tier1);
// => { rpm: 60, concurrent: 10 }

const chat = withRateLimit(xai.post.v1.chat.completions, limiter);
```

### 自定义限制

```typescript
const limiter = createRateLimiter({ rpm: 30, concurrent: 5 });
const chat = withRateLimit(xai.post.v1.chat.completions, limiter);
```

### 跨端点共享限制器

RPM限制在全球范围内适用,因此在所有终点共享一个单一的限值:

```typescript
const limiter = createRateLimiter(XAI_RATE_LIMITS.tier2);

const chat = withRateLimit(xai.post.v1.chat.completions, limiter);
const responses = withRateLimit(xai.post.v1.responses, limiter);
```

### 用重试编译

地点 `withRateLimit` 最内层的重试计数到极限:

```typescript
const limiter = createRateLimiter(XAI_RATE_LIMITS.tier1);

const chat = withRetry(
  withRateLimit(xai.post.v1.chat.completions, limiter),
  { retries: 2 }
);
```

### 批处理

并行的点火请求——限制手柄自动间隔:

```typescript
const limiter = createRateLimiter(XAI_RATE_LIMITS.tier1);
const chat = withRateLimit(xai.post.v1.chat.completions, limiter);
const prompts = ["Name a prime number.", "Name a noble gas."];

const results = await Promise.all(
  prompts.map((p) =>
    chat({
      model: "grok-3",
      messages: [{ role: "user", content: p }],
    })
  )
);
```

### xAI 费率限制等级

| 预设 | 常规 | 同时 | 支出门槛值 |
| --- | --- | --- | --- |
| `free` | 页:1 | 2个 | 0美元 (单位:美元) |
| `tier1` | 页:1 | 10个 | 0美元+ (单位:千美元) |
| `tier2` | 200个 | 第25条 | 100美元+ (单位:千美元) |
| `tier3` | 500个 | 第50条 | $500+ (单位:千美元) |
| `tier4` | 1 000个 | 100个 | 1 000美元+ (单位:千美元) |

部分 [辣点](https://github.com/justintanner/apicity) 单相机.

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/%40apicity/xai/LICENSE)。 。 。 .

## 常见问题

### @apicity/xai 是什么？

X\.AI / Grok 提供商进行聊天和搜索\.

### 如何安装 @apicity/xai？

在项目目录运行 npm install @apicity/xai，或使用 pnpm add / yarn add / bun add。

### @apicity/xai 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @apicity/xai 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @apicity/xai 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @apicity/xai 可以商用吗？

@apicity/xai 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @apicity/xai 的下载量有多少？

根据 npm 官方下载统计，@apicity/xai 在 2026/10/06 – 2026/11/04 这 30 天内被下载 4,050 次，日均约 135 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @apicity/xai 还在维护吗？

最新版本 0\.26\.0 发布于 2026/11/05（1 天前）；至今共发布 89 个版本，其中过去 12 个月发布了 89 个；首次发布于 2026/05/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。