Skip to main content
실존 인물 에셋은 본인이 확인한 인물의 모습을 비디오에서 참조하는 데 사용합니다. 에셋 그룹 생성, 본인의 웹페이지 확인, 에셋 추가, 에셋 사용 가능 상태 대기, 비디오 생성 작업 제출 순서로 진행합니다. 이 페이지는 이미지 에셋을 예로 들어 AIHubMix API로 에셋을 관리하고, 새로운 /ai/v1/videos를 우선 사용하여 비디오를 생성합니다. 기존 /v1/videos 클라이언트는 호환 프로토콜 예제를 참조하세요.

사전 요구 사항

  • 유효한 AIHubMix API Key를 준비하고 환경 변수 AIHUBMIX_API_KEY에서 읽습니다.
  • 새 비디오 API를 사용하기 전에 콘솔에서 비동기 작업을 활성화하고, 계정에 충분한 잔액과 대상 모델의 사용 권한이 있는지 확인합니다.
  • 에셋에 등장하는 본인이 해당 용도에 동의하고 웹페이지의 확인 절차를 직접 완료해야 합니다. 하나의 에셋 그룹에는 동일 인물의 에셋만 추가합니다.
  • 모델 프로바이더가 읽을 수 있는 이미지 직접 링크를 준비하고, 에셋 처리 중 링크가 계속 유효한지 확인합니다.
  • 명령줄 예제에는 Bash, curl, jq가 필요합니다. 같은 터미널에서 순서대로 실행하고, 반환된 에셋 그룹, 확인 세션, 에셋 및 비디오 작업 ID를 보관합니다.
BytePlus 공식 실존 인물 에셋 가이드는 Seedance 2.0과 Seedance 2.5를 다룹니다. 이 페이지의 새 비디오 API 주 예제는 운영 환경 검증을 완료한 AIHubMix 모델 ID doubao-seedance-2-5-260628을 사용합니다. 구체적인 버전, 참조 미디어 유형 및 파라미터는 현재 모델 Schema와 계정에서 사용 가능한 기능을 기준으로 합니다. 검증 범위는 이번 절차 검증을 참조하세요. 이를 근거로 모든 Seedance 버전에서 실존 인물 에셋을 사용할 수 있다고 가정하지 마세요.
터미널 환경을 준비합니다. API Key는 실행 환경에서 이미 주입되어 있어야 합니다.

  1. 에셋 그룹 생성

요청 본문은 name만 허용하며, 이름은 비어 있을 수 없고 최대 100자입니다. 생성에 성공하면 HTTP 201을 반환하며, 초기 상태는 pending_auth입니다. 에셋 그룹의 공개 필드는 id, object, name, status, created_at, updated_at입니다. objectasset_group으로 고정되며, 시간 필드는 Unix 초 단위입니다. 이후 status=active를 기준으로 에셋 그룹에 에셋을 추가할 수 있는지 판단합니다. 생성 응답을 잃은 경우 바로 다시 생성하지 않도록 먼저 목록을 조회합니다.
목록은 data, has_more, next_after를 반환합니다. 다음 페이지에는 after에 이전 페이지의 next_after를 전달합니다. limit의 기본값은 20, 최댓값은 100입니다. 이름은 멱등성 식별자로 사용되지 않으므로 ID와 생성 시간을 함께 확인하여 에셋 그룹을 식별하세요.

  1. 본인 확인 링크 가져오기

