Volcengine Ark (Doubao)

Volcengine Ark 是字节跳动用于提供豆包及其他模型的平台。AISIX 允许应用通过网关的 OpenAI 兼容 API 调用这些模型，同时管理 Ark 凭证、调用方访问权限、速率限制和用量核算。

一个 Ark 服务提供方密钥可以同时处理 OpenAI 兼容的豆包 Chat、原生 Responses、原生 Messages 和 Count Tokens，以及 Seedance 视频任务。本指南先验证文本 API，然后复用该服务提供方密钥进行视频生成。

准备工作

开始前，请准备以下内容：

• 一套 AISIX 环境：
  • 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
  • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
• 从 Volcengine Ark 控制台获取的 Ark API Key。
• curl 和 jq。

使用 AISIX Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且不含尾部斜杠
# 本地私有化部署快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

为豆包文本请求创建服务提供方密钥、模型别名和调用方 API Key。后续视频工作流会复用服务提供方密钥和调用方 Key。

创建服务提供方密钥

创建用于存储 Ark 凭证和 API Root 的服务提供方密钥：

# 请替换为实际值
export ARK_API_KEY="YOUR_PROVIDER_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "volcengine-prod",
    "provider": "volcengine",
    "api_key": "'"${ARK_API_KEY}"'",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "apis": {
      "responses": {},
      "messages": { "base": "https://ark.cn-beijing.volces.com/api/compatible" }
    },
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider 为 volcengine，这是网关视频路由用于分发的服务提供方 ID。Volcengine Ark 未收录在 models.dev 中，但它并非社区目录条目：网关原生实现了 Ark 视频传输格式，AISIX Cloud Admin API 会直接接受该 ID，并为聊天流量推导出 openai 适配器。adapter 字段仅适用于 BYO 服务提供方密钥。

❷ api_key 存储 Ark API Key。AISIX 会在 OpenAI 兼容、Responses 和视频路由中将其作为 Bearer Token 发送，并在原生 Messages 和 Count Tokens 中将其作为 x-api-key 发送。它遵循服务提供方密钥中的凭证处理行为。

❸ api_base 是 Ark 的 OpenAI 兼容 Base，其版本路径段为 /api/v3。AISIX 会将端点路径原样追加到 api_base，因此该值会生成 https://ark.cn-beijing.volces.com/api/v3/chat/completions。对于此服务提供方，该字段可选；省略时，AISIX Cloud Admin API 会填入同一规范值。但示例仍显式设置此字段，以便在配置中清楚显示每个密钥指向的上游 Root。

❹ apis 启用 Ark 的原生 Responses、Messages 和 Count Tokens 路由。Responses 使用 api_base；Messages 和 Count Tokens 使用单独的 /api/compatible Base。

该命令会把返回的服务提供方密钥 ID 保存到 PROVIDER_KEY_ID。

示例使用中国北京主机 https://ark.cn-beijing.volces.com/api/v3。字节跳动还运营该平台的国际版本 BytePlus ModelArk，其亚太区地址为 https://ark.ap-southeast.bytepluses.com/api/v3，欧洲区地址为 https://ark.eu-west.bytepluses.com/api/v3。API Key 和模型可用性因平台及区域而异，因此请使用账户实际预配的主机和模型 ID。任何以 /api/v3 结尾的 Ark Base 都可直接用于视频路由，因为网关会根据该后缀推导服务商 Root。

BytePlus 也在其 OpenAI 兼容根地址上提供原生 Responses API。将此示例改用于 BytePlus 时，请保留 apis.responses，但省略 apis.messages。/api/compatible Messages Base 是 Volcengine 专用的，BytePlus 当前没有对应 Messages 和 Count Tokens 路由的文档。

下文使用的 doubao-* 模型 ID 属于 Volcengine Ark。BytePlus 的对应模型使用不同 ID，因此仅更改 api_base 并不足够。使用 BytePlus 账户时，请在 BytePlus ModelArk 文档中选择适用于所在区域的模型 ID。

