闪绘 API 开发者文档
控制台

SHANHUI API

统一模型与视频 API

通过一个域名接入模型查询、OpenAI 兼容协议、Anthropic Messages 与 Seedance 异步视频任务。

生产地址https://ai.shanhui.tvHTTPS
GET/v1/models POST/v1/chat/completions POST/doubao/api/v3/contents/generations/tasks POST/v1/videos
能力以模型列表为准当前生产环境提供 4 个 Seedance 模型。Chat 与 Anthropic 路径已经开放，但只有当你的 /v1/models 返回对应文本模型时才可调用。

开始使用

快速开始

先验证密钥并读取模型，不要从文档示例猜测模型名称。

  1. 创建密钥登录闪绘控制台创建 sk-... API 密钥。
  2. 保存到服务端不要把密钥写入浏览器代码、公开仓库或 URL。
  3. 查询模型从响应 data[].id 选择当前密钥有权访问的模型。
bash
export SHANHUI_API_KEY="替换为你的闪绘 API 密钥"

curl --fail-with-body --show-error "https://ai.shanhui.tv/v1/models" \
  -H "Authorization: Bearer $SHANHUI_API_KEY"
OpenAI SDK 的 base_url 使用 https://ai.shanhui.tv/v1；Seedance 原生接口使用完整前缀 https://ai.shanhui.tv/doubao/api/v3。

开始使用

鉴权与 API 密钥

所有请求都必须携带当前闪绘密钥。

HTTP
Authorization: Bearer YOUR_SHANHUI_API_KEY
Content-Type: application/json

Anthropic Messages 同时接受 x-api-key。密钥权限还受账户状态、分组、模型白名单、额度和有效期限制。任务查询必须使用任务所属用户的密钥。

开始使用

模型目录

下面是 2026-10-13 在生产环境查询到的完整模型列表。

模型 ID主要用途
doubao-seedance-2-0-260128Seedance 视频任务
doubao-seedance-2-0-fast-260128Seedance 快速视频任务
doubao-seedance-2-0-mini-260615Seedance Mini 视频任务
doubao-seedance-2-5-260628Seedance 2.5 视频任务

模型会随生产渠道能力变化并自动同步。客户端仍应在运行时调用 GET /v1/models，因为令牌白名单可能让不同用户看到不同结果。

文本协议

Chat Completions

POST/v1/chat/completions

请求与响应遵循 OpenAI Chat Completions 格式。将占位模型替换成当前密钥返回的对话模型；不要把 Seedance 模型发送到 Chat 端点。

bash
curl --fail-with-body --show-error "https://ai.shanhui.tv/v1/chat/completions" \
  -H "Authorization: Bearer $SHANHUI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID_FROM_V1_MODELS",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": false
  }'

流式输出将 stream 设为 true，响应使用 SSE；读取 choices[].delta 直到收到 [DONE]。

文本协议

Anthropic Messages

POST/v1/messages

仅当模型列表返回可用于 Anthropic 协议的 Claude 模型时调用。响应的 content 是内容块数组，不要按 OpenAI 的 choices 解析。

bash
curl --fail-with-body --show-error "https://ai.shanhui.tv/v1/messages" \
  -H "x-api-key: $SHANHUI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "CLAUDE_MODEL_ID_FROM_V1_MODELS",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "你好"}]
  }'
当前生产环境只提供 Seedance 视频模型，因此此端点当前没有可示范的 Claude 模型。后续模型同步后无需更换域名。

视频 API

视频任务流程

创建任务保存 ID轮询状态读取结果

Seedance 是异步任务。创建成功只表示服务已受理，不能立即当作生成成功。保存顶层 id，再用同一用户的密钥查询。

queued排队running生成中succeeded成功failed / expired终止

视频 API

Seedance 原生接口

