Hyperouter API

版本 v1 · 更新于 2026 年 10 月 25 日

Hyperouter 是位于众多模型厂商之前的统一 HTTP API。你发送一个指定模型的请求，Hyperouter 会选出能够处理它的服务商，转发请求，并按该服务商的标价从你的余额中扣费。

所有接口都沿用 OpenAI 的请求与响应格式。只需更换 base URL 和 API 密钥，即可使用 OpenAI SDK。Hyperouter 在 OpenAI 的请求体之上增加了少量字段，本参考中均标注为“新增”。

快速开始

1. 登录并创建 API 密钥。密钥以 sk-hr-v1- 开头，仅显示一次。
2. 将密钥保存到环境变量中，例如 HYPEROUTER_API_KEY。
3. 充值：在控制台中提交充值申请。付款确认后，工作人员会为你的余额入账。
4. 将任意 OpenAI SDK 指向上述 base URL，并选择一个模型。

curl https://api.hyperouter.app/v1/chat/completions \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "x-ai/grok-4.7",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.hyperouter.app/v1",
  apiKey: process.env.HYPEROUTER_API_KEY,
});

const res = await client.chat.completions.create({
  model: "x-ai/grok-4.7",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(res.choices[0].message.content);

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.hyperouter.app/v1",
    api_key=os.environ["HYPEROUTER_API_KEY"],
)

res = client.chat.completions.create(
    model="x-ai/grok-4.7",
    messages=[{"role": "user", "content": "Hello"}],
)
print(res.choices[0].message.content)

身份验证

每个请求都以 Bearer 令牌的形式携带你的 API 密钥。

Authorization: Bearer sk-hr-v1-...

密钥可以动用你的余额，请只保存在服务端，切勿放入浏览器或移动端代码。Hyperouter 只保存每个密钥的哈希值，因此丢失的密钥无法再次显示，请重新创建。

在控制台中，你可以为每个密钥命名、设置额度上限，或将其停用。停用的密钥立即失效。如果某个请求会使密钥超出其额度上限，将被拒绝并返回 402 insufficient_credits。

身份验证错误

curl https://api.hyperouter.app/v1/generations/0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21 \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY"

{ "error": { "message": "The API key is not valid.", "type": "authentication_error", "code": "invalid_api_key", "param": null } }

错误

所有错误都使用 OpenAI 的错误对象，并配以对应的 HTTP 状态码。

{
  "error": {
    "message": "n must be an integer from 1 to 128",
    "type": "invalid_request_error",
    "code": "invalid_body",
    "param": "n"
  }
}

类型与状态码

Hyperouter 从不返回 502 或 504：这两个状态码会以我们边缘网络的裸页面形式到达你手中，不带错误响应体。在网关本应返回它们的场景下，你会收到 503 及下述响应体，网关状态码则放在 X-Upstream-Status 中。

可能遇到的 code

重试与幂等

网络错误或超时并不能告诉你 Hyperouter 是否收到了请求。如果你再次发送，可能会启动第二个任务并重复付费。Idempotency-Key 可以让重复请求变得安全：Hyperouter 会识别出重复请求，不启动第二个任务，不再次预扣，并直接返回首次请求的结果。

对每一个会产生费用的请求都发送该请求头。 为每个新请求生成一个新的随机值，例如 UUID v4。将它与请求一起保存，并在重新发送同一请求时每次都使用相同的值。

发送键

以下接口接受该请求头：

OpenAI SDK 不会自动发送该请求头。请将它作为额外请求头传入；SDK 在自动重试时会原样重新发送。

curl https://api.hyperouter.app/v1/images/generations \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{"model": "x-ai/grok-imagine-image", "prompt": "A lighthouse at dusk", "n": 1}'

import uuid

key = str(uuid.uuid4())  # one per request; reuse it when you retry this request
img = client.images.generate(
    model="x-ai/grok-imagine-image",
    prompt="A lighthouse at dusk",
    extra_headers={"Idempotency-Key": key},
)

import { randomUUID } from "node:crypto";

const key = randomUUID(); // one per request; reuse it when you retry this request
const img = await client.images.generate(
  { model: "x-ai/grok-imagine-image", prompt: "A lighthouse at dusk" },
  { headers: { "Idempotency-Key": key } },
);

重复请求的返回结果

规则

• 作用域。 键归属于发送它的 API 密钥。两个 API 密钥可以使用相同的值，互不影响。
• 有效期。 键在首次请求后 30 分钟内有效。请在此时间内重试。
• 相同请求。 方法、路径和请求体都一致时，两个请求视为相同。JSON 会在解析后比较，因此字段顺序和空白不影响判断。图片或视频是请求体中的 URL，因此比较的是 URL，而不是它所指向的字节。
• 计费。 使用同一个键发出的请求，无论重复多少次，最多只计费一次。由首次请求的结果直接应答的重复请求不产生费用。
• 保证。 同一个键绝不会启动多于一个任务，包括两个重复请求同时到达的情况。

聊天补全

聊天回复不会被重放。使用相同键的重复请求会返回 409，code 为 idempotency_key_replayed，error.generation_id 即首次请求的 id。该请求不会再次运行或计费。请通过 GET /v1/generations/{id} 查询首次请求，以了解其状态、用量和费用。如果首次聊天补全失败且未计费，其键会被释放，重复请求将作为新请求运行。

{
  "error": {
    "message": "A request with this Idempotency-Key already ran as generation 019a1f3c-5b7e-7d21-9c4a-2e8f6b0d3a17. Chat replies are not replayed: GET /v1/generations/019a1f3c-5b7e-7d21-9c4a-2e8f6b0d3a17 for its record.",
    "type": "conflict",
    "code": "idempotency_key_replayed",
    "param": null,
    "generation_id": "019a1f3c-5b7e-7d21-9c4a-2e8f6b0d3a17"
  }
}

OpenAI SDK 的自动重试

OpenAI SDK 默认会对 408、409、429 或 5xx 响应重试两次，除非响应带有响应头 x-should-retry: false。凡是重试会启动第二个任务或产生第二次扣费的响应，Hyperouter 都会附带 x-should-retry: false：

• 同步图像请求的 503 timeout：其任务仍在继续，成功后会计费；请使用其 generation_id 轮询 GET /v1/generations/{id}；
• 任务创建之后出现的 500，例如已完成的图像无法读回时；
• 409 idempotency_key_reused 和 idempotency_key_replayed，重试无法改变其结果。

对于 429、409 idempotency_key_in_use，以及任务创建之前的 5xx，Hyperouter 从不附带该响应头，这些情况可以放心重试。使用 Idempotency-Key 时，所有重试都是安全的。

模型

列出你的账户当前可调用的所有模型，包含价格及所支持的功能。没有已启用服务商的模型不会列出。部分模型需要为你的账户开通权限：开通后才会列出。该接口需要 API 密钥，并列出该密钥所属账户可调用的模型。响应可以缓存 60 秒，仅限在你的客户端缓存。

参数

无。

响应

{
  "data": [{
    "id": "x-ai/grok-4.7",
    "name": "Grok 4.7",
    "kind": "chat",
    "context_length": 500000,
    "architecture": { "input_modalities": ["text", "image"], "output_modalities": ["text"] },
    "pricing": {
      "prompt": "0.000002", "completion": "0.000006", "input_cache_read": "0.0000005",
      "request": "0", "image": "0", "video_second": "0"
    },
    "top_provider": { "context_length": 500000, "max_completion_tokens": 32768 },
    "response_modes": ["sync", "stream"],
    "supported_parameters": ["max_tokens", "temperature", "top_p", "stop", "stream", "tools", "tool_choice", "response_format", "seed", "frequency_penalty", "presence_penalty"],
    "extra_parameters": {}
  }]
}

curl https://api.hyperouter.app/v1/models \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY"

错误

该接口没有专属错误。

聊天模型

价格按每 100 万 token 计：输入 / 缓存输入 / 输出。

对 x-ai/ 模型，提示词达到 200,000 token 及以上的请求，整体按长上下文费率计费，该费率为上表的两倍。deepseek/ 模型在任何提示词长度下都只有一档费率，默认先推理再作答（reasoning_effort: "none" 可将其关闭），其推理过程计入 max_tokens，上限为 384,000。z-ai/glm-5.3 始终会推理：reasoning_effort 取 low、high 或 max，none 会被拒绝。openai/ 模型同样会推理，提示词最多 272,000 token。

聊天补全

为一段对话创建模型响应。请求体即 OpenAI 的 Chat Completions 请求。Hyperouter 新增了 models、provider 和 moderation。

参数

其他字段会被忽略。每个模型在 GET /v1/models 中的 supported_parameters 精确列出了它所接受的参数。Grok 4.20 及更新的模型会忽略 logprobs 和 top_logprobs，因此不在列表中。

provider 对象

默认情况下，Hyperouter 会把每个聊天请求发给该模型价格最低的健康服务商，价格相同时选最近首 token 耗时最低的。反复出错的服务商会被跳过，直到恢复。provider 对象沿用 OpenRouter 的请求格式。

响应

OpenAI 的聊天补全响应。id 即请求 id：可用 GET /v1/generations/{id} 查询。Hyperouter 新增了 provider（完成该请求的服务商的公开名称，例如 xAI）和 usage.cost（费用，单位美元，JSON 数字）。

{
  "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21",
  "object": "chat.completion",
  "model": "x-ai/grok-4.7",
  "provider": "xAI",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Hello! How can I help?" },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 8,
    "total_tokens": 17,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "cost": 0.000066
  }
}