확인 세션을 생성합니다. 요청 본문은 필요하지 않습니다.
생성에 성공하면 HTTP 201을 반환합니다. 공개 필드는 id, object, group_id, status, created_at, expires_at, completed_at입니다. objectverification_session으로 고정되며, 시간 필드는 Unix 초 단위입니다. 완료되지 않은 경우 completed_atnull입니다.
verification_url은 생성 성공 응답에만 포함되며, 이후 조회에서는 링크가 다시 반환되지 않습니다. 링크를 에셋에 등장하는 본인에게 신속히 전달하고 공개 로그, 코드 저장소 또는 피드백 스크린샷에 포함하지 마세요. 유효 기간은 expires_at을 기준으로 하며, 만료 후에는 기존 링크를 계속 사용할 수 없습니다.
본인이 verification_url을 열어 페이지에 표시된 주체와 용도를 확인하고, 관련 약관을 읽고 동의한 뒤 페이지 안내에 따라 절차를 완료합니다. BytePlus 공식 가이드에 따르면 이 과정에는 개인 BytePlus 계정 로그인이 필요합니다. 페이지에서 카메라 권한을 요구하면 본인이 직접 기기를 조작하여 권한을 허용해야 합니다. 공식 페이지에는 에셋 업로드 등의 단계가 포함될 수 있으므로 실제 안내에 따라 완료하세요. 이 페이지에서 이어지는 API 에셋 생성 단계도 수행하여 AIHubMix가 반환하는 에셋 ID를 받아야 합니다. 웹페이지에 표시된 다른 에셋 ID를 API 예제에 직접 대입하지 마세요.

  1. 확인 결과 조회

클라이언트는 10~15초마다 조회할 수 있으며, 로컬 대기 상한을 설정해야 합니다. 이 간격은 사용 권장 사항입니다. 웹페이지에 완료가 표시되거나 빈 페이지가 반환되어도 API로 세션이 verified이고 에셋 그룹이 active인지 확인한 후 에셋을 추가해야 합니다. 다시 생성할 때 409 verification_session_active가 반환되면 먼저 기존 세션과 에셋 그룹을 조회합니다. 유효한 세션이 존재하거나, 에셋 그룹의 확인이 이미 완료되었거나, 이전 결과가 아직 확인 대기 중인 경우에는 반복해서 새로 생성하지 마세요. 계속 완료되지 않으면 지원팀에 문의하세요.
웹페이지의 internal error는 확인 세션이 종료되었음을 의미하지 않습니다. 먼저 이 절의 GET 요청 두 개를 실행하여 세션과 에셋 그룹을 조회하세요. 세션이 여전히 pending이면 같은 그룹의 세션을 반복해서 생성하지 마세요. 세션이 verified이고 에셋 그룹이 active인 경우에만 에셋 추가를 진행합니다. 웹페이지 오류만으로는 원인을 판단할 수 없으므로 계속 완료되지 않으면 ID를 보관하여 지원팀에 문의하세요.

  1. 이미지 주소로 에셋 생성

이미지 준비

이미지 파일을 반환하는 절대 HTTP(S) 주소를 제공하고 HTTPS를 우선 사용합니다. 링크는 로그인이나 추가 요청 헤더 없이 읽을 수 있어야 합니다. 로컬 경로, 사설망 주소, Base64 및 사용자 이름과 비밀번호가 포함된 URL은 에셋 생성 API에 사용할 수 없습니다. URL에는 # 프래그먼트를 포함하지 마세요. BytePlus 실존 인물 에셋 가이드에 따르면 선명한 정면 사진을 권장하며, 다음 에셋 등록 요구 사항을 충족해야 합니다. 위 내용은 공식 에셋 라이브러리의 요구 사항이며, 비디오 모델에는 별도의 참조 에셋 제한이 있을 수 있습니다. 업로드 전에 대상 모델의 요구 사항도 함께 확인하세요. HTTP 생성 요청에 성공해도 에셋 처리가 통과되었음을 의미하지는 않습니다.

생성 요청

