模型发现

使用模型页面或模型 API 查看可用的文本模型。模型元数据包括厂商、服务提供商、模态、上下文长度、支持的 API 系列、支持的能力、可用性、账户级限制和积分定价。

端点： GET /v1/models 用途： 列出当前账户可用的模型。

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

能力矩阵

API 系列兼容性矩阵

认证

每个 API 请求都使用 bearer token。请将密钥存储在服务器端环境变量中，团队访问变更时及时轮换，并记录请求 ID 以便调试。

密钥安全建议

1. 将 API 密钥保留在服务器端。切勿在浏览器或移动客户端代码中暴露密钥。
2. 为开发、预发布、生产和第三方集成使用不同的密钥。
3. 在可用时按环境、服务、客户或租户限定密钥范围。
4. 在员工离职、供应商访问变更或疑似泄露后轮换密钥。
5. 将密钥存储在密钥管理器或环境变量中，而非源代码中。

编程智能体

BasicRouter 兼容支持 OpenAI 兼容或 Anthropic 兼容 API 端点的编程智能体和 AI 开发工具。使用 mwf/coding-auto 等路由别名，BasicRouter 即可路由到最佳的可用编程模型，无需开发者更改工具配置。

通用 OpenAI 兼容配置

此配置适用于 Cursor、Codex、Hermes、OpenClaw、Continue、Aider、Cline、基于 LangChain 的智能体、基于 LlamaIndex 的智能体以及自定义 OpenAI 兼容智能体运行时。

export OPENAI_BASE_URL="https://api.basicrouter.ai/api/v1"
export OPENAI_API_KEY="$BASICROUTER_API_KEY"
export OPENAI_MODEL="mwf/coding-auto"

通用 Anthropic 兼容配置

此配置适用于 Claude 兼容客户端以及期望 Anthropic Messages 格式的工具。

export ANTHROPIC_BASE_URL="https://api.basicrouter.ai/api/anthropic"
export ANTHROPIC_API_KEY="$BASICROUTER_API_KEY"
export ANTHROPIC_MODEL="mwf/coding-auto"

推荐的智能体模型

Cursor 快速指南

使用 OpenAI 兼容端点。

Base URL: https://api.basicrouter.ai/api/v1
API Key:  BASICROUTER_API_KEY
Model:    mwf/coding-auto

推荐步骤：

1. 打开 Cursor 设置。
2. 添加或启用 OpenAI 兼容 API 密钥配置。
3. 将 OpenAI base URL 覆盖设置为 https://api.basicrouter.ai/api/v1。
4. 添加自定义模型，例如 mwf/coding-auto、 mwf/coding-fast 或 mwf/coding-long。
5. 使用支持流式输出和工具调用的模型以获得最佳智能体表现。

故障排查：

Claude Code 快速指南

使用 Anthropic 兼容网关端点。

export ANTHROPIC_BASE_URL="https://api.basicrouter.ai/api/anthropic"
export ANTHROPIC_API_KEY="$BASICROUTER_API_KEY"
export ANTHROPIC_MODEL="mwf/coding-auto"

BasicRouter 为 Claude Code 和 Anthropic SDK 兼容性提供此 Anthropic 兼容路径：

POST /api/v1/messages

推荐要求：

Codex 快速指南

将 BasicRouter 作为自定义 OpenAI 兼容模型提供商使用。

示例提供商配置：

[model_providers.basicrouter]
name = "BasicRouter"
base_url = "https://api.basicrouter.ai/api/v1"
env_key = "BASICROUTER_API_KEY"
wire_api = "responses"

model_provider = "basicrouter"
model = "mwf/coding-auto"

环境变量：

export BASICROUTER_API_KEY="br_xxx"

推荐模型：

故障排查：

Hermes 快速指南

除非你的 Hermes 部署配置了其他协议，否则使用 OpenAI 兼容端点。

export OPENAI_BASE_URL="https://api.basicrouter.ai/api/v1"
export OPENAI_API_KEY="$BASICROUTER_API_KEY"
export OPENAI_MODEL="mwf/coding-auto"