提示词改写类模型只返回一个候选，usage 的 token 数为零，并按每个请求收取固定的 cost。

流式输出

设置 "stream": true 后，响应是 OpenAI 数据块格式的服务器发送事件流，以 data: [DONE] 结束。设置 stream_options.include_usage 时，[DONE] 之前的最后一个数据块带有空的 choices 数组，以及包含 cost 的 usage 对象和 provider 字段。无论你是否请求该数据块，用量都会被收集用于计费。

在第一个 token 到达之前，流每 15 秒发送一次注释行 : processing 以保持连接。SSE 客户端会忽略注释。

只有在发出第一个 token 之前才会回退到其他服务商。如果服务商在流中途失败，流会以 data: {"error": {...}} 结束，随后是 data: [DONE]，并且已生成的 token 仍会计费。

服务商生成的 token 都会计费，无论你是否读取。你中止的流，或你不再等待的回复，并不会在服务商处停止，服务商会继续并按完整回答计费：Hyperouter 会把它读到末尾（最多再读 5 分钟）并按此计费。

已接受请求的服务商可能仍在运行它。如果它随后停止响应（流上 5 分钟没有 token，或超过了 max_tokens 的回复所需时间），或其回答在第一个 token 之前中断，该请求不会被转发给其他服务商：它会返回 503，code 为 timeout 或 upstream_error，并带有 error.generation_id，按其预扣金额计费，其记录上带有 usage_estimated: true。