创建模型

Ark 模型 ID 由系列名称、版本数字和发布日期后缀组成，各部分用连字符分隔。示例使用 doubao-seed-2-1-pro-260628，Volcengine 文档说明该模型支持 Responses、Messages 和 Count Tokens。Ark 还会预配 ID 以 ep- 开头的自定义推理端点。model_name 接受这两种形式，因为网关会将该值作为上游 model 原样转发。创建模型别名前，请在 Ark 模型列表中查看当前目录和协议支持情况。

创建调用方将在请求中发送的模型别名：

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "doubao-flagship-prod",
    "model_name": "doubao-seed-2-1-pro-260628",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

❶ display_name 是调用方在 model 中发送的别名。

❷ model_name 是 Ark 模型 ID，或你在 Ark 控制台中预配的推理端点 ID；后者以 ep- 开头。

❸ provider_key_id 将别名关联到 Ark 服务提供方密钥。

创建调用方 API Key

创建可访问该模型别名的调用方 API Key。明文密钥由服务器生成，并且只在响应中返回一次，因此请立即保存：

CALLER_KEY_RESPONSE=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "volcengine-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }')

export AISIX_API_KEY=$(printf '%s' "$CALLER_KEY_RESPONSE" | jq -r '.plaintext')
CALLER_API_KEY_ID=$(printf '%s' "$CALLER_KEY_RESPONSE" | jq -r '.api_key.id')

allowed_models 值必须引用上一步保存的模型 ID，因此该密钥只能访问你创建的别名。这些命令还会保留调用方密钥的资源 ID，以便后续添加视频模型。写入后，配置会自动投射到关联的网关。

使用开源 AISIX 网关配置

导出上游凭证，并选择应用将发送给网关的调用方 API Key：

export ARK_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

对于新网关，请使用此完整资源文件。对于现有网关，请将这些条目合并到其当前文件中，并保留其他资源：

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: "volcengine-prod"
    provider: "volcengine"
    adapter: "openai"
    api_key: ${ARK_API_KEY}
    api_base: "https://ark.cn-beijing.volces.com/api/v3"
    apis:
      responses: {}
      messages:
        base: "https://ark.cn-beijing.volces.com/api/compatible"

models:
  - display_name: "doubao-flagship-prod"
    provider: "volcengine"
    model_name: "doubao-seed-2-1-pro-260628"
    provider_key: "volcengine-prod"

api_keys:
  - display_name: "volcengine-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "doubao-flagship-prod"

如果 AISIX 安装在本地，请在加载前验证文件：

aisix validate --resources resources.yaml

验证后，在网关进程环境中提供文件引用的环境变量，再启动网关。仅当这些变量已经可供进程使用时，才重新加载现有网关；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两条命令中使用 -e 传入它引用的每个环境变量。资源加载后，准备下文共用的验证请求：

export AISIX_API_KEY="$CALLER_API_KEY"

验证服务提供方连接

导出 AISIX 网关 Origin：

# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

通过 AISIX 代理发送 Chat Completions 请求：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-flagship-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Doubao."
      }
    ]
  }'

网关返回 OpenAI 兼容响应，并回显调用方可见的别名 doubao-flagship-prod。如果请求失败，请检查服务提供方密钥中的 api_key、api_base 和 model_name 中的 Ark 模型 ID。Ark 按平台和区域提供模型，因此上游返回找不到模型的错误，也可能表示你的账户无法在 api_base 指向的主机上使用该模型。

使用同一别名验证原生 Responses 转发：

curl -sS -X POST "$AISIX_PROXY/v1/responses" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-flagship-prod",
    "input": "Say hello from the Ark Responses API."
  }'

响应采用 Ark 原生 Responses 格式，而不是 AISIX Chat 桥接格式。

使用 Count Tokens 请求验证单独的 Messages Base；该请求不会生成模型响应：

