콘텐츠로 이동
무료 가입
Wan

Wan 동영상 API: 텍스트·이미지·참조 생성 및 편집

BetterToken API Key로 Wan에 연결하고 Model ID와 작업 유형에 맞는 필드, 미디어, 생성 방식을 선택하세요.

텍스트, 첫 프레임 또는 참조 미디어로 동영상을 생성하고 기존 동영상을 편집할 수 있습니다. 3.0과 Prime은 세 가지 생성 작업을 지원합니다. 2.7은 텍스트 기반 동영상 생성, 이미지 기반 동영상 생성, 참조 생성, 편집별로 Model ID를 선택하세요.

먼저 BetterToken API Key를 준비하세요. Base URL은 https://bettertoken.ai/v1이며 인증에는 Authorization: Bearer YOUR_API_KEY를 사용합니다. Model ID는 대소문자까지 정확히 복사하세요.

아래의 모든 request.json은 같은 흐름을 사용합니다. 먼저 견적을 확인한 뒤 생성, 폴링 및 다운로드를 진행하세요. 견적은 생성을 시작하지 않으며 작업 생성 시 유료 작업이 제출됩니다. 현재 요금은 모델 광장에서 확인하세요.

모델 및 작업 유형

다음 표는 작업 유형별 허용 값을 보여 줍니다. 필드 기본값, 미디어 개수, 조합 제한은 해당 절을 확인하세요. 미디어 크기는 1 MB = 1048576바이트로 환산합니다.

Model ID작업길이(초)출력 설정화면 비율오디오미디어 역할
wan2.7-i2vimage_to_video2–15, 간격 1720p, 1080p전달하지 않음provider_defaultfirst_frame, last_frame, driving_audio
wan2.7-r2vreference_to_video2–15, 간격 1720p, 1080p16:9, 9:16, 1:1, 4:3, 3:4provider_defaultreference_image, reference_video
wan2.7-t2vtext_to_video2–15, 간격 1720p, 1080p16:9, 9:16, 1:1, 4:3, 3:4provider_defaultdriving_audio
wan2.7-videoeditvideo_edit2–15, 간격 1; auto 사용 가능720p, 1080p전달하지 않음provider_defaultbase_video
wan3.0-video-primeimage_to_video2–30, 간격 1; auto 사용 가능480p, 720p, 1080padaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16on, offfirst_frame, last_frame
wan3.0-video-primereference_to_video2–30, 간격 1; auto 사용 가능480p, 720p, 1080padaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16on, offreference_image, reference_video, reference_audio
wan3.0-video-primetext_to_video2–30, 간격 1; auto 사용 가능480p, 720p, 1080padaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16on, off없음
wan3.0-videoimage_to_video2–30, 간격 1; auto 사용 가능480p, 720p, 1080padaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16on, offfirst_frame, last_frame
wan3.0-videoreference_to_video2–30, 간격 1; auto 사용 가능480p, 720p, 1080padaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16on, offreference_image, reference_video, reference_audio
wan3.0-videotext_to_video2–30, 간격 1; auto 사용 가능480p, 720p, 1080padaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16on, off없음

이미지-투-비디오(wan2.7-i2v, 그리고 adaptive를 지정한 wan3.0-video / wan3.0-video-prime)와 adaptive를 지정한 레퍼런스-투-비디오에서는 출력 화면비가 입력 이미지를 따릅니다. 출력 등급은 고정 가로세로 크기가 아니라 전체 픽셀 수를 정합니다. 이 페이지의 1:1 샘플 이미지로 테스트한 결과 720p는 960×960, 480p는 640×640이었습니다. 가로형 또는 세로형으로 고정하려면 output.aspect_ratio를 명시하세요(wan2.7-i2v는 이 필드를 지원하지 않으므로 원하는 비율의 입력 이미지를 사용하세요).

예제 미디어

이미지 기반 동영상 생성 및 이미지 참조 예제는 흰 테이블 위의 파란 도자기 머그잔을 사용합니다. 예제 이미지를 그대로 사용하거나, 사용 권한이 있고 이 페이지의 제한을 충족하는 공개 HTTPS 미디어로 먼저 바꿔도 됩니다.

동영상 생성 참조 이미지: 흰 테이블 위의 파란 도자기 머그잔

편집 예제는 도시 광장에 있는 소년의 동영상을 사용합니다. 길이는 약 5.04초이며 1280 × 720, 24 fps입니다. 참조 이미지가 아니라 base_video로 전달합니다.

텍스트로 동영상 생성

wan2.7-t2v

텍스트 설명만으로 동영상을 생성하려면 이 작업 유형을 사용하세요.

model을 이 절의 Model ID로, operation을 text_to_video로 설정하세요. 아래 표에 있는 생성 필드만 사용하고 미디어는 media 배열에 넣으세요.

필드유형필수허용 값 또는 범위기본값
audio.modestring아니요provider_defaultprovider_default
duration.modestring아니요fixedfixed
duration.secondsinteger아니요2–15, 간격 1초; 고정 길이에만 사용5
output.aspect_ratiostring아니요16:9, 9:16, 1:1, 4:3, 3:416:9
output.formatstring아니요mp4mp4
output.resolutionstring아니요720p, 1080p1080p
promptstring예문자열없음
provider_options.alibaba.prompt_extendboolean아니요true / false; 프롬프트 확장 제어true
seedinteger아니요0–2147483647, 간격 1; 난수 시드, 0 허용없음
watermarkboolean아니요false, truefalse

미디어 요구 사항

미디어 역할유형 및 개수형식파일별 제한
driving_audioaudio, 선택, 최대 1개wav, mp3최대 크기 15 MB; 길이 2–30초

미디어의 필수 여부는 아래 조합 제한도 충족해야 합니다.

선택 항목인 driving_audio는 구동 오디오이며 type="audio"를 사용합니다. 참조 생성의 reference_audio와는 다른 미디어 역할입니다.

조합 제한

  • duration.mode="fixed"이면 duration.seconds가 필요합니다. fixed를 명시할 때는 초 단위 길이도 함께 입력하세요.

요청 예제

아래 JSON을 request.json으로 저장하고 공통 흐름에 따라 견적을 먼저 확인한 뒤 작업을 생성하세요.

{
"model": "wan2.7-t2v",
"operation": "text_to_video",
"prompt": "A blue ceramic mug on a white table. Slowly move the camera closer in soft daylight.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"output": {
"resolution": "720p",
"aspect_ratio": "16:9"
}
}

자주 발생하는 422 오류

422 오류 코드해결 방법
enum / range / step이 절의 필드 표에 따라 값과 간격을 조정하세요.
unsupported_field이 작업 유형의 필드 표에 없는 필드를 삭제하세요.
requires이 절의 조합 제한에 따라 초 단위 길이, 화면 비율, 오디오 설정 또는 미디어를 추가하세요.
count / media_role이 절의 미디어 표에 따라 역할과 개수를 조정하세요.
video_input_unsupported공개 HTTPS URL, Content-Type, 파일 형식을 확인한 뒤 견적을 다시 요청하세요.

wan3.0-video-prime

텍스트 설명만으로 동영상을 생성하려면 이 작업 유형을 사용하세요.

model을 이 절의 Model ID로, operation을 text_to_video로 설정하세요. 아래 표에 있는 생성 필드만 사용하고 미디어는 media 배열에 넣으세요.

필드유형필수허용 값 또는 범위기본값
audio.modestring아니요on, offon
duration.modestring아니요fixed, autofixed
duration.secondsinteger아니요2–30, 간격 1초; 고정 길이에만 사용5
output.aspect_ratiostring아니요adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16adaptive
output.formatstring아니요mp4mp4
output.resolutionstring아니요480p, 720p, 1080p1080p
promptstring예문자열없음
provider_options.alibaba.prompt_extendboolean아니요true / false; 프롬프트 확장 제어true
seedinteger아니요0–2147483647, 간격 1; 난수 시드, 0 허용없음
watermarkboolean아니요false, truefalse

미디어 요구 사항

이 작업 유형은 미디어를 받지 않습니다.

조합 제한

  • duration.mode="fixed"이면 duration.seconds가 필요합니다. fixed를 명시할 때는 초 단위 길이도 함께 입력하세요.
  • duration.mode="auto"를 사용하면 duration.seconds를 전달하지 마세요.

요청 예제

