Seedance 실제 인물·가상 인물 에셋 API 연동

Seedance는 실제 사람의 얼굴이 담긴 일반 사진을 받지 않습니다. 같은 인물이나 캐릭터를 비디오에 일관되게 등장시키려면 에셋을 만들고, 에셋이 Active가 되면 그 asset://... URI를 Seedance 비디오 작업에 넣으세요.

항목	내용
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와 가상 인물 에셋 API 레퍼런스에 있음

에셋의 당사자인 인물이 공식 H5 신원 확인, 동의, 라이브니스 확인을 직접 완료해야 합니다. 실제 인물을 바탕으로 한 가상 캐릭터에도 해당 인물의 초상, 목소리, 이름, 상표, 사용에 관한 권리가 필요합니다.

인증

모든 에셋 엔드포인트는 LaoZhang API 키를 사용합니다.

Authorization: Bearer <LAOZHANG_API_KEY>
Content-Type: application/json

호출하는 쪽에 YingTu 세션, Google 세션, 쿠키는 필요 없습니다. API 키로 LaoZhang API 계정과 사용 가능한 잔액을 확인합니다. 인증 기록과 에셋 기록은 그것을 만든 API 키에 묶이므로, 이후의 조회와 실제 인물 에셋 생성 요청에도 같은 키를 써야 합니다. 키는 서버 측 환경 변수에 보관하세요. 전체 키를 브라우저 코드, URL, 로그, 고객 지원 문의에 넣지 마세요. 아래 예제는 LAOZHANG_API_KEY에서 키를 읽습니다.

export LAOZHANG_API_KEY="YOUR_API_KEY"   # LaoZhang API 키로 바꾸세요

과금

인증과 에셋 호출이 별도로 과금되는지는 콘솔 가격 페이지와 호출 로그에서 확인할 수 있습니다. 에셋으로 비디오를 만드는 것은 별개의 Seedance 작업이며, 다른 Seedance 작업과 똑같이 과금됩니다. Seedance 2.0 / 2.5 페이지의 과금과 가격 절을 참고하세요.

엔드포인트

가상 인물 에셋:

메서드	경로	용도
`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은 거부됩니다.

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, 초기 상태가 들어 있습니다.

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

id는 YingTu에서 에셋 상태를 조회할 때, uri는 Seedance 비디오 작업에 쓸 때 사용합니다. 두 값 모두 반환된 그대로 보관하고, 예시 값을 보고 내부 식별자를 직접 만들거나 디코딩하지 마세요.

실제 인물 에셋 만들기

실제 인물 에셋은 에셋을 만들기 전에 동의와 라이브니스 확인 단계를 거칩니다. API 호출자는 자사 제품 안에서 이 절차를 시작할 수 있지만, verification_url은 에셋의 당사자인 인물에게 전달해야 합니다.

인증 세션 생성

HTTPS callback_url을 넣어 POST /api/seedance-assets/real-persons/verifications를 호출합니다.선택 항목인 language에는 다음 값을 쓸 수 있습니다.

zh(기본값)
en
zh-Hant

당사자의 인증 완료

일회용 verification_url을 당사자에게 안전하게 전달합니다. 링크는 30분 후 만료되며, 로그에 남기거나 오래 보관하면 안 됩니다.

인증 결과 조회

콜백에서 verification_id를 읽어 상태를 조회합니다. 대기 중인 인증도 HTTP 200을 반환하므로, 상태가 verified가 된 뒤에만 에셋을 만드세요.

실제 인물 에셋 생성과 조회

같은 인물의 정면 얼굴이 선명하게 나온 이미지를 공개 HTTPS URL로 보냅니다. 반환된 공개 id로 에셋이 Active가 될 때까지 조회합니다.

인증 세션을 만듭니다.

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"
  }'

인증이 끝나면 실제 인물 에셋을 만듭니다.

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"
  }'

일반 image_url로는 실제 인물 에셋 절차를 대신할 수 없습니다. 실제 인물의 신원이나 일관성을 유지해야 하는 워크플로는 먼저 인증을 마치고 Active 상태의 실제 인물 에셋 URI를 받아야 합니다.

에셋 상태 조회

두 에셋 모두 생성 응답의 공개 id로 조회합니다. 예를 들면 다음과 같습니다.

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로 실행합니다.

{
  "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 또는 Telegram(@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

비디오 생성 API

텍스트 API

Seedance 실제 인물·가상 인물 에셋 API 연동

인증

과금

엔드포인트

가상 인물 에셋 만들기

실제 인물 에셋 만들기

에셋 상태 조회

Seedance 비디오 작업에서 에셋 사용

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

자주 묻는 질문

실제 인물 사진을 참조 이미지로 쓸 수 있나요?

가상 인물 에셋과 실제 인물 에셋 중 무엇을 써야 하나요?

API 키를 바꾼 뒤에도 기존 에셋을 조회할 수 있나요?

관련 문서

​인증

​과금

​엔드포인트

​가상 인물 에셋 만들기

​실제 인물 에셋 만들기

​에셋 상태 조회

​Seedance 비디오 작업에서 에셋 사용

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

​자주 묻는 질문

​실제 인물 사진을 참조 이미지로 쓸 수 있나요?

​가상 인물 에셋과 실제 인물 에셋 중 무엇을 써야 하나요?

​API 키를 바꾼 뒤에도 기존 에셋을 조회할 수 있나요?

​관련 문서

인증

과금

엔드포인트

가상 인물 에셋 만들기

실제 인물 에셋 만들기

에셋 상태 조회

Seedance 비디오 작업에서 에셋 사용

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

자주 묻는 질문

실제 인물 사진을 참조 이미지로 쓸 수 있나요?

가상 인물 에셋과 실제 인물 에셋 중 무엇을 써야 하나요?

API 키를 바꾼 뒤에도 기존 에셋을 조회할 수 있나요?

관련 문서