POST/doubao/api/v3/contents/generations/tasks
bash
curl --fail-with-body --show-error \
  "https://ai.shanhui.tv/doubao/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $SHANHUI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-mini-260615",
    "content": [{
      "type": "text",
      "text": "清晨的森林，阳光穿过树叶，镜头缓慢向前推进。"
    }],
    "duration": 4,
    "resolution": "480p",
    "ratio": "16:9",
    "generate_audio": false,
    "watermark": false,
    "execution_expires_after": 3600
  }'

创建响应

响应直接返回任务对象，不会额外包裹一层 data。

JSON
{
  "id": "task_YOUR_TASK_ID",
  "model": "doubao-seedance-2-0-mini-260615",
  "status": "queued",
  "created_at": 1791734195
}

常用字段

字段类型说明
modelstring必填，使用模型列表中的准确 ID。
contentarray必填，包含文本和可选参考素材。
durationinteger输出时长；支持范围由模型决定。
resolutionstring480p、720p、1080p 或模型支持值。
ratiostring例如 16:9、9:16、1:1、adaptive。
generate_audioboolean是否请求生成音频，受模型限制。
watermarkboolean是否请求水印。
execution_expires_afterinteger任务有效时间，单位秒，不是 HTTP 超时。

视频 API

参考图片与视频

在原生接口的 content 中加入参考素材。URL 必须可由生成服务直接访问，不能使用本机路径、localhost 或需要登录的页面地址。

JSON
{
  "model": "doubao-seedance-2-0-mini-260615",
  "content": [
    {"type": "text", "text": "参考角色外观与动作，生成自然挥手画面。"},
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {"url": "https://example.com/character.jpg"}
    },
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": {"url": "https://example.com/motion.mp4"}
    }
  ],
  "duration": 4,
  "resolution": "480p",
  "ratio": "16:9"
}

图片也可使用与真实编码一致的 Base64 data URL。素材组合、大小、格式和审核规则由模型及生成服务决定；任务进入 queued 不表示素材准备一定成功。

视频 API

素材模式

需要按素材流程处理输入时，可添加 image_source_mode: "asset" 或 video_source_mode: "asset"。该模式仍使用公网可访问素材。

JSON
{
  "image_source_mode": "asset",
  "video_source_mode": "asset"
}
闪绘当前未开放本地文件预签名上传或完整素材库管理 API。不要把一次素材任务成功理解为任意素材 ID 都可复用。

视频 API

OpenAI 视频接口

POST/v1/videos

使用 JSON 创建视频任务。Seedance 扩展参数放在 metadata 中。

bash
curl --fail-with-body --show-error "https://ai.shanhui.tv/v1/videos" \
  -H "Authorization: Bearer $SHANHUI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-mini-260615",
    "prompt": "清晨的森林，镜头缓慢向前推进。",
    "seconds": 4,
    "metadata": {
      "resolution": "480p",
      "ratio": "16:9",
      "generate_audio": false,
      "watermark": false,
      "execution_expires_after": 3600
    }
  }'
GET/v1/videos/{task_id}

OpenAI 视频状态使用 in_progress 和 completed。需要原生状态、实际用量或结构化失败详情时，使用同一个任务 ID 查询原生 v3 接口。

视频 API

查询任务与结果

GET/doubao/api/v3/contents/generations/tasks/{task_id}
bash
export SHANHUI_TASK_ID="task_替换为创建响应中的ID"

curl --fail-with-body --show-error \
  "https://ai.shanhui.tv/doubao/api/v3/contents/generations/tasks/$SHANHUI_TASK_ID" \
  -H "Authorization: Bearer $SHANHUI_API_KEY"

建议每 5–10 秒查询一次。只有外层状态为 succeeded 才表示完整流程成功；不要因为内部生成步骤完成就提前结束轮询。

成功结果

JSON
{
  "id": "task_YOUR_TASK_ID",
  "status": "succeeded",
  "model": "doubao-seedance-2-0-mini-260615",
  "content": {
    "video_url": "https://media.example/result.mp4?temporary-signature=..."
  },
  "duration": 4,
  "resolution": "480p",
  "ratio": "16:9",
  "usage": {
    "completion_tokens": 40594,
    "total_tokens": 40594
  }
}

