동영상 모델고급 사용자업데이트
POST/v1/videos/generations
Kling 4
요청 ID kling-v4
프로토콜
POST /v1/videos/generations· 영상 생성 예시GET /v1/videos/tasks/{id}· 영상 작업 조회 예시GET /v1/videos/tasks/{id}/content· 영상 다운로드 예시DELETE /v1/videos/tasks/{id}· 완료된 영상 작업 삭제 예시POST /v1/videos/assets· 소재 업로드 예시DELETE /v1/videos/assets/{id}· 소재 삭제 예시
인증
요청에는 API 키 관리의 API 키가 필요합니다. JSON 요청은 Content-Type: application/json을 지정하세요.
Authorization: Bearer YOUR_API_KEY
요청 매개변수
POST /v1/videos/generations
| 필드 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
model | string | 필수 | kling-v4. 이 페이지에 표시된 모델 ID를 사용하세요. |
prompt | string | 조건부 | 장면, 동작, 카메라 움직임을 설명합니다. 텍스트 및 참조 생성에는 필수이며 첫 프레임을 사용하면 생략할 수 있습니다. |
content | array<object> | 조건부 | 참조 미디어와 선택적 텍스트 항목입니다. prompt만으로 생성할 때는 생략합니다. 이미지는 최대 8장입니다. 참조 모드는 각각 3~30초인 영상 최대 5개, 총 30초를 허용합니다. 편집이나 연장에는 영상 하나만 사용합니다. |
content[].type | string | 필수 | 사용 가능한 값은 text, image_url, input_image, video_url, input_video입니다. |
content[].text | string | 조건부 | type: "text"인 항목에 프롬프트를 지정하세요. |
content[].role | string | 조건부 | first_frame과 last_frame을 사용합니다. 마지막 프레임에는 첫 프레임이 필요합니다. 연장 시 last_frame 이미지 한 장을 목표 마지막 프레임으로 지정할 수 있습니다. 일반 참조 이미지에는 reference_image를 사용합니다. 참조 영상에는 reference_video를 사용합니다. |
content[].asset_id | string | 조건부 | POST /v1/videos/assets에 소재를 업로드하고 반환된 id를 사용합니다. multipart에서 kind(image, video)를 file보다 먼저 보냅니다. |
resolution | string | 선택 | 사용 가능한 값은 720p, 1080p입니다. 기본값은 720p입니다. |
ratio | string | 선택 | 출력 화면 비율입니다. aspect_ratio도 사용할 수 있습니다. 사용 가능한 값은 16:9, 9:16, 1:1, 21:9입니다. 참조 모드는 기본값인 auto도 지원합니다. 연장에는 생략합니다. 텍스트 생성 기본값은 16:9입니다. |
duration | integer | 선택 | 출력 길이이며 단위는 초입니다. 3~30초 범위의 정수입니다. 편집에서 생략하면 원본 영상 길이를 따릅니다. 다른 모드의 기본값은 5초입니다. 연장 시 추가 구간의 길이입니다. |
generate_audio | boolean | 선택 | 오디오는 항상 생성됩니다. 생략하거나 true로 설정합니다. |
omni_reference_task_type | string | 선택 | 사용 가능한 값은 auto, reference, edit, extend입니다. 기본값 auto는 입력 미디어에 따라 모드를 결정합니다. edit과 extend에는 영상 하나가 필요합니다. |
요청 예시
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-v4",
"prompt": "Slow camera push toward a paper lantern swaying gently by a lake.",
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"generate_audio": true
}'
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-v4",
"prompt": "Slow camera push toward a paper lantern swaying gently by a lake.",
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"generate_audio": true,
"content": [
{
"type": "image_url",
"role": "first_frame",
"asset_id": "YOUR_FIRST_FRAME_ASSET_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-v4",
"prompt": "Slow camera push toward a paper lantern swaying gently by a lake.",
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"generate_audio": true,
"content": [
{
"type": "image_url",
"role": "first_frame",
"asset_id": "YOUR_FIRST_FRAME_ASSET_ID"
},
{
"type": "image_url",
"role": "last_frame",
"asset_id": "YOUR_LAST_FRAME_ASSET_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-v4",
"prompt": "Match the camera motion from the reference video in a lakeside lantern scene.",
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"generate_audio": true,
"omni_reference_task_type": "reference",
"content": [
{
"type": "video_url",
"role": "reference_video",
"asset_id": "YOUR_VIDEO_ASSET_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-v4",
"prompt": "Preserve the subject and change the setting to a lakeside at dusk.",
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"generate_audio": true,
"omni_reference_task_type": "edit",
"content": [
{
"type": "video_url",
"role": "reference_video",
"asset_id": "YOUR_VIDEO_ASSET_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-v4",
"prompt": "Continue the motion as the camera glides farther over the lake.",
"resolution": "720p",
"duration": 5,
"generate_audio": true,
"omni_reference_task_type": "extend",
"content": [
{
"type": "video_url",
"role": "reference_video",
"asset_id": "YOUR_VIDEO_ASSET_ID"
},
{
"type": "image_url",
"role": "last_frame",
"asset_id": "YOUR_LAST_FRAME_ASSET_ID"
}
]
}'
영상 작업 조회
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
소재 업로드
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/assets' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-F 'kind=image' \
-F '[email protected];type=image/png'
소재 업로드 · 영상 업로드
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/assets' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-F 'kind=video' \
-F '[email protected];type=video/mp4'
소재 삭제
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/assets/YOUR_ASSET_ID' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-i \
-X DELETE
응답 및 작업
HTTP 202 · 작업 접수
json
{
"id": "vid_1785398400000000000",
"object": "video.generation.job",
"model": "kling-v4",
"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-v4",
"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 · 길이: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30 · 화면 비율: 16:9, 9:16, 1:1, 21:9 · 참조 이미지: 최대 8개