> ## Documentation Index > Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt > Use this file to discover all available pages before exploring further. # Doubao 실존 인물 에셋 사용 가이드 > 본인이 웹페이지에서 확인을 완료한 후 실존 인물 에셋을 생성하고, asset:// 참조로 Doubao Seedance 비디오 생성을 호출하며, 에셋을 조회, 재시도 및 삭제하는 방법을 설명합니다. 실존 인물 에셋은 본인이 확인한 인물의 모습을 비디오에서 참조하는 데 사용합니다. 에셋 그룹 생성, 본인의 웹페이지 확인, 에셋 추가, 에셋 사용 가능 상태 대기, 비디오 생성 작업 제출 순서로 진행합니다. 이 페이지는 이미지 에셋을 예로 들어 AIHubMix API로 에셋을 관리하고, 새로운 `/ai/v1/videos`를 우선 사용하여 비디오를 생성합니다. 기존 `/v1/videos` 클라이언트는 [호환 프로토콜 예제](#compatible-video)를 참조하세요.

사전 요구 사항

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

1. 에셋 그룹 생성

```bash theme={null} GROUP_JSON=$(curl --fail-with-body -sS --max-time 60 \ -X POST "$BASE_URL/ai/v1/asset-groups" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"我的真人素材"}') printf '%s\n' "$GROUP_JSON" | jq . GROUP_ID=$(printf '%s' "$GROUP_JSON" | jq -er '.id') ``` 요청 본문은 `name`만 허용하며, 이름은 비어 있을 수 없고 최대 100자입니다. 생성에 성공하면 HTTP `201`을 반환하며, 초기 상태는 `pending_auth`입니다. 에셋 그룹의 공개 필드는 `id`, `object`, `name`, `status`, `created_at`, `updated_at`입니다. `object`는 `asset_group`으로 고정되며, 시간 필드는 Unix 초 단위입니다. 이후 `status=active`를 기준으로 에셋 그룹에 에셋을 추가할 수 있는지 판단합니다. 생성 응답을 잃은 경우 바로 다시 생성하지 않도록 먼저 목록을 조회합니다. ```bash theme={null} curl --fail-with-body -sS "$BASE_URL/ai/v1/asset-groups?limit=20" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` 목록은 `data`, `has_more`, `next_after`를 반환합니다. 다음 페이지에는 `after`에 이전 페이지의 `next_after`를 전달합니다. `limit`의 기본값은 `20`, 최댓값은 `100`입니다. 이름은 멱등성 식별자로 사용되지 않으므로 ID와 생성 시간을 함께 확인하여 에셋 그룹을 식별하세요.

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

확인 세션을 생성합니다. 요청 본문은 필요하지 않습니다. ```bash theme={null} SESSION_JSON=$(curl --fail-with-body -sS --max-time 60 \ -X POST "$BASE_URL/ai/v1/asset-groups/$GROUP_ID/verification-sessions" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY") SESSION_ID=$(printf '%s' "$SESSION_JSON" | jq -er '.id') printf '%s' "$SESSION_JSON" | jq '{id, status, expires_at, verification_url}' ``` 생성에 성공하면 HTTP `201`을 반환합니다. 공개 필드는 `id`, `object`, `group_id`, `status`, `created_at`, `expires_at`, `completed_at`입니다. `object`는 `verification_session`으로 고정되며, 시간 필드는 Unix 초 단위입니다. 완료되지 않은 경우 `completed_at`은 `null`입니다. `verification_url`은 생성 성공 응답에만 포함되며, 이후 조회에서는 링크가 다시 반환되지 않습니다. 링크를 에셋에 등장하는 본인에게 신속히 전달하고 공개 로그, 코드 저장소 또는 피드백 스크린샷에 포함하지 마세요. 유효 기간은 `expires_at`을 기준으로 하며, 만료 후에는 기존 링크를 계속 사용할 수 없습니다. 본인이 `verification_url`을 열어 페이지에 표시된 주체와 용도를 확인하고, 관련 약관을 읽고 동의한 뒤 페이지 안내에 따라 절차를 완료합니다. BytePlus 공식 가이드에 따르면 이 과정에는 개인 BytePlus 계정 로그인이 필요합니다. 페이지에서 카메라 권한을 요구하면 본인이 직접 기기를 조작하여 권한을 허용해야 합니다. 공식 페이지에는 에셋 업로드 등의 단계가 포함될 수 있으므로 실제 안내에 따라 완료하세요. 이 페이지에서 이어지는 API 에셋 생성 단계도 수행하여 AIHubMix가 반환하는 에셋 ID를 받아야 합니다. 웹페이지에 표시된 다른 에셋 ID를 API 예제에 직접 대입하지 마세요.