아래 JSON을 request.json으로 저장하고 공통 흐름에 따라 견적을 먼저 확인한 뒤 작업을 생성하세요.

{
"model": "wan3.0-video-prime",
"operation": "text_to_video",
"prompt": "A blue ceramic mug on a white table. Slowly move the camera closer in soft daylight.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"output": {
"resolution": "720p",
"aspect_ratio": "16:9"
}
}

자주 발생하는 422 오류

422 오류 코드해결 방법
enum / range / step이 절의 필드 표에 따라 값과 간격을 조정하세요.
unsupported_field이 작업 유형의 필드 표에 없는 필드를 삭제하세요.
requires이 절의 조합 제한에 따라 초 단위 길이, 화면 비율, 오디오 설정 또는 미디어를 추가하세요.
excludes자동 길이 또는 마지막 프레임과 충돌하는 필드를 삭제하세요.

wan3.0-video

텍스트 설명만으로 동영상을 생성하려면 이 작업 유형을 사용하세요.

model을 이 절의 Model ID로, operation을 text_to_video로 설정하세요. 아래 표에 있는 생성 필드만 사용하고 미디어는 media 배열에 넣으세요.

필드유형필수허용 값 또는 범위기본값
audio.modestring아니요on, offon
duration.modestring아니요fixed, autofixed
duration.secondsinteger아니요2–30, 간격 1초; 고정 길이에만 사용5
output.aspect_ratiostring아니요adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16adaptive
output.formatstring아니요mp4mp4
output.resolutionstring아니요480p, 720p, 1080p1080p
promptstring예문자열없음
provider_options.alibaba.prompt_extendboolean아니요true / false; 프롬프트 확장 제어true
seedinteger아니요0–2147483647, 간격 1; 난수 시드, 0 허용없음
watermarkboolean아니요false, truefalse

미디어 요구 사항

이 작업 유형은 미디어를 받지 않습니다.

조합 제한

  • duration.mode="fixed"이면 duration.seconds가 필요합니다. fixed를 명시할 때는 초 단위 길이도 함께 입력하세요.
  • duration.mode="auto"를 사용하면 duration.seconds를 전달하지 마세요.

요청 예제

아래 JSON을 request.json으로 저장하고 공통 흐름에 따라 견적을 먼저 확인한 뒤 작업을 생성하세요.

{
"model": "wan3.0-video",
"operation": "text_to_video",
"prompt": "A blue ceramic mug on a white table. Slowly move the camera closer in soft daylight.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"output": {
"resolution": "720p",
"aspect_ratio": "16:9"
}
}

자주 발생하는 422 오류

422 오류 코드해결 방법
enum / range / step이 절의 필드 표에 따라 값과 간격을 조정하세요.
unsupported_field이 작업 유형의 필드 표에 없는 필드를 삭제하세요.
requires이 절의 조합 제한에 따라 초 단위 길이, 화면 비율, 오디오 설정 또는 미디어를 추가하세요.
excludes자동 길이 또는 마지막 프레임과 충돌하는 필드를 삭제하세요.

이미지로 동영상 생성

wan2.7-i2v

이미지로 시작 장면 또는 시작·끝 장면을 지정하려면 이 작업 유형을 사용하세요.

model을 이 절의 Model ID로, operation을 image_to_video로 설정하세요. 아래 표에 있는 생성 필드만 사용하고 미디어는 media 배열에 넣으세요.

필드유형필수허용 값 또는 범위기본값
audio.modestring아니요provider_defaultprovider_default
duration.modestring아니요fixedfixed
duration.secondsinteger아니요2–15, 간격 1초; 고정 길이에만 사용5
output.formatstring아니요mp4mp4
output.resolutionstring아니요720p, 1080p1080p
promptstring예문자열없음
provider_options.alibaba.prompt_extendboolean아니요true / false; 프롬프트 확장 제어true
seedinteger아니요0–2147483647, 간격 1; 난수 시드, 0 허용없음
watermarkboolean아니요false, truefalse

미디어 요구 사항

미디어 역할유형 및 개수형식파일별 제한
first_frameimage, 1개(필수)jpeg, jpg, png, bmp, webp최대 크기 20 MB; 너비 240–8000 px; 높이 240–8000 px
last_frameimage, 선택, 최대 1개jpeg, jpg, png, bmp, webp최대 크기 20 MB; 너비 240–8000 px; 높이 240–8000 px
driving_audioaudio, 선택, 최대 1개wav, mp3최대 크기 15 MB; 길이 2–30초

