Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kapon.cloud/llms.txt

Use this file to discover all available pages before exploring further.

本页介绍如何在 kapon 中接入 BytePlus Dreamina Seedance 2.0 官方视频生成能力，包括：
  • OpenAI 风格视频接口：POST /v1/videos
  • VolcArk 原生任务接口：POST /volcark/api/v3/contents/generations/tasks
  • 私域素材引用：asset://<Asset_Id>
  • Seedance 2.0 / 2.0 Fast 的模型名、参数限制和任务查询方式
与 Doubao Seedance 1.x 不同，Seedance 2.0 使用多模态 content[] 结构和顶层生成参数，平台不会复用旧的 prompt 拼参路径。

​
1. 前置条件

export BASE_URL="https://models.kapon.cloud"
export TOKEN="oh-xxxxxxxxxxxxxxxx"
通用请求头： 
Authorization: Bearer <TOKEN>
Content-Type: application/json
你的账号需要已经具备以下能力：
  • 可以调用平台上的 BytePlus / VolcArk 视频模型
  • 如果要使用 asset://<Asset_Id> 素材工作流，还需要可以访问 BytePlus 素材库接口
如果你已经拿到平台发放的 API Token，通常不需要自己关心底层渠道、AK/SK 或插件配置。 如果请求返回 feature_disabled、channel_not_available 或素材库相关权限错误，说明当前账号或平台环境还没有开通对应能力，请联系平台管理员处理。

​
2. 模型

推荐直接使用以下对外模型名：
对外模型上游模型
seedance-2-0dreamina-seedance-2-0-260128
seedance-2-0-fastdreamina-seedance-2-0-fast-260128
兼容别名：
  • seedance-2-0, seedance-2-0-260128, dreamina-seedance-2-0, dreamina-seedance-2-0-260128
  • seedance-2-0-fast, seedance-2-0-fast-260128, dreamina-seedance-2-0-fast, dreamina-seedance-2-0-fast-260128
响应中的 model 统一返回稳定的对外模型名，不暴露上游版本化 ID。

​
3. 两类接口

​
3.1 OpenAI 风格接口

功能路径
创建任务POST /v1/videos
查询任务GET /v1/videos/{id}
下载视频GET /v1/videos/{id}/content
适合已经接入 OpenAI Sora / Veo SDK 的普通业务调用方。

​
3.2 VolcArk 原生接口

功能路径
创建任务POST /volcark/api/v3/contents/generations/tasks
查询任务GET /volcark/api/v3/contents/generations/tasks/{task_id}
列表查询GET /volcark/api/v3/contents/generations/tasks
取消任务DELETE /volcark/api/v3/contents/generations/tasks/{task_id}
适合已经按 BytePlus ModelArk 原生协议组织请求体的调用方。
原生路径保留 BytePlus 风格路径与字段语义，但平台默认要求参考素材先进入私域素材库，再以 asset://<Asset_Id> 引用。这是 kapon 的显式安全策略收紧，不是 BytePlus 官方默认限制。

​
4. OpenAI 风格创建示例

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "prompt": "A cinematic close-up of a glass greenhouse at sunrise, soft camera movement, natural light.",
    "duration": 8,
    "ratio": "16:9",
    "resolution": "720p",
    "generate_audio": true,
    "watermark": true
  }'
典型响应： 
{
  "id": "video_01HWXK7B9Y8N6V5J3M2Q4R8S0T",
  "object": "video",
  "status": "queued",
  "model": "seedance-2-0",
  "seconds": 8,
  "size": "1280x720"
}

​
4.1 OpenAI 风格扩展字段

字段说明
duration / seconds时长，允许 4-15
size如 1280x720、1920x1080、720x1280，平台会推导 ratio + resolution
ratioadaptive、16:9、9:16、1:1、4:3、3:4、21:9
resolution480p、720p、1080p；seedance-2-0-fast 不支持 1080p
generate_audio是否生成音频
watermark是否保留水印
references.audio[]参考音频，最多 3 个
references.video[]参考视频，最多 3 个

