Kling 2.5 Turbo 텍스트-투-비디오 API 호출 방법: curl 및 Python 가이드

kling-2.5-turbo/text-to-video 엔드포인트가 제공하는 것

kling-2.5-turbo/text-to-video는 HiAPI에서 외부에 제공하는 텍스트-투-비디오 모델입니다. 텍스트 프롬프트를 주면 생성된 비디오를 반환합니다. 이름에 있는 "turbo"는 최적화 방향을 설명합니다. 표준 품질 등급보다 더 빠른 처리 속도를 얻는 대신 일부 디테일을 잃습니다. 초안 렌더링, 스토리보드 미리보기, 소셜 미디어 편집 및 창의적 반복 작업에서는 이 절충이 대개 올바른 선택입니다.

첫 줄의 코드를 작성하기 전에 가장 먼저 체득해야 할 점은 이것이 비동기 엔드포인트라는 것입니다. 비디오 생성은 수 초에서 수 분이 걸리며, 이는 어떤 합리적인 HTTP 타임아웃보다도 훨씬 깁니다. 따라서 API는 두 가지 작업으로 분리됩니다.

1. 제출 —— 프롬프트와 파라미터를 POST하면 즉시 작업 식별자를 받습니다.
2. 폴링 —— 해당 식별자로 작업을 반복적으로 GET하여 종료 상태에 도달할 때까지 확인한 다음, 완료된 응답 페이로드에서 비디오 결과를 읽습니다.

이것을 단일 블로킹 호출로 모델링하려고 하면 타임아웃, 재시도 시 중복 생성, 고부하에서의 연결 재설정을 겪게 됩니다. 먼저 제출하고 폴링하는 패턴은 우회해야 할 번거로움이 아니라 올바른 사고 모델입니다. 아래의 모든 코드 예제는 이를 중심으로 구성되어 있으며, 이것을 체득하면 통합의 나머지 부분은 간단합니다.

또한 한 가지 기대를 설정해야 합니다. 엔드포인트는 상태를 가지지만 그 상태는 서버에 있고, 여러분 쪽에 있지 않습니다. 작업은 여러분의 HTTP 연결과 독립적으로 존재합니다. 스크립트는 폴링 도중에 충돌하고 재시작한 뒤, 해당 ID를 어딘가에 영속화해 두었다면 그 ID로 동일한 작업에 다시 연결할 수 있습니다. 처음부터 이 관점으로 설계하십시오.

요청 구조: 프롬프트, 빠른 프리셋 및 유연한 길이

제어할 수 있는 필드는 몇 개에 불과하지만 각 필드는 작업에 실질적인 영향을 미칩니다. 실제로 중요한 부분은 다음과 같습니다.

프롬프트

프롬프트는 주요 창의적 입력입니다. 검색 쿼리가 아니라 장면 설명으로 다루십시오. 이 모델에서 좋은 프롬프트는 보통 다음을 포함합니다:

• 피사체 —— 화면에 누가 또는 무엇이 있는지.
• 동작 —— 피사체가 클립 동안 무엇을 하는지.
• 카메라 —— 구도와 움직임, 예를 들어 slow dolly in, static wide shot, handheld follow.
• 환경과 조명 —— 장면, 시간, 분위기.
• 스타일 —— 느낌을 유도하고 싶다면 cinematic, anime, product photography 등을 쓸 수 있습니다.

구체적으로 유지하고 피사체를 앞에 두십시오. 모호한 프롬프트는 모호한 움직임을 낳으며, turbo 등급은 해석의 여지를 덜 남기므로 이 점을 증폭시킵니다.

fast/turbo 프리셋

이 모델 패밀리는 일부 정밀도를 지연 시간과 맞바꾸는 빠른 프리셋을 지원합니다. 이를 활성화하면 백엔드에 속도를 우선시하라고 알리는 것입니다. 움직임은 여전히 일관되지만 미세한 질감, 작은 얼굴, 복잡한 배경은 품질 경로보다 더 일찍 저하됩니다. 프롬프트 변형을 테스트하는 반복 루프에서 이것을 사용하고, 최종 메인 샷을 렌더링할 때는 품질 경로가 더 나은 마지막 단계인지 고려하십시오. 이 프리셋은 요청 필드이므로 계정 수준의 전역 설정이 아니라 작업별 결정입니다.