示例

curl https://api.hyperouter.app/v1/chat/completions \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "x-ai/grok-4.7",
    "models": ["x-ai/grok-4.6"],
    "provider": { "sort": "latency" },
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

错误

图像

两者都沿用 OpenAI 的 Images API，请求体为 JSON。/v1/images/edits 接受 OpenAI 的 JSON 形式：图片是 images，即 1 到 5 个 https URL。OpenAI SDK 的 images.edit 会以 multipart/form-data 发送图片文件，这同样可行：Hyperouter 的边缘节点会将每个文件（PNG、JPEG 或 WebP，每个 20 MiB，每次请求 50 MiB）保存 3 天，对应一个服务商可以获取、无法猜测的 https://api.hyperouter.app/u/... URL，然后按 JSON 运行该请求。视频文件会被拒绝（400 invalid_video）：请以 https URL 发送视频。两者都支持下列通用功能，以及作为顶层字段传入的任意模型专属参数。

参数

模型未列出的通用功能，例如在不支持 seed 的模型上使用 seed，会被拒绝并返回 400 unsupported_parameter。这类参数绝不会被悄悄丢弃，因为那会改变输出和价格。

响应

{
  "created": 1730000000,
  "data": [{ "url": "https://..." }],
  "usage": { "cost": 0.02 },
  "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21"
}