IMAGE_URL을 본인으로부터 사용 동의를 받은 이미지 직접 링크로 바꾸세요. 예제 도메인은 자리표시자이며 실존 인물 이미지를 제공하지 않습니다.
요청 본문은 위의 세 필드만 허용합니다. Idempotency-Key는 선택 사항인 요청 헤더이며, 최대 128바이트로 앞뒤 공백이나 제어 문자를 포함할 수 없습니다. 오디오 및 비디오의 파일 제한은 위 공식 가이드를 참조하고 대상 모델이 지원하는 유형과 길이를 확인하세요. 최초 생성은 일반적으로 HTTP 201을 반환하고, 기존 에셋을 재사용하면 200을 반환합니다. 결과가 아직 확인 대기 중이고 상태가 reconciling이면 202를 반환합니다. 항상 객체의 status를 읽으세요. 에셋의 공개 필드는 id, object, group_id, asset_type, status, client_reference_id, created_at, updated_at, deleted_at입니다. objectasset으로 고정됩니다. 제공하지 않았거나 삭제된 client_reference_id는 반환되지 않으며, 삭제되지 않은 경우 deleted_atnull입니다. 시간 필드는 Unix 초 단위이며, 조회 시 원본 이미지 주소는 반환되지 않으므로 애플리케이션 기록을 직접 보관하세요.

  1. 에셋 사용 가능 상태 대기

10~15초마다 조회할 수 있으며, 로컬 대기 상한을 설정해야 합니다. 로컬 폴링을 중지해도 서버 작업은 취소되지 않습니다.
생성 결과를 알 수 없고 일치하는 결과가 계속 확인되지 않으면 에셋이 reconciling 상태로 유지될 수 있으며, 에셋이나 에셋 그룹 삭제에도 영향을 줄 수 있습니다. ID와 원래 요청 식별자를 보관하여 지원팀에 문의하세요. 식별자를 바꾸어 반복 생성하지 말고, 일정 시간이 지나면 자동 정리될 것이라고 가정하지 마세요.

  1. 에셋으로 비디오 생성

비디오 참조에는 AIHubMix 에셋 생성 응답의 전체 id를 사용하며, 형식은 asset://<asset_id>입니다. 한 요청에서 참조하는 모든 에셋은 동일한 에셋 그룹에 속하고 현재 계정이 소유해야 하며, 모두 active 상태여야 합니다. 에셋 그룹도 사용 가능한 상태를 유지해야 합니다. 참조 유형은 에셋 생성 시의 asset_type과 일치해야 합니다. asset://는 비디오 참조 필드에 사용되며 브라우저 다운로드 주소로 사용할 수 없습니다.

새 비디오 프로토콜

먼저 엔드포인트 경로를 기준으로 현재 모델 Schema를 확인합니다.
모델이 참조 이미지를 지원하는지 확인한 후 제출합니다. 다음은 이번 운영 환경 검증에 성공한 Seedance 2.5 파라미터를 사용합니다. duration=4, resolution="480p", aspect_ratio="3:4", generate_audio=false입니다. 새 버전은 input_references[].url을 직접 사용하며, ASSET_ID는 앞서 AIHubMix가 반환한 에셋 ID입니다.
새 버전은 정수 duration으로 요청 길이를 지정하며, 다른 허용값은 모델 Schema를 기준으로 합니다. resolution="480p"는 요청하는 해상도 등급이며 출력 너비나 높이가 480픽셀로 고정됨을 보장하지 않습니다. 실제 크기는 생성 파일을 기준으로 합니다. 첫 프레임과 마지막 프레임에는 frame_images[].image_url.urlframe_type을 함께 사용할 수 있으며, 모델이 해당 기능을 지원할 때만 사용하세요. 전체 파라미터는 비디오 생성을 참조하세요.

호환 비디오 프로토콜

기존 클라이언트가 /v1/videos를 사용하는 경우 참조를 content 또는 extra_body.content에 넣고, URL은 해당 미디어 객체 안에 중첩합니다. 이 예제는 extra_body.content를 사용합니다.
호환 예제는 doubao-seedance-2-0-260128을 유지하며, 기존 호환 API 규약과 BytePlus 공식 에셋 참조 설명을 바탕으로 작성되었습니다. 이번에는 Seedance 2.0 비디오 생성 및 /v1/videos 호환 생성 요청을 실제로 테스트하지 않았으므로 새 버전의 Seedance 2.5 검증 결과를 이 예제에 직접 적용할 수 없습니다.
두 예제 중 하나를 선택하여 실행하세요. 각 비디오 생성은 독립적인 요청입니다. 호환 요청에 input_references를 섞어 넣지 마세요. 두 위치에 content를 모두 제공하면 extra_body.content가 최상위 content를 덮어쓰므로 한 곳에만 제공하는 것을 권장합니다. 호환 버전이 반환한 idGET /v1/videos/{id} 조회에 사용하고, 완료 후 GET /v1/videos/{id}/content로 다운로드합니다. 호환 버전 ID를 /ai/v1/videos 조회에 사용하지 마세요. 자세한 설명은 호환 비디오 API를 참조하세요.

  1. 새 버전 비디오 폴링 및 다운로드