유연한 길이

길이는 단일 고정 값이 아니라 모델이 지원하는 범위 내에서 유연합니다. 긴 길이는 더 많은 프레임을 생성한다는 뜻이므로 완료 시간이 길고 비용이 더 높습니다. 과금은 출력 초 단위로 계산됩니다. 샷을 충족하는 최소 길이를 선택하십시오. 소셜 미디어 게시물용 5초 루프는 내러티브 비트와 같은 길이가 필요 없습니다.

필드 규율

필요한 필드만 설정하십시오. 알 수 없거나 잘못 입력된 키는 조용한 구성 오류의 흔한 원인이므로 JSON 요청 본문을 작고 명확하게 유지하고 파이프라인 구성의 나머지와 함께 버전 관리하십시오.

curl로 요청하기

모든 HiAPI 호출은 동일한 인증 패턴을 사용합니다. Authorization 헤더에 bearer token을 담습니다. 키를 환경 변수에 두어 셸 기록이나 커밋된 스크립트에 나타나지 않게 하십시오.

export HIAPI_API_KEY="your_api_key_here"

그런 다음 작업을 제출하십시오. 정확한 필드 이름과 엔드포인트 경로는 모델 참조에서 가져와야 하며, 아래 형식이 표준 형식입니다:

curl -X POST "https://api.hiapi.ai/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-2.5-turbo/text-to-video",
    "prompt": "나무 테이블 위의 세라믹 커피잔으로 천천히 돌리 인(dolly-in), 표면을 비스듬히 스치는 아침 햇살, 피어오르는 증기, 얕은 심도, 시네마틱",
    "duration": 5,
    "fast": true
  }'

받게 될 것은 비디오가 아닙니다. 작업 식별자와 초기 상태를 포함한 확인 응답입니다. 보통 queued 또는 processing 상태에 더해 id 필드가 있습니다. 그 ID를 저장하십시오. 이후 모든 작업의 핸들입니다.

최소 응답은 대략 다음과 같습니다:

{
  "id": "job_abc123",
  "status": "queued",
  "model": "kling-2.5-turbo/text-to-video"
}

제출 호출은 빠르게 반환되어야 합니다. 정상 조건에서는 1초보다 훨씬 짧습니다. 만약 멈춘다면 문제는 연결성이나 인증에 있지 모델에 있지 않습니다. 401이 반환되면 헤더 형식을 확인하십시오(Bearer 접두사가 중요합니다). 422가 반환되면 JSON 요청 본문 형식이 잘못되었거나 필수 필드가 누락된 것입니다.

이 호출에 -L, 재시도 또는 긴 타임아웃을 추가하지 마십시오. 제출 단계는 빠르게 성공하거나 빠르게 실패합니다. 모든 대기는 폴링 루프에서 발생하며, 이는 다음에 다룰 내용입니다.

Python에서의 동일한 요청

Python 버전은 동일한 HTTP 계약의 얇은 래퍼입니다. requests와 공유 Session을 사용하여 제출과 각 폴링 사이에 연결 풀이 작동하게 하십시오. 함수로 감싸서 나머지 코드가 원시 HTTP에 직접 접촉하지 않게 하십시오.

import os
import time
import requests

BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

session = requests.Session()

def submit_video(prompt: str, duration: int = 5, fast: bool = True) -> str:
    body = {
        "model": "kling-2.5-turbo/text-to-video",
        "prompt": prompt,
        "duration": duration,
        "fast": fast,
    }
    resp = session.post(f"{BASE}/video/generations", json=body, headers=HEADERS, timeout=15)
    resp.raise_for_status()
    return resp.json()["id"]

