# Seedance 2.0 (https://wanapi.app/ko/docs/seedance-2-0) Seedance 2.0은 텍스트, 첫 프레임과 마지막 프레임, 이미지·동영상·오디오 참조 입력을 지원하며 480p, 720p, 1080p, 4K로 출력합니다. 요청당 최대 15초의 동영상을 생성할 수 있습니다. [모델 상세 정보 및 플레이그라운드](/ko/models/seedance-2-0)에서 확인하세요. ## Wan API 연동 [#wan-api-연동] API 기본 URL은 `https://api.wanapi.app`입니다. [API 키 설정](/ko/settings/apikeys)에서 **Seedance** 모델 제품군의 키를 만들고 `Authorization: Bearer YOUR_API_KEY`로 전송하세요. 키는 서버에 보관하세요. 플레이그라운드는 웹사이트 로그인 세션을 사용하며 같은 계정 잔액에서 요금이 차감됩니다. 브라우저에 키를 붙여 넣을 필요는 없습니다. 활성화된 계정과 충분한 잔액이 필요합니다. `GET /v1/models`로 해당 키에서 사용할 수 있는 모델을 확인할 수 있습니다. Seedance 모델은 `POST /v1/videos`를 사용하며, JSON 본문에서 모델을 선택합니다. | 설정 | Seedance 2.0 | | --------------- | ------------------------------------------------------------------------- | | 모델 ID | `bytedance/seedance-2.0` | | `resolution` | `480p`, `720p`, `1080p`, `4k`. 기본값: `720p`. | | `duration` | 출력 길이 4–15초 또는 자동 설정인 `-1`. 기본값: `5`. | | `aspectRatio` | `adaptive`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`. 기본값: `adaptive`. | | `generateAudio` | 기본값은 `true`입니다. `false`로 설정해도 토큰 요율은 낮아지지 않습니다. | | 출력 | 요청당 동영상 1개, 24 fps. | [요청 필드](#request-fields)에서 최상위 필드 13개를 모두 설명합니다. `aspectRatio`와 `generateAudio`를 포함하여 여기에 표시된 필드명을 사용하세요. ## Seedance 2.0 작업 제출 [#seedance-20-작업-제출] 다음은 720p, 4초 길이의 텍스트 기반 동영상 생성 요청입니다. 서버에서 `WAN_API_KEY`를 Seedance 키로 설정하세요. 한 번 제출한 후 반환된 `id`를 저장하세요. ```bash curl https://api.wanapi.app/v1/videos \ -H "Authorization: Bearer $WAN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "bytedance/seedance-2.0", "prompt": "A paper boat floats through a sunlit stream. Slow tracking shot.", "resolution": "720p", "aspectRatio": "16:9", "duration": 4, "generateAudio": true }' ``` ## Seedance 2.0 작업 조회 [#seedance-20-작업-조회] 반환된 `id`를 `TASK_ID`로 저장한 다음 같은 키로 조회하세요. 제출 시 작업 접수 정보가 반환되며, 동영상은 작업이 완료된 후 사용할 수 있습니다. 처음에는 5초 간격으로 조회하세요. [작업 상태와 다운로드](#poll-and-download-the-video)에서 자세히 확인할 수 있습니다. ```bash curl "https://api.wanapi.app/v1/videos/$TASK_ID" \ -H "Authorization: Bearer $WAN_API_KEY" ``` ## Seedance 2.0 요금 [#seedance-20-요금] 요율은 동영상 토큰 100만 개당 USD 기준입니다. 입력 및 출력 동영상 토큰 사용량에 따라 최종 요금이 결정됩니다. 해상도, 길이, 참조 동영상 입력이 사용량에 영향을 줍니다. 참조 동영상의 포함 여부에 맞는 요율을 확인하세요. 오디오에는 별도의 요금 구간이 없습니다. [Seedance 2.0 요금 및 예상 비용](/ko/models/seedance-2-0#pricing)을 확인하세요. 제출 전에 [플레이그라운드](/ko/models/seedance-2-0#playground)에서 예상 비용을 검토하세요. ## 요청 필드 [#request-fields] JSON 객체를 전송하세요. `model`은 필수이며, 비어 있지 않은 프롬프트 또는 하나 이상의 미디어 입력이 필요합니다. 나머지 필드는 선택 사항입니다. 정의되지 않은 필드는 거부됩니다. | 필드 | 유형 | 규격 | | ----------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `model` | 문자열 | 필수: `bytedance/seedance-2.0`. | | `prompt` | 문자열 | 텍스트 지시문. 이 서비스에서는 최대 20,000자입니다. 프롬프트 또는 미디어 입력이 필요합니다. | | `image` | URL 또는 URL 객체 | 첫 프레임 이미지 URL 또는 `type: "url"`, `url`, 선택 사항인 `mediaType`을 포함하는 객체입니다. `image`와 `frameImages` 중 하나만 사용하세요. | | `frameImages` | 배열 | `first_frame` 1개와 선택 사항인 `last_frame` 1개입니다. 각 항목에는 `frameType`과 `image`가 포함됩니다. 아래 프레임 예시를 참고하세요. | | `inputReferences` | 배열 | 이미지 최대 9개, 동영상 최대 3개입니다. 각 항목에는 `type: "url"`, `url`, `mediaType`이 포함됩니다. `data`/`mediaType`을 사용하는 URL 형식도 허용됩니다. | | `aspectRatio` | 문자열 | `adaptive`(기본값), `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`. | | `resolution` | 문자열 | `480p`, `720p`, `1080p`, `4k`. 기본값: `720p`. 해상도 구간으로 `854x480`, `1280x720`, `1920x1080`, `3840x2160`도 허용됩니다. 화면 형태는 `aspectRatio`로 선택하세요. | | `duration` | 정수 | 출력 길이 4–15초 또는 자동 설정인 `-1`. 기본값: `5`. | | `fps` | 정수 | `24`로 고정됩니다. 생략하거나 `24`를 보내세요. | | `seed` | 정수 | 선택 사항. `-1`부터 `2147483647`까지입니다. 결과의 재현성을 보장하지 않습니다. `providerOptions.bytedance.seed`를 동시에 지정하지 마세요. | | `generateAudio` | 불리언 | 오디오를 생성합니다. 기본값: `true`. 비활성화해도 토큰 요율은 달라지지 않습니다. | | `n` | 정수 | `1`로 고정됩니다. 요청당 동영상 1개입니다. | | `providerOptions` | 객체 | 선택 사항인 `bytedance` 객체: `referenceAudio`(HTTP(S) URL 최대 3개), `seed`(최상위 `seed`와 같은 범위). `draft: true`는 지원하지 않습니다. 정의되지 않은 옵션은 거부됩니다. | ### 입력 조합 및 미디어 제한 [#입력-조합-및-미디어-제한] * 첫 프레임에는 `image`를 사용하거나, 첫 프레임과 선택 사항인 마지막 프레임에 `frameImages`를 사용하세요. 마지막 프레임만 지정하거나 같은 프레임 유형을 중복 지정하면 거부됩니다. * 프레임은 `inputReferences` 또는 `providerOptions.bytedance.referenceAudio`와 함께 사용할 수 없습니다. * 참조 모드에서는 이미지 최대 9개, 동영상 최대 3개, 오디오 최대 3개를 사용할 수 있으며, 전체 참조 입력은 최대 15개입니다. * 미디어 입력은 공개 HTTP(S) URL이어야 합니다. 파일 바이트 직접 업로드와 인증 정보가 포함된 URL은 허용되지 않습니다. * 이미지: JPEG, PNG, WebP, BMP, TIFF 또는 GIF. 30 MB 미만, 가로·세로 각각 300–6000픽셀, 화면 비율 0.4–2.5. * 동영상: MP4 또는 MOV. 파일당 최대 50 MB, 각 클립 2–15초, 전체 길이 합계 최대 15초. 가로·세로 각각 300–6000픽셀, 화면 비율 0.4–2.5, 24–60 fps. * 오디오: MP3 또는 WAV. 파일당 최대 15 MB, 각 클립 2–15초, 전체 길이 합계 최대 15초. 참조 이미지나 동영상이 하나 이상 필요합니다. * 원격 미디어의 크기, 인코딩, 길이는 처리 중에 확인합니다. URL 유효성 검사만으로 파일을 사용할 수 있다고 보장할 수는 없습니다. * 이전 작업의 초안을 이용한 최종 렌더링과 임의의 원본 작업 옵션은 이 엔드포인트에서 제공하지 않습니다. ## 프레임 및 참조 입력 예시 [#프레임-및-참조-입력-예시] 다음 본문을 같은 `POST /v1/videos` 엔드포인트로 전송하세요. 제출하기 전에 모든 `example.com` URL을 직접 접근할 수 있는 본인의 미디어 URL로 바꾸세요. 작업이 끝날 때까지 입력 URL에 접근할 수 있도록 유지하세요. ### 첫 프레임과 마지막 프레임 [#첫-프레임과-마지막-프레임] 첫 프레임만 지정하려면 `image: "https://example.com/first-frame.jpg"`를 사용하고 `frameImages`는 생략하세요. 클립의 시작과 끝 프레임을 모두 지정하려면 다음과 같이 요청하세요. ```json { "model": "bytedance/seedance-2.0", "prompt": "The camera slowly moves from the opening scene to the closing scene.", "frameImages": [ { "frameType": "first_frame", "image": "https://example.com/first-frame.jpg" }, { "frameType": "last_frame", "image": "https://example.com/last-frame.jpg" } ], "aspectRatio": "adaptive", "resolution": "720p", "duration": 4 } ``` ### 이미지, 동영상 및 오디오 참조 [#이미지-동영상-및-오디오-참조] 이미지와 동영상 입력은 MIME 유형을 명시하여 `inputReferences`에 넣으세요. 오디오 URL은 `providerOptions.bytedance.referenceAudio`에 넣으세요. 이 요청에 프레임 입력을 추가하지 마세요. ```json { "model": "bytedance/seedance-2.0", "prompt": "Use the character from the image and the camera movement from the video.", "inputReferences": [ { "type": "url", "url": "https://example.com/character.jpg", "mediaType": "image/jpeg" }, { "type": "url", "url": "https://example.com/motion.mp4", "mediaType": "video/mp4" } ], "providerOptions": { "bytedance": { "referenceAudio": [ "https://example.com/sound.wav" ] } }, "resolution": "720p", "duration": 4 } ``` ## 작업 상태 조회 및 동영상 다운로드 [#poll-and-download-the-video] 작업이 접수되면 다음과 같은 객체가 반환됩니다. 아래 ID와 타임스탬프는 예시입니다. ```json { "id": "task_EXAMPLE", "object": "video", "model": "bytedance/seedance-2.0", "status": "queued", "progress": 0, "created_at": 1792022400 } ``` API 키로 `GET /v1/videos/{task_id}`를 반복 조회하세요. 조회 결과에는 같은 공개 작업 ID와 모델이 반환됩니다. `status`로 조회를 멈출 시점을 판단하세요. `progress`는 남은 시간의 예상치가 아닙니다. | 상태 | 의미 | 다음 단계 | | ------------- | ------------- | ------------------------------ | | `queued` | 작업이 접수되었습니다. | 조회를 계속하세요. | | `in_progress` | 생성이 진행 중입니다. | 조회를 계속하세요. | | `completed` | 동영상이 준비되었습니다. | `videos[0].url`을 확인하여 다운로드하세요. | | `failed` | 생성에 실패했습니다. | 조회를 멈추고 `error`를 확인하세요. | 완료된 작업의 조회 결과에는 `url`과 `mediaType`을 담은 객체 배열인 `videos`가 포함됩니다. 타임스탬프는 Unix 초 단위이며, 완료가 기록되면 `completed_at`이 표시됩니다. ```json { "id": "task_EXAMPLE", "object": "video", "model": "bytedance/seedance-2.0", "status": "completed", "progress": 100, "created_at": 1792022400, "completed_at": 1792022460, "videos": [ { "url": "/v1/tasks/task_EXAMPLE/artifacts/video/content", "mediaType": "video/mp4" } ] } ``` 반환된 URL이 상대 경로이면 `https://api.wanapi.app`을 기준으로 전체 URL을 구성하고 API 키로 인증하세요. 위 예시에서는 다음과 같이 다운로드합니다. ```bash curl "https://api.wanapi.app/v1/tasks/$TASK_ID/artifacts/video/content" \ -H "Authorization: Bearer $WAN_API_KEY" \ -o video.mp4 ``` 서명된 HTTPS 미디어 URL이 반환되면 해당 호스트에 API 키를 전달하지 말고 URL을 그대로 사용하세요. 결과 URL은 만료될 수 있습니다. 보관할 동영상은 본인의 저장소에 저장하세요. 기존 결과를 조회하거나 다운로드해도 새 생성 작업은 만들어지지 않습니다. 실패한 작업에는 `code`와 `message`가 포함된 `error` 객체가 반환됩니다. 예시는 다음과 같습니다. ```json { "id": "task_EXAMPLE", "object": "video", "model": "bytedance/seedance-2.0", "status": "failed", "error": { "code": "generation_failed", "message": "Video generation failed" } } ``` ## 결제 및 오류 처리 [#결제-및-오류-처리] 최종 요금은 실제 동영상 토큰 사용량과 현재 모델 요율에 따라 결정됩니다. 플레이그라운드에 표시되는 비용은 예상 최대 금액이며 확정 견적이 아닙니다. 동영상 길이가 길거나 출력 해상도가 높으면 토큰 사용량이 늘어날 수 있습니다. 실패한 요청에는 요금이 부과되지 않습니다. * **잘못된 매개변수:** 다시 제출하기 전에 필드나 입력 조합을 수정하세요. URL 형식뿐 아니라 미디어 형식과 제한도 확인하세요. * **인증 또는 모델 접근:** 요청한 모델을 사용할 수 있는 유효한 Seedance 키를 사용하세요. * **잔액 부족:** 새로운 유료 요청을 보내기 전에 잔액을 충전하세요. 키의 한도를 설정해도 계정 잔액이 추가되지는 않습니다. * **일시적인 조회 실패:** 대기 간격을 점차 늘리고 최대 대기 시간을 정하여 GET을 재시도하세요. 조회 실패가 생성 실패를 뜻하지는 않습니다. * **제출 시간 초과 또는 작업 ID 누락:** 결과를 확인할 수 없는 상태일 수 있습니다. POST를 자동으로 반복하지 마세요. 두 번째 유료 작업이 생성될 수 있습니다. * **다운로드 실패:** 새로 생성하기 전에 기존 결과의 다운로드를 재시도하세요. 제출 여부가 불확실하여 조사가 필요하면 작업 ID를 보관하고 [지원팀](/ko/contact)에 문의하세요. [Seedance 2.0 OpenAPI 스키마 다운로드](https://wanapi.app/models/seedance-2-0/openapi.json).