미디어의 필수 여부는 아래 조합 제한도 충족해야 합니다.

선택 항목인 driving_audio는 구동 오디오이며 type="audio"를 사용합니다. 참조 생성의 reference_audio와는 다른 미디어 역할입니다.

조합 제한

  • duration.mode="fixed"이면 duration.seconds가 필요합니다. fixed를 명시할 때는 초 단위 길이도 함께 입력하세요.
  • first_frame을 반드시 제공하세요.

요청 예제

아래 JSON을 request.json으로 저장하고 공통 흐름에 따라 견적을 먼저 확인한 뒤 작업을 생성하세요.

{
"model": "wan2.7-i2v",
"operation": "image_to_video",
"prompt": "Slowly move the camera closer to the blue ceramic mug. Preserve its shape and the white table.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"output": {
"resolution": "720p"
},
"media": [
{
"id": "first",
"type": "image",
"role": "first_frame",
"source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png"
}
]
}

자주 발생하는 422 오류

422 오류 코드해결 방법
enum / range / step이 절의 필드 표에 따라 값과 간격을 조정하세요.
unsupported_field이 작업 유형의 필드 표에 없는 필드를 삭제하세요.
requires이 절의 조합 제한에 따라 초 단위 길이, 화면 비율, 오디오 설정 또는 미디어를 추가하세요.
count / media_role이 절의 미디어 표에 따라 역할과 개수를 조정하세요.
video_input_unsupported공개 HTTPS URL, Content-Type, 파일 형식을 확인한 뒤 견적을 다시 요청하세요.

wan3.0-video-prime

이미지로 시작 장면 또는 시작·끝 장면을 지정하려면 이 작업 유형을 사용하세요.

model을 이 절의 Model ID로, operation을 image_to_video로 설정하세요. 아래 표에 있는 생성 필드만 사용하고 미디어는 media 배열에 넣으세요.

필드유형필수허용 값 또는 범위기본값
audio.modestring아니요on, offon
duration.modestring아니요fixed, autofixed
duration.secondsinteger아니요2–30, 간격 1초; 고정 길이에만 사용5
output.aspect_ratiostring아니요adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16adaptive
output.formatstring아니요mp4mp4
output.resolutionstring아니요480p, 720p, 1080p1080p
promptstring예문자열없음
provider_options.alibaba.prompt_extendboolean아니요true / false; 프롬프트 확장 제어true
seedinteger아니요0–2147483647, 간격 1; 난수 시드, 0 허용없음
watermarkboolean아니요false, truefalse

미디어 요구 사항

미디어 역할유형 및 개수형식파일별 제한
first_frameimage, 1개(필수)jpeg, jpg, png, bmp, webp최대 크기 20 MB; 너비 240–8000 px; 높이 240–8000 px
last_frameimage, 선택, 최대 1개jpeg, jpg, png, bmp, webp최대 크기 20 MB; 너비 240–8000 px; 높이 240–8000 px

미디어의 필수 여부는 아래 조합 제한도 충족해야 합니다.

조합 제한

  • duration.mode="fixed"이면 duration.seconds가 필요합니다. fixed를 명시할 때는 초 단위 길이도 함께 입력하세요.
  • duration.mode="auto"를 사용하면 duration.seconds를 전달하지 마세요.
  • first_frame, last_frame 중 하나 이상을 제공하세요.

요청 예제

아래 JSON을 request.json으로 저장하고 공통 흐름에 따라 견적을 먼저 확인한 뒤 작업을 생성하세요.

{
"model": "wan3.0-video-prime",
"operation": "image_to_video",
"prompt": "Slowly move the camera closer to the blue ceramic mug. Preserve its shape and the white table.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"output": {
"resolution": "720p",
"aspect_ratio": "adaptive"
},
"media": [
{
"id": "first",
"type": "image",
"role": "first_frame",
"source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png"
}
]
}

자주 발생하는 422 오류