Hyperouter 会将每个结果保存 30 天，因此链接从不指向模型厂商。30 天后记录仍会保留，但其 outputs 为空。

等待结果

• 对 response_modes 包含 sync 的模型，请求最多会等待图像 90 秒，并返回真实状态：带图像的 200，或错误。参数校验、余额和容量方面的错误会先出现，并带有各自的状态码。
• 90 秒后图像仍未就绪时，会返回 503，code 为 timeout，并带有响应头 x-should-retry: false，这样 OpenAI SDK 不会重试并启动第二张图像。任务会继续运行，错误中以 generation_id 携带其 id：请轮询 GET /v1/generations/{id} 获取结果。只有成功时才会计费。如需自行安全地重试，请发送 Idempotency-Key：使用相同键的重试会等待同一个任务。
• response_modes 仅为 async 的模型需要 Prefer: respond-async。缺少时，响应为 400，code 为 async_required。

• 对任何列出 async 的模型，如要避免长时间占用连接，请发送 Prefer: respond-async（RFC 7240）。该请求头可以重复出现，也可以携带其他偏好，例如 Prefer: wait=10, respond-async。你会立即收到 202，响应头为 Preference-Applied: respond-async：

  { "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21", "status": "queued" }

  请轮询 GET /v1/generations/{id}，或接收 image.completed 或 image.failed Webhook。图像的 Webhook 仅对带有该请求头发送的任务触发。

示例

curl https://api.hyperouter.app/v1/images/generations \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "x-ai/grok-imagine-image", "prompt": "A lighthouse at dusk", "n": 1}'

curl https://api.hyperouter.app/v1/images/edits \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "x-ai/grok-imagine-image", "prompt": "make it night",
       "images": [{"image_url": "https://example.com/photo.png"}]}'

错误

失败任务的 message 末尾会在 Provider: 之后附上服务商给出的原因（如有），以便区分提示词被拒、服务商繁忙和服务故障。其中的 URL 会替换为 <url>。

图像模型

部分模型需要为你的账户开通权限。控制台中的模型参考列出了你的账户可调用的所有模型，以及其参数、价格和说明。

视频

视频沿用 OpenAI 的 Videos API。视频是一个任务。创建、编辑、延长或 remix 调用会立即返回 200，并带有状态为 queued 的 Video 对象。你需要轮询 GET /v1/videos/{id} 直到状态变为 completed，或接收 Webhook。Prefer 在此不起作用：视频始终是异步的。

创建视频

所有视频接口的请求体都是 JSON；OpenAI SDK 的 videos.create 附带 input_reference 图片文件的形式同样被接受，文件的处理方式与图像编辑相同。每张图片和每个视频都是指向公共主机的 https URL，并原样传给服务商：服务商必须能够获取它，服务商无法获取或读取的 URL 会使视频以 vendor_rejected 失败，且不收取任何费用。data: URL、http:// URL、IP 地址或内部名称会被拒绝，返回 400 invalid_image 或 400 invalid_video。multipart/form-data 请求体会被拒绝，返回 400 unsupported_content_type。

编辑、延长与 remix

源视频必须已经完成。以 URL 提供的视频是一个 https URL，与图片一样原样传给服务商。如果以 URL 提供视频，对没有固定最大时长的模型，需要提供 seconds。

列出、查询、下载、删除

Video 对象

{
  "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21",
  "object": "video",
  "model": "x-ai/grok-imagine-video",
  "status": "completed",
  "progress": 100,
  "prompt": null,
  "seconds": "8",
  "size": "",
  "created_at": 1730000000,
  "completed_at": 1730000137,
  "expires_at": 1732592000,
  "error": null,
  "remixed_from_video_id": null,
  "usage": { "cost": 0.4, "seconds": 8 }
}

视频按你请求的秒数计费。该金额会预先预扣，任务失败时全额释放。

示例：x-ai/grok-imagine-video

模型 x-ai/grok-imagine-video 根据提示词生成视频，可选择一张图片作为起始画面。seconds 为 1 到 15。价格：每秒 $0.050。

