Kling 4.0 API 출시. 동영상 생성을 시작하세요 →
PoYoPoYo
how-tos

Kling 4.0 API 가이드: Python과 cURL로 첫 동영상 생성하기

PoYo Team
4 min read
Share:

필름 영사기에 필름을 거는 영사기사, 에디토리얼 일러스트

PoYo의 Kling 4.0 API는 하나의 모델 ID kling-4.0으로 텍스트-동영상 생성, 첫 프레임/마지막 프레임 생성, 시각적 참조, 동영상 편집을 모두 처리합니다. 요청을 제출하고 작업 ID를 보관한 뒤, 작업이 끝날 때까지 폴링하면 됩니다. 이 가이드는 2026년 10월 24일에 확인한 PoYo의 현재 스키마를 기준으로 하며, 다른 제공업체의 필드 이름과는 호환되지 않습니다.

Kling 4.0 플레이그라운드에서 입력값을 화면으로 직접 시험해 보거나 API 문서를 참고하세요.

cURL로 첫 동영상 생성하기

셸 환경 변수에 POYO_API_KEY를 설정한 다음, 아래의 5초짜리 요청을 제출하세요. 인증 정보는 브라우저 코드가 아니라 서버에 보관해야 합니다.

curl --fail-with-body https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "kling-4.0",
    "input": {
      "prompt": "A paper boat floats beneath a stone bridge. One continuous low tracking shot, soft morning light, gentle water sounds, no speech or on-screen text.",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

JSON 응답에서 data.task_id를 읽으세요. 제출에 성공했다고 해서 동영상이 완성된 것은 아닙니다. 아래의 YOUR_TASK_ID를 해당 값으로 바꾸세요.

curl --fail-with-body \
  https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

문서에 정의된 상태는 not_started, running, finished, failed입니다. 완료되면 data.files에서 동영상 file_url을 확인하세요. 실패한 경우 error_message를 확인하고, 원인 분석을 위해 작업 ID를 보관하세요. 기존 작업을 폴링할 때는 요청을 다시 제출할 필요가 없습니다.

대기 시간을 제한한 Python 폴링 루프

requests를 설치하고 백엔드에서 실행하세요. 이 코드는 HTTP 오류와 애플리케이션 오류를 모두 확인하고, 작업이 실패하면 중단하며, 대기 시간을 30분으로 제한합니다. 시간이 초과되면 나중에 같은 작업을 다시 확인하세요. 제출을 자동으로 반복하면 과금되는 작업이 하나 더 생길 수 있습니다.

import os
import time
import requests

base = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]

def checked(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") not in (0, 200):
        raise RuntimeError(body.get("message") or "PoYo API error")
    return body["data"]

task = checked(session.post(base + "/api/generate/submit", json={
    "model": "kling-4.0",
    "input": {
        "prompt": "A paper boat floats beneath a stone bridge. Slow tracking shot.",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9",
    },
}, timeout=60))
task_id = task["task_id"]
print("Task:", task_id, flush=True)
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    task = checked(session.get(
        base + "/api/generate/status/" + task_id, timeout=60))
    if task["status"] == "failed":
        raise RuntimeError(task.get("error_message") or "Generation failed")
    if task["status"] == "finished":
        videos = [f["file_url"] for f in task.get("files", [])
                  if f.get("file_type") == "video"]
        if not videos:
            raise RuntimeError("Finished task returned no video")
        print(videos[0])
        break
    time.sleep(10)
else:
    raise TimeoutError("Check the saved task ID again: " + task_id)

올바른 입력 모드 선택하기

목적input 안의 필드주요 제약
텍스트-동영상prompt 또는 multi_prompt둘 중 정확히 하나만 지정
첫 프레임/마지막 프레임순서대로 지정한 URL 1~2개를 담은 image_urlsaspect_ratio 생략
참조 기반 생성reference_image_urls, reference_video_urls 또는 kling_elements선택 사항인 첫 프레임은 최대 1개
영상 편집video_url과 promptimage_urls, multi_prompt, reference_video_urls, aspect_ratio 사용 불가

참조 이미지가 함께 있더라도 소스 동영상 필드가 있으면 편집 모드가 선택됩니다. 이미지-동영상 생성에서는 첫 번째 이미지가 시작 프레임이 되고, 두 번째 이미지가 마지막 프레임을 정의합니다. 참조 이미지는 인물의 정체성이나 스타일을 안내하는 용도이며, 시작·끝 프레임과는 의미가 다릅니다.

제출 전에 검증해야 할 제한

생성은 3~30초 범위의 정수 길이와 720p 또는 1080p를 지원합니다. 이 PoYo 스키마에서 일반 프롬프트는 26,000자로 제한됩니다. multi_prompt의 각 샷은 최대 512자까지 허용되며, 샷 길이를 생략하면 기본값은 5초입니다. 샷 길이의 합계는 3~30초여야 하고, 최상위 duration을 명시했다면 그 값이 합계와 같아야 합니다.

참조는 이미지 최대 10개, 동영상 최대 5개, 주체(subject) 최대 7개를 허용하며, 전체 에셋은 합쳐서 15개를 넘을 수 없습니다. 첫 프레임은 이미지 제한과 전체 제한 모두에 포함됩니다. 각 참조 동영상 또는 주체 동영상은 3~30초여야 하며, 실제 길이의 합계는 30초를 넘을 수 없습니다. 크기를 초과한 입력을 통과시키려고 길이를 내림해서 보내지 마세요.

첫 청구 금액 이해하기

동영상 입력이 없는 5초 720p 요청은 142.5 크레딧이며, 현재 공시된 환산 기준으로 $0.7125입니다. 동영상 입력이 있으면 단가와 과금 대상 길이가 모두 달라집니다. 참조 동영상이나 편집 워크플로의 비용을 추정하기 전에 가격 예시를 확인하세요.

공식 크리에이터 제품은 여러 키프레임 등 추가 제어 기능을 홍보합니다. 여기서 다루는 PoYo 스키마는 최대 2개의 시작·끝 프레임과 샷별 프롬프트를 제공하므로, 이 엔드포인트에 임의로 만든 keyframes, seed, negative_prompt, generate_audio 필드를 보내지 마세요. 실제 동작하는 예시는 프롬프트 가이드와 Omni Reference 튜토리얼에서 이어서 확인하세요.

자주 묻는 질문

API 모델 ID가 kling-4-0인가요? 아닙니다. 그것은 페이지 슬러그입니다. 요청에 사용하는 모델 ID는 kling-4.0입니다.

여기서 4K를 요청할 수 있나요? 현재 이 PoYo 엔드포인트는 720p와 1080p만 허용합니다. 크리에이터 앱의 마케팅 사양을 그대로 옮기지 말고 제공업체 스키마를 확인하세요.

콜백을 사용할 수 있나요? 제출 요청은 최상위 callback_url을 지원합니다. 콜백 처리 방법은 최신 문서를 참고하세요. 위의 폴링 예시는 콜백에 의존하지 않습니다.

어디서부터 시작하면 되나요? 먼저 짧은 텍스트 전용 요청을 보내고 작업 ID와 결과를 저장한 다음, 플레이그라운드에서 입력 방식을 하나씩 추가해 보세요.

Share: