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 私域素材库接口。它的主要用途是：
  • 创建素材组
  • 上传图片 / 视频 / 音频素材
  • 查询素材状态
  • 为 Seedance 2.0 生成 asset://<Asset_Id> 引用
这些接口是 kapon 对外提供的素材库能力，不是 BytePlus 原始 OpenAPI 路径。普通调用方只需要使用平台发放的 API Token 即可。

​
1. 前置条件

export BASE_URL="https://models.kapon.cloud"
export TOKEN="oh-xxxxxxxxxxxxxxxx"
统一请求头： 
Authorization: Bearer <TOKEN>
Content-Type: application/json
你的账号需要已经具备以下能力：
  • 可以访问 BytePlus 素材库接口
  • 可以在后续视频生成请求中使用 asset://<Asset_Id> 素材引用
如果你拿到的是可直接调用的 API Token，通常不需要自己关心底层 AK/SK、项目名或区域配置。 如果接口返回 channel_not_available、ak_required、sk_required 等错误，说明当前平台环境或账号权限还没有开通，请联系平台管理员处理。

​
2. 接口概览

所有接口统一挂载在： 
POST /v1/byteplus/assets/{action}
支持的公开 Action：
功能推荐路径
创建素材组POST /v1/byteplus/assets/create-asset-group
创建素材POST /v1/byteplus/assets/create-asset
查询素材组列表POST /v1/byteplus/assets/list-asset-groups
查询素材列表POST /v1/byteplus/assets/list-assets
查询单个素材组POST /v1/byteplus/assets/get-asset-group
查询单个素材POST /v1/byteplus/assets/get-asset
兼容大小写和分隔符写法，例如：
  • CreateAssetGroup
  • create-asset-group
  • create_asset_group
默认不开放的 Action：
  • UpdateAsset
  • UpdateAssetGroup
  • DeleteAsset
  • DeleteAssetGroup
这些请求会返回 403 forbidden_action。

​
3. 请求路由

素材库接口没有 model 字段，因此某些平台环境下需要显式指定： 
?channel_id=<channel_id>
示例： 
curl -X POST "$BASE_URL/v1/byteplus/assets/list-assets?channel_id=123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
行为规则：
  • 只有一个可用素材库入口时，平台可自动推断
  • 存在多个可用入口时，未传 channel_id 会返回 400 channel_id_required
  • 如果你不确定该传哪个 channel_id，请向平台管理员确认

​
4. 创建素材组

curl -X POST "$BASE_URL/v1/byteplus/assets/create-asset-group?channel_id=123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "campaign-product-shots",
    "Description": "Assets for spring product videos"
  }'
典型响应： 
{
  "Id": "group-20260429142802-f7wmx"
}
平台会自动：
  • 补 ProjectName 默认值
  • 在 Description 中写入租户标记

​
5. 创建素材

curl -X POST "$BASE_URL/v1/byteplus/assets/create-asset?channel_id=123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId": "group-20260429142802-f7wmx",
    "URL": "https://example-cdn.example.com/input/product.png",
    "AssetType": "Image",
    "Name": "product-front.png"
  }'
典型响应： 
{
  "Id": "asset-20260429143042-8cdfz",
  "Status": "Pending"
}
说明：
  • AssetType 支持 Image / Video / Audio
  • CreateAsset 是异步处理，不能保证立即可用
  • 素材变成 Active 之前，不要拿去生成视频

​
6. 查询素材状态

curl -X POST "$BASE_URL/v1/byteplus/assets/get-asset?channel_id=123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Id": "asset-20260429143042-8cdfz"
  }'
典型响应： 
{
  "Id": "asset-20260429143042-8cdfz",
  "GroupId": "group-20260429142802-f7wmx",
  "AssetType": "Image",
  "Status": "Active",
  "URL": "https://ark-media-asset-ap-southeast-1.example.com/asset.png"
}
常见状态：
  • Pending
  • Processing
  • Active
  • Failed

​
7. 在视频生成中引用素材

素材进入 Active 后，使用： 
asset://<Asset_Id>
例如： 
{
  "input_reference": ["asset://asset-20260429143042-8cdfz"]
}
对于多模态参考： 
{
  "references": {
    "video": ["asset://asset-video-1"],
    "audio": ["asset://asset-audio-1"]
  }
}

​
8. 安全与租户隔离

平台在素材库上做了几层显式收紧：

​
8.1 资源归属校验

  • CreateAsset(GroupId=...) 会校验目标素材组是否属于当前用户
  • GetAsset / GetAssetGroup 会校验资源是否属于当前用户
  • ListAssets / ListAssetGroups 会过滤掉其他租户的资源

​
8.2 不开放高风险动作

以下能力默认不开放：
  • 更新素材
  • 删除素材
  • 更新素材组
  • 删除素材组
  • Moderation.Strategy=Skip
如果请求体中传： 
{
  "Moderation": {
    "Strategy": "Skip"
  }
}
平台会返回： 
{
  "error": {
    "message": "Moderation.Strategy=Skip is not allowed via One-Hub byteplus assets API",
    "type": "invalid_request_error",
    "code": "moderation_skip_not_allowed"
  }
}

​
9. 常见错误

HTTPcode场景
400channel_id_required当前环境存在多个素材库入口，但请求里未指定 channel_id
400ak_required平台侧素材库能力未完成开通
400sk_required平台侧素材库能力未完成开通
400moderation_skip_not_allowed请求尝试使用 Moderation.Strategy=Skip
403forbidden_action请求了 Update* / Delete*
404asset_not_found资产或素材组不存在，或不属于当前用户
503channel_not_available当前账号没有可用素材库入口，或平台暂未开通该能力

​
10. 相关页面