API 接入文档

OpenAI 兼容接口 · GPT 与 Grok 通用

本站提供 OpenAI 兼容接口。GPT 与 Grok 使用同一套地址和 API Key，模型以你的 Key 权限和 /v1/models 为准。

API 地址

标准地址：

Plain Text

https://xx.com/v1

两个地址格式相同、Key 相同。国内访问标准地址较慢时，可改用高带宽地址。base_url 已经包含 /v1，客户端不要再拼一次，完整路径是 /v1/responses、/v1/chat/completions，不是 /v1/v1/...。

创建 API Key

登录主站后进入「API / Key」或「客户端 Key」页面创建 Key。

请求时使用客户端 API Key，不要使用管理员登录 Token、网页登录 Cookie 或上游账号凭据。

HTTP

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

2.1 下游 / 中转站怎么填

GPT 和 Grok 都走 OpenAI 兼容协议。Sub2API、NewAPI、OneAPI、OpenCode 加渠道时：

平台选 **OpenAI**，不要选 Grok

Base URL：`https://xx.com/v1`

Key 用本站发的客户端 Key

模型名填 `grok-4.6`、`grok-4.5` 等 `/v1/models` 里返回的名字

Grok 平台是给官方 xAI 用的，Key 要以 xai- 开头，空 Base URL 会打 api.x.ai。用本站 Key 去点「同步上游模型」会失败。选 OpenAI 就能拉到模型。

查看可用模型

Bash

curl https://xx.com/v1/models \
  -H "Authorization: Bearer $MYSANDBOX_API_KEY"

先拉模型列表，再选用实际返回的模型名。Grok 文本常见为 grok-4.6、grok-4.5；图片为 grok-imagine-image-2.0；视频为 grok-imagine-video-1.5。列表里没有对应模型，说明当前 Key 没有该分组权限。

Grok 文本对接（完整说明）

Grok 4\.6 是思考模型。请求会先推理再出字，首字比普通聊天模型慢是正常现象，不是线路故障。

推荐协议：/v1/responses。只支持 Chat Completions 的客户端用 /v1/chat/completions。两种协议都可用。

4.1 推理强度

/v1/responses 请传：

JSON

"reasoning": { "effort": "low" }

/v1/chat/completions 请传：

JSON

"reasoning_effort": "low"

可选值：low、medium、high。部分客户端也会传 xhigh。

不传推理强度时，Grok 4\.6 仍可能思考。需要更快首字时明确传 low；需要更深推理再传 high。后台「推理强度」显示为 -，表示这次请求没有带该字段。

4.2 必须开流式

请始终设置 "stream": true。关闭流式时，要等整段生成完才返回。输出几千到上万 token 时，会表现为等 1 到 4 分钟，容易被当成卡死。

4.3 Responses 示例

Bash

curl https://xx.com/v1/responses \
  -H "Authorization: Bearer $MYSANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "input": "用三句话说明什么是流式响应。",
    "stream": true,
    "reasoning": { "effort": "low" }
  }'

Python：

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="hhttps://xx.com/v1",
)

with client.responses.stream(
    model="grok-4.6",
    input="用三句话说明什么是流式响应。",
    reasoning={"effort": "low"},
) as stream:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)

4.4 Chat Completions 示例

Bash

curl https://xx.com/v1/chat/completions \
  -H "Authorization: Bearer $MYSANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [
      {"role": "user", "content": "用三句话说明什么是流式响应。"}
    ],
    "stream": true,
    "reasoning_effort": "low"
  }'

Python：

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://xx.com/v1",
)

stream = client.chat.completions.create(
    model="grok-4.6",
    messages=[{"role": "user", "content": "用三句话说明什么是流式响应。"}],
    stream=True,
    extra_body={"reasoning_effort": "low"},
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

NewAPI / OneAPI / OpenCode / Sub2API：平台选 OpenAI（不要选 Grok），Base URL 填 https://xx.com/v1，模型填 grok-4.6，打开 Stream。走 Responses 时，在高级参数里加上 reasoning.effort。

4.5 速度说明（现网实测）

短请求、流式、grok-4.6：首字大约 1 到 3 秒，出字大约每秒 50 token。

带 high 思考：首字常见 6 到 15 秒，这是模型在推理。

上下文到十几万、三十万 token：首字会到 20 秒到 1 分钟以上。同一条 Responses 会话会把前文放进缓存，后面即使只发一句，实际上仍在读整段历史。

要加快：新开对话、截短上下文、推理用 low、打开 stream。不要用关流式的长生成来判断线路。

stop 如需传递，请用数组，例如 [""]，不要传单个字符串。

GPT 文本

GPT 同样走上面的地址和 Key。支持 Responses 的客户端优先用 /v1/responses。

Bash

curl https://xx.com/v1/responses \
  -H "Authorization: Bearer $MYSANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "请用三句话解释什么是 HTTP 流式响应。",
    "stream": false
  }'

