동영상 생성
플랫폼 형식으로 Kling 4.0 텍스트·이미지·Omni 동영상 작업을 생성합니다.
기본 입력은 공통 필드, 고급 입력은 metadata.contents을 사용합니다. 생성 설정은 metadata.settings, 콜백과 워터마크는 metadata.options에 지정합니다.
/v1/video/generations플랫폼 공통 필드와 metadata로 텍스트·이미지·Omni 작업을 생성합니다. 별칭 POST /v1/videos/generations도 같은 매개변수를 사용합니다. 모두 kling-4.0 모델이며 Omni는 다중 참조 기능이지 별도 모델이 아닙니다.
생성 결과와 조회
생성 성공 시 최상위 작업 객체를 반환합니다. id와 task_id는 문자열 작업 ID입니다. task_id를 저장하고 플랫폼 조회 API로 상태와 동영상 URL을 확인합니다.
status: "queued"는 접수 후 대기 중임을 뜻하며 progress: 0는 생성 실패를 뜻하지 않습니다. 생성 응답에는 최종 동영상 URL이 없습니다. created_at는 Unix 초 타임스탬프로, 네이티브 응답의 밀리초와 다릅니다.
입력 방식 선택
| 시나리오 | 입력 방식 | 상세 규칙 |
|---|---|---|
| 텍스트 생성 | prompt, 고급 설정에서는 metadata.operation: "text-to-video" 지정 | 텍스트 생성 매개변수 |
| 이미지 생성 | image / images 또는 유형을 지정한 metadata.contents, 작업: image-to-video | 이미지 소스와 키프레임 제한 |
| Omni 참조·편집 | metadata.operation: "omni-video" 및 metadata.contents 사용 | 소재 유형·참조·조합 제한 |
명시한 metadata.settings가 간편 필드보다 우선합니다. 이미지·동영상 참조 id는 선택 사항이며 요소·음성 참조 id는 필수입니다. 지정한 소재 참조 ID는 같은 작업 안에서 중복될 수 없습니다.
주요 오류와 해결 방법
| 응답·오류 | 확인 및 조치 |
|---|---|
HTTP 401, Invalid token | Authorization: Bearer your-api-key와 요청 사이트에 유효한 API Key 확인 |
HTTP 400, 模型名称不能为空 | model: "kling-4.0" 지정 |
HTTP 400, prompt cannot be empty | 텍스트 생성에는 비어 있지 않은 prompt 필요. 고급 입력은 해당 네이티브 작업에 맞춰 metadata.contents 지정 |
HTTP 400, duration must be an integer | 3 같은 정수 사용. 문자열 "3"나 소수는 사용하지 않음 |
settings.resolution ... is invalid | 픽셀 크기 대신 720p 또는 1080p 사용. size를 제거하고 metadata.settings.resolution로 통일 권장 |
HTTP 400, invalid JSON request body | 따옴표·쉼표·괄호 확인. 주석 없는 유효한 JSON 사용 |
HTTP 400은 code/message/data 또는 error 객체를 반환할 수 있습니다. 생성 단계의 code: "fail_to_fetch_task"는 상위 서비스의 매개변수 검증 오류일 수도 있습니다. 코드만 보고 반복 전송하지 말고 message의 원인을 확인하세요.
message는 code/message/request_id를 포함한 JSON 문자열일 수 있으며 이미 파싱된 객체가 아닙니다. 형식을 확인한 뒤 파싱하세요. 문의 시 요청 ID를 보관하되 API Key는 제공하지 마세요. 입력 제한은 해당 네이티브 작업을 따르며 공통 검증 오류의 범위가 모델 기능을 뜻하지는 않습니다.