다음 Python 예제는 앞의 새 버전 생성 단계에 이어서만 사용합니다. 환경 변수의 VIDEO_ID를 읽으며 작업을 다시 생성하지 않습니다. requests를 설치해야 합니다.
30분은 예제의 로컬 대기 상한이며 서버 작업의 시간 제한을 의미하지 않습니다. 조회 HTTP 200은 생성 성공을 의미하지 않으므로 반드시 status를 확인해야 합니다. 폴링에는 /ai/v1/videos/{id}를 사용하며, 통합 작업 API /ai/v1/tasks/{id}는 읽기 전용 스냅샷을 제공합니다. 비디오 조회 및 다운로드에는 작업 생성 시 사용한 것과 동일한 API Key를 사용합니다. 완료 후 신속히 다운로드하여 직접 보관하세요. 결과에는 보관 기간이 있으며 expires_at을 기준으로 합니다. 만료 후에는 410 artifact_expired가 반환될 수 있습니다.

이번 절차 검증

2026-09-07 운영 환경 검증에서는 공개 HTTPS JPEG 직접 링크, 본인이 완료한 웹페이지 확인, 위 Seedance 2.5 파라미터를 사용했으며 다음 결과가 관찰되었습니다. 이번 파일의 크기는 1,558,358바이트입니다. ffprobe로 확인한 결과는 H.264, 24 fps, 560 × 752픽셀, 4.041667초이며 오디오 트랙은 없습니다. 이 수치는 해당 생성 결과에만 해당하며, 모든 요청이 동일한 크기, 길이 또는 파일 크기를 출력한다는 의미는 아닙니다. 처음 확인 페이지를 열었을 때 internal error가 발생했으며, 이후 API 조회 상태는 여전히 pending이었습니다. 페이지 오류의 원인은 아직 확인되지 않았습니다. 해당 테스트에서는 이후 별도 테스트 그룹의 새 페이지를 사용했고, 본인이 절차를 완료한 후 세션이 verified, 에셋 그룹이 active임을 확인했습니다. 새 그룹 사용은 이번 테스트에서 취한 처리 방법일 뿐, 에셋 그룹을 반복 재생성하라는 일반적인 권장 사항이 아니며 원래 세션이 종료되었음을 의미하지도 않습니다. 이번에는 Seedance 2.0 비디오 생성, 호환 API 생성, 오디오 및 비디오 에셋, 첫 프레임과 마지막 프레임, 삭제 및 기타 예외 조합을 실제로 테스트하지 않았습니다. 관련 설명은 API 규약과 공식 자료에 근거하여 유지하며, 이번 검증은 가이드 전체의 모든 상황을 포함하지 않습니다.