curl https://api.hyperouter.app/v1/videos \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "x-ai/grok-imagine-video",
    "prompt": "She turns to the camera and smiles",
    "input_reference": { "image_url": "https://example.com/portrait.png" },
    "seconds": 8
  }'

{
  "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21",
  "object": "video",
  "model": "x-ai/grok-imagine-video",
  "status": "queued",
  "progress": 0,
  "prompt": "She turns to the camera and smiles",
  "seconds": "8",
  "size": "",
  "created_at": 1730000000,
  "completed_at": null,
  "expires_at": 1732592000,
  "error": null,
  "remixed_from_video_id": null,
  "usage": null
}

该任务收费 8 × $0.050 = $0.40，因此结算后的对象显示 "usage": {"cost": 0.4, "seconds": 8}。

错误

视频模型

控制台中的模型参考列出了你的账户可调用的所有视频模型。

生成记录

返回你的某个请求的记录，任何类型均可：包括状态、用量、扣费、耗时，对于图像和视频还包括输出的签名链接。可用它来轮询以 Prefer: respond-async 发送的图像请求，并核对支出。记录中从不包含提示词和补全文本。Hyperouter 仅为满足法律义务将其加密保存 180 天，任何 API 或控制台页面都不会返回它们（隐私政策）。

参数

响应

{
  "data": {
    "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21",
    "kind": "chat",
    "model": "x-ai/grok-4.7",
    "provider_name": "xAI",
    "status": "done",
    "created_at": "2026-10-24T08:12:00Z",
    "finished_at": "2026-10-24T08:12:02Z",
    "usage": {
      "input_tokens": 120, "output_tokens": 300, "cache_read_tokens": 0,
      "image": 0, "video_seconds": 0, "cost": 0.00204
    },
    "usage_estimated": false,
    "ttft_ms": 320,
    "latency_ms": 2100,
    "error": null,
    "outputs": []
  }
}

curl https://api.hyperouter.app/v1/generations/0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21 \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY"

错误

模型专属参数

部分模型拥有其他模型没有的字段，称为额外参数。你可以像其他字段一样，将它们作为请求体的顶层字段发送。所有 OpenAI SDK 都可以发送它们（Python 中用 extra_body，JavaScript 中用额外属性）。

GET /v1/models 在 extra_parameters 中列出每个模型的额外参数。每一项包含：

控制台中的模型参考介绍了你的账户可调用的每个模型的额外参数。

规则

• 已知参数但该模型不具备时会被拒绝：返回 400 invalid_request_error，code 为 unsupported_parameter，param 设为字段名（例如 loras），message 为 This model does not support "loras".。只要目录中有某个模型声明了该参数，它就是已知参数。同一规则也适用于通用功能（resolution、ratio、audio、seed、negative_prompt、first_frame、last_frame、reference_images、reference_videos、prompt_extend）。不会悄悄丢弃任何参数，因为那会改变输出和价格。
• 类型错误的值会被拒绝并返回 400 invalid_body，param 设为该名称，message 形如 loras must be of type array.。
• 超出 values 的值会被拒绝并返回 400 invalid_body，message 为 <name> must be one of [...]。
• 没有任何模型声明的字段会被忽略，与 OpenAI 的 API 忽略未知字段的做法一致。
• 每个模型都按自己的 schema 校验参数：允许的取值、最小值和最大值、必填字段以及列表长度。超出范围的值返回 400 invalid_body，param 指明字段，例如 seconds must be one of 5, 8.
• 模型厂商不允许的组合，例如参考媒体与关键帧同时使用，会返回 400 invalid_combination 并附上原因。这些检查在任何扣费之前执行。
• 会改变价格的字段，例如 resolution 和 audio，已计入预先预扣的金额，因此预扣金额是精确的。

通用功能

这些字段在所有具备它们的模型上名称相同。模型在 supported_parameters 中列出其接受的字段。

提示词扩写