curl -sS -X POST "$AISIX_PROXY/v1/messages/count_tokens" \
  -H "x-api-key: ${AISIX_API_KEY}" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-flagship-prod",
    "messages": [
      {
        "role": "user",
        "content": "Count this Ark prompt."
      }
    ]
  }'

成功响应包含 input_tokens。如果 Chat Completions 正常而其中一个请求失败，请确认模型支持所请求的协议，并检查对应的 apis 声明。

提供成本元数据

models.dev 不提供 Volcengine Ark 模型的定价，因此 AISIX Cloud 定价目录中没有 volcengine 服务提供方的每 Token 费率，创建该服务提供方的别名时，控制台也不会建议模型 ID。预算和用量报告所需的成本元数据由运维人员在模型别名上提供，这与 BYO 端点的处理方式相同。在设置费率之前，这些别名的用量不包含成本信号，因此基于支出的控制功能无法识别这部分流量。

在 AISIX Cloud 部署中通过模型定价设置费率，或在开源 AISIX 网关的 resources.yaml 中使用模型的 cost 字段设置费率，详见成本元数据。此外，视频提交会记录为零 Token，AISIX Cloud 预算尚未对视频任务应用基于时长的成本核算。

使用 Seedance 生成视频

同一服务提供方密钥可以驱动网关已建模的视频路由。创建第二个指向当前 Ark 视频模型（例如 Doubao Seedance 2.0）的别名。由于带日期的模型 ID 会随版本在目录中的变化而更新，请在创建别名前查看 Ark 模型列表：

在 AISIX Cloud 中创建视频别名：

VIDEO_MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "doubao-video-prod",
    "model_name": "doubao-seedance-2-0-260128",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$VIDEO_MODEL_ID"

将新模型 ID 添加到调用方密钥的 allowed_models。该字段是替换列表，因此也要包含现有聊天模型 ID：

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/api_keys/$CALLER_API_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_models": ["'"${MODEL_ID}"'", "'"${VIDEO_MODEL_ID}"'"]
  }'

对于开源 AISIX 网关，请将 doubao-video-prod 添加到现有 models 集合。将现有 volcengine-caller 条目替换为下面更新后的条目，使其允许两个模型别名。保留无关条目和集合：

resources.yaml（视频模型访问）

models:
  - display_name: "doubao-video-prod"
    provider: "volcengine"
    model_name: "doubao-seedance-2-0-260128"
    provider_key: "volcengine-prod"

api_keys:
  - display_name: "volcengine-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "doubao-flagship-prod"
      - "doubao-video-prod"

按照上述说明验证声明式资源文件，然后重新加载或重启网关。

提交视频任务：

curl -sS -X POST "$AISIX_PROXY/v1/videos" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-video-prod",
    "prompt": "A paper boat drifts down a rain-soaked street at dusk.",
    "seconds": 5
  }'

在围绕此路由编写脚本前，需要了解以下五种服务提供方特有行为：

