Seedance 2.0 또는 2.0-Fast에서 비디오 워크플로우를 구축하는 경우, Asset Library는 이미지, 비디오, 오디오와 같은 참조 미디어를 생성 과정에 깔끔하게 가져오는 방법입니다. 호출할 때마다 원본 미디어를 전달하는 대신, 파일을 한 번 등록하면 Atlas가 이를 검증하고 전처리하며, 사용자는 원하는 만큼 여러 번 생성 작업에서 고유 ID를 통해 해당 파일을 참조할 수 있습니다.

이 가이드를 통해 세 번의 cURL 호출만으로 참조 미디어를 생성에 활용하는 방법을 알아보겠습니다.

Asset Library란 무엇인가 (그리고 무엇이 아닌가)

Asset Library는 Seedance 2.0 / 2.0-Fast 비디오 생성을 위한 관리형 미디어 저장소입니다. 에셋을 등록하면 시스템이 전처리 과정을 거치며, 상태가 Active가 되면 생성 요청 시 asset://<asset_id> 형식으로 참조할 수 있습니다.

디버깅 시간을 줄이기 위해 사전에 알아두어야 할 두 가지 사항은 다음과 같습니다.

• 비디오와 오디오는 반드시 여기에 먼저 등록해야 합니다. 생성 요청 시 URL을 직접 포함(inline)하여 전달할 수 없습니다. 이미지만 인라인 전달이 가능합니다. 따라서 모든 비디오 또는 오디오 참조 워크플로우에서 Asset Library는 선택 사항이 아닌 필수 진입점입니다.
• 공개 URL을 통한 업로드만 지원합니다. Base64 또는 데이터 URL은 지원되지 않습니다. 등록 시 파일은 공개적으로 접근 가능한 URL에 위치해야 합니다.

시작하기 전에

대시보드에서 Atlas Cloud API 키를 발급받아야 합니다.

사용자들이 자주 실수하는 한 가지 상세 사항은 Asset Library와 생성 API가 서로 다른 호스트를 사용한다는 점입니다.

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

두 호스트 모두 동일한 인증 헤더를 사용합니다.

plaintextCopy
1export ATLASCLOUD_API_KEY="your-api-key-here"

plaintextCopy
1Authorization: Bearer $ATLASCLOUD_API_KEY

3단계 흐름

등록(Register) → 활성화(Active) 상태 확인 → 생성 시 참조

1단계 — 에셋 등록

Atlas에게 공개 URL을 알려줍니다. 타입을 Image, Video, 또는 Audio로 설정하세요 (기본값은 Image입니다).

plaintextCopy
1curl -X POST "https://console.atlascloud.ai/api/v1/sd/assets" \
2  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "type": "Video",
6    "url": "https://your-public-host.com/reference-clip.mp4"
7  }'

응답으로 에셋의 id와 Processing(처리 중) 상태가 반환됩니다.

아래와 같이 표시됩니다:

id(위에서 강조된 값)를 기록해 두세요. 이 ID로 상태를 확인하고 참조하게 됩니다.

참고: "공개 URL"이란 무엇인가?

가장 많이 실수하는 부분이므로 정확히 이해해야 합니다. Atlas는 해당 URL에 HTTP GET 요청을 보내 파일을 가져옵니다. 따라서 그 URL은 파일 원본 바이트를 직접 반환해야 하며, 로그인, 쿠키, "클릭하여 보기" 페이지, 또는 렌더링을 위한 JavaScript 실행 등이 필요 없어야 합니다.

빠른 테스트 방법: 시크릿 모드 브라우저 탭에서 해당 URL을 열어보세요. 로그인을 거치지 않고 이미지가 보이거나 비디오가 즉시 다운로드된다면 Atlas도 가져올 수 있습니다. 뷰어 페이지나 로그인 프롬프트, 미리보기 UI가 나타난다면 불가능합니다.

즉, Google 포토나 Google 드라이브 공유 링크는 작동하지 않습니다. 해당 링크는 Google의 인증 및 리다이렉트 시스템을 거쳐 미디어를 표시하는 웹 페이지로 연결되기 때문입니다. Atlas는 미디어가 아닌 페이지 래퍼를 가져오게 됩니다.

권장되는 방식:

• 공개 읽기(public-read) 권한이 설정된 객체 스토리지 또는 사전 서명된(presigned) URL — Amazon S3, Google Cloud Storage, Cloudflare R2, Azure Blob 등. 사전 서명된 URL은 공개적이면서도 시간 제한이 있어 이상적입니다.
• 파일을 직접 서빙하는 CDN 또는 자체 웹 서버.
• Atlas 자체 업로드 엔드포인트 — 로컬 파일(또는 Google 포토 등에서 내보낸 파일)만 있는 경우, 먼저 Atlas에 업로드하여 공개 저장소 URL을 얻은 다음 해당 URL을 등록하십시오:

plaintextCopy
1# 로컬 파일 업로드 → public storage.atlascloud.ai URL 반환
2curl -X POST "https://api.atlascloud.ai/api/v1/model/uploadMedia" \
3  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
4  -F "file=@./reference-clip.mp4"