设置 "prompt_expand": true 后，Hyperouter 会在模型生成前为它改写你的提示词：图像得到更完整的描述，视频得到逐秒的脚本。该功能默认关闭，提示词按原样发送。只有 supported_parameters 中列出 prompt_expand 的模型才接受它，而且只能用于创建图像或视频；用在其他模型上，或用于视频的编辑、延长、重混时，会以 400 unsupported_parameter 拒绝；它也不能与 prompt_extend: true 同时使用（400 invalid_body）。

提示词扩写需由 Hyperouter 为账户开通后才能使用，请提交支持工单申请。开通前，GET /v1/models 不会为任何模型列出 prompt_expand；在提供该功能的模型上发送 prompt_expand: true 会返回 403 permission_error，code 为 feature_not_enabled，param 为 prompt_expand，不会预扣费用，也不会发送给服务商。

• 实际生成的内容。 图像响应、视频对象和 GET /v1/generations/{id} 都带有 expanded_prompt，即模型实际收到的提示词。它在请求后保留 30 天，之后返回 null。prompt 仍是你自己的原文。
• 改写模型。 prompt_expand_model 指定负责改写的聊天模型，默认 x-ai/grok-4.6。它只在 prompt_expand: true 时有效（否则 400 invalid_body）。不存在或不是聊天模型的模型返回 400 unknown_model，你的账户无法调用的模型返回 403 model_not_enabled，两者都发生在冻结任何费用之前。能读取图像的模型会看到请求中的图片；不能读取图像的模型只根据文本改写。
• 价格。 改写在同一个请求上计费，按它实际用掉的 token、以改写模型（prompt_expand_model，缺省为 x-ai/grok-4.6）的 token 价格计算；它可能产生的最高费用会和生成费用一起预先冻结。各模型的详情见模型参考。
• 不执行的情况。 改写失败、超时或无法使用时，按你发送的原始提示词生成，返回 expanded_prompt: null，不收费。
• 语言。 视频台词遵循 locale（未设置时为英语），前提是模型会说该语言。

以聊天模型调用改写

开通了提示词扩写的账户还会获得一个聊天模型，它返回改写结果而不进行生成；你的模型参考中列出了它的名称。在 POST /v1/chat/completions 上调用它，且只发送一条 user 消息：其中的文本是提示词，其 image_url 部分（https URL，最多 5 个）是图片；data: 或 http:// URL 返回 400 invalid_image，param 为 messages。target_model 为必填项，须是列出 prompt_expand 的模型。seconds、locale 和 negative_prompt 为可选项。带图片的视频目标会以该图片作为首帧来编写。它不支持流式输出（stream: true 返回 400 unsupported_parameter），任何其他消息（包括 system 消息）都返回 400 invalid_body。

这个聊天模型始终使用 x-ai/grok-4.6，不接受 prompt_expand_model。choices[0].message.content 是一个 JSON 字符串：{"prompt": "...", "negative_prompt": "..."}，视频目标另含 "beats"（每秒一行）。按 x-ai/grok-4.6 的 token 价格计费，费用见 usage。要求模型输出其指令的提示词返回 400 prompt_rejected；改写结果被拒绝或为空时返回 422 expansion_refused，改写失败时返回 503 upstream_error。以上情况均不收费。

内容审核

moderation 字段沿用 OpenAI 的定义。它适用于 /v1/chat/completions、/v1/images/generations、/v1/images/edits 以及 /v1/videos 及其编辑、延长和 remix 调用。

其他任何值都会被拒绝：400 invalid_request_error，code 为 invalid_body，param 为 moderation，message 为 moderation must be auto or low.

low 需要 Hyperouter 为账户启用后才可使用；请提交支持工单申请。在此之前，带有 low 的请求会返回 403 permission_error，code 为 moderation_not_enabled，param 为 moderation，且不会发送给服务商。

{
  "model": "qwen/qwen-image-2.0",
  "prompt": "...",
  "moderation": "low"
}

响应不会说明是否使用了该关闭选项。服务条款中的政策仍然适用。被模型厂商的过滤器拒绝的请求会以 400 content_rejected 失败，且不收费。

Webhook

你无需轮询，可以让自己的某个端点在任务结束时接收请求。请在控制台中添加端点。其格式沿用 OpenAI 的 Webhook，并采用 Standard Webhooks 方案签名，因此 OpenAI SDK 可以直接校验。