​
4.2 多模态参考示例

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "prompt": "Use Video 1 as the camera movement reference, Image 1 as the opening frame, and Audio 1 as background music.",
    "input_reference": [
      "asset://asset-image-1"
    ],
    "references": {
      "video": [
        "asset://asset-video-1"
      ],
      "audio": [
        "asset://asset-audio-1"
      ]
    },
    "duration": 10,
    "ratio": "16:9",
    "resolution": "1080p",
    "generate_audio": true
  }'

​
5. VolcArk 原生创建示例

curl -X POST "$BASE_URL/volcark/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "content": [
      {
        "type": "text",
        "text": "Use Image 1 as the opening frame and Audio 1 as background music."
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": {
          "url": "asset://asset-image-1"
        }
      },
      {
        "type": "audio_url",
        "role": "reference_audio",
        "audio_url": {
          "url": "asset://asset-audio-1"
        }
      }
    ],
    "duration": 8,
    "ratio": "16:9",
    "resolution": "720p",
    "generate_audio": true,
    "watermark": true
  }'
典型响应： 
{
  "id": "cgt-xxxx",
  "platform_id": "video_<PlatformTaskID>"
}
说明：
  • id：BytePlus 原生任务 ID
  • platform_id：One-Hub 平台任务 ID，格式固定为 video_<ULID>
  • 查询接口同时接受原生 id 和平台 platform_id

​
6. 素材引用规则

平台默认要求参考素材使用可信 URI： 
asset://<Asset_Id>
约束：
  • 图片最多 5 个
  • 视频最多 3 个
  • 音频最多 3 个
  • 提示词里引用素材使用 Image 1 / Video 1 / Audio 1，不要把 Asset ID 写进 prompt
裸公网 URL 默认会被拒绝： 
{
  "error": {
    "message": "input_reference must use asset://<Asset_Id>; raw public URLs are not allowed for seedance-2-0",
    "type": "invalid_arguments",
    "code": "raw_url_not_allowed"
  }
}

​
7. 查询任务

OpenAI 风格查询： 
curl "$BASE_URL/v1/videos/video_01HWXK7B9Y8N6V5J3M2Q4R8S0T" \
  -H "Authorization: Bearer $TOKEN"
VolcArk 原生查询： 
curl "$BASE_URL/volcark/api/v3/contents/generations/tasks/video_01HWXK7B9Y8N6V5J3M2Q4R8S0T" \
  -H "Authorization: Bearer $TOKEN"
原生查询中，平台会在 BytePlus 响应基础上附加 platform_id，并继续接受 video_<ULID> 反解到上游 task_id。

​
8. 计费说明

Seedance 2.0 官方链路不复用 Sutui magic-2-credits，平台会按以下维度派生官方计费 SKU：
  • 请求模型：seedance-2-0 / seedance-2-0-fast
  • 最终分辨率：480p / 720p / 1080p
  • 是否包含视频参考输入
平台只对 成功出片 计费；创建失败、处理中失败、素材预处理失败不扣成功出片费用。 当上游 usage 或创建期计费元数据缺失，而任务又已成功出片时，平台会走预定义的高档 fallback SKU 结算，并在后台留下 fallback/degraded 标记和告警，避免静默低价或漏记账。

​
9. 常见问题

​
9.1 1080p 被拒绝

seedance-2-0-fast 不支持 1080p，请改用：
  • seedance-2-0 + 1080p
  • 或 seedance-2-0-fast + 720p/480p

​
9.2 为什么原生路径不接受公网 URL 素材

这是 kapon 的安全策略：默认要求素材先入私域可信素材库，再以 asset://<Asset_Id> 引用。这样平台可以把多租户隔离、审核边界和可追溯性固定下来。

​
9.3 为什么平台关闭新建后还能查老任务

平台可以随时关闭新的 Seedance 2.0 创建入口，但这通常只影响新任务提交，不影响你查询、下载或回看已经创建成功的历史任务。