YingTu Logo
Google 로그인을 확인하는 중…
Seedance 작업 공간으로 돌아가기
REST API 레퍼런스

가상 인물 에셋 API

비공개 AIGC 가상 인물 에셋을 생성합니다. 상태가 Active가 된 뒤 반환된 asset:// URI를 영상 생성에 사용할 수 있습니다.

가상 인물 에셋 API공개 HTTPS 이미지 URL 하나로 재사용 가능한 Asset ID를 생성합니다.실제 인물 에셋 API공식 H5 본인 인증을 생성·조회하고 동의된 실제 인물 Asset ID를 만듭니다.

엔드포인트

Base URL

https://yingtu.ai
POST /api/seedance-assets/virtual-humans
GET /api/seedance-assets/virtual-humans/{id}

인증

YingTu 또는 Google 로그인이 필요하지 않습니다. LaoZhang API Key를 Authorization: Bearer <LAOZHANG_API_KEY>로 전송합니다.

헤더필수설명
Authorization가능Bearer 인증으로 전송하는 LaoZhang API Key.
Content-TypePOST만생성 작업은 application/json을 사용합니다.

요청

필드필수설명
name불가선택 사항. 에셋 이름, 최대 64자.
image_url가능필수 공개 HTTPS 이미지 URL. 공식 CreateAsset은 URL만 받습니다.

생성 요청

cURL
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"
  }'
HTTP request
POST /api/seedance-assets/virtual-humans
Content-Type: application/json
Authorization: Bearer $LAOZHANG_API_KEY

{
  "image_url": "https://cdn.example.com/avatar.webp",
  "name": "brand-avatar"
}

응답 예시

HTTP/1.1 202 Accepted
Content-Type: application/json

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

코드 예시

JavaScript · Node.js
const response = await fetch("https://yingtu.ai/api/seedance-assets/virtual-humans", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LAOZHANG_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    image_url: "https://cdn.example.com/avatar.webp",
    name: "brand-avatar",
  }),
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
Python · requests
import os
import requests

response = requests.post(
    "https://yingtu.ai/api/seedance-assets/virtual-humans",
    headers={"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"},
    json={
        "image_url": "https://cdn.example.com/avatar.webp",
        "name": "brand-avatar",
    },
    timeout=60,
)

response.raise_for_status()
print(response.json())

에셋 상태 조회

curl --request GET \
	  --url https://yingtu.ai/api/seedance-assets/virtual-humans/ast_eyJvcGFxdWUiOiJleGFtcGxlIn0 \
	  --header "Authorization: Bearer $LAOZHANG_API_KEY"
상태 응답
HTTP/1.1 200 OK
Content-Type: application/json

{
	  "request_id": "req_01JZEXAMPLE",
	  "id": "ast_eyJvcGFxdWUiOiJleGFtcGxlIn0",
  "object": "seedance.asset",
  "kind": "virtual_human",
  "status": "Active",
  "uri": "asset://asset-20260729-example",
	  "created_at": "2026-07-29T05:00:00Z",
	  "updated_at": "2026-07-29T05:01:00Z"
}
Failed · HTTP 200
{
  "request_id": "req_01JZEXAMPLE",
  "id": "ast_eyJvcGFxdWUiOiJleGFtcGxlIn0",
  "object": "seedance.asset",
  "kind": "virtual_human",
  "status": "Failed",
  "uri": "asset://asset-20260729-example",
  "failure": {
    "code": "InvalidImage",
    "message": "The image did not pass upstream validation."
  }
}

오류

HTTP 상태오류 코드설명재시도
400invalid_request요청 본문, 필드 또는 파라미터 값이 올바르지 않습니다.불가
401invalid_api_keyAPI Key가 없거나 유효하지 않거나 비활성화되었습니다.불가
403resource_not_owned인증 또는 에셋이 현재 API Key 소유가 아니거나 공개 ID가 잘못되었습니다.불가
403capability_unavailable서비스 계정에 비공개 인물 에셋 권한이 활성화되지 않았습니다.불가
413payload_too_largeJSON 요청 본문이 16KB를 초과했습니다.불가
415unsupported_media_typePOST 요청의 Content-Type이 application/json이 아닙니다.불가
429rate_limit_exceeded현재 API Key의 호출 한도에 도달했습니다.가능
500internal_error서비스가 요청을 완료하지 못했습니다.불가
502upstream_error업스트림 에셋 또는 인증 서비스 오류입니다.가능
503authentication_unavailableAPI Key 검증 서비스를 일시적으로 사용할 수 없습니다.가능
503service_unavailable에셋 API의 서버 설정을 일시적으로 사용할 수 없습니다.가능
Error object
{
  "error": {
    "code": "invalid_request",
	    "message": "image_url is required.",
    "request_id": "req_01JZEXAMPLE",
    "retryable": false
  }
}

요청 제한 및 추적

API Key당 생성 POST 요청은 시간당 최대 12회이며 GET 상태 조회는 계산하지 않습니다. 업스트림 권한에 따른 추가 제한이 있을 수 있습니다. 제한 시 429와 Retry-After를 반환합니다.

모든 성공 및 오류 응답에는 request_id가 포함됩니다. 지원 문의 시 이 값을 제공하고 전체 API Key는 보내지 마세요.

X-RateLimit-Limit: <limit>
X-RateLimit-Remaining: <remaining>
X-RateLimit-Reset: <unix-seconds>
Retry-After: <seconds>