载荷只携带 id，从不包含结果、提示词或费用。请使用你的 API 密钥获取对象：data.id 就是 GET /v1/videos/{id} 和 GET /v1/generations/{id} 所接受的 id。对于原始任务，它是创建请求返回的 X-Generation-Id。

{
  "id": "evt_0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21",
  "object": "event",
  "type": "video.completed",
  "created_at": 1761300000,
  "data": { "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21" }
}

请求头与校验

每次投递都是一个 POST 请求，带有 content-type: application/json 以及以下请求头：

• webhook-id：事件 id。每次重试都相同，可用它去重。
• webhook-timestamp：Unix 秒。
• webhook-signature：v1, 加上 id.timestamp.body 的 base64 HMAC-SHA256，以该端点的密钥作为 key。

签名密钥以 whsec_ 开头。它在你创建端点和轮换密钥时仅显示一次。请在解析之前，对原始请求体进行校验：

// Node, with the OpenAI SDK
const event = client.webhooks.unwrap(rawBody, req.headers, process.env.HYPEROUTER_WEBHOOK_SECRET);
if (event.type === "video.completed") {
  const video = await client.videos.retrieve(event.data.id);
}

签名校验失败时 unwrap 会抛出异常；请对这类请求返回错误状态码。后续调用使用与本 API 其余部分相同的 base URL。

端点、重试与限制

• 端点必须是 https，端口为 443（或不写端口），且使用主机名而非 IP 地址。该主机必须解析到公共地址；Hyperouter 在连接时会再次检查。不会跟随重定向。
• 一个账户最多有 10 个端点。每个端点可选择自己需要的事件类型。
• 10 秒内返回 2xx 即视为成功。其他情况会在约 5 秒、1 分钟、5 分钟、30 分钟、2 小时、5 小时、10 小时和 10 小时后重试，之后该次投递被标记为失败。
• 如果某个端点的所有投递连续 3 天失败，该端点会被停用，控制台会说明原因。修复接收端后请重新启用。
• 控制台会列出每个端点的投递记录，包含状态、尝试次数、最近一次 HTTP 状态码和最近一次错误。它提供“重新发送”（事件 id 不变）和“发送测试事件”，后者会投递一个 webhook.test 事件，其 data.id 为该端点的 id。

MCP 服务器

AI 助手可以通过模型上下文协议（MCP）操作你的 Hyperouter 账户。该服务器管理控制台功能：API 密钥、活动记录、额度、工单、Webhook 和模型列表。它不运行模型。模型调用仍通过 API 密钥发往 /v1。

该服务器使用 Streamable HTTP 和 JSON-RPC 2.0。支持 MCP 版本 2025-11-25 和 2025-06-18。它是无状态的：没有会话，GET /mcp 返回 405。

访问令牌

MCP 客户端使用控制台访问令牌进行认证，而不是 API 密钥。

• 在控制台中创建令牌。为它设置名称、作用域，还可以选择设置过期时间。
• 令牌以 hr_dt_ 开头，仅显示一次。Hyperouter 只保存其哈希值。
• 一个账户用户最多可持有 25 个未过期且未吊销的令牌。在控制台中吊销令牌即可立即使其失效。
• 令牌不能用于 /v1，API 密钥也不能用于 /mcp。
• 令牌以创建它的用户的身份行事，拥有该用户的权限。每条消息都会检查权限，因此角色变更在下一次调用时生效。

请以 Bearer 令牌的形式发送令牌：

Authorization: Bearer hr_dt_...

协议

通知，或对服务器的响应，会返回无响应体的 202。JSON-RPC 批量请求会被拒绝并返回错误 -32600。单条消息不得超过 1 MiB。未知的 MCP-Protocol-Version 请求头会返回 400。浏览器请求必须来自 https://dash.hyperouter.app；不发送 Origin 请求头的客户端不受影响。

curl https://api.hyperouter.app/mcp \
  -H "Authorization: Bearer $HYPEROUTER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

工具

