> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedance 2.0 人脸认证

> 通过 Sunra 的 Ark Assets API 注册并认证参考素材（例如人脸），以便在 Seedance 2.0 中使用。

# 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_url` | string                        | 是  | 素材的公网可访问 URL（如人脸图片），需服务器可访问。     |
| `name`       | string                        | 否  | 名称，缺省时从 `source_url` 推断文件名。      |
| `asset_type` | `image` \| `video` \| `audio` | 否  | 素材类型，缺省时按 URL 扩展名推断（默认 `image`）。 |

**响应** —— 创建出的 asset：

```json theme={null}
{
  "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}
```

```json theme={null}
{
  "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
```

| 字段          | 类型      | 默认 | 说明                                           |
| ----------- | ------- | -- | -------------------------------------------- |
| `status`    | string  | —  | 按状态过滤（`processing` \| `active` \| `failed`）。 |
| `page`      | integer | 1  | 页码。                                          |
| `page_size` | integer | 20 | 每页条数。                                        |

**响应：**

```json theme={null}
{
  "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}
```

```json theme={null}
{ "deleted": true }
```

## 示例

<CodeGroup>
  ```bash cURL theme={null}
  # 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"
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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"))
  ```
</CodeGroup>

## 用素材生成视频

素材变为 `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
```

| 字段                 | 类型                          | 说明                                      |
| ------------------ | --------------------------- | --------------------------------------- |
| `prompt`           | string                      | 提示词；用 `@Image1` 引用素材。                   |
| `reference_images` | string\[]                   | 0–9 个引用，把 `asset://<ark_asset_id>` 放这里。 |
| `resolution`       | `480p` \| `720p` \| `1080p` | 输出分辨率（默认 `720p`）。                       |
| `ratio`            | string                      | 宽高比；`adaptive` 自动选择。                    |
| `duration`         | integer                     | 秒，4–15（或 `-1` 自动）。                      |
| `generate_audio`   | boolean                     | 是否生成同步音频（默认 `true`）。                    |

（也有不带 `-fast` 的版本：`bytedance/seedance-2.0-relay/reference-to-video`。）

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```python Python theme={null}
  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"])
  ```
</CodeGroup>

之后轮询返回的 `status_url` 直到生成结束（见 [Queue](/zh-Hans/multimodal/queue)）。若上游模型内容审核拦截输入，prediction 会以 `success: false` + `unsafe_content` 错误结束——改 prompt 或参考图后重试即可（真人脸 + 未成年指向的 prompt 是常见触发点）。