推荐模型策略：

OpenClaw 快速指南

使用 OpenAI 兼容端点进行 OpenAI 风格智能体运行时配置。

export OPENAI_BASE_URL="https://api.basicrouter.ai/api/v1"
export OPENAI_API_KEY="$BASICROUTER_API_KEY"
export OPENAI_MODEL="mwf/coding-auto"

如果 OpenClaw 支持多提供商，请将 BasicRouter 配置为 OpenAI 兼容提供商，并使用 BasicRouter 路由别名进行模型选择。

{
  "provider": "openai-compatible",
  "base_url": "https://api.basicrouter.ai/api/v1",
  "api_key_env": "BASICROUTER_API_KEY",
  "model": "mwf/coding-auto"
}

智能体兼容性检查清单

控制台使用

BasicRouter 控制台是 API 访问、模型可用性、路由策略、用量可见性和计费管理的运维控制面板。它为账户管理员提供密钥、模型、请求、积分和生产模型流量账户级控制的集中视图。

管理 API 密钥

在控制台中创建、轮换、吊销和标记 API 密钥。为开发、预发布、生产和各个服务使用不同的密钥，以便按环境或应用审计和隔离用量。

模型列表

使用模型页面查看账户可用的模型。每个模型条目可能包括厂商、服务提供商、模态、支持的 API 系列、上下文长度、能力标志、可用性状态和定价信息。

对于生产应用，启用流量前请验证模型能力。部分参数和功能取决于模型，可能并非在所有 API 系列中都受支持。

用量与日志

用量与日志视图提供 API 流量的运维可见性。团队可以检查请求量、所选模型、解析的路由目标、积分消耗、延迟、错误码和请求 ID。

• 排查失败的请求。
• 识别高成本工作负载。
• 比较不同应用和环境之间的模型用量。
• 验证路由和兜底行为。
• 调查延迟或提供商可用性问题。
• 联系支持时提供请求 ID。

每个 API 响应包含或暴露一个 BasicRouter 请求 ID。请将此 ID 存储在应用日志中，以提高生产调试和支持升级的效率。

兜底

兜底是 BasicRouter 的弹性机制。当主模型或路由策略失败时，系统自动切换到备用模型以继续处理请求。这使你的应用保持响应能力，并最大限度地降低服务中断的风险。

为什么兜底很重要

在生产环境中，模型服务可能会遇到许多不可预测的问题：

• 模型服务故障：上游 API 暂时不可用或超时。
• 性能波动：模型高负载导致响应缓慢或失败。
• 路由失败：智能路由选择的所有候选模型均不可用。

兜底通过提供可靠的备用路径来保持应用的可用性。

核心优势

全局兜底模型配置

BasicRouter 支持从控制台后端设置全局兜底模型。所有请求在失败时自动使用此模型作为备用。

配置方法：

1. 前往 BasicRouter 策略设置页面。
2. 找到 默认兜底模型 设置。
3. 从下拉列表中选择你的全局兜底模型。
4. 保存设置以立即生效。

全局配置的优势：

• 无需修改代码：配置一次即全局生效，无需在每个请求上重复设置。
• 集中管理：在一个位置管理兜底策略，便于调整和监控。
• 简化维护：降低代码复杂度和配置出错的可能性。
• 灵活覆盖：请求级兜底配置优先级更高，可为特定场景覆盖全局设置。

请求级兜底配置

对于特定业务场景，可在单个请求上指定兜底模型以覆盖全局配置。

使用 router.fallBackModels 参数指定兜底模型：

{
  "model": "claude-sonnet-4",
  "messages": [
    {
      "role": "user",
      "content": "Explain what quantum computing is"
    }
  ],
  "router": {
    "fallBackModels": ["glm-5.2"]
  }
}

优先级规则

当存在多个兜底配置时，优先级从高到低为：

1. 请求级 router.fallBackModels：在单个请求上指定的兜底模型。
2. 全局默认兜底模型：在控制台配置的全局兜底模型。
3. 无兜底：如果两者都未配置，请求失败时返回错误。

账户管理