Chat Completions：

Bash

curl hhttps://xx.com/v1/chat/completions \
  -H "Authorization: Bearer $MYSANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      {"role": "user", "content": "请用三句话解释什么是 HTTP 流式响应。"}
    ],
    "stream": false
  }'

Grok 图片

当前 grok heavy Key 的 /v1/models 会返回 grok-imagine-image-2.0。图片是同步接口，一次请求直接返回，不要轮询。

Bash

curl https://xx.com/v1/images/generations \
  -H "Authorization: Bearer $MYSANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "A single red apple on a plain white table, studio product photo, no text",
    "n": 1,
    "size": "2K"
  }'

size 可用 1K、2K、4K。现网 grok heavy 计费为 1K $0.04、2K $0.06、4K $0.06（以你的分组定价为准）。官方 Imagine 实际上游按 1K/2K 生成，4K 不会报 400，会按 2K 上送并按 4K 档计费。

实测成功响应形态：

JSON

{
  "data": [
    {
      "url": "https://imgen.x.ai/...",
      "mime_type": "image/jpeg"
    }
  ]
}

图床域名是 imgen.x.ai，链接有时效，拿到后请尽快转存。图生图走 /v1/images/edits，模型同样是 grok-imagine-image-2.0。

Grok 视频

当前 grok heavy Key 的 /v1/models 会返回 grok-imagine-video-1.5。视频是异步接口：先提交拿 request_id，再查询状态，完成后用同一个 Key 下载 mp4。

/v1/videos 和 /v1/videos/generations 都可以提交。不要套 OpenAI 视频的 seconds / size，实测会 422。

Bash

curl https://xx.com/v1/videos/generations \
  -H "Authorization: Bearer $MYSANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "A red apple slowly rotating on a white table, simple studio shot",
    "duration": 6,
    "aspect_ratio": "16:9",
    "resolution": "480p"
  }'

提交成功会立刻返回：

JSON

{
  "request_id": "66dfbe34-a2e4-99d7-8623-0ef7902f742a"
}

查询进度：

Bash

curl https://xx.com/v1/videos/$REQUEST_ID \
  -H "Authorization: Bearer $MYSANDBOX_API_KEY"

完成态实测为 status=done、progress=100。video.url 是站内相对路径，不是公网直链。

下载视频：

Bash

curl -L https://xx.com/v1/videos/$REQUEST_ID/content \
  -H "Authorization: Bearer $MYSANDBOX_API_KEY" \
  -o grok-video.mp4

实测 content 接口返回 Content-Type: video/mp4。不传 duration 时默认生成 8 秒。resolution 现网有 480p、720p、1080p 成功记录。grok heavy 视频价目前为 480p $0.04/秒、720p $0.07/秒、1080p $0.125/秒，以分组定价为准。

常见问题

`401 API_KEY_REQUIRED`：没有发送客户端 API Key，或认证头格式不正确。

`401`：Key 已停用、过期，或当前 Key 没有目标模型权限。

`404`：检查是否把 `/v1` 重复拼接。

`400` 或 `422`：检查模型名、请求体，以及有没有把 Responses 请求发到 Chat Completions。

`429`：上游或当前 Key 限流，降低并发，并遵守 `Retry-After`。

Grok 首字很慢：先看有没有开 `stream`、有没有传 `reasoning.effort`、上下文是否已经很长。短请求流式 1 到 3 秒出字，说明线路正常。

Grok 后台推理强度为 `-`：请求没带 `reasoning` / `reasoning_effort`，不是接口没适配。

`422` 且提示 `xAI upstream returned status 422`：Grok 视频不要传 OpenAI 的 `seconds`、`size`。改用 `duration`、`aspect_ratio`、`resolution`。

视频提交成功但还没有文件：先轮询 `/v1/videos/{request_id}`，等到 `status` 为 `done` 再下载 `/content`。

`/v1/models` 没有 `grok-imagine-*`：当前 Key 没有图片/视频分组权限。

同步上游模型失败、选 Grok 平台拉不到模型：改选 OpenAI 平台。Grok 页只认官方 `xai-` Key，不认本站 Key。

本站是第三方 OpenAI\-compatible API 接入服务，与 OpenAI、xAI 或其他上游厂商没有官方关联。可用模型、权限、速度和额度以 /v1/models、你的 Key 权限和实际响应为准。