422 오류 코드해결 방법
enum / range / step이 절의 필드 표에 따라 값과 간격을 조정하세요.
unsupported_field이 작업 유형의 필드 표에 없는 필드를 삭제하세요.
requires이 절의 조합 제한에 따라 초 단위 길이, 화면 비율, 오디오 설정 또는 미디어를 추가하세요.
excludes자동 길이 또는 마지막 프레임과 충돌하는 필드를 삭제하세요.
count / media_role이 절의 미디어 표에 따라 역할과 개수를 조정하세요.
video_input_unsupported공개 HTTPS URL, Content-Type, 파일 형식을 확인한 뒤 견적을 다시 요청하세요.

wan3.0-video

이미지로 시작 장면 또는 시작·끝 장면을 지정하려면 이 작업 유형을 사용하세요.

model을 이 절의 Model ID로, operation을 image_to_video로 설정하세요. 아래 표에 있는 생성 필드만 사용하고 미디어는 media 배열에 넣으세요.

필드유형필수허용 값 또는 범위기본값
audio.modestring아니요on, offon
duration.modestring아니요fixed, autofixed
duration.secondsinteger아니요2–30, 간격 1초; 고정 길이에만 사용5
output.aspect_ratiostring아니요adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16adaptive
output.formatstring아니요mp4mp4
output.resolutionstring아니요480p, 720p, 1080p1080p
promptstring예문자열없음
provider_options.alibaba.prompt_extendboolean아니요true / false; 프롬프트 확장 제어true
seedinteger아니요0–2147483647, 간격 1; 난수 시드, 0 허용없음
watermarkboolean아니요false, truefalse

미디어 요구 사항

미디어 역할유형 및 개수형식파일별 제한
first_frameimage, 1개(필수)jpeg, jpg, png, bmp, webp최대 크기 20 MB; 너비 240–8000 px; 높이 240–8000 px
last_frameimage, 선택, 최대 1개jpeg, jpg, png, bmp, webp최대 크기 20 MB; 너비 240–8000 px; 높이 240–8000 px

미디어의 필수 여부는 아래 조합 제한도 충족해야 합니다.

조합 제한

  • duration.mode="fixed"이면 duration.seconds가 필요합니다. fixed를 명시할 때는 초 단위 길이도 함께 입력하세요.
  • duration.mode="auto"를 사용하면 duration.seconds를 전달하지 마세요.
  • first_frame, last_frame 중 하나 이상을 제공하세요.

요청 예제

아래 JSON을 request.json으로 저장하고 공통 흐름에 따라 견적을 먼저 확인한 뒤 작업을 생성하세요.

{
"model": "wan3.0-video",
"operation": "image_to_video",
"prompt": "Slowly move the camera closer to the blue ceramic mug. Preserve its shape and the white table.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"output": {
"resolution": "720p",
"aspect_ratio": "adaptive"
},
"media": [
{
"id": "first",
"type": "image",
"role": "first_frame",
"source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png"
}
]
}

자주 발생하는 422 오류

422 오류 코드해결 방법
enum / range / step이 절의 필드 표에 따라 값과 간격을 조정하세요.
unsupported_field이 작업 유형의 필드 표에 없는 필드를 삭제하세요.
requires이 절의 조합 제한에 따라 초 단위 길이, 화면 비율, 오디오 설정 또는 미디어를 추가하세요.
excludes자동 길이 또는 마지막 프레임과 충돌하는 필드를 삭제하세요.
count / media_role이 절의 미디어 표에 따라 역할과 개수를 조정하세요.
video_input_unsupported공개 HTTPS URL, Content-Type, 파일 형식을 확인한 뒤 견적을 다시 요청하세요.

참조 미디어로 생성

wan2.7-r2v

참조 미디어로 피사체나 동작의 특징을 유지하려면 이 작업 유형을 사용하세요.

model을 이 절의 Model ID로, operation을 reference_to_video로 설정하세요. 아래 표에 있는 생성 필드만 사용하고 미디어는 media 배열에 넣으세요.

