Skip to main content
새 연동에는 비디오 생성과 통합 /ai/v1/videos 프로토콜을 사용하세요. 이 페이지의 /v1/videos 호환 인터페이스와 모델 어댑터는 계속 사용할 수 있습니다. 호출 전에 모델 Schema API를 조회하고 반환된 path로 프로토콜을 선택한 뒤 해당 request.schema를 읽으세요. 배열 순서에 의존하지 마세요.

현재 모델 목록

이 목록은 현재 제공되는 모델을 뜻하며 모든 모델이 같은 입력 필드를 지원한다는 뜻은 아닙니다. 모델 Schema 응답의 path로 엔드포인트를 선택하고 해당 request.schema를 확인하세요.

API 상세 설명

요청 헤더

비디오 생성 작업 생성

요청 본문

모델별로 응답 형식이 약간 다르지만, 모두 id(video_id)와 status 필드를 포함합니다. status로 작업 진행 상황을 판단하면 됩니다.

응답 예시 (Tongyi Wanxiang/Veo/Jimeng)

응답 예시 (Sora)

공통 상태 값 설명

비디오 상태 조회

이 API를 폴링하여 작업 완료 여부를 확인합니다. 15초마다 한 번씩 조회하는 것을 권장합니다.

응답 예시 (생성 완료 - Tongyi Wanxiang)

응답 예시 (생성 완료 - Sora)

모든 모델은 status == "completed"로 완료 상태를 판단한 후, /content API를 호출하여 다운로드합니다.

비디오 콘텐츠 다운로드

상태가 completed가 되면 이 API를 호출하여 MP4 비디오 파일을 다운로드합니다. 응답: 비디오 바이너리 스트림을 직접 반환합니다(Content-Type: video/mp4).
주의: 비디오 다운로드 링크는 일반적으로 24시간의 유효 기간이 있으므로, 제때 다운로드하여 저장하세요.

비디오 작업 삭제

이 API는 이미 생성된 비디오 작업을 삭제하는 데 사용됩니다.

각 모델 파라미터 상세

OpenAI Sora

팁: 모든 모델의 seconds 파라미터는 통일적으로 문자열 타입으로 전달합니다(예: "8").
예제

Google Veo

예제
이미지 필드 참고:
  • 첫 프레임 우선순위: first_frame > input_reference(OpenAI 호환 단일 프레임).
  • first_frame / last_frame / reference_images의 각 요소는 다음을 허용합니다: 공개 URL, base64 데이터 URL(data:image/png;base64,...), 또는 {"mime_type":"image/png","data":"<base64>"} 객체.
  • OpenRouter 스타일의 frame_images(요소에 frame_type: first_frame | last_frame) 및 input_references 별칭도 허용됩니다.
  • 참조 이미지는 최대 3장까지 허용하며, 초과하면 400을 반환합니다.
팁: Veo는 네이티브 오디오 생성을 지원하므로, prompt에 효과음을 묘사할 수 있습니다. 예: “배경에 새소리가 들린다”, “피아노 선율”.

Tongyi Wanxiang

각 모델 지원 길이 지원 해상도 (너비*높이)
주의: wan2.6은 720P와 1080P만 지원; wan2.5는 480P, 720P, 1080P 지원; wan2.2는 480P와 1080P만 지원.
예제
팁: wan2.5 이상 버전은 기본적으로 음성이 있는 비디오를 생성하며(자동 더빙), 중국어 prompt의 효과가 더 좋습니다.

Doubao Seedance

실존 인물 에셋을 사용하기 전에 에셋 그룹 생성, 본인 확인 및 에셋 등록을 완료하고, 기존 호환 클라이언트는 실존 인물 에셋 호환 프로토콜 예제를 참조하세요. extra_body.content 지원 참조 유형 예제
Seedance 2.0 / 2.0 Fast

Kling

이 목록은 현재 제공되는 모델을 뜻하며 모든 모델이 같은 입력 필드를 지원한다는 뜻은 아닙니다. 모델 Schema 응답의 path로 엔드포인트를 선택하고 해당 request.schema를 확인하세요.

전체 호출 예제

FAQ

비디오 생성에는 얼마나 걸리나요?

비디오 생성은 일반적으로 1-5분이 소요되며, 구체적인 시간은 모델, 해상도, 길이에 따라 다릅니다. 15초의 폴링 간격을 설정하는 것을 권장합니다.

input_reference 파라미터는 어떻게 사용하나요?

input_reference는 이미지-비디오 시나리오에 사용되며, 세 가지 전달 방식을 지원합니다.

비디오 다운로드 링크의 유효 기간은 얼마나 되나요?

생성된 비디오 다운로드 링크는 일반적으로 24시간의 유효 기간이 있으므로, 제때 다운로드하여 저장하세요.

각 모델의 seconds 파라미터는 어떤 차이가 있나요?

> 팁: 모든 모델의 seconds 파라미터는 통일적으로 문자열 타입으로 전달하며(예: "8"), API가 자동으로 처리합니다.

모델별 size 파라미터 형식은 어떤 차이가 있나요?

seconds 와 duration 은 어떤 차이가 있나요?

둘은 의미가 동일하며 모두 비디오 길이를 나타냅니다. API는 이 두 파라미터명을 모두 지원합니다(Sora 제외, Sora는 seconds만 허용). 통일적으로 seconds 사용을 권장합니다.

더 나은 prompt를 작성하는 방법은?

  • 구체적인 장면 묘사: 주체, 동작, 환경, 조명, 분위기를 포함
  • 카메라 언어 지정: 예: “클로즈업”, “항공 촬영”, “푸시 인 샷”, “슬로우 모션”
  • 스타일 묘사: 예: “시네마틱”, “다큐멘터리 스타일”, “애니메이션 스타일”
  • 중국어 모델은 중국어 prompt 효과가 더 좋음: Tongyi Wanxiang은 중국어에 최적화됨
  • Veo는 오디오 묘사 지원: prompt에 소리를 묘사 가능, 예: “새소리”, “피아노 선율”

오류 응답 및 호환 오류 코드

이 절은 이 페이지의 Legacy /v1/videos/* API에 적용됩니다. 새로운 /ai/v1/videos/*는 별도의 비디오 오류 계약을 사용합니다. 두 API의 응답 구조와 오류 코드는 각각 처리해야 합니다. Legacy 비디오 API의 일반적인 HTTP 오류 응답은 다음과 같습니다. 일반 오류에는 보통 code와 param이 없으며, tid는 일반적으로 message 끝에 추가됩니다.

HTTP 5xx 오류 피드백 제출

HTTP 5xx 오류가 발생한 경우에만 피드백을 제출하고 message의 tid를 함께 제공하세요.

HTTP 200 + status=failed

조회 요청이 성공하면 HTTP 상태가 200일 수 있습니다. 비디오 작업이 failed이면 error에 모델 프로바이더가 제공한 동적 message가 포함되며, 일반적인 작업 실패에는 안정적인 code가 없습니다.
message에 파라미터, 콘텐츠 정책 또는 미디어 입력 문제가 명확히 표시되면 해당 입력을 수정한 후 작업을 다시 생성하세요. 원인이 명확하지 않으면 비디오 ID가 해당 오류의 진단 식별자입니다.
마지막 업데이트: 2026-09-01