• 聊天 api_base 会原样复用。 AISIX 会识别 /api/v3 后缀，据此推导服务商 Root，并在其下组合 Ark 原生任务路径：任务提交到 POST {root}/api/v3/contents/generations/tasks，并通过 GET {root}/api/v3/contents/generations/tasks/{id} 轮询。已为豆包聊天流量配置的服务提供方密钥无需修改即可用于视频路由。
• seconds 映射到 duration；size 不会转发。 seconds 会作为服务提供方的整数 duration 转发。Ark 使用分辨率和宽高比质量等级表达输出尺寸，而不是像素 WIDTHxHEIGHT 值。因此，提供的 size 会进行格式验证，格式错误的值会在联系服务提供方前以 400 失败，但不会包含在上游请求中，最终采用服务提供方的默认输出设置。
• 服务提供方原生视频字段需要透传路由。 标准化请求只建模 prompt、seconds 和 size；其他字段会被忽略。若要发送参考 content、resolution、ratio、generate_audio 或 watermark 等 Ark 字段，请通过 /passthrough/volcengine/contents/generations/tasks 发送 Ark 原生正文和准确的模型 ID，并通过 /passthrough/volcengine/contents/generations/tasks/{id} 轮询任务。透传不会返回统一的 AISIX 视频对象或网关编码的任务 ID。本页的 /passthrough/volcengine 路径假定一条透传路由认领该前缀，target_url 设为 Ark 的 API 根地址；在调用方 Key 的 allowed_routes 上授予路由名称。
• 报告完整的四状态生命周期。 AISIX 将 Ark 任务状态映射到统一枚举：queued 报告为 queued，running 报告为 in_progress，succeeded 报告为 completed；failed、cancelled 和 expired 则都报告为 failed，并在可用时包含服务提供方的错误码和消息。任务完成后，轮询响应还会通过 seconds 报告实际视频时长。
• 已完成视频通过重定向交付。 GET /v1/videos/{id}/content 返回 302，其 Location 响应头指向服务提供方签名的下载 URL。视频字节会从 Ark 存储直接传输到客户端，不经过网关，因此下载时请使用 curl -L。

有关完整的提交、轮询和下载工作流，包括状态语义及轮询时的速率限制行为，请参阅视频生成。

端点覆盖范围

Volcengine Ark 服务提供方密钥会解析到 openai 适配器，因此路由支持情况由该适配器和各路由自身的服务提供方规则共同决定：

路由	使用 volcengine 模型别名时的行为
/v1/chat/completions	支持缓冲和流式响应。
/v1/embeddings	当别名指向 Ark 嵌入模型（例如 doubao-embedding-text-240515）时支持。AISIX 会将 /embeddings 追加到 api_base，从而访问服务提供方的文本向量化端点。
/v1/responses	由于本指南声明了 apis.responses，请求会发送到 Ark 原生 Responses API。如果没有此声明，AISIX 会通过 Chat Completions 桥接 Responses。请使用 Ark 文档中支持 Responses 的模型。
/v1/messages 和 /v1/messages/count_tokens	由于本指南声明了 apis.messages，请求会发送到 Volcengine 原生 Anthropic 兼容路由。如果没有此声明，Messages 会转换为 Chat Completions，而 Count Tokens 不可用。BytePlus 没有此配置的文档。
/v1/videos 及其状态和内容路由	支持。请参阅使用 Seedance 生成视频。
/v1/images/generations	标准化路由不受支持，因为它只接受配置的服务提供方为 openai 的模型。Ark 为图像模型提供相同路径；请通过 /passthrough/volcengine/images/generations 发送原生请求体和准确的 Ark 模型 ID。
/v1/rerank	不支持。此路由仅接受 openai、cohere 和 jina 服务提供方值。
/v1/models	返回调用方可访问的 AISIX 别名，而不是 Ark 目录。请查阅上文链接的 Ark 控制台或模型列表，确认可用的服务提供方模型 ID。
/passthrough/volcengine/*rest	通过已配置的透传路由可用于 AISIX 尚未建模的服务提供方原生 API。透传不会重写 AISIX 别名，并会增量中继 SSE。可识别的 Chat、Completions 和 Responses 信封会记录受支持的用量字段。没有可识别载体字段的请求保持不透明：缓冲响应记录零 Token，而不透明 SSE 仍可记录顶层受支持的 usage 字段。

完整端点和服务提供方矩阵请参阅服务提供方兼容性。

后续步骤

现在，你已将 AISIX 连接到 Volcengine Ark，并验证了模型别名。请继续阅读以下指南：

• 模型别名：为此别名配置路由、重试行为或成本元数据。
• 模型定价：设置该服务提供方的预算和用量报告所需、由运维人员提供的每 Token 费率。
• 视频生成：按照完整的提交、轮询和下载工作流处理 Seedance 任务。
• 服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。