tools/list 返回当前的工具集。每个工具对应一个控制台路由，并带有描述其参数的 JSON Schema。这些工具涵盖：

• 账户与密钥：get_me、list_api_keys、create_api_key、update_api_key。
• 活动与额度：list_activity、get_activity、get_activity_summary、get_credits、get_topup_fee。
• 工单：list_tickets、create_ticket、get_ticket、reply_to_ticket、close_ticket。
• Webhook：list_webhooks、create_webhook、update_webhook、rotate_webhook_secret、delete_webhook、list_webhook_deliveries、resend_webhook_delivery、send_test_webhook。
• 模型：list_models。
• 带有 admin_ 前缀的工作人员工具，仅对拥有工作人员权限的用户显示。

工具以一个文本内容项作答，其内容是该路由的 JSON 响应体。路由失败时，结果带有 isError: true，文本为 <message> (<code>, HTTP <status>)。未知的工具，或你的令牌看不到的工具，会返回 JSON-RPC 错误 -32602。

审批

敏感的写操作（例如为账户入账）不会立即执行。工具不会执行它，而是返回 status 为 approval_required 的结果，以及控制台上的 approval_url。用户打开该链接，通过二次验证并批准该操作。审批在 24 小时后过期。用户也可以拒绝。

计费与限制

• 请求由预付的美元余额支付，按实际处理该请求的服务商的标价计费，不加价。
• 先预扣，再结算。 请求运行之前，Hyperouter 会预扣其最高可能产生的费用：聊天为你的输入加 max_tokens，图像为请求的数量，视频为请求的秒数。请求结束后，按实际用量扣费，其余预扣金额释放。余额不会变为负数。
• 失败的请求，或失败的图像或视频任务，不收费。失败的回退尝试也不收费。
• 每个响应都以 usage.cost 给出其费用，即以美元计的 JSON 数字：聊天、图像、已结算的视频，以及 GET /v1/generations/{id} 中均是如此。控制台会显示每个请求，以及按日、按模型和按密钥统计的支出。
• 金额是精确的：货币以十亿分之一美元为单位计数，绝不通过浮点数取整。GET /v1/models 中的价格是十进制字符串。
• 目前充值为人工处理。请在控制台中提交充值申请，附上金额、付款凭证编号和付款截图。工作人员核对付款后为你的余额入账，并在同一工单中回复。
• 充值手续费。 每笔充值收取所付金额 5.5% 的手续费，最低 $0.80，在充值入账时扣除：付款 $100 入账 $94.50，付款 $10 入账 $9.20。当前生效的手续费会在你申请充值之前显示在额度页面上，你的历史记录中的每笔充值也会显示所付金额和手续费。请求本身不收取手续费。

速率限制

每个账户都有每分钟请求数和同时进行中的请求数两项限制。两者都将账户下的所有 API 密钥合并计算，并适用于每一个启动工作的请求：聊天补全、图像和视频的创建，以及原始创建请求。读取结果（GET /v1/generations/{id}、GET /v1/videos…、原始任务轮询）不计入；原始轮询按服务商单独计数，上限与每分钟请求数相同。

你的等级取决于你累计的充值总额（不含充值手续费）：

你当前的限制显示在额度页面上。以上为默认值；工作人员可以针对整个平台或单个账户调整，调整在一分钟内生效。

超出任一限制时，请求会在预扣或转发任何内容之前被拒绝，返回 429，type: rate_limit_error，code: rate_limited，以及以秒为单位的 Retry-After 响应头。message 会指明你触及的限制。即使请求被拒绝，也会计入当前这一分钟。进行中的请求（包括流式请求）在结束之前一直计数。

为防止密钥被猜测，Hyperouter 按客户端地址统计 API 密钥校验失败次数。一分钟内超过 30 次，该地址的所有 /v1 路由将被屏蔽 15 分钟：返回 429、rate_limit_error、too_many_auth_failures，并带有 Retry-After。使用有效密钥也无法解除屏蔽。

支持

如有计费、充值和 API 方面的问题，请在控制台中提交工单，工作人员会在同一对话中回复。你也可以发邮件至 [email protected]。反馈具体请求时，请附上响应中的 id。