> ## 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 연동

> 실제 인물 인증부터 실제 인물·가상 인물 에셋 생성, 상태 조회, Seedance 비디오 작업에서의 사용까지 LaoZhang API 키 하나로 처리하는 방법을 안내합니다.

Seedance는 실제 사람의 얼굴이 담긴 일반 사진을 받지 않습니다. 같은 인물이나 캐릭터를 비디오에 일관되게 등장시키려면 에셋을 만들고, 에셋이 `Active`가 되면 그 `asset://...` URI를 [Seedance 비디오 작업](https://docs.laozhang.ai/ko/api-capabilities/seedance2-video-generation.md)에 넣으세요.

| 항목 | 내용 |
| - | - |
| base URL | `https://yingtu.ai` |
| 인증 | LaoZhang API 키를 Bearer 토큰으로 사용. YingTu나 Google 세션, 별도의 YingTu API 키는 필요 없음 |
| 가상 인물 에셋 | 제공 중. 공개 HTTPS 이미지 한 장으로 재사용 가능한 Asset ID 생성 |
| 실제 인물 에셋 | 제공 중. Asset ID를 만들기 전에 공식 H5 동의·라이브니스 절차 완료 필요 |
| 에셋 상태 조회 | 제공 중. 에셋이 `Active` 또는 `Failed`가 될 때까지 공개 `id`로 조회 |
| 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 세션, 쿠키는 필요 없습니다. 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/ko/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 이미지 한 장을 보내세요. 사설망, 루프백, 쿠키나 로그인으로 보호된 이미지 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. 당사자의 인증 완료**

일회용 `verification_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를 `content`에 `reference_image`로 추가합니다. 비디오 생성은 LaoZhang API의 [Seedance 비디오 생성 API](https://docs.laozhang.ai/ko/api-capabilities/seedance2-video-generation.md)로 실행합니다.

```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
}
```

두 도메인은 맡는 단계가 다르며, 둘 다 LaoZhang API 키를 받습니다.

* 에셋 생성과 조회: `https://yingtu.ai/api/seedance-assets/...`
* 비디오 작업 생성과 결과 조회: `https://api.laozhang.ai/seedance/api/v3/...`

## 제한, 오류, 연동 완료 기준

* API 키 하나당 생성용 `POST` 요청은 시간당 최대 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 이미지 한 장으로 만드는 가상 인물 에셋이면 충분합니다.

실제 인물의 신원과 외모를 유지하려면 실제 인물 에셋을 쓰세요. 당사자가 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/ko/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.