필드유형필수허용 값 또는 범위기본값
audio.modestring아니요provider_defaultprovider_default
duration.modestring아니요fixedfixed
duration.secondsinteger아니요2–15, 간격 1초; 고정 길이에만 사용5
output.aspect_ratiostring아니요16:9, 9:16, 1:1, 4:3, 3:416:9
output.formatstring아니요mp4mp4
output.resolutionstring아니요720p, 1080p1080p
promptstring예문자열없음
provider_options.alibaba.prompt_extendboolean아니요true / false; 프롬프트 확장 제어true
seedinteger아니요0–2147483647, 간격 1; 난수 시드, 0 허용없음
watermarkboolean아니요false, truefalse

미디어 요구 사항

미디어 역할유형 및 개수형식파일별 제한
reference_imageimage, 선택, 최대 10개jpeg, jpg, png, bmp, webp최대 크기 20 MB; 너비 240–8000 px; 높이 240–8000 px
reference_videovideo, 선택, 최대 5개mp4, mov최대 크기 100 MB; 너비 240–4096 px; 높이 240–4096 px; 길이 1–15초; 최소 프레임 속도 16 fps; 이 역할의 최대 총길이 15초

미디어의 필수 여부는 아래 조합 제한도 충족해야 합니다.

조합 제한

  • duration.mode="fixed"이면 duration.seconds가 필요합니다. fixed를 명시할 때는 초 단위 길이도 함께 입력하세요.
  • reference_image, reference_video 중 하나 이상을 제공하세요.

요청 예제

아래 JSON을 request.json으로 저장하고 공통 흐름에 따라 견적을 먼저 확인한 뒤 작업을 생성하세요.

{
"model": "wan2.7-r2v",
"operation": "reference_to_video",
"prompt": "Create a product video of the blue ceramic mug in the reference image. Keep its shape and color.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"output": {
"resolution": "720p",
"aspect_ratio": "16:9"
},
"media": [
{
"id": "reference",
"type": "image",
"role": "reference_image",
"source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png"
}
]
}

자주 발생하는 422 오류

422 오류 코드해결 방법
enum / range / step이 절의 필드 표에 따라 값과 간격을 조정하세요.
unsupported_field이 작업 유형의 필드 표에 없는 필드를 삭제하세요.
requires이 절의 조합 제한에 따라 초 단위 길이, 화면 비율, 오디오 설정 또는 미디어를 추가하세요.
count / media_role이 절의 미디어 표에 따라 역할과 개수를 조정하세요.
video_input_unsupported공개 HTTPS URL, Content-Type, 파일 형식을 확인한 뒤 견적을 다시 요청하세요.

wan3.0-video-prime

참조 미디어로 피사체나 동작의 특징을 유지하려면 이 작업 유형을 사용하세요.

model을 이 절의 Model ID로, operation을 reference_to_video로 설정하세요. 아래 표에 있는 생성 필드만 사용하고 미디어는 media 배열에 넣으세요.

필드유형필수허용 값 또는 범위기본값
audio.modestring아니요on, offon
duration.modestring아니요fixed, autofixed
duration.secondsinteger아니요2–30, 간격 1초; 고정 길이에만 사용5
output.aspect_ratiostring아니요adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16adaptive
output.formatstring아니요mp4mp4
output.resolutionstring아니요480p, 720p, 1080p1080p
promptstring예문자열없음
provider_options.alibaba.prompt_extendboolean아니요true / false; 프롬프트 확장 제어true
seedinteger아니요0–2147483647, 간격 1; 난수 시드, 0 허용없음
watermarkboolean아니요false, truefalse

미디어 요구 사항

미디어 역할유형 및 개수형식파일별 제한
reference_imageimage, 선택, 최대 10개jpeg, jpg, png, bmp, webp최대 크기 20 MB; 너비 240–8000 px; 높이 240–8000 px
reference_videovideo, 선택, 최대 5개mp4, mov최대 크기 100 MB; 너비 240–4096 px; 높이 240–4096 px; 길이 1–15초; 최소 프레임 속도 16 fps; 이 역할의 최대 총길이 15초
reference_audioaudio, 선택, 최대 5개wav, mp3최대 크기 15 MB; 길이 1–15초; 이 역할의 최대 총길이 15초

미디어의 필수 여부는 아래 조합 제한도 충족해야 합니다.