def poll_video(job_id: str, timeout_s: int = 600, interval_s: float = 3.0) -> dict:
    deadline = time.monotonic() + timeout_s
    delay = interval_s
    while time.monotonic() < deadline:
        resp = session.get(f"{BASE}/video/generations/{job_id}", headers=HEADERS, timeout=15)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status")
        if status in ("succeeded", "failed", "cancelled"):
            return data
        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)
    raise TimeoutError(f"job {job_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    job = submit_video("세라믹 커피잔으로 천천히 돌리 인, 아침 햇살, 피어오르는 증기, 시네마틱")
    result = poll_video(job)
    print(result)

간소화하지 말고 유지할 가치가 있는 몇 가지 세부 사항이 있습니다. 각 요청의 timeout은 멈춘 소켓이 워커를 매달리게 하지 않게 하며, 합리적인 상한을 둔 지수 백오프와 별도의 TimeoutError는 호출자가 "여전히 실행 중"과 "고장남"을 구분할 수 있게 합니다.

httpx를 더 선호한다면 변환은 간단합니다. 동일한 메서드, URL, JSON 요청 본문입니다. 전송 계층은 흥미로운 부분이 아닙니다. 계약이 핵심입니다. 폴링을 시작하기 전에 job_id를 영속적인 곳에 저장하여 재시작이 진행 중인 생성을 고아로 만들지 않게 하십시오.

작업 폴링 및 응답 읽기

폴링 루프는 대부분의 통합 버그가 발생하는 곳입니다. 세 가지 규칙이 신뢰성을 유지합니다.

규칙 1: 종료 상태만 루프를 끝낸다

일시적 상태인 queued, processing과 succeeded, failed, cancelled 같은 종료 상태를 보게 됩니다. 종료 상태만 루프를 종료합니다. 알 수 없는 상태 문자열을 성공으로 취급하지 말고 processing에서 중단하지 마십시오. 매 반복마다 상태를 기록하십시오. 새벽 2시에 문제가 생겼을 때 그 로그가 유일한 증거입니다.

규칙 2: 백오프하라, 헛돌지 말라

1분 걸리는 작업에 고정 1초 폴링은 낭비이며, 배치 작업을 실행할 때 공격적 폴링은 속도 제한에 걸릴 수 있습니다. 약 2~3초에서 시작하여 매 라운드 약 1.5배씩 늘리고 10~15초로 상한을 두십시오. 1분 작업의 총 요청 수가 60에서 15 미만으로 줄어들고 최악의 경우 감지 지연은 여전히 상한 값에 불과합니다.

규칙 3: 자산과 메타데이터를 분리하라

완료된 응답 페이로드는 둘 다 포함합니다. 비디오 자체는 URL로 전달되며(보통 만료 시간이 있음), 그 외 모든 것——작업 ID, 모델, 길이, 상태, 소요 시간——은 어떻게 얻었는지에 대한 메타데이터입니다. URL을 읽고, 제때 다운로드하고, 직접 저장하십시오. 생성된 자산 URL은 영구 CDN이 아닙니다. 인도물로 취급하고 집으로 삼지 마십시오. 작업 ID를 자신의 사본과 함께 영속화하여 어떤 클립이든 그것을 생성한 정확한 요청으로 추적할 수 있게 하십시오.

failed에 대한 참고

failed 상태는 전송 오류가 아니라 작업 수준 결과입니다. HTTP 호출은 성공했고 생성은 성공하지 못했습니다. 오류 페이로드를 읽으십시오. 콘텐츠 정책 거부, 지원되지 않는 파라미터 조합 또는 내부 장애를 나타낼 수 있습니다. 정책 거부에 대해 그대로 재시도하면 다시 실패할 뿐이므로 재시도를 고려하기 전에 원인별로 분기하십시오.

오류, 타임아웃 및 재시도 처리

두 가지 오류 세계를 구분하고 각각 처리하십시오.

전송 수준 오류는 HTTP 실패입니다. 연결 재설정, 5xx 응답, 속도 제한 429, 클라이언트 타임아웃입니다. 이들은 작업이 실행되었는지 알려주지 않습니다. 지수 백오프와 지터로 재시도하고 시도 횟수를 제한하십시오.

작업 수준 오류는 성공한 HTTP 응답 내의 종료 상태입니다. 작업이 실행되었고 명확한 결과를 생성했습니다. 폴링을 재시도하는 것은 도움이 되지 않습니다. 재시도한다면 그것은 새로운 제출이며, 실패 원인이 일시적일 때만 수행해야 합니다.

올바른 것 재시도하기

이것이 미묘한 부분입니다. 제출 호출이 타임아웃되면 서버가 작업을 수락했는지 알 수 없습니다. 맹목적으로 재제출하면 두 번의 생성과 두 번의 과금이 발생할 수 있습니다. 더 안전한 패턴은 클라이언트 생성 요청 키로 제출을 멱등하게 만드는 것입니다. 이를 헤더나 요청 본문 필드로 보내면 중복 제출이 새 작업을 시작하는 대신 원래 작업을 반환합니다. 사용 중인 API 표면이 이를 제공하지 않는다면, 제출 타임아웃 시 프롬프트 해시와 길이를 기록하고 재제출 전에 최근 작업을 확인하십시오.

모든 계층에 타임아웃 두기

세 가지 다른 타임아웃을 설정하고 혼동하지 마십시오:

• 요청별 타임아웃 —— 짧게, 예를 들어 10~15초. 이는 단일 HTTP 호출을 제한하며 작업이 아닙니다.
• 전체 작업 마감 시간 —— 전체 생성의 벽시계 예산. 초과하면 작업을 고아로 표시하고 경고한 뒤 계속하십시오.
• 클라이언트 대면 타임아웃 —— 사용자가 기다리는 경우 진행 상황을 스트리밍할지 아니면 프런트엔드에 작업 핸들을 반환할지 결정하십시오.

실용적인 재시도 전략

429와 5xx는 백오프로 재시도하고 상한을 작게 두십시오. 400, 401, 403, 422는 절대 재시도하지 마십시오. 그것들은 요청의 버그이며 반복하면 할당량만 태웁니다. 매 실패의 응답 본문을 기록하십시오. HiAPI 오류 페이로드는 보통 문제가 있는 필드를 지적합니다.

배치 안전성

많은 작업을 팬아웃할 때 동시성 제한과 지터가 있는 시작 지연을 추가하십시오. 100개의 동시 제출은 자초한 속도 제한 사고입니다. 각자 독립적으로 폴링하는 5~10개 워커의 풀이 훨씬 안정적이고 관찰하기 쉽습니다.

출시 전 프로덕션 체크리스트

이것이 노트북을 떠나기 전에 이러한 결정을 확정하십시오.

• 타임아웃과 마감 시간. 모든 호출에 요청별 타임아웃이 있고, 전체 작업 마감 시간이 있으며, 작업이 고아가 될 때 무슨 일이 일어나는지 명확한 정책이 있습니다. 매직 넘버가 아니라 상수로 작성하십시오.
• ID 영속화. 폴링 시작 전에 job_id와 프롬프트 해시를 저장하십시오. 이것이 재시작과 감사를 가능하게 하는 핵심입니다.
• 자산 저장. 성공 시 완료된 비디오를 자체 저장소 버킷에 다운로드하십시오. 통제하지 않는 URL을 영구 참조로 프런트엔드나 데이터베이스에 절대 보내지 마십시오.
• 로깅. 작업 ID, 모델, 길이, 프리셋, 소요 시간을 포함하여 모든 상태 전환을 기록하십시오. 비용이나 품질 문제가 발생할 때 이를 답할 수 있는 데이터셋입니다.
• 비용 의식. 과금은 출력 초 기준이므로 길이가 주요 비용 레버입니다. turbo 프리셋은 지연 시간(따라서 워커 점유)을 낮게 유지합니다. 기능별 생성 초를 추적하여 비용 논의가 추측이 아닌 실제 숫자에 기반하게 하십시오.
• 멱등성. 제출 시 클라이언트 요청 키를 사용하고 안전한 재제출의 조건에 대한 규칙을 만드십시오.
• 실패 UX. 작업 수준 실패 시 사용자가 무엇을 보게 될지 지금 결정하십시오. 재시도 버튼, 폴백 프롬프트 또는 일반 텍스트 메시지입니다. 조용한 헛돌기는 최악의 선택입니다.
• 프롬프트 버전 관리. 프롬프트를 핸들러에 인라인하지 말고 구성에 두어 재배포 없이 다른 변형의 출력을 비교할 수 있게 하십시오.

엔드포인트 자체는 작습니다. 한 번 제출, 한 번 폴링입니다. 거의 모든 엔지니어링 노력은 그 주변의 생명주기에 있으며, 바로 그곳이 프로덕션 품질을 결정하는 곳입니다. HiAPI의 kling-2.5-turbo/text-to-video 모델 참조에서 시작하여 여기 설명된 스캐폴딩을 그 주위에 구축하십시오.