3. 확인 결과 조회

```bash theme={null} curl --fail-with-body -sS "$BASE_URL/ai/v1/verification-sessions/$SESSION_ID" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . curl --fail-with-body -sS "$BASE_URL/ai/v1/asset-groups/$GROUP_ID" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` | 세션 상태 | 다음 단계 | | ---------- | -------------------------------------------- | | `creating` | 세션 생성 중이므로 나중에 조회합니다. 계속 완료되지 않으면 지원팀에 문의합니다 | | `pending` | 본인의 절차 완료 또는 결과 확인을 기다리는 중이므로 나중에 다시 조회합니다 | | `verified` | 본인 확인이 완료되었습니다. 이어서 에셋 그룹이 `active`인지 확인합니다 | | `rejected` | 이번 확인이 승인되지 않았습니다. 웹페이지 안내를 확인한 후 다시 시작합니다 | | `expired` | 이번 확인이 만료되었습니다. 확인 절차를 다시 시작합니다 | | `failed` | 이번 확인이 실패했습니다. 오류 안내를 확인하고 필요한 경우 지원팀에 문의합니다 | 클라이언트는 10\~15초마다 조회할 수 있으며, 로컬 대기 상한을 설정해야 합니다. 이 간격은 사용 권장 사항입니다. 웹페이지에 완료가 표시되거나 빈 페이지가 반환되어도 API로 세션이 `verified`이고 에셋 그룹이 `active`인지 확인한 후 에셋을 추가해야 합니다. 다시 생성할 때 `409 verification_session_active`가 반환되면 먼저 기존 세션과 에셋 그룹을 조회합니다. 유효한 세션이 존재하거나, 에셋 그룹의 확인이 이미 완료되었거나, 이전 결과가 아직 확인 대기 중인 경우에는 반복해서 새로 생성하지 마세요. 계속 완료되지 않으면 [지원팀](/ko/FAQs/Feedback)에 문의하세요. 웹페이지의 `internal error`는 확인 세션이 종료되었음을 의미하지 않습니다. 먼저 이 절의 GET 요청 두 개를 실행하여 세션과 에셋 그룹을 조회하세요. 세션이 여전히 `pending`이면 같은 그룹의 세션을 반복해서 생성하지 마세요. 세션이 `verified`이고 에셋 그룹이 `active`인 경우에만 에셋 추가를 진행합니다. 웹페이지 오류만으로는 원인을 판단할 수 없으므로 계속 완료되지 않으면 ID를 보관하여 지원팀에 문의하세요.

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

이미지 준비