위 응답의 download_url을 1단계에서 에셋을 등록할 때 url 값으로 사용하세요.

2단계 — 활성화될 때까지 상태 확인(Polling)

Atlas가 파일을 검증하고 전처리합니다. 상태가 Active로 바뀔 때까지 에셋 상태를 확인하세요. (이 엔드포인트는 작업이 Processing 상태인 동안 상위 작업을 자동으로 체크합니다.)

plaintextCopy
1curl "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \
2  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"

라이프사이클은 다음과 같습니다:

plaintextCopy
1Create → Processing → Active → (사용 준비 완료)
2                  ↓
3                Failed → error_code / error_message 확인

Failed 상태가 되면 error_code와 error_message를 통해 원인을 알 수 있습니다. 주로 형식, 크기, 시간 제한, 해상도 제한 등과 관련이 있습니다. 재등록하기 전에 아래 요구 사항 표를 확인하세요.

간혹 아래와 같이 정책 위반 오류가 발생하는 경우가 있는데, 이는 에셋이 가드레일을 위반했을 가능성이 높기 때문입니다. 에셋이 규칙을 위반하지 않았다고 확신하거나 본인이 저작권자라면 저희에게 문의하여 해결해 주시기 바랍니다!

3단계 — 생성 작업에서 참조

에셋이 Active 상태가 되면, Seedance 요청의 해당 필드(image, last_image, reference_images, reference_video, 또는 reference_audio 등)에 asset://<asset_id>를 입력합니다.

이 단계에서는 호스트가 api.atlascloud.ai로 변경됨에 유의하세요.

plaintextCopy
1curl -X POST "https://api.atlascloud.ai/api/v1/model/generateVideo" \
2  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model": "bytedance/seedance-2.0/image-to-video",
6    "input": {
7      "prompt": "A cinematic dolly shot, warm sunset light",
8      "image": "asset://<asset_id>"
9    }
10  }'

이 요청은 prediction id를 반환합니다. 이 ID로 비디오 생성이 완료되었는지 확인하세요:

plaintextCopy
1curl "https://api.atlascloud.ai/api/v1/model/prediction/<prediction_id>" \
2  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"

상태가 completed(또는 succeeded)이면 outputs에서 결과 URL을 확인할 수 있습니다.

이것이 전체 루프입니다. 에셋의 목적은 재사용성에 있습니다. 한 번 등록하면 필요한 만큼 많은 생성 작업에서 동일한 asset://<asset_id>를 참조할 수 있습니다.

에셋 관리

라이브러리는 전체 라이프사이클을 완벽하게 제어할 수 있도록 합니다.

plaintextCopy
1# 에셋 목록 확인 (페이지네이션 및 필터 지원)
2curl "https://console.atlascloud.ai/api/v1/sd/assets" \
3  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
4
5# 에셋 이름 변경
6curl -X PUT "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \
7  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
8  -H "Content-Type: application/json" \
9  -d '{ "name": "sunset-reference-v2" }'
10
11# 휴지통으로 이동 (복구 가능 — 물리적 삭제가 아닌 소프트 삭제)
12curl -X DELETE "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \
13  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
14
15# 휴지통 에셋 목록 확인
16curl "https://console.atlascloud.ai/api/v1/sd/assets/trash" \
17  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
18
19# 휴지통에서 복구
20curl -X POST "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>/restore" \
21  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"

삭제는 의도적으로 복구가 가능하게 설계되었습니다. 에셋은 휴지통으로 이동하며 복구할 수 있으므로, 실수로 삭제하더라도 에셋을 잃지 않습니다.

입력 요구 사항

검증은 등록 단계에서 이루어지므로, 형식이 잘못된 파일은 생성 요청을 보내기 전에 미리 실패 처리됩니다. Failed 상태를 방지하기 위해 아래 제한 사항을 확인하세요.

이미지

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

비디오

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

오디오

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

오류 코드

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

기억해야 할 유의 사항

• 비디오와 오디오는 반드시 사전 등록해야 합니다. 이미지만 인라인으로 전달할 수 있습니다. 비디오/오디오 등록 단계를 건너뛰면 생성할 참조 파일이 없게 됩니다.
• URL만 지원, Base64 불가. 소스 파일은 등록 시점에 반드시 공개 URL에 위치해야 합니다.
• 두 개의 호스트. 에셋은 console.atlascloud.ai, 생성은 api.atlascloud.ai입니다. 혼동하면 404 / 401 오류의 가장 흔한 원인이 됩니다.
• 검증 후 생성. 잘못된 입력은 생성이 시작되기 전 등록 단계에서 실패하게 되며, 이것이 바로 이 시스템의 핵심입니다. 요구 사항 표를 먼저 확인하세요.

구축 시작하기

API 키를 발급받고 실제 Seedance 2.0 엔드포인트에서 워크플로우를 테스트해 보세요.

• API 키 발급받기
• Seedance 2.0 모델
• 문서