视频地址读取 content.video_url，实际计费用量读取 usage.completion_tokens。未知状态必须保留原始响应，不能按成功处理。

用量与排错

素材失败与错误详情

任务查询返回 HTTP 200，也可能在业务层显示 status: failed。

排错时优先使用原生 v3 查询，并同时检查 error 与 failure_detail。

JSON
{
  "id": "task_YOUR_TASK_ID",
  "status": "failed",
  "error": {
    "code": "task_failed",
    "message": "第 1 张参考图片格式、内容或大小不符合要求。"
  },
  "failure_detail": {
    "code": "material_invalid",
    "stage": "material_validation",
    "provider_code": null,
    "materials": [{
      "type": "image",
      "index": 1,
      "content_index": null,
      "index_scope": "normalized_sources"
    }],
    "message": "请更换有效参考图片后重试。"
  }
}
字段含义
stage: material_validation素材格式、内容或规则校验失败。
stage: material_preparation素材下载、解析或准备阶段失败。
index_scope说明 index 使用的序号范围，不能直接当作 content 数组下标。
provider_code服务方没有提供时可能为 null。

OpenAI 视频查询可能只返回简化后的错误；需要素材级详情时使用原生查询。

用量与排错

计费规则

提交时 100% 预扣，任务结束后按实际用量多退少补。

  • 预估 Token：(输入秒数 + 输出秒数) × 宽 × 高 × 24 / 1024。
  • 提交任务时按完整预估费用预扣，不再使用 30% 比例。
  • 成功后以 usage.completion_tokens 和实际参数结算。
  • 失败任务退回预扣；实际用量缺失时保留预估费用，避免错误按零结算。
  • 参考视频单价由计费表达式选择一次，不会重复应用折扣。
模型条件人民币 / 百万 Token
2.0480p/720p，无参考视频 / 有参考视频¥34.50 / ¥21.00
2.01080p，无参考视频 / 有参考视频¥38.25 / ¥23.25
2.04K，无参考视频 / 有参考视频¥19.50 / ¥12.00
2.0 Fast无参考视频 / 有参考视频¥27.75 / ¥16.50
2.0 Mini无参考视频 / 有参考视频¥17.25 / ¥10.50
2.5480p/720p，无参考视频 / 有参考视频¥56.00 / ¥33.60
2.51080p，无参考视频 / 有参考视频¥61.60 / ¥36.80

最终扣费以控制台消费记录为准。创建请求超时不表示任务未创建；若已拿到任务 ID，应继续查询，不要直接重复提交。

用量与排错

错误处理

状态或现象检查方向
400检查 JSON 类型、必填字段、模型、时长、分辨率和素材格式。
401确认密钥属于闪绘，Bearer 或 x-api-key 格式正确，密钥未过期。
403检查余额、用户状态、令牌模型权限、分组和 IP 限制。
404检查接口路径、任务 ID、模型名称和任务所属用户。
429降低轮询频率并退避；创建请求不要未经核对就自动重试。
5xx保留请求时间、模型、任务 ID 和脱敏响应，避免无条件重复生成。
failed / expired读取 error 和 failure_detail，停止轮询。

用量与排错

兼容范围

能力状态说明
模型查询已验证生产域名返回当前 Token 的 4 个完整模型 ID。
Seedance 原生创建与查询协议已验证顶层响应、原生状态、结果与实际用量字段已适配。
OpenAI 视频创建与查询协议已验证扩展参数放在 metadata。
Chat / Anthropic等待模型路径可用；当前生产环境没有文本或 Claude 模型。
付费成功任务未实测未主动发起付费生成，成功链路仍需首个真实任务确认。
模型目录、参数存在或任务被受理，都不代表所有模型与素材组合已经逐项验收。生产调用应保存完整响应并针对终态处理。