동영상 모델고급 사용자업데이트
POST/v1/videos/generations
Kling V3
요청 ID kling-v3
프로토콜
POST /v1/videos/generations· 영상 생성 예시GET /v1/videos/tasks/{id}· 영상 작업 조회 예시GET /v1/videos/tasks/{id}/content· 영상 다운로드 예시DELETE /v1/videos/tasks/{id}· 완료된 영상 작업 삭제 예시
인증
요청에는 API 키 관리의 API 키가 필요합니다. JSON 요청은 Content-Type: application/json을 지정하세요.
Authorization: Bearer YOUR_API_KEY
요청 매개변수
POST /v1/videos/generations
| 필드 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
model | string | 필수 | kling-v3. 이 페이지에 표시된 모델 ID를 사용하세요. |
prompt | string | 조건부 | 장면, 동작, 카메라 움직임을 설명합니다. 텍스트 지시가 필요하면 이 필드나 type: "text"인 content 항목을 사용합니다. |
content | array<object> | 조건부 | 참조 미디어와 선택적 텍스트 항목입니다. prompt만으로 생성할 때는 생략합니다. 이미지는 최대 2장입니다. |
content[].type | string | 필수 | 사용 가능한 값은 text, image_url, input_image입니다. |
content[].text | string | 조건부 | type: "text"인 항목에 프롬프트를 지정하세요. |
content[].role | string | 조건부 | first_frame과 last_frame을 사용합니다. 마지막 프레임에는 첫 프레임이 필요합니다. |
content[].asset_id | string | 조건부 | POST /v1/videos/assets에 소재를 업로드하고 반환된 id를 사용합니다. multipart에서 kind(image)를 file보다 먼저 보냅니다. 본인 계정의 미디어만 사용할 수 있습니다. 미디어 ID와 공개 HTTPS URL 중 하나를 사용합니다. |
content[].image_url | string | 조건부 | 공개 HTTPS 이미지 URL을 문자열로 전달합니다. |
resolution | string | 선택 | 사용 가능한 값은 720p, 1080p, 4K입니다. 기본값은 720p입니다. |
ratio | string | 선택 | 출력 화면 비율입니다. aspect_ratio도 사용할 수 있습니다. 사용 가능한 값은 16:9, 9:16, 1:1입니다. 기본값은 9:16입니다. |
duration | integer | 선택 | 출력 길이이며 단위는 초입니다. 3~15초 범위의 정수입니다. 기본값은 5입니다. |
generate_audio | boolean | 선택 | 오디오 트랙 생성 여부입니다. 기본값은 true입니다. |
요청 예시
API Key를 로컬 환경 변수 ICODEEASY_API_KEY에 설정하고 직접 HTTP 호출을 허용하는 엔드포인트를 선택하세요. 특정 클라이언트가 필요한 경우 해당 설정 가이드를 따르세요.
예시의 미디어 URL 및 에셋 ID를 유효한 내 에셋으로 바꾸세요.
Video Generations
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/generations' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-H 'Content-Type: application/json' \
--data '{
"model": "kling-v3",
"prompt": "Slow camera push toward a paper lantern swaying gently by a lake.",
"resolution": "720p",
"ratio": "16:9",
"duration": 5
}'
영상 작업 조회
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID' \
-H "Authorization: Bearer $ICODEEASY_API_KEY"
영상 다운로드
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID/content' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-L \
-o result.mp4
완료된 영상 작업 삭제
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-i \
-X DELETE
응답 및 작업
HTTP 202 · 작업 접수
json
{
"id": "vid_1785398400000000000",
"object": "video.generation.job",
"model": "kling-v3",
"created_at": "2026-07-30T08:00:00Z",
"status_url": "/v1/videos/tasks/vid_1785398400000000000",
"content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
"status": "queued",
"updated_at": "2026-07-30T08:00:00Z",
"task_id": "vid_1785398400000000000"
}
HTTP 200 · 완료 작업 조회
json
{
"id": "vid_1785398400000000000",
"object": "video.generation.job",
"model": "kling-v3",
"created_at": "2026-07-30T08:00:00Z",
"status_url": "/v1/videos/tasks/vid_1785398400000000000",
"content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
"status": "succeeded",
"updated_at": "2026-07-30T08:01:00Z",
"url": "/v1/videos/tasks/vid_1785398400000000000/content"
}
id를 저장하세요. 같은 API 키로 status_url에 GET 요청을 보내 status가 succeeded 또는 failed가 될 때까지 확인하세요. 성공한 뒤 content_url에서 내려받고 HTTP 리디렉션을 따르세요. 두 경로는 API 기본 URL에 대한 상대 경로입니다.
| 필드 | 유형 | 설명 |
|---|---|---|
id / task_id | string | 작업 ID입니다. 생성 응답의 task_id는 id와 같습니다. |
status | string | 작업 상태이며 queued, running, succeeded 또는 failed입니다. |
progress | integer | 생성 진행률입니다. 진행률 값이 없으면 생략됩니다. |
error.code | string | 작업 실패 시 반환되는 오류 분류입니다. |
주요 오류
| HTTP | 오류 유형 | 설명 |
|---|---|---|
| 400 | invalid_request | 모델, 매개변수 조합, 참조 미디어를 확인하세요. |
| 401 | unauthorized | API 키가 누락되었거나 유효하지 않거나 비활성화되었는지 확인하세요. |
| 402 | insufficient_balance | 작업 제출에 필요한 잔액이 부족합니다. |
| 404 | not_found | 조회 결과가 404이면 작업 ID를 보관하고 조회 URL과 작업을 만든 계정의 API 키를 확인하세요. 작업이 이미 완료되었을 수 있으니 이 응답만으로 다시 제출하지 마세요. |
| 409 | video_not_ready | 영상이 아직 생성 중입니다. 상태 조회를 계속하세요. |
| 503 | submission_unknown | 제출 결과를 확인할 수 없습니다. 새 요청을 보내기 전에 지원팀에 작업 생성 여부를 확인하세요. |
전체 연동 가이드 · 요청 필드, 작업 상태 및 응답 형식은 전체 API 가이드를 참고하세요.
기능 및 제한
text_to_video· 지원image_to_video· 지원first_frame· 지원last_frame· 지원reference_images· 지원audio· 지원- 제한 해상도: 720p, 1080p, 4K · 화면 비율: 16:9, 9:16, 1:1 · 길이: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 · 참조 이미지: 최대 2개