跳转到主要内容

​
Seedance 2.0 人脸认证

部分 Seedance 2.0 场景——例如用某个特定人物的人脸驱动视频——要求参考素材先在上游注册并认证后才能使用。Sunra 提供了一套 Ark Assets API 来完成这件事：你提交一张图片（或视频 / 音频）的 URL，Sunra 在上游完成注册，待其变为 active 后即可在 Seedance 2.0 生成请求中引用。 这些接口不走推理流程——没有 prediction 记录、没有队列、也没有按次推理计费，只是上游素材注册的一层轻量管理接口。

​
鉴权

鉴权方式与 Sunra API 其余部分一致——在 Authorization 头里带上你的 API key： 
Authorization: Bearer $SUNRA_API_KEY
所有 Ark Assets 接口都按 organization 隔离，你只能查看和管理本组织创建的素材。

​
调用流程

  1. 创建：用素材 URL 创建 asset → 返回 ark_asset_id，status 为 processing。
  2. 轮询：用「获取素材」接口轮询，直到 status 变为 active。
  3. 使用：把 asset://<ark_asset_id> 作为参考，传入 Seedance 2.0 relay 的 reference-to-video 请求（见下方用素材生成视频）。
状态值：processing（上游注册中）、active（可用）、failed（注册失败）。

​
创建素材

POST https://api.sunra.ai/v1/ark/assets
字段类型必填说明
source_urlstring是素材的公网可访问 URL（如人脸图片），需服务器可访问。
namestring否名称，缺省时从 source_url 推断文件名。
asset_typeimage | video | audio否素材类型，缺省时按 URL 扩展名推断（默认 image）。
响应 —— 创建出的 asset： 
{
  "id": "665f1c...",
  "ark_asset_id": "cgt-20260609-abc123",
  "name": "face.jpg",
  "asset_type": "image",
  "source_url": "https://example.com/face.jpg",
  "status": "processing",
  "created_at": "2026-06-09T15:00:00.000Z"
}

​
获取素材

获取单个 asset，并从上游刷新其状态。素材就绪后，响应会带上 ark_url。 
GET https://api.sunra.ai/v1/ark/assets/{ark_asset_id}

{
  "id": "665f1c...",
  "ark_asset_id": "cgt-20260609-abc123",
  "name": "face.jpg",
  "asset_type": "image",
  "source_url": "https://example.com/face.jpg",
  "status": "active",
  "ark_url": "https://.../authenticated-asset",
  "created_at": "2026-06-09T15:00:00.000Z"
}

​
列出素材

POST https://api.sunra.ai/v1/ark/assets/list
字段类型默认说明
statusstring—按状态过滤（processing | active | failed）。
pageinteger1页码。
page_sizeinteger20每页条数。
响应： 
{
  "items": [ { "ark_asset_id": "cgt-...", "status": "active", "asset_type": "image" } ],
  "total": 1,
  "page": 1,
  "page_size": 20
}

​
删除素材

将素材从本组织列表中软删除（不影响上游注册）。 
DELETE https://api.sunra.ai/v1/ark/assets/{ark_asset_id}

{ "deleted": true }

​
示例

# 1. 创建
curl -X POST "https://api.sunra.ai/v1/ark/assets" \
  -H "Authorization: Bearer $SUNRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source_url":"https://example.com/face.jpg","asset_type":"image"}'

# 2. 轮询直到 active
curl "https://api.sunra.ai/v1/ark/assets/cgt-20260609-abc123" \
  -H "Authorization: Bearer $SUNRA_API_KEY"

const base = "https://api.sunra.ai/v1/ark/assets";
const headers = {
  Authorization: `Bearer ${process.env.SUNRA_API_KEY}`,
  "Content-Type": "application/json",
};

// 1. 创建
const created = await (
  await fetch(base, {
    method: "POST",
    headers,
    body: JSON.stringify({
      source_url: "https://example.com/face.jpg",
      asset_type: "image",
    }),
  })
).json();

// 2. 轮询直到 active
let asset = created;
while (asset.status === "processing") {
  await new Promise((r) => setTimeout(r, 3000));
  asset = await (
    await fetch(`${base}/${created.ark_asset_id}`, { headers })
  ).json();
}
console.log(asset.status, asset.ark_url);

import os, time, requests

base = "https://api.sunra.ai/v1/ark/assets"
headers = {"Authorization": f"Bearer {os.environ['SUNRA_API_KEY']}"}

# 1. 创建
asset = requests.post(
    base,
    headers=headers,
    json={"source_url": "https://example.com/face.jpg", "asset_type": "image"},
).json()

# 2. 轮询直到 active
while asset["status"] == "processing":
    time.sleep(3)
    asset = requests.get(f"{base}/{asset['ark_asset_id']}", headers=headers).json()

print(asset["status"], asset.get("ark_url"))

​
用素材生成视频

素材变为 active 后，把它写成 asset://<ark_asset_id> 放进 Seedance 2.0 relay reference-to-video 请求的 reference_images（或 reference_videos / reference_audios），并在 prompt 里用 @Image1 引用（第 1 张 = @Image1，第 2 张 = @Image2，依此类推）。
必须用 relay 端点。 已认证的 Ark 素材只有 relay 模型认得——bytedance/seedance-2.0-relay 和 bytedance/seedance-2.0-fast-relay；素材写成 asset://<ark_asset_id>（不是 URL）。非 relay 的 bytedance/seedance-2.0(-fast) 直连 Volcengine，会以 InvalidParameter 拒绝 asset://。 
POST https://api.sunra.ai/v1/queue/bytedance/seedance-2.0-fast-relay/reference-to-video
字段类型说明
promptstring提示词；用 @Image1 引用素材。
reference_imagesstring[]0–9 个引用，把 asset://<ark_asset_id> 放这里。
resolution480p | 720p | 1080p输出分辨率（默认 720p）。
ratiostring宽高比；adaptive 自动选择。
durationinteger秒，4–15（或 -1 自动）。
generate_audioboolean是否生成同步音频（默认 true）。
（也有不带 -fast 的版本：bytedance/seedance-2.0-relay/reference-to-video。） 
curl -X POST "https://api.sunra.ai/v1/queue/bytedance/seedance-2.0-fast-relay/reference-to-video" \
  -H "Authorization: Bearer $SUNRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "@Image1 中的人在镜头前讲话",
    "reference_images": ["asset://<ARK_ASSET_ID>"],
    "resolution": "720p",
    "ratio": "adaptive",
    "duration": 5,
    "generate_audio": true
  }'

import os, requests

asset_id = asset["ark_asset_id"]  # create/get 返回，status == "active" 后

resp = requests.post(
    "https://api.sunra.ai/v1/queue/bytedance/seedance-2.0-fast-relay/reference-to-video",
    headers={"Authorization": f"Bearer {os.environ['SUNRA_API_KEY']}"},
    json={
        "prompt": "@Image1 中的人在镜头前讲话",
        "reference_images": [f"asset://{asset_id}"],
        "resolution": "720p",
        "ratio": "adaptive",
        "duration": 5,
        "generate_audio": True,
    },
)
print(resp.json()["request_id"])
之后轮询返回的 status_url 直到生成结束（见 Queue）。若上游模型内容审核拦截输入，prediction 会以 success: false + unsafe_content 错误结束——改 prompt 或参考图后重试即可（真人脸 + 未成年指向的 prompt 是常见触发点）。