根据账户类型，控制台可能包括账户级模型启用、经销商或分销商控制、计费配置和访问设置。管理员可使用这些控制项，使模型访问、用量可见性和计费责任与应用、客户账户或业务单元保持一致。

生产运维检查清单

计费与积分

BasicRouter 在文本、图像、视频和其他支持的模型工作负载中采用基于积分的计费模型。积分为多模型和多提供商用量提供统一单位，使团队能够跨模态和 API 系列一致地管理消耗。

详细的模型定价可在模型页面或通过模型元数据 API 获取。定价可能因模型、提供商、模态、分辨率、token 类型、输出长度、任务时长、账户类型和商业协议而异。

充值与钱包

账户可添加按量付费钱包积分以获得灵活用量。除非账户适用自定义计费规则，否则钱包积分在月度套餐积分和资源包消耗完毕后使用。

除非适用商业条款另有规定，钱包积分不会过期。充值按量付费钱包时会收取服务费。

月度套餐和资源包

每个用户或账户可选择一个有效的月度套餐。月度套餐在计费周期内提供约定数量的用量容量、商业条款和账户级访问配置。

用户还可购买多个资源包以获得额外用量容量。资源包可将承诺用量与按量付费钱包余额分开，适用于大批量文本、图像、视频或专用工作负载用量。

扣费顺序

除非配置了自定义计费规则，否则积分按以下顺序扣减：

对于有自定义商业条款的账户，扣费顺序、过期规则、包含用量和定价可能不同。账户特定规则会显示在控制台或通过商业协议提供。

自定义定价

可为每个用户或账户自定义定价。企业客户、经销商账户、分销商账户和大批量客户可能符合自定义定价条件。请联系销售获取报价。

自定义定价可按账户、模型、提供商、模态、区域、用量或商业协议配置。启用自定义定价后，控制台和计费 API 会在可用时反映账户特定的定价和扣减规则。

计价单位

不同模型模态使用不同的计量单位。BasicRouter 根据模型定价规则将这些单位转换为积分。

计价单位可能因模型而异。在生产环境中启用模型前，请务必参考模型详情页面或定价元数据。

用量归因

BasicRouter 用量可按账户、API 密钥、模型、模态或时间范围查看。这使团队能够将成本归因到应用、环境、客户或内部业务单元。

积分余额

查看账户可用的积分数量。余额分为三个按顺序扣减的钱包：月度套餐积分、购买的资源包和按量付费钱包。还提供一个合并资源总量（月度套餐 + 资源包，不含按量付费），用于将包含用量与充值消费分开跟踪。

以编程方式获取此信息，请参见 API 参考中的 GET /v1/billing/balance。

用量详情

查看分页的、按时间顺序排列的用量记录列表，用于报告、监控和内部成本分摊。每条记录显示模型、模型类型（文本、图像或视频）、扣减的积分，以及每次扣减来自哪个钱包的明细。结果可筛选到特定时间范围。

以编程方式获取此信息，请参见 API 参考中的 GET /v1/usage。

交易记录

使用交易记录查看积分变动，包括充值、套餐分配、资源包发放、用量扣减、调整和管理修正。

以编程方式获取此信息，请参见 API 参考中的 GET /v1/billing/transactions。

失败请求与退款

校验错误、认证错误和权限错误通常不计费，因为未发生模型执行。到达上游模型或生成部分输出的请求可能会消耗积分，具体取决于模型、提供商和响应状态。

对于异步图像和视频任务，计费行为取决于任务是已接受、已开始、已完成、已失败还是已取消。任务详情响应在消耗积分时会包含用量信息。

充值、月度套餐、资源包和已消耗的积分不可退款，除非适用商业协议另有规定或法律要求。

API 参考

通用约定

Base URL

所有端点均提供在 /v1 前缀下。

认证

