POST
https://nezhagate.com/v1/videos/generations
Kling 4.0은 콰이쇼우(Kuaishou) Kling의 차세대 영상 모델입니다. POST /v1/videos/generations로 비동기 작업을 제출합니다. 소재가 없으면 텍스트-투-비디오이고, 참조 이미지 10장·참조 영상 5개·참조 오디오 3개까지 함께 넣을 수 있습니다. 3~30초, 720P / 1080P, 16:9 또는 9:16이며 항상 사운드가 포함됩니다. 초당 과금이며 참조 영상이 있으면 과금 초 = 출력 초 + 참조 영상 초입니다.
빠른 시작
세 단계면 됩니다: 작업 제출 → 결과 조회 → 영상 링크 받기. YOUR_API_KEY를 내 키로 바꾸면 아래 명령을 그대로 실행할 수 있습니다.
1단계 · 제출(작업 ID를 바로 돌려줍니다, HTTP 202)
curl https://nezhagate.com/v1/videos/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "kling-4.0", "prompt": "떨어지는 단풍잎 속에서 무용수가 회전하고 카메라가 천천히 그녀 주위를 돈다", "duration": 5, "resolution": "720P", "size": "16:9"}'응답(HTTP 202)
{
"id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
"object": "video.generation.job",
"status": "queued",
"created": 1791281400,
"model": "kling-4.0"
}2단계 · status가 succeeded 또는 failed가 될 때까지 5~10초마다 조회
curl https://nezhagate.com/v1/videos/jobs/img_5c2e8f1a9b3d7e6f0a4c8b2d \ -H "Authorization: Bearer YOUR_API_KEY"
성공했을 때의 응답
{
"id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
"object": "video.generation.job",
"status": "succeeded",
"created": 1791281400,
"model": "kling-4.0",
"data": [
{"url": "https://img.nezhagate.com/i/8c1f0e5d2b7a49e3a6d0c4f1b9e2a7d5.mp4"}
],
"usage": {"clips": 1, "model": "kling-4.0"}
}3단계 · data[0].url이 결과 영상(MP4)입니다. 15일 동안 보관되므로 더 오래 쓰려면 내 저장소에 내려받아 두세요.
전체 예제(Python: 제출 → 대기 → 로컬에 저장)
import time
import requests
BASE = "https://nezhagate.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
# 1. 제출
job = requests.post(f"{BASE}/videos/generations", headers=HEADERS, json={
"model": "kling-4.0",
"prompt": "떨어지는 단풍잎 속에서 무용수가 회전하고 카메라가 천천히 그녀 주위를 돈다",
"duration": 5,
"resolution": "720P",
"size": "16:9",
}).json()
if "error" in job:
raise SystemExit(job["error"]["message"])
# 2. 10초마다 조회, 최대 1시간까지 대기
deadline = time.time() + 3600
while job["status"] not in ("succeeded", "failed") and time.time() < deadline:
time.sleep(10)
job = requests.get(f"{BASE}/videos/jobs/{job['id']}", headers=HEADERS).json()
# 3. 영상 내려받기
if job["status"] == "succeeded":
url = job["data"][0]["url"]
with open("kling-4.0.mp4", "wb") as f:
f.write(requests.get(url).content)
print("saved", url)
elif job["status"] == "failed":
print("failed:", job["error"]["code"], job["error"]["message"])
else:
print("still", job["status"], job["id"])대기 중일 때는 조회 결과에 queue_position(앞에 있는 작업 수)과 eta_seconds(예상 대기 시간)도 함께 옵니다. 프로그램에 정해 둔 대기 시간을 넘겨도 다시 제출하지 마세요. 작업은 그대로 남아 있으니 나중에 같은 작업 ID로 이어서 조회하면 됩니다.
인증
Authorization: Bearer YOUR_API_KEY Content-Type: application/json
콘솔에서 API 키를 만들면 시작할 수 있습니다.
사양 한눈에 보기
| 길이 | 3~30초, 1초 단위(기본값 5초) |
| 해상도 | 720P / 1080P |
| 화면 비율 | 16:9 / 9:16 |
| 참조 이미지 | 최대 10장 · 모두 참조(인물·의상·소품·배경), 첫 프레임으로 쓰지 않음 |
| 참조 영상 | 최대 5개 · 각 2~30초·높이 700~4553픽셀, 합계 30초 이하 · 과금 초에 포함 |
| 참조 오디오 | 최대 3개 · 각 5~30초의 깨끗한 사람 목소리, 음색을 정함 · 과금 없음 |
| 소리 | 항상 켜져 있으며 끌 수 없음(audio: false는 거절) |
| 프롬프트 길이 | 최대 2,500자(중국어와 영어 모두 글자 수로 셉니다) |
| 과금 방식 | 초당: (출력 초 + 참조 영상 초) × 해상도별 초당 단가 |
요청 파라미터
POST /v1/videos/generations의 요청 본문(JSON):
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| model | string | 예 | 모델 ID: kling-4.0. |
| prompt | string | 예 | 장면, 카메라, 동작, 소리를 설명합니다(최대 2,500자). 소재가 있으면 각 소재의 역할을 적으세요. 예: "1번 이미지의 인물이 2번 이미지의 숲에서 참조 영상의 동작대로 창을 휘두르며 참조 오디오의 목소리로 “덤벼라!”라고 말한다". |
| duration | integer | 아니오 | 출력 길이, 3~30 사이의 정수 초, 기본값 5. seconds로도 쓸 수 있습니다. |
| resolution | string | 아니오 | 720P(기본값) 또는 1080P. |
| size | string | 아니오 | 16:9(기본값) 또는 9:16. aspect_ratio로도 쓸 수 있습니다. 다른 비율은 거절됩니다(400). |
| images | array | 아니오 | 참조 이미지 최대 10장(공개 링크, data: URI 또는 base64, 장당 16MB 이하). image(1장)나 reference_images로도 보낼 수 있습니다. 모두 참조이며 첫 프레임으로 쓰지 않습니다. start_frame, end_frame, image_role=first_frame은 거절됩니다. |
| video_references | array | 아니오 | 참조 영상 최대 5개(mp4 / mov, 각 2~30초·높이 700~4553픽셀·50MB 이하, 합계 30초 이하): 바로 내려받을 수 있는 링크, base64(data:video/mp4;base64,...) 또는 Playground 업로드 링크. 초 단위로 과금합니다(아래 "가격" 참고). |
| audio_reference | array | 아니오 | 참조 오디오 최대 3개(mp3 / wav / m4a, 각 5~30초·15MB 이하)로 인물의 목소리를 정합니다. 깨끗한 사람 목소리만 가능합니다(음악·효과음은 실패). http(s) 링크만 받으며 참조 이미지나 참조 영상이 함께 있어야 합니다. 과금하지 않습니다. |
| audio | boolean | 아니오 | 모든 영상에 사운드가 포함되며 끌 수 없습니다. false는 거절되니(400) 보내지 마세요. |
| callback_url | string | 아니오 | 작업이 끝나면 결과를 보낼 주소. 아래 웹훅 부분을 보세요. |
| n | integer | 아니오 | 작업 하나는 영상 1개를 만들므로 넣지 않아도 됩니다. 1보다 큰 값을 넣어도 영상은 1개만 나오지만, 제출할 때 n개 분의 크레딧이 예약되고 초과분은 작업이 끝날 때 돌아옵니다. |
그 밖의 필드(seed, negative_prompt, fps, watermark 등)는 전달되지 않으며 가격에도 영향을 주지 않습니다. 결과는 항상 MP4이며 url로 돌려줍니다.
가격
초당 과금: 비용 = 해상도별 초당 단가 × (출력 초 + 각 참조 영상의 초). 같은 참조 영상 링크는 한 번만 셉니다. 참조 이미지와 참조 오디오는 무료입니다. 제출 시 이 금액을 예치하고 성공하면 같은 금액으로 정산하며 실패하면 전액 환불합니다. 1크레딧 = $0.005.
| 해상도 | 초당 크레딧 | 초당 가격(USD) | 5초 영상 1개 | 출력 10초 + 참조 영상 5초(과금 15초) |
|---|---|---|---|---|
| 720P | 18 | $0.09 | $0.45 | $1.35 |
| 1080P | 25 | $0.125 | $0.625 | $1.875 |
참조 소재
- 참조 이미지: 모두 참조이며 첫 프레임으로 쓰지 않습니다. 프롬프트에 번호별로 역할을 적으세요. 예: "1번 이미지의 인물", "2번 이미지의 배경".
- 참조 영상: 동작과 카메라 무빙을 정하며 참조 이미지와 함께 쓸 수 있습니다. 각 2~30초, 높이 700~4553픽셀(예: 1280×720 가로 또는 720×1280 세로. 480P 영상은 실패), 합계 30초 이하. 제출할 때 각 영상을 내려받아 길이와 크기를 재며, 길이를 읽을 수 없거나 너무 짧거나 높이가 부족하면 400을 반환하고 과금하지 않습니다.
- 참조 오디오: 인물의 목소리를 정하며 5~30초의 깨끗한 사람 목소리여야 합니다. 음악·효과음·5초 미만 오디오는 거절됩니다. 말할 대사는 프롬프트에 적으세요.
- 이미지는 각각 공개 이미지 URL,
data:URI, base64 중 하나로 보낼 수 있으며 한 장당 16MB 이하입니다. 여러 장은images에 배열로 넣으세요. 제출할 때 당사가 이미지를 먼저 저장한 뒤 작업을 대기열에 넣습니다. 읽을 수 없는 이미지가 있으면 400으로 거절되고message에 몇 번째 이미지인지 적혀 있으며, 과금되지 않습니다. - 당사가 저장한 참조 소재는 7일, 결과 영상은 15일 동안 보관됩니다.
참조 이미지·참조 영상·참조 오디오를 함께 쓰는 예
curl https://nezhagate.com/v1/videos/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "kling-4.0", "prompt": "1번 이미지의 인물이 2번 이미지의 숲에서 참조 영상의 동작대로 창을 휘두르며 참조 오디오의 목소리로 외친다: 덤벼라", "images": ["https://example.com/character.png", "https://example.com/forest.png"], "video_references": ["https://example.com/moves-1280x720.mp4"], "audio_reference": ["https://example.com/voice-8s.mp3"], "duration": 10, "resolution": "720P", "size": "16:9"}'이 작업은 출력 10초에 참조 영상 5초라 15초를 과금합니다. 참조 오디오는 무료입니다.
작업 상태와 응답 필드
GET /v1/videos/jobs/{id}는 아래 상태를 돌려줍니다. 각 필드의 설명은 비동기 작업에 있습니다. 5~10초마다 조회하거나, 아래의 웹훅으로 결과를 받으세요. 조회는 무료이며, 같은 계정의 어느 키로든 조회할 수 있습니다.
| 상태 | 의미 |
|---|---|
| queued | 대기 중. queue_position(앞에 있는 작업 수)과 eta_seconds(예상 대기 시간)가 함께 옵니다. |
| processing | 생성 중. |
| succeeded | 완료. 결과는 data[0].url, 과금 내역은 usage에 있습니다. |
| failed | 실패. 사유는 error에 있고, 예약된 크레딧은 전액 환불됩니다. |
processing이queued로 돌아갈 때가 있습니다. 예를 들어 모든 회선이 가득 찼을 때, 완성된 영상을 다시 가져오는 중일 때, 서비스가 재시작된 뒤입니다. 어떤 회선이 작업을 끝내지 못하면 게이트웨이가 다음 회선으로 넘겨 다시 만들 수 있습니다. 회선을 몇 번 거치든 작업 하나에 한 번만 과금됩니다.- 한 계정은 최대 50개 작업을 동시에 생성하며, 그보다 많은 작업은 제출 순서대로 대기합니다. 15분이 지나도 시작되지 않은 작업은 자동으로 실패 처리되고 전액 환불됩니다. 작업 기록은 3일, 영상 링크는 15일 동안 보관됩니다.
생성 시간
당사 테스트(720P / 1080P, 3~5초)에서는 보통 3~5분 안에 완성되었습니다. 대기열이 붐비면 더 걸립니다. 최대 120분까지 기다리며 시간 초과 시 전액 환불합니다.
당사 테스트 기준 생성 시간 중앙값: 3.3 분.
오류와 환불
제출 단계의 오류는 HTTP 4xx / 5xx로 바로 돌아오며, 작업은 만들어지지 않고 과금되지 않습니다. 작업이 접수된 뒤의 실패는 작업 조회 결과로 알려 주며, 예약된 크레딧은 전액 환불됩니다. 전체 코드는 오류 코드에 있습니다.
제출할 때 돌아오는 오류
| HTTP | code | 원인 | 조치 |
|---|---|---|---|
| 400 | invalid_request | 파라미터가 올바르지 않습니다. 길이, 해상도, 화면 비율 또는 참조 소재 수가 이 모델의 허용 범위를 벗어났거나, 프롬프트가 너무 길거나, 참조 이미지나 참조 영상을 읽을 수 없거나, 항상 소리가 포함되는 모델에 audio: false를 보낸 경우 등입니다. 구체적인 원인은 message에 적혀 있습니다. | message에 적힌 대로 고친 뒤 다시 제출하세요. |
| 400 | invalid_callback_url | callback_url이 공개된 http(s) 주소가 아니거나 2000자를 넘습니다. | 인터넷에서 접근할 수 있는 주소를 쓰세요. |
| 400 | model_not_found | 모델 ID의 철자가 틀렸거나, model이 없거나, 이 엔드포인트에서 쓸 수 없는 모델입니다(예: 이미지 엔드포인트에 채팅 모델을 지정한 경우). | GET /v1/models 또는 API 레퍼런스에 있는 모델 ID를 쓰세요. |
| 401 | invalid_api_key | 키가 없거나, 삭제되었거나, 비활성화되었습니다. 계정이 비활성화된 경우에도 나옵니다. | 콘솔의 「API Keys」 페이지에서 이 키를 확인하세요. |
| 402 | insufficient_quota | 이 요청의 크레딧을 예약하기에 잔액이 부족합니다. 게이트웨이는 요청에 들 수 있는 최대 비용을 먼저 예약하므로, 동시 호출이 몰릴 때도 이 오류가 날 수 있습니다. | 동시 호출이 몰린 경우라면 몇 초 기다린 뒤 다시 시도하고, 그렇지 않으면 충전하세요. |
| 429 | rate_limit_exceeded | 이 키에 설정한 분당 요청 수를 넘었습니다(최근 60초 기준). Retry-After 헤더는 붙지 않습니다. | 몇 초 기다린 뒤 다시 시도하거나, 콘솔에서 이 키의 한도를 올리세요. |
| 503 | model_maintenance | 모델이 점검 중이라 요청을 받지 않습니다. 점검 중에는 다른 모델이 대신 답변하지도 않습니다. | 점검이 끝나면 다시 시도하세요. 진행 상황은 서비스 상태에서 볼 수 있습니다. |
| 503 | service_unavailable | 참조 소재 저장 실패처럼 당사 측에서 일시적인 오류가 났습니다. 작업은 만들어지지 않았고 과금되지도 않았습니다. | 잠시 후 다시 시도하세요. |
작업 실패(status가 failed)
| code | 언제 나오나요 | 조치 |
|---|---|---|
| content_policy | 영상: 프롬프트, 참조 소재, 또는 생성된 화면이나 소리가 콘텐츠 심사를 통과하지 못했습니다(소리가 걸렸으면 param이 audio입니다). Wan Standard 및 Prime: 입력 소재가 심사를 통과하지 못했습니다. error.reason은 FaceDetectionSuspect(실제 사람 얼굴 의심) 또는 DataInspectionFailed(입력 콘텐츠 심사 실패)입니다. error.message에 원인과 조정 방법이 표시됩니다. 실패한 작업은 과금되지 않습니다. | 프롬프트를 고쳐 쓰거나 참조 소재를 바꾼 뒤 다시 제출하세요. 같은 입력은 다시 거부됩니다. |
| duration_rejected | 참조 소재가 받아들여지지 않았습니다: 참조 오디오가 5~30초의 깨끗한 사람 목소리가 아니거나 참조 영상의 길이가 맞지 않습니다. param이 audio이면 오디오 문제입니다. | 5초 이상의 사람 목소리로 바꾸고(또는 참조 오디오를 빼고) 참조 영상을 2~30초로 자른 뒤 다시 제출하세요. 그대로 보내면 또 실패합니다. |
| render_failed | 영상: 이번에는 영상이 나오지 않았습니다. 대개 일시적인 현상입니다. | 같은 요청을 그대로 다시 제출하면 대개 성공합니다. |
| render_timeout | 영상: 대기나 렌더링이 너무 오래 걸려 업스트림이 작업을 포기했습니다. | 다시 제출하세요. |
| result_fetch_failed | 영상은 생성되었지만, 당사 측에서 영상을 내려받거나 저장하는 데 계속 실패했습니다. | 다시 제출하세요. |
| upstream_error | 그 밖의 실패: 모든 회선을 시도했지만 실패했거나, 15분 동안 기다려도 시작되지 않았거나, 업스트림이 이유 없이 거부한 경우 등입니다. 구체적인 내용은 message에 있습니다. | 다시 제출하면 대개 성공합니다. |
message의 문구가 아니라 code로 판단하세요. 모르는 code가 오거나 code가 없으면 upstream_error로 처리하면 됩니다. 다시 제출하면 대개 성공합니다. 실패한 작업은 모두 전액 환불됩니다.
조회 대신 웹훅으로 받기
제출할 때 callback_url을 넣으면 작업이 끝나는 즉시(성공이든 실패든) 게이트웨이가 조회 엔드포인트와 똑같은 결과를 그 URL로 보냅니다. 서명이 포함되며, 전송에 실패하면 자동으로 재시도합니다. 콘솔의 「설정 → 웹훅」에서 계정 전체에 쓸 주소를 지정할 수도 있습니다. 웹훅 문서 →
curl https://nezhagate.com/v1/videos/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "kling-4.0", "prompt": "떨어지는 단풍잎 속에서 무용수가 회전하고 카메라가 천천히 그녀 주위를 돈다", "duration": 5, "resolution": "720P", "size": "16:9", "callback_url": "https://your-domain.com/webhook"}'