조합 제한

  • duration.mode="fixed"이면 duration.seconds가 필요합니다. fixed를 명시할 때는 초 단위 길이도 함께 입력하세요.
  • duration.mode="auto"를 사용하면 duration.seconds를 전달하지 마세요.
  • reference_image, reference_video, reference_audio 중 하나 이상을 제공하세요.
  • 참조 동영상이 있으면 입력 동영상 총길이와 출력 길이의 합이 30초를 넘을 수 없습니다. 자동 길이를 사용해도 출력 상한은 이 남은 시간의 제한을 받습니다.

요청 예제

아래 JSON을 request.json으로 저장하고 공통 흐름에 따라 견적을 먼저 확인한 뒤 작업을 생성하세요.

{
"model": "wan3.0-video-prime",
"operation": "reference_to_video",
"prompt": "Create a product video of the blue ceramic mug in the reference image. Keep its shape and color.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"output": {
"resolution": "720p",
"aspect_ratio": "adaptive"
},
"media": [
{
"id": "reference",
"type": "image",
"role": "reference_image",
"source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png"
}
]
}

자주 발생하는 422 오류

422 오류 코드해결 방법
enum / range / step이 절의 필드 표에 따라 값과 간격을 조정하세요.
unsupported_field이 작업 유형의 필드 표에 없는 필드를 삭제하세요.
requires이 절의 조합 제한에 따라 초 단위 길이, 화면 비율, 오디오 설정 또는 미디어를 추가하세요.
excludes자동 길이 또는 마지막 프레임과 충돌하는 필드를 삭제하세요.
sum_lte참조 동영상 총길이 또는 출력 길이를 줄여 합계가 30초를 넘지 않도록 하세요.
count / media_role이 절의 미디어 표에 따라 역할과 개수를 조정하세요.
video_input_unsupported공개 HTTPS URL, Content-Type, 파일 형식을 확인한 뒤 견적을 다시 요청하세요.

wan3.0-video

참조 미디어로 피사체나 동작의 특징을 유지하려면 이 작업 유형을 사용하세요.

model을 이 절의 Model ID로, operation을 reference_to_video로 설정하세요. 아래 표에 있는 생성 필드만 사용하고 미디어는 media 배열에 넣으세요.

필드유형필수허용 값 또는 범위기본값
audio.modestring아니요on, offon
duration.modestring아니요fixed, autofixed
duration.secondsinteger아니요2–30, 간격 1초; 고정 길이에만 사용5
output.aspect_ratiostring아니요adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16adaptive
output.formatstring아니요mp4mp4
output.resolutionstring아니요480p, 720p, 1080p1080p
promptstring예문자열없음
provider_options.alibaba.prompt_extendboolean아니요true / false; 프롬프트 확장 제어true
seedinteger아니요0–2147483647, 간격 1; 난수 시드, 0 허용없음
watermarkboolean아니요false, truefalse

미디어 요구 사항

미디어 역할유형 및 개수형식파일별 제한
reference_imageimage, 선택, 최대 10개jpeg, jpg, png, bmp, webp최대 크기 20 MB; 너비 240–8000 px; 높이 240–8000 px
reference_videovideo, 선택, 최대 5개mp4, mov최대 크기 100 MB; 너비 240–4096 px; 높이 240–4096 px; 길이 1–15초; 최소 프레임 속도 16 fps; 이 역할의 최대 총길이 15초
reference_audioaudio, 선택, 최대 5개wav, mp3최대 크기 15 MB; 길이 1–15초; 이 역할의 최대 총길이 15초

미디어의 필수 여부는 아래 조합 제한도 충족해야 합니다.

조합 제한

  • duration.mode="fixed"이면 duration.seconds가 필요합니다. fixed를 명시할 때는 초 단위 길이도 함께 입력하세요.
  • duration.mode="auto"를 사용하면 duration.seconds를 전달하지 마세요.
  • reference_image, reference_video, reference_audio 중 하나 이상을 제공하세요.
  • 참조 동영상이 있으면 입력 동영상 총길이와 출력 길이의 합이 30초를 넘을 수 없습니다. 자동 길이를 사용해도 출력 상한은 이 남은 시간의 제한을 받습니다.

요청 예제

아래 JSON을 request.json으로 저장하고 공통 흐름에 따라 견적을 먼저 확인한 뒤 작업을 생성하세요.