对 /v1/* 端点的调用使用 API Key 认证（非 JWT）。API Key 通过以下请求头传递：

缺少或无效的密钥返回 401。

余额预检

所有调用模型的端点在执行前都会进行余额预检：

• 余额不足返回 Insufficient credit，映射为：
  • OpenAI 协议：HTTP 400， code = insufficient_quota
  • Anthropic 协议：HTTP 402，type = billing_error
• 部分端点还会按模型估算最低成本以进行第二次预检。

POST https://api.basicrouter.ai/api/v1/chat/completions

OpenAI Chat Completions 兼容端点。支持流式和非流式、工具调用、JSON 模式和多模态输入。

Message 字段：

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/chat/completions \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "glm-5.2",
    "messages": [{"role": "user", "content": "Describe Hangzhou in one sentence."}],
    "stream": false,
    "temperature": 0.7
  }'

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1721380000,
  "model": "glm-5.2",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Hangzhou is ..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 12, "completion_tokens": 18, "total_tokens": 30}
}

响应字段（非流式）：

流式响应示例：

data: {"object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant","content":"..."}}]}

data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"..."}}]}

data: [DONE]

POST https://api.basicrouter.ai/api/v1/responses

OpenAI Responses 兼容端点。使用 input 代替 messages，使用 instructions 代替系统消息，使用 text 块代替 response_format。

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/responses \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "glm-5.2",
    "input": "Describe Hangzhou in one sentence.",
    "instructions": "Be concise.",
    "stream": false
  }'

{
  "id": "resp_xxx",
  "object": "response",
  "model": "glm-5.2",
  "status": "completed",
  "created_at": 1721380000,
  "output": [
    {
      "id": "msg_xxx",
      "type": "message",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "Hangzhou is ..."}],
      "status": "completed"
    }
  ],
  "usage": {"input_tokens": 12, "output_tokens": 18, "total_tokens": 30}
}

响应字段（非流式）：

流式遵循 Responses API 事件：

POST https://api.basicrouter.ai/api/v1/messages

Anthropic Messages 兼容端点。接受 x-api-key 和 anthropic-version: 2023-06-01 请求头。内容块支持 text、image、tool_use、tool_result、 thinking 和 redacted_thinking。

图片块示例：

{ "type": "image", "source": { "type": "base64", "media_type": "...", "data": "..." } }
{ "type": "image", "source": { "type": "url", "url": "..." } }

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/messages \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "claude-sonnet-4.6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Describe Hangzhou in one sentence."}]
  }'

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4.6",
  "content": [{"type": "text", "text": "Hangzhou is ..."}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 12, "output_tokens": 18}
}

响应字段（非流式）：

GET https://api.basicrouter.ai/api/v1/models

返回所有已上线、已启用的 API 模型。

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "glm-5.2",
      "object": "model",
      "display_name": "glm-5.2",
      "created": 1721380000,
      "owned_by": "Zai",
      "input_modalities": ["text", "image"],
      "output_modalities": ["text"],
      "context_length": 128000
    }
  ]
}

每个模型条目（data[]）字段：

GET https://api.basicrouter.ai/api/v1/models/{model}

返回单个模型，结构与列表条目相同。模型不存在时返回 HTTP 404。

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/models/gpt-5.5 \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

成功响应：单个模型对象，字段与 /v1/models 列表条目相同。

当模型不存在时，返回 HTTP 404：

{"error": {"message": "The model 'xxx' does not exist", "type": "invalid_request_error", "code": "invalid_model_error"}}

GET https://api.basicrouter.ai/api/v1/image-models

在调用 /v1/image-generations 之前，查询图像模型支持的分辨率、比例和最大数量。无需认证。

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/image-models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2",
      "object": "image_model",
      "displayName": "GPT Image 1",
      "description": "...",
      "icon": "...",
      "created": 1721380000,
      "maxCount": 4,
      "fileMax": 10,
      "resolutions": ["720p", "1080p"],
      "ratios": ["1:1", "3:2"]
    }
  ]
}

GET https://api.basicrouter.ai/api/v1/video-models

在调用 /v1/video-generations 之前，查询视频模型支持的 videoType 值、时长范围、分辨率和比例。无需认证。

VideoTypeOption 字段：

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/video-models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "sora-2",
      "object": "video_model",
      "displayName": "Sora 2",
      "description": "...",
      "icon": "...",
      "created": 1721380000,
      "allowedVideoTypes": [
        {"code": 1, "name": "text-to-video"},
        {"code": 2, "name": "image-to-video"},
        {"code": 3, "name": "image-to-video (first/last frame)"}
      ],
      "videoDurationMin": 5,
      "videoDurationMax": 10,
      "videoDurationSuggest": [5, 8, 10],
      "resolutions": ["1080p", "720p"],
      "ratios": ["16:9", "9:16"],
      "fileMax": 5
    }
  ]
}

POST https://api.basicrouter.ai/api/v1/image-generations

异步提交图像生成任务。立即返回 taskId；通过轮询 GET /v1/image-generations/{taskId} 或通过 callbackUrl webhook 获取结果。

model、支持的 resolution / ratio 值、 count 上限和参考图片上传限制（fileMax）必须先从 GET /v1/image-models 获取。仅接受该模型规格中公布的值。

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/image-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-4.5",
    "text": "A cat drinking water by the river",
    "count": 1,
    "resolution": "2k",
    "ratio": "1:1",
    "imageUrls": []
  }'

{
  "code": 200,
  "message": "image task is commit",
  "data": {"taskId": "img_xxx"}
}

错误响应：

// Insufficient credit
{ "code": 500, "message": "Insufficient credit" }

// Model not found
{ "code": 404, "message": "Model not found: xxx" }

GET https://api.basicrouter.ai/api/v1/image-generations/{taskId}

轮询图像生成任务。status 为 pending / success / failed。images 是图片 URL 数组的 JSON 字符串；text 携带模型附加的文本描述（如 Gemini 多模态输出），否则为 null。

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/image-generations/img_xxx \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "img_xxx",
    "status": "success",
    "errorMessage": null,
    "images": "[\"https://.../1.png\"]",
    "text": null
  }
}

响应 data 字段：

任务未找到：

{ "code": 500, "message": "task not found" }

如果提交时提供了 callbackUrl，服务器会通过 webhook 推送最终的 success / failed 结果，数据结构相同。

完整示例（提交 + 轮询）

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class ImageGenerationExample {
  private static final String BASE = "https://api.basicrouter.ai/api/v1";
  private static final String API_KEY = System.getenv("BASICROUTER_API_KEY");

  public static void main(String[] args) throws Exception {
    HttpClient http = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10)).build();

    // 1. Submit the task.
    String body = "{"
        + "\"model\":\"seedream-4.5\","
        + "\"text\":\"A cat drinking water by the river\","
        + "\"count\":1,"
        + "\"resolution\":\"2k\","
        + "\"ratio\":\"1:1\","
        + "\"imageUrls\":[]"
        + "}";
    HttpResponse<String> submit = http.send(
        HttpRequest.newBuilder(URI.create(BASE + "/image-generations"))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
        HttpResponse.BodyHandlers.ofString());

    String taskId = extract(submit.body(), "taskId");
    System.out.println("taskId = " + taskId);

    // 2. Poll until terminal status.
    String status = "pending";
    while ("pending".equals(status)) {
      Thread.sleep(15_000L);
      HttpResponse<String> poll = http.send(
          HttpRequest.newBuilder(URI.create(BASE + "/image-generations/" + taskId))
              .header("Authorization", "Bearer " + API_KEY).GET().build(),
          HttpResponse.BodyHandlers.ofString());
      status = extract(poll.body(), "status");
      System.out.println("status = " + status);
    }

    if (!"success".equals(status)) {
      throw new RuntimeException("image generation failed: " + status);
    }
    // images is a JSON-stringified array of URLs.
    String images = extract(pollResult(http, taskId), "images");
    System.out.println("images = " + images);
  }

  // Minimal JSON field extractor — use Jackson/Gson in production.
  private static String extract(String json, String field) {
    int i = json.indexOf("\"" + field + "\":");
    if (i < 0) return null;
    i += field.length() + 3;
    if (json.charAt(i) == '\"') {
      int end = json.indexOf('\"', i + 1);
      return json.substring(i + 1, end);
    }
    int end = i;
    while (end < json.length() && "0123456789.".indexOf(json.charAt(end)) >= 0) end++;
    return json.substring(i, end);
  }

  private static String pollResult(HttpClient http, String taskId) throws Exception {
    return http.send(HttpRequest.newBuilder(URI.create(BASE + "/image-generations/" + taskId))
        .header("Authorization", "Bearer " + API_KEY).GET().build(),
        HttpResponse.BodyHandlers.ofString()).body();
  }
}

import os
import time
import requests

BASE = "https://api.basicrouter.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['BASICROUTER_API_KEY']}"}

# 1. Submit the task.
resp = requests.post(
    f"{BASE}/image-generations",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "model": "seedream-4.5",
        "text": "A cat drinking water by the river",
        "count": 1,
        "resolution": "2k",
        "ratio": "1:1",
        "imageUrls": [],
    },
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print(f"taskId = {task_id}")

# 2. Poll until terminal status.
while True:
    time.sleep(15)
    poll = requests.get(f"{BASE}/image-generations/{task_id}", headers=HEADERS)
    poll.raise_for_status()
    data = poll.json()["data"]
    status = data["status"]
    print(f"status = {status}")
    if status != "pending":
        break

if status != "success":
    raise RuntimeError(f"image generation failed: {data.get('errorMessage')}")

# images is a JSON-stringified array of URLs.
import json
images = json.loads(data["images"])
print(f"images = {images}")

POST https://api.basicrouter.ai/api/v1/video-generations

异步提交视频生成任务。立即返回 taskId；通过轮询 GET /v1/video-generations/{taskId} 或通过 callbackUrl webhook 获取结果。

model、允许的 videoType 值、时长范围 （videoDurationMin/Max）、支持的 resolution / ratio 和参考素材上传限制（fileMax）必须先从 GET /v1/video-models 获取。仅接受该模型 allowedVideoTypes 中列出的 videoType 代码。

各 videoType 示例：

1. 文生视频（videoType=1）

仅从文本提示词生成视频；无需参考素材。

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 1,
    "text": "A cat jumping on a bed",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "seedance-2.0"
  }'

2. 图生视频 - 首帧（videoType=2）

在 imageUrls 中提供单张起始帧；模型从该帧开始生成视频。

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 2,
    "text": "Happily shaking head",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "seedance-2.0",
    "imageUrls": ["https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/first-frame.png"]
  }'

3. 图生视频 - 首尾帧（videoType=3）

在 imageUrls 中提供首帧和尾帧（顺序： [首帧, 尾帧]）；模型在两帧之间生成过渡视频。

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 3,
    "text": "Put on the hat",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "seedance-2.0",
    "imageUrls": [
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/first-frame.png",
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/last-frame.png"
    ]
  }'

4. 图生视频 - 参考（videoType=4）

在 imageUrls 中提供一张或多张参考图；模型使用其风格/内容作为参考（而非强制首/尾帧）来生成视频。

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 4,
    "text": "Two cats playing together",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "kling-v3-omni-video",
    "imageUrls": [
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/ref-1.png",
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/ref-2.png"
    ]
  }'

5. 全部参考（videoType=5）

混合图片 / 视频 / 音频参考。在提示词中按位置引用素材：imageUrls 中第 1 项为 @图片 1，videoUrls 中第 1 项为 @视频 1，audioUrls 中第 1 项为 @音频 1。videoUrls 也接受纯 URL 字符串。

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 5,
    "text": "Use the first-person framing of @视频 1 and @音频 1 as background music. First-person tea ad; start frame is @图片 1 ... end frame is @图片 2.",
    "model": "seedance-2.0",
    "imageUrls": [
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg",
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"
    ],
    "videoUrls": ["https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"],
    "audioUrls": ["https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 11
  }'

提交响应（五种类型通用）：

{
  "code": 200,
  "message": "success",
  "data": {"taskId": "vid_xxx"}
}

GET https://api.basicrouter.ai/api/v1/video-generations/{taskId}

轮询视频生成任务。status 为 pending / success / failed；videoUrl 是生成的视频 URL，lastFrameUrl 是尾帧 URL（图生视频场景）。

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/video-generations/vid_xxx \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "code": 200,
  "message": "success",
  "data": {
    "status": "success",
    "videoUrl": "https://.../out.mp4",
    "lastFrameUrl": null,
    "message": null
  }
}

响应 data 字段：

如果提交时提供了 callbackUrl，服务器会通过 webhook 推送最终结果，数据结构相同。

完整示例（提交 + 轮询）

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class VideoGenerationExample {
  private static final String BASE = "https://api.basicrouter.ai/api/v1";
  private static final String API_KEY = System.getenv("BASICROUTER_API_KEY");

  public static void main(String[] args) throws Exception {
    HttpClient http = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10)).build();

    // 1. Submit the task (videoType=1: text-to-video).
    String body = "{"
        + "\"videoType\":1,"
        + "\"text\":\"A cat jumping on a bed\","
        + "\"resolution\":\"480p\","
        + "\"ratio\":\"16:9\","
        + "\"duration\":4,"
        + "\"model\":\"seedance-2.0\""
        + "}";
    HttpResponse<String> submit = http.send(
        HttpRequest.newBuilder(URI.create(BASE + "/video-generations"))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
        HttpResponse.BodyHandlers.ofString());

    String taskId = extract(submit.body(), "taskId");
    System.out.println("taskId = " + taskId);

    // 2. Poll until terminal status. Video tasks take longer — poll every 20s.
    String status = "pending";
    String lastBody = null;
    while ("pending".equals(status)) {
      Thread.sleep(20_000L);
      HttpResponse<String> poll = http.send(
          HttpRequest.newBuilder(URI.create(BASE + "/video-generations/" + taskId))
              .header("Authorization", "Bearer " + API_KEY).GET().build(),
          HttpResponse.BodyHandlers.ofString());
      lastBody = poll.body();
      status = extract(lastBody, "status");
      System.out.println("status = " + status);
    }

    if (!"success".equals(status)) {
      throw new RuntimeException("video generation failed: " + status);
    }
    String videoUrl = extract(lastBody, "videoUrl");
    System.out.println("videoUrl = " + videoUrl);
  }

  // Minimal JSON field extractor — use Jackson/Gson in production.
  private static String extract(String json, String field) {
    int i = json.indexOf("\"" + field + "\":");
    if (i < 0) return null;
    i += field.length() + 3;
    if (json.charAt(i) == '\"') {
      int end = json.indexOf('\"', i + 1);
      return json.substring(i + 1, end);
    }
    int end = i;
    while (end < json.length() && "0123456789.".indexOf(json.charAt(end)) >= 0) end++;
    return json.substring(i, end);
  }
}

import os
import time
import requests

BASE = "https://api.basicrouter.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['BASICROUTER_API_KEY']}"}

# 1. Submit the task (videoType=1: text-to-video).
resp = requests.post(
    f"{BASE}/video-generations",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "videoType": 1,
        "text": "A cat jumping on a bed",
        "resolution": "480p",
        "ratio": "16:9",
        "duration": 4,
        "model": "seedance-2.0",
    },
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print(f"taskId = {task_id}")

# 2. Poll until terminal status. Video tasks take longer — poll every 20s.
while True:
    time.sleep(20)
    poll = requests.get(f"{BASE}/video-generations/{task_id}", headers=HEADERS)
    poll.raise_for_status()
    data = poll.json()["data"]
    status = data["status"]
    print(f"status = {status}")
    if status != "pending":
        break

if status != "success":
    raise RuntimeError(f"video generation failed: {data.get('message')}")

print(f"videoUrl = {data['videoUrl']}")
if data.get("lastFrameUrl"):
    print(f"lastFrameUrl = {data['lastFrameUrl']}")

GET https://api.basicrouter.ai/api/v1/billing/balance

返回账户余额，分为三个钱包：月度套餐、资源包和按量付费积分。

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/billing/balance \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "totalCredit": 128.50,
  "totalResourceCredit": 30.00,
  "wallets": {
    "monthlyPlan": {"id": "pkg_xxx", "credit": 50.00, "name": "Monthly plan"},
    "resourcePacks": [
      {"id": "rp_xxx", "credit": 30.00, "name": "Video resource pack"}
    ],
    "payAsYouGo": 48.50
  }
}

响应字段：

WalletDetailVO 字段：：

GET https://api.basicrouter.ai/api/v1/usage

分页的模型调用计费详情，按价格 （priceSnapshotId）快照，按订单创建时间倒序排列。仅返回正常扣费记录 （reason = model usage）。

查询参数：

curl --request GET \
  --url "https://api.basicrouter.ai/api/v1/usage?page=1&size=20&startTime=2026-07-01T00:00:00&endTime=2026-07-31T23:59:59" \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

响应包装：

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

UsageDetailVO 字段：

CreditDetailItem 字段：

空值约定：仅填充与各 modelType 相关的字段，其余为 null。text 填充 token 字段； image 填充 imageCount/imageResolution/imageRatio； video 填充 videoResolution/videoRatio/videoDurationSec。

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "priceSnapshotId": "snap_9f3c1a2b",
        "taskId": "task_5e8a1c33",
        "credit": 0.0342,
        "model": "glm-5.2",
        "modelType": "text",
        "inputTokens": 1280,
        "outputTokens": 642,
        "totalTokens": 1922,
        "cacheReadTokens": 0,
        "cacheWriteTokens": 0,
        "imageCount": null,
        "imageResolution": null,
        "imageRatio": null,
        "videoResolution": null,
        "videoRatio": null,
        "videoDurationSec": null,
        "orderCreatedAt": "2026-07-18T14:23:11",
        "creditDetails": [
          {
            "credit": 0.0342,
            "deductionSource": "balance",
            "packageName": ""
          }
        ]
      },
      {
        "priceSnapshotId": "snap_a12f77c0",
        "taskId": "task_c71e44a2",
        "credit": 1.8000,
        "model": "seedance-2.0",
        "modelType": "video",
        "inputTokens": null,
        "outputTokens": null,
        "totalTokens": null,
        "cacheReadTokens": null,
        "cacheWriteTokens": null,
        "imageCount": null,
        "imageResolution": null,
        "imageRatio": null,
        "videoResolution": "1080p",
        "videoRatio": "16:9",
        "videoDurationSec": 8,
        "orderCreatedAt": "2026-07-17T22:41:09",
        "creditDetails": [
          {
            "credit": 1.5000,
            "deductionSource": "Monthly Package",
            "packageName": "基础月度套餐"
          },
          {
            "credit": 0.3000,
            "deductionSource": "Resource Package",
            "packageName": "byteplus视频资源包"
          }
        ]
      }
    ],
    "total": 128,
    "current": 1,
    "size": 20,
    "pages": 7
  }
}

GET https://api.basicrouter.ai/api/v1/billing/transactions

分页返回当前用户已支付（status=2）的充值交易，按 created_at 倒序排列。

curl --request GET \
  --url "https://api.basicrouter.ai/api/v1/billing/transactions?page=1&size=20&startTime=2026-07-01%2000:00:00&endTime=2026-07-31%2023:59:59" \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

响应包装：

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

TransactionVO 字段：

TransactionVO 字段：

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "orderNo": "R20260718abc123",
        "thirdPartyOrderNo": "wx_pay_xxx",
        "amount": 50.00,
        "actualAmount": 48.50,
        "discount": 1.50,
        "paymentMethod": "wechat",
        "serviceFeeAmount": 0.00,
        "paymentChannel": "wechat",
        "source": "recharge",
        "packageName": null,
        "createdAt": "2026-07-18T14:23:11"
      }
    ],
    "total": 28,
    "current": 1,
    "size": 20,
    "pages": 2
  }
}

运维

错误处理

BasicRouter 返回稳定的错误码，便于应用统一处理重试、兜底、计费问题和调试。

兼容上游的端点会尽量保留原始 API 系列的错误结构。BasicRouter 原生端点使用 BasicRouter 错误对象。

HTTP 状态码与错误码映射

常见错误码