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

# Seedance 実在人物・バーチャルヒューマンのアセットAPI

> 実在の人物の本人確認、実在人物とバーチャルヒューマンのアセットの作成と状態確認を行い、LaoZhang APIのキーでSeedanceの動画タスクに使う手順です。

Seedanceは実在の人物の顔写真をそのまま受け付けないため、人物やキャラクターを一貫して登場させるにはアセットを使います。`Active` になったアセットの `asset://...` URIを、[Seedanceの動画タスク](https://docs.laozhang.ai/ja/api-capabilities/seedance2-video-generation.md)に追加します。

| 項目 | 内容 |
| - | - |
| ベースURL | `https://yingtu.ai` |
| 認証 | LaoZhang APIのキーをBearerトークンとして使う。YingTuやGoogleのセッション、YingTu専用のAPIキーは不要 |
| バーチャルヒューマンのアセット | 利用可能。公開HTTPSの画像1枚から、再利用できるアセットIDを作成する |
| 実在人物のアセット | 利用可能。アセットIDを作成する前に、公式H5ページ（スマートフォン向けWebページ）で同意と生体確認を完了する |
| アセットの状態照会 | 利用可能。公開用の `id` で、アセットが `Active` か `Failed` になるまで照会する |
| Seedanceの動画生成 | 利用可能。`asset://...` URIを `reference_image` として動画タスクに追加する |
| 完全なリファレンス | リクエストフィールド、レスポンスオブジェクト、エラーコード、レート制限は、YingTuの[実在人物アセットAPI](https://yingtu.ai/en/docs/seedance-assets/real-person)と[バーチャルヒューマンアセットAPI](https://yingtu.ai/en/docs/seedance-assets/virtual-human)のリファレンスで定義されている |

> [!WARNING]
>
> 映る本人が、公式H5ページで本人確認、同意、生体確認を完了する必要があります。実在の人物をもとにしたバーチャルキャラクターにも、肖像、声、氏名、商標、利用に関する権利が必要です。

## 認証

アセットのエンドポイントは、すべてLaoZhang APIのキーを使います。

```http theme={null}
Authorization: Bearer <LAOZHANG_API_KEY>
Content-Type: application/json
```

呼び出し側には、YingTuやGoogleのセッションもCookieも必要ありません。APIキーで、LaoZhang APIのアカウントと利用可能な残高が検証されます。本人確認とアセットの記録は作成したAPIキーにひも付くため、その後の照会と実在人物のアセット作成にも同じキーを使ってください。

キーはサーバー側の環境変数に保存してください。キー全体を、ブラウザー向けのコード、URL、ログ、サポートへの問い合わせに含めないでください。以下の例は、キーを `LAOZHANG_API_KEY` から読み取ります。

```bash theme={null}
export LAOZHANG_API_KEY="YOUR_API_KEY"   # 自分のLaoZhang APIキーに置き換える
```

## 課金

本人確認とアセットの呼び出しが別途課金されるかどうかは、[コンソールの料金ページ](https://api.laozhang.ai/account/pricing)と[呼び出しログ](https://api.laozhang.ai/log)に表示されます。アセットを使った動画生成は独立したSeedanceのタスクで、ほかのSeedanceのタスクと同じく課金されます。詳しくは[Seedance 2.0 / 2.5](https://docs.laozhang.ai/ja/api-capabilities/seedance2-video-generation.md)の「課金と料金」を参照してください。

## エンドポイント

バーチャルヒューマンのアセット：

| メソッド | パス | 用途 |
| - | - | - |
| `POST` | `/api/seedance-assets/virtual-humans` | 公開HTTPSの画像からバーチャルヒューマンのアセットを作成する |
| `GET` | `/api/seedance-assets/virtual-humans/{id}` | アセットの処理状態を照会する |

実在人物のアセット：

| メソッド | パス | 用途 |
| - | - | - |
| `POST` | `/api/seedance-assets/real-persons/verifications` | 公式H5ページでの本人確認セッションを作成する |
| `GET` | `/api/seedance-assets/real-persons/verifications/{verification_id}` | 本人確認の状態を照会する |
| `POST` | `/api/seedance-assets/real-persons` | 本人確認のあとで実在人物のアセットを作成する |
| `GET` | `/api/seedance-assets/real-persons/{id}` | アセットの処理状態を照会する |

## バーチャルヒューマンのアセットを作成する

バーチャルヒューマンのアセットは、デジタルヒューマン、ブランドキャラクター、バーチャル司会者、企業のスポークスパーソンなどの用途に使えます。認証なしで取得できる公開HTTPSの画像を1枚送ってください。プライベートアドレス、ループバック、Cookieやサインインが必要な画像URLは拒否されます。

```bash theme={null}
curl --request POST \
  --url https://yingtu.ai/api/seedance-assets/virtual-humans \
  --header "Authorization: Bearer $LAOZHANG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "image_url": "https://cdn.example.com/avatar.webp",
    "name": "brand-avatar"
  }'
```

作成に成功すると、照会用の公開 `id`、アセットの `uri`、初期状態が返ります。

```json theme={null}
{
  "request_id": "req_01JZEXAMPLE",
  "id": "ast_eyJvcGFxdWUiOiJleGFtcGxlIn0",
  "object": "seedance.asset",
  "kind": "virtual_human",
  "name": "brand-avatar",
  "status": "Processing",
  "uri": "asset://asset-20260729-example"
}
```

> [!NOTE]
>
> **`id` はYingTuでの状態照会に、`uri` はSeedanceの動画タスクに使います。**
>
> * どちらも返された値をそのまま保存してください。
> * 例の値から内部の識別子を組み立てたり、デコードしたりしないでください。

## 実在人物のアセットを作成する

実在人物のアセットでは、作成の前に同意と生体確認の手順が加わります。APIの呼び出し側は自社のプロダクト内でこの手順を開始できますが、`verification_url` は映る本人に届ける必要があります。

**1. 本人確認セッションを作成する**

HTTPSの `callback_url` を付けて、`POST /api/seedance-assets/real-persons/verifications` を呼び出します。

任意の `language` には、次の値を指定できます。

* `zh`（既定値）
* `en`
* `zh-Hant`

**2. 本人に確認を完了してもらう**

1回限りの `verification_url` を、安全な方法で本人に届けます。このURLは30分で失効し、ログへの記録や長期保存はしないでください。

**3. 本人確認の結果を照会する**

コールバックから `verification_id` を読み取り、状態を照会します。確認中でもHTTP 200が返ります。アセットを作成するのは、状態が `verified` になってからにしてください。

**4. 実在人物のアセットを作成して照会する**

同じ人物がはっきり正面を向いた画像の公開HTTPS URLを送ります。返された公開 `id` で、アセットが `Active` になるまで照会します。

本人確認セッションを作成します。

```bash theme={null}
curl --request POST \
  --url https://yingtu.ai/api/seedance-assets/real-persons/verifications \
  --header "Authorization: Bearer $LAOZHANG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "callback_url": "https://customer.example.com/seedance/verified",
    "language": "en"
  }'
```

本人確認のあとで、実在人物のアセットを作成します。

```bash theme={null}
curl --request POST \
  --url https://yingtu.ai/api/seedance-assets/real-persons \
  --header "Authorization: Bearer $LAOZHANG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "verification_id": "ver_eyJvcGFxdWUiOiJleGFtcGxlIn0",
    "image_url": "https://cdn.example.com/presenter.webp",
    "name": "presenter-a"
  }'
```

> [!WARNING]
>
> **通常の `image_url` は、実在人物のアセットの手順の代わりになりません。** 実在の人物の同一性や見た目の一貫性を保つワークフローでは、先に本人確認を完了し、`Active` な実在人物アセットのURIを取得してください。

## アセットの状態を確認する

どちらの種類のアセットも、作成のレスポンスで返った公開 `id` を使います。例：

```bash theme={null}
curl --request GET \
  --url https://yingtu.ai/api/seedance-assets/virtual-humans/ast_eyJvcGFxdWUiOiJleGFtcGxlIn0 \
  --header "Authorization: Bearer $LAOZHANG_API_KEY"
```

| 状態 | 意味 | 次の対応 |
| - | - | - |
| `Processing` | 上流のサービスがアセットを処理中 | 時間をおいて再度照会する。まだ動画タスクには使えない |
| `Active` | アセットの準備が完了 | `asset://...` URIをSeedanceのタスクに追加する |
| `Failed` | アセットの処理に失敗 | `failure` を読み、画像や権限の問題を解決してから、アセットを作成し直す |

失敗したアセットでも、HTTP 200で `status` が `Failed`、`failure` オブジェクト付きのレスポンスが返ることがあります。HTTPステータスだけで、アセットの準備ができたと判断しないでください。

## Seedanceの動画タスクでアセットを使う

実在人物またはバーチャルヒューマンのアセットが `Active` になったら、完全な `asset://...` URIを `reference_image` として `content` に追加します。動画の生成は、LaoZhang APIの[Seedance 2.0 / 2.5](https://docs.laozhang.ai/ja/api-capabilities/seedance2-video-generation.md)の動画生成APIで行います。

```json theme={null}
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "実在のプレゼンターが商品を紹介し、隣のバーチャル司会者がそれに応える。カメラはゆっくりと寄っていく。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://asset-real-person-example"
      },
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://asset-virtual-human-example"
      },
      "role": "reference_image"
    }
  ],
  "ratio": "16:9",
  "duration": 4,
  "resolution": "720p",
  "watermark": false,
  "generate_audio": true
}
```

2つのドメインは、それぞれ別の手順を受け持ちます。どちらもLaoZhang APIのキーで認証できます。

* アセットの作成と照会：`https://yingtu.ai/api/seedance-assets/...`
* 動画タスクの作成と結果の取得：`https://api.laozhang.ai/seedance/api/v3/...`

## 制限、エラー、完了の目安

* 作成系の `POST` リクエストは、APIキーごとに1時間12回までです。アセットの状態照会の `GET` は、この上限に数えません。`429` が返ったら、`Retry-After` の時間だけ待ってください。
* 実在人物の本人確認リンクは30分有効です。期限切れのセッションは `410 verification_expired` を返すため、作成し直してください。
* 本人確認が完了する前に実在人物のアセットを作成すると、`409 verification_pending` が返ります。
* `403 capability_unavailable` は、アカウントに非公開の人物アセット機能の権限がないことを意味し、画像を変えても解決しません。`request_id` を添えて、[hi@laozhang.ai](mailto:hi@laozhang.ai)またはTelegram（[@laozhang\_cn](https://t.me/laozhang_cn)）でサポートに利用について問い合わせてください。
* 成功・エラーのどちらのレスポンスにも `request_id` が含まれます。サポートへの連絡時には添えてください。ただし、APIキー全体は絶対に含めないでください。
* アセットの照会が `Active` を返し、返された `asset://...` URIを使ったSeedanceのタスクが成功すれば、連携は完了です。

## よくある質問

### 実在の人物の写真を参照画像に使えますか？

いいえ。Volcengineは、Seedance 2.0系のモデルとSeedance 2.5で、実在の人物の顔が写った参照画像や参照動画を受け付けず、上流のコンテンツ審査がそうしたリクエストをブロックします。

登場させたい人物に合わせて、アセットの種類を選びます。

* 特定の実在人物を登場させる場合：その人物に本人確認を完了してもらい、実在人物のアセットを作成します（上の「実在人物のアセットを作成する」を参照）。
* 特定の人物ではなく、リアルなキャラクターがほしいだけの場合：バーチャルヒューマンのアセットを作成します（上の「バーチャルヒューマンのアセットを作成する」を参照）。

どちらの場合も、アセットが `Active` になるのを待ってから、その `asset://...` URIを `reference_image` として送ってください。

### どちらのアセットを使えばよいですか？

動画に特定の実在人物を登場させる必要があるかどうかで決まります。実在の個人を表さないデジタルヒューマン、ブランドキャラクター、バーチャル司会者なら、公開HTTPSの画像1枚から作るバーチャルヒューマンのアセットで足ります。

実在の人物の同一性と容姿を保つには、実在人物のアセットを使います。本人が30分以内に公式H5ページで同意と生体確認を完了する必要があり、呼び出し側が代わりに完了することはできません。

実在の人物をもとにしたバーチャルキャラクターにも、肖像、声、氏名、利用に関する権利が必要です。

### APIキーを変えてもアセットを照会できますか？

いいえ。本人確認とアセットの記録は作成したAPIキーにひも付くため、別のキーで照会したり、その本人確認から実在人物のアセットを作成したりすると、`403 resource_not_owned` が返ります。キーをローテーションしたり無効にしたりする前に、それらのアセットをもう照会する必要がないことを確認してください。上の「認証」も参照してください。

## 関連ドキュメント

* [実在人物アセットAPIの完全なリファレンス](https://yingtu.ai/en/docs/seedance-assets/real-person)
* [バーチャルヒューマンアセットAPIの完全なリファレンス](https://yingtu.ai/en/docs/seedance-assets/virtual-human)
* [Seedance 2.0 / 2.5 動画生成API](https://docs.laozhang.ai/ja/api-capabilities/seedance2-video-generation.md)
* [呼び出しログの確認方法](https://docs.laozhang.ai/en/faq/call-logs.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.