이미지 파일을 반환하는 절대 HTTP(S) 주소를 제공하고 HTTPS를 우선 사용합니다. 링크는 로그인이나 추가 요청 헤더 없이 읽을 수 있어야 합니다. 로컬 경로, 사설망 주소, Base64 및 사용자 이름과 비밀번호가 포함된 URL은 에셋 생성 API에 사용할 수 없습니다. URL에는 `#` 프래그먼트를 포함하지 마세요. [BytePlus 실존 인물 에셋 가이드](https://docs.byteplus.com/en/docs/ModelArk/2315856)에 따르면 선명한 정면 사진을 권장하며, 다음 에셋 등록 요구 사항을 충족해야 합니다. | 항목 | 요구 사항 | | ----------- | ------------------------------------------- | | 형식 | JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF | | 이미지 한 장의 크기 | 30 MB 미만 | | 가로세로 비율 | 0.4 초과, 2.5 미만 | | 너비와 높이 | 모두 300픽셀 초과, 6000픽셀 미만 | | 인물 | 해당 에셋 그룹에서 확인을 완료한 인물과 동일해야 함 | 위 내용은 공식 에셋 라이브러리의 요구 사항이며, 비디오 모델에는 별도의 참조 에셋 제한이 있을 수 있습니다. 업로드 전에 대상 모델의 요구 사항도 함께 확인하세요. HTTP 생성 요청에 성공해도 에셋 처리가 통과되었음을 의미하지는 않습니다.

생성 요청

`IMAGE_URL`을 본인으로부터 사용 동의를 받은 이미지 직접 링크로 바꾸세요. 예제 도메인은 자리표시자이며 실존 인물 이미지를 제공하지 않습니다. ```bash theme={null} IMAGE_URL="https://cdn.example.com/portrait.jpg" ASSET_KEY="portrait-image-001" ASSET_BODY=$(jq -n --arg url "$IMAGE_URL" --arg ref "$ASSET_KEY" \ '{url: $url, asset_type: "image", client_reference_id: $ref}') ASSET_JSON=$(curl --fail-with-body -sS --max-time 60 \ -X POST "$BASE_URL/ai/v1/asset-groups/$GROUP_ID/assets" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $ASSET_KEY" \ -d "$ASSET_BODY") printf '%s\n' "$ASSET_JSON" | jq . ASSET_ID=$(printf '%s' "$ASSET_JSON" | jq -er '.id') ``` | 요청 필드 | 필수 | 설명 | | --------------------- | --- | --------------------------------------------- | | `url` | 예 | 접근 가능한 에셋 파일 주소 | | `asset_type` | 예 | `image`, `video` 또는 `audio`. 이 예제는 `image` 사용 | | `client_reference_id` | 아니요 | 애플리케이션 측 에셋 식별자, 최대 128바이트 | 요청 본문은 위의 세 필드만 허용합니다. `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`입니다. `object`는 `asset`으로 고정됩니다. 제공하지 않았거나 삭제된 `client_reference_id`는 반환되지 않으며, 삭제되지 않은 경우 `deleted_at`은 `null`입니다. 시간 필드는 Unix 초 단위이며, 조회 시 원본 이미지 주소는 반환되지 않으므로 애플리케이션 기록을 직접 보관하세요.

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

```bash theme={null} curl --fail-with-body -sS "$BASE_URL/ai/v1/assets/$ASSET_ID" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` | 에셋 상태 | 의미 및 처리 방법 | | ------------- | ------------------------------------------------------ | | `creating` | 생성이 아직 완료되지 않았습니다. ID를 보관하고 나중에 조회합니다 | | `processing` | 처리 중입니다. 계속 조회합니다 | | `active` | 비디오 참조 에셋으로 사용할 수 있습니다 | | `failed` | 에셋 처리에 실패했습니다. 이미지 및 인물 일치 요구 사항을 확인합니다 | | `reconciling` | 생성 또는 삭제 결과가 아직 확인 대기 중입니다. 계속 조회하고 당분간 비디오에 사용하지 않습니다 | | `deleting` | 삭제 처리 중입니다. 당분간 비디오에 사용하지 않습니다 | | `deleted` | 삭제가 완료되었습니다. 더 이상 비디오에 사용하지 않습니다 | 10\~15초마다 조회할 수 있으며, 로컬 대기 상한을 설정해야 합니다. 로컬 폴링을 중지해도 서버 작업은 취소되지 않습니다. 생성 결과를 알 수 없고 일치하는 결과가 계속 확인되지 않으면 에셋이 `reconciling` 상태로 유지될 수 있으며, 에셋이나 에셋 그룹 삭제에도 영향을 줄 수 있습니다. ID와 원래 요청 식별자를 보관하여 지원팀에 문의하세요. 식별자를 바꾸어 반복 생성하지 말고, 일정 시간이 지나면 자동 정리될 것이라고 가정하지 마세요.

6. 에셋으로 비디오 생성

비디오 참조에는 AIHubMix 에셋 생성 응답의 전체 `id`를 사용하며, 형식은 `asset://`입니다. 한 요청에서 참조하는 모든 에셋은 동일한 에셋 그룹에 속하고 현재 계정이 소유해야 하며, 모두 `active` 상태여야 합니다. 에셋 그룹도 사용 가능한 상태를 유지해야 합니다. | 에셋 유형 | 새 버전 `input_references[].type` | 호환 버전 중첩 필드 | | ------- | ------------------------------ | --------------- | | `image` | `image_url` | `image_url.url` | | `video` | `video_url` | `video_url.url` | | `audio` | `audio_url` | `audio_url.url` | 참조 유형은 에셋 생성 시의 `asset_type`과 일치해야 합니다. `asset://`는 비디오 참조 필드에 사용되며 브라우저 다운로드 주소로 사용할 수 없습니다.

새 비디오 프로토콜

먼저 엔드포인트 경로를 기준으로 현재 모델 Schema를 확인합니다. ```bash theme={null} curl --fail-with-body -sS "$BASE_URL/call/schema/models/$MODEL/endpoints" \ | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema' ``` 모델이 참조 이미지를 지원하는지 확인한 후 제출합니다. 다음은 이번 운영 환경 검증에 성공한 Seedance 2.5 파라미터를 사용합니다. `duration=4`, `resolution="480p"`, `aspect_ratio="3:4"`, `generate_audio=false`입니다. 새 버전은 `input_references[].url`을 직접 사용하며, `ASSET_ID`는 앞서 AIHubMix가 반환한 에셋 ID입니다. ```bash theme={null} VIDEO_BODY=$(jq -n --arg model "$MODEL" --arg asset "asset://$ASSET_ID" \ '{model: $model, prompt: "The person in the reference image smiles and waves at the camera.", duration: 4, resolution: "480p", aspect_ratio: "3:4", generate_audio: false, input_references: [{type: "image_url", url: $asset}]}') VIDEO_JSON=$(curl --fail-with-body -sS --max-time 120 \ -X POST "$BASE_URL/ai/v1/videos" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" \ -H "Content-Type: application/json" \ -d "$VIDEO_BODY") printf '%s\n' "$VIDEO_JSON" | jq . VIDEO_ID=$(printf '%s' "$VIDEO_JSON" | jq -er '.id') export VIDEO_ID ``` 새 버전은 정수 `duration`으로 요청 길이를 지정하며, 다른 허용값은 모델 Schema를 기준으로 합니다. `resolution="480p"`는 요청하는 해상도 등급이며 출력 너비나 높이가 480픽셀로 고정됨을 보장하지 않습니다. 실제 크기는 생성 파일을 기준으로 합니다. 첫 프레임과 마지막 프레임에는 `frame_images[].image_url.url`과 `frame_type`을 함께 사용할 수 있으며, 모델이 해당 기능을 지원할 때만 사용하세요. 전체 파라미터는 [비디오 생성](/ko/api/aihubmix-video-generation)을 참조하세요.

호환 비디오 프로토콜

기존 클라이언트가 `/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 검증 결과를 이 예제에 직접 적용할 수 없습니다. ```bash theme={null} COMPAT_MODEL="doubao-seedance-2-0-260128" COMPAT_BODY=$(jq -n --arg model "$COMPAT_MODEL" --arg asset "asset://$ASSET_ID" \ '{model: $model, prompt: "The person in the reference image smiles and waves at the camera.", extra_body: {content: [{type: "image_url", image_url: {url: $asset}, role: "reference_image"}]}}') curl --fail-with-body -sS --max-time 120 \ -X POST "$BASE_URL/v1/videos" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" \ -H "Content-Type: application/json" \ -d "$COMPAT_BODY" | jq . ``` 두 예제 중 하나를 선택하여 실행하세요. 각 비디오 생성은 독립적인 요청입니다. 호환 요청에 `input_references`를 섞어 넣지 마세요. 두 위치에 `content`를 모두 제공하면 `extra_body.content`가 최상위 `content`를 덮어쓰므로 한 곳에만 제공하는 것을 권장합니다. 호환 버전이 반환한 `id`는 `GET /v1/videos/{id}` 조회에 사용하고, 완료 후 `GET /v1/videos/{id}/content`로 다운로드합니다. 호환 버전 ID를 `/ai/v1/videos` 조회에 사용하지 마세요. 자세한 설명은 [호환 비디오 API](/ko/api/Video-Gen)를 참조하세요.

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

다음 Python 예제는 앞의 새 버전 생성 단계에 이어서만 사용합니다. 환경 변수의 `VIDEO_ID`를 읽으며 작업을 다시 생성하지 않습니다. `requests`를 설치해야 합니다. ```python theme={null} import os import time from pathlib import Path import requests base_url = "https://aihubmix.com" video_id = os.environ["VIDEO_ID"] headers = {"Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}"} deadline = time.monotonic() + 1800 while time.monotonic() < deadline: response = requests.get( f"{base_url}/ai/v1/videos/{video_id}", headers=headers, timeout=30 ) response.raise_for_status() task = response.json() status = task["status"] if status == "completed": break if status in {"failed", "cancelled"}: raise RuntimeError(f"视频任务未完成：{task.get('error') or status}") time.sleep(15) else: raise TimeoutError(f"本地等待已结束，请稍后继续查询原任务：{video_id}") temporary = Path("result.mp4.part") with requests.get( f"{base_url}/ai/v1/videos/{video_id}/content", headers=headers, timeout=120, stream=True, ) as response: response.raise_for_status() with temporary.open("wb") as output: for chunk in response.iter_content(chunk_size=1024 * 1024): if chunk: output.write(chunk) temporary.replace("result.mp4") print("视频已保存为 result.mp4") ``` 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 파라미터를 사용했으며 다음 결과가 관찰되었습니다. | 단계 | 이번 결과 | | ---------------- | --------------------------------------------------------------------------------------- | | 에셋 그룹 생성 | HTTP `201`, `status=pending_auth` | | 확인 세션 생성 | HTTP `201`, `status=pending` | | 본인 확인 완료 후 조회 | 세션 HTTP `200`, `status=verified`, 에셋 그룹 `active` | | 이미지 에셋 생성 및 조회 | 생성 HTTP `201`, `status=processing`, 이후 조회 HTTP `200`, `status=active` | | 새 버전 비디오 생성 및 조회 | 생성 HTTP `200`, `status=in_progress`, 이후 조회 HTTP `200`, `status=completed`, `error=null` | | 비디오 다운로드 | HTTP `200`, `Content-Type: video/mp4`, 파일이 ffmpeg 전체 디코딩을 통과함 | 이번 파일의 크기는 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로 제출한 작업도 포함됩니다. 삭제는 되돌릴 수 없으며, 다운로드한 비디오 파일은 직접 관리해야 합니다. 개별 에셋 삭제: ```bash theme={null} curl --fail-with-body -sS -X DELETE "$BASE_URL/ai/v1/assets/$ASSET_ID" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` `202`는 삭제가 아직 처리 중임을 의미합니다. `status=deleted`가 될 때까지 `GET /ai/v1/assets/{id}`로 계속 조회합니다. 삭제를 반복 요청하면 현재 상태를 반환합니다. `reconciling`이면 결과를 계속 확인하고, 계속 완료되지 않으면 지원팀에 문의하세요. 에셋 그룹 전체를 삭제하면 그룹 내 에셋도 함께 삭제됩니다. `cascade=true`를 명시적으로 전달해야 합니다. ```bash theme={null} curl --fail-with-body -sS -X DELETE \ "$BASE_URL/ai/v1/asset-groups/$GROUP_ID?cascade=true" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` 접수 후 `202`를 반환하며, `GET /ai/v1/asset-groups/{id}`로 조회합니다. `deleting`은 처리 중, `partially_deleted`는 아직 전체 삭제가 완료되지 않았음을 의미하며, `deleted`가 되어야 완료입니다. 목록에는 기본적으로 삭제된 에셋 그룹이 표시되지 않습니다. `409 asset_group_in_use`는 아직 종료되지 않은 작업이나 비디오 작업이 있음을 의미합니다. 기다리면서 관련 상태를 조회한 후 다시 시도하세요. 호환 비디오 작업은 종료 여부를 직접 확인해야 하며, 삭제 요청이 모든 호환 작업의 사용 여부를 자동으로 판단한다고 가정하지 마세요.

자주 묻는 질문

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

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

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

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

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

| HTTP | `error.code` | 처리 방법 | | ---- | ---------------------------------------------------------------------------- | ------------------------------------------- | | 400 | `invalid_request` | 요청 필드, 구조 및 사용한 비디오 프로토콜을 확인합니다 | | 400 | `asset_group_invalid` | 에셋 그룹 이름을 확인합니다 | | 400 | `asset_invalid` | URL, 에셋 유형 및 요청 식별자를 확인합니다 | | 400 | `asset_binding_mismatch` | 한 비디오 요청에서는 같은 에셋 그룹의 에셋만 참조합니다 | | 400 | `cascade_confirmation_required` | 그룹 전체 삭제 의도를 확인한 후 `cascade=true`를 전달합니다 | | 401 | `authentication_failed` | API Key 환경 변수와 인증 요청 헤더를 확인합니다 | | 403 | `async_not_enabled` | 비동기 작업을 활성화한 후 새 비디오 API를 사용합니다 | | 404 | `asset_group_not_found`, `asset_not_found`, `verification_session_not_found` | 리소스 ID와 소유 계정을 확인합니다 | | 409 | `asset_group_not_verified` | 본인 확인 결과를 조회하고 에셋 그룹이 사용 가능해질 때까지 기다립니다 | | 409 | `verification_session_active` | 기존 세션이나 에셋 그룹을 조회하여 중복 시작을 피합니다 | | 409 | `asset_not_ready` | 에셋 상태를 조회하고 비디오 생성 전에 `active`가 될 때까지 기다립니다 | | 409 | `asset_idempotency_conflict` | 식별자에 대응하는 원래 URL과 유형을 확인합니다 | | 409 | `asset_group_in_use` | 관련 작업과 비디오 작업이 종료된 후 삭제합니다 | | 503 | `asset_group_unavailable`, `verification_unavailable`, `asset_unavailable` | 나중에 다시 시도합니다. 계속 사용할 수 없으면 지원팀에 문의합니다 | 기타 비디오 오류는 [비동기 작업 오류 코드](/ko/api/async-tasks#error-codes)를 참조하세요. 피드백에는 발생 시간, HTTP 상태, `error.code`, 반환된 `error.tid`(있는 경우), 관련 리소스 ID를 제공하세요. API Key, 확인 링크 또는 서명된 이미지 주소는 제공하지 마세요.

참고 자료

* [BytePlus: 실존 인물 에셋 추가](https://docs.byteplus.com/en/docs/ModelArk/2315856) * [BytePlus: Seedance로 인물 비디오 생성](https://docs.byteplus.com/en/docs/ModelArk/2608626) * [AIHubMix 네이티브 비디오 생성](/ko/api/aihubmix-video-generation) * [OpenAI 호환 비디오 API](/ko/api/Video-Gen) * [비동기 작업](/ko/api/async-tasks) 업데이트: 2026-09-07