멱등성 재시도

  • 에셋 생성 요청이 시간 초과되거나 응답을 잃은 경우 원래 Idempotency-Key, client_reference_id, URL, asset_type을 유지하여 동일한 요청을 다시 보냅니다. 두 식별자 중 하나라도 동일 계정 및 동일 에셋 그룹의 기존 에셋과 일치하면 해당 에셋을 재사용합니다.
  • 동일 식별자에 대응하는 URL 또는 asset_type이 변경되면 409 asset_idempotency_conflict를 반환합니다. 서명된 이미지 URL을 갱신하는 경우도 URL 변경에 해당합니다.
  • 두 식별자를 모두 제공하지 않으면 요청 간 중복 제거를 보장하지 않습니다. 별도 에셋을 생성하려는 의도가 확실할 때만 새 식별자를 사용하세요.
  • 에셋 ID를 받은 후에는 GET /ai/v1/assets/{id} 조회를 우선 사용합니다. reconciling은 실패를 의미하지 않으므로 새 식별자로 바꾸어 다시 생성하지 마세요.
  • 에셋 삭제가 완료되면 원래 멱등성 식별자는 더 이상 보관되지 않습니다. 이를 이용해 삭제한 에셋을 찾으려 하지 말고 이전 생성 요청을 다시 실행하지 마세요.
  • 이 절의 멱등성 규약은 에셋 생성에만 적용됩니다. 에셋 그룹, 확인 세션 및 비디오 생성에는 적용할 수 없습니다. 새 버전 비디오 생성 응답을 잃은 경우 먼저 GET /ai/v1/videos?limit=20&order=desc로 원래 작업을 찾아 중복 생성을 피하세요.

에셋 및 에셋 그룹 삭제

삭제 전에 해당 에셋을 참조하는 모든 비디오 작업이 종료되었는지 확인합니다. 호환 API로 제출한 작업도 포함됩니다. 삭제는 되돌릴 수 없으며, 다운로드한 비디오 파일은 직접 관리해야 합니다. 개별 에셋 삭제:
202는 삭제가 아직 처리 중임을 의미합니다. status=deleted가 될 때까지 GET /ai/v1/assets/{id}로 계속 조회합니다. 삭제를 반복 요청하면 현재 상태를 반환합니다. reconciling이면 결과를 계속 확인하고, 계속 완료되지 않으면 지원팀에 문의하세요. 에셋 그룹 전체를 삭제하면 그룹 내 에셋도 함께 삭제됩니다. cascade=true를 명시적으로 전달해야 합니다.
접수 후 202를 반환하며, GET /ai/v1/asset-groups/{id}로 조회합니다. deleting은 처리 중, partially_deleted는 아직 전체 삭제가 완료되지 않았음을 의미하며, deleted가 되어야 완료입니다. 목록에는 기본적으로 삭제된 에셋 그룹이 표시되지 않습니다. 409 asset_group_in_use는 아직 종료되지 않은 작업이나 비디오 작업이 있음을 의미합니다. 기다리면서 관련 상태를 조회한 후 다시 시도하세요. 호환 비디오 작업은 종료 여부를 직접 확인해야 하며, 삭제 요청이 모든 호환 작업의 사용 여부를 자동으로 판단한다고 가정하지 마세요.

자주 묻는 질문

웹페이지 절차를 완료했는데 에셋을 추가할 수 없는 이유는 무엇인가요?

먼저 확인 세션과 에셋 그룹을 조회하여 verifiedactive를 기준으로 판단합니다. 웹페이지에 internal error가 표시되어도 같은 확인을 수행하세요. pending 상태에서는 같은 그룹의 세션을 반복 생성하지 마세요. 결과가 아직 확인되지 않았으면 나중에 다시 조회하고, 계속 완료되지 않으면 ID를 제공하여 지원팀에 문의하세요. 확인 링크나 본인 사진을 제출할 필요는 없습니다.

에셋을 사용할 수 있는데 비디오 생성이 계속 실패하는 이유는 무엇인가요?

참조에 AIHubMix가 반환한 에셋 ID를 사용했는지, 모든 에셋이 같은 그룹에 속하는지, 미디어 유형이 일치하는지, 현재 모델이 해당 입력을 지원하는지 확인하세요. 에셋의 active는 에셋이 사용 가능함을 의미하며, 비디오 작업의 완료 상태와 오류 정보는 별도로 확인해야 합니다.

일반적인 API 오류는 어떻게 처리하나요?

기타 비디오 오류는 비동기 작업 오류 코드를 참조하세요. 피드백에는 발생 시간, HTTP 상태, error.code, 반환된 error.tid(있는 경우), 관련 리소스 ID를 제공하세요. API Key, 확인 링크 또는 서명된 이미지 주소는 제공하지 마세요.

참고 자료

업데이트: 2026-09-07