{
"model": "wan3.0-video",
"operation": "reference_to_video",
"prompt": "Create a product video of the blue ceramic mug in the reference image. Keep its shape and color.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"output": {
"resolution": "720p",
"aspect_ratio": "adaptive"
},
"media": [
{
"id": "reference",
"type": "image",
"role": "reference_image",
"source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png"
}
]
}

자주 발생하는 422 오류

422 오류 코드해결 방법
enum / range / step이 절의 필드 표에 따라 값과 간격을 조정하세요.
unsupported_field이 작업 유형의 필드 표에 없는 필드를 삭제하세요.
requires이 절의 조합 제한에 따라 초 단위 길이, 화면 비율, 오디오 설정 또는 미디어를 추가하세요.
excludes자동 길이 또는 마지막 프레임과 충돌하는 필드를 삭제하세요.
sum_lte참조 동영상 총길이 또는 출력 길이를 줄여 합계가 30초를 넘지 않도록 하세요.
count / media_role이 절의 미디어 표에 따라 역할과 개수를 조정하세요.
video_input_unsupported공개 HTTPS URL, Content-Type, 파일 형식을 확인한 뒤 견적을 다시 요청하세요.

동영상 편집

wan2.7-videoedit

기존 동영상의 화면을 수정하려면 이 작업 유형을 사용하세요. 먼저 제한을 충족하는 원본 동영상을 준비하세요.

model을 이 절의 Model ID로, operation을 video_edit로 설정하세요. 아래 표에 있는 생성 필드만 사용하고 미디어는 media 배열에 넣으세요.

필드유형필수허용 값 또는 범위기본값
audio.modestring아니요provider_defaultprovider_default
duration.modestring아니요fixed, autoauto
duration.secondsinteger아니요2–15, 간격 1초; 고정 길이에만 사용없음
output.formatstring아니요mp4mp4
output.resolutionstring아니요720p, 1080p1080p
promptstring예문자열없음
provider_options.alibaba.prompt_extendboolean아니요true / false; 프롬프트 확장 제어true
seedinteger아니요0–2147483647, 간격 1; 난수 시드, 0 허용없음
watermarkboolean아니요false, truefalse

미디어 요구 사항

미디어 역할유형 및 개수형식파일별 제한
base_videovideo, 1개(필수)mp4, mov최대 크기 100 MB; 너비 240–4096 px; 높이 240–4096 px; 길이 1–15초; 최소 프레임 속도 16 fps; 이 역할의 최대 총길이 15초

미디어의 필수 여부는 아래 조합 제한도 충족해야 합니다.

조합 제한

  • duration.mode="fixed"이면 duration.seconds가 필요합니다. fixed를 명시할 때는 초 단위 길이도 함께 입력하세요.
  • base_video를 반드시 제공하세요.
  • duration.mode="auto"를 사용하면 duration.seconds를 전달하지 마세요.

요청 예제

아래 JSON을 request.json으로 저장하고 공통 흐름에 따라 견적을 먼저 확인한 뒤 작업을 생성하세요.

{
"model": "wan2.7-videoedit",
"operation": "video_edit",
"prompt": "Keep the boy and his motion in the source video. Give the city plaza warmer evening lighting.",
"duration": {
"mode": "auto"
},
"output": {
"resolution": "720p"
},
"media": [
{
"id": "base",
"type": "video",
"role": "base_video",
"source": "https://bettertoken.ai/video-api/shared/kling-hero-3.0.mp4"
}
]
}

자주 발생하는 422 오류

422 오류 코드해결 방법
enum / range / step이 절의 필드 표에 따라 값과 간격을 조정하세요.
unsupported_field이 작업 유형의 필드 표에 없는 필드를 삭제하세요.
requires이 절의 조합 제한에 따라 초 단위 길이, 화면 비율, 오디오 설정 또는 미디어를 추가하세요.
excludes자동 길이 또는 마지막 프레임과 충돌하는 필드를 삭제하세요.
count / media_role이 절의 미디어 표에 따라 역할과 개수를 조정하세요.
video_input_unsupported공개 HTTPS URL, Content-Type, 파일 형식을 확인한 뒤 견적을 다시 요청하세요.

공식 자료

BetterToken을 호출할 때는 이 페이지의 필드와 실시간 모델 카탈로그의 해당 작업 유형을 사용하세요.