HiAPI에서 Kandinsky 6.0 Pro 텍스트-투-비디오 사용하기: curl 및 Python 튜토리얼

kandinsky-6.0-pro/text-to-video 요청의 역할

kandinsky-6.0-pro/text-to-video는 텍스트 프롬프트를 짧은 비디오 클립으로 변환합니다. 프롬프트와 몇 가지 생성 파라미터를 보내면 모델이 저장하고 재생할 수 있는 비디오 파일을 생성합니다. 이것이 제품의 전부입니다. 프롬프트를 입력하고 비디오 클립을 출력합니다.

핵심 아키텍처 세부 사항은 이것이 동기 호출이아니라는 점입니다. 첫 요청의 응답 본문에서 바로 비디오를 받지 않습니다. 대신 작업을 생성하면 API가 해당 작업의 식별자를 반환하고 모델은 백그라운드에서 작업합니다. 코드는 작업 상태를 확인하면서 완료를 보고할 때까지 기다려야 하며, 그때 결과를 다운로드할 수 있습니다.

이 패턴에는 처음부터 설계에 반영해야 할 몇 가지 결과가 따릅니다:

• 클라이언트가 폴링해야 합니다. 단일 POST로 완료된 비디오를 반환할 수 없으므로 모든 통합에는 상태 폴링 루프나 webhook 유사 재확인이 필요합니다.
• 요청은 여러분 쪽에서 멱등적이어야 합니다. 스크립트가 제출 후 충돌하면 두 번째 작업이 조용히 생성되는 것을 원하지 않을 것입니다. 작업 식별자를 캡처하고 영구 저장하세요.
• 지연 시간은 변동됩니다. 비디오 생성은 이미지나 텍스트 호출보다 느리므로 대기는 정상이며 결함이 아닙니다.

이 튜토리얼의 나머지 부분은 이 수명 주기 순서를 따릅니다: 준비, curl로 제출, 폴링, 다운로드, 그리고 Python으로 동일한 흐름 재구성. 코드는 작동하는 뼈대로 간주하세요. 엔드포인트 경로와 필드 이름은 항상 해당 모델의 API 참조와 대조해 확인해야 합니다. 이러한 세부 사항은 플랫폼이 발전함에 따라 변경됩니다.

첫 요청을 보내기 전에

첫 호출 전에 네 가지를 준비해야 합니다.

1. HiAPI 계정 및 API 키

HiAPI 계정에서 발급받은 API 키로 인증합니다. 키는 가능한 한 소스 코드 관리와 셸 기록에서 제외하세요. 일반적인 방법은 환경 변수로 내보내고 코드가 거기서 읽게 하는 것입니다:

export HIAPI_API_KEY="your-key-here"

다음의 모든 요청은 키가 bearer token으로 Authorization 요청 헤더에 담겨 전송된다고 가정합니다. 아직 키를 만들지 않았다면 먼저 계정 대시보드에서 생성하세요.

2. HTTP 클라이언트

curl만으로 요청이 작동하는지 확인하기에 충분합니다. 반복 실행이 필요한 모든 작업에는 Python 3와 requests 라이브러리를 사용하세요. 의존성이 하나뿐이고 코드가 읽기 쉬우며 나중에 스케줄러나 서비스에 넣기 쉽습니다:

python3 -m pip install requests

3. 출력을 저장할 위치

비디오 파일은 JSON 응답보다 훨씬 큽니다. 로컬 디렉터리에 쓸지 객체 스토리지로 스트리밍할지 미리 정하세요. 이 튜토리얼에서는 로컬 ./output 디렉터리로 충분합니다:

mkdir -p output

4. 프롬프트에 익숙해지기

코드를 작성하기 전에 프롬프트를 작성하세요. 구체적이고 서술적인 프롬프트(주체, 동작, 카메라 동작, 시각적 스타일)는 문제가 발생했을 때 비교할 수 있는 기준선을 제공합니다. 프롬프트가 셸 프롬프트에서 입력한 문자열이 아니라 스크립트에 명명된 상수일 때 한 번에 하나의 변수만 바꾸기가 훨씬 쉽습니다.

이것이 전체 사전 조건 목록입니다. SDK 설치도, 빌드 단계도 없습니다. 플랫폼은 일반 HTTPS로 접근합니다.

사용 가능한 curl 요청

첫 목표는 작업(비디오가 아닌)을 반환하는 명령을 얻는 것입니다. 코드를 추가하기 전에 먼저 이것이 작동하게 하세요.

요청은 세 부분으로 구성됩니다: 모델의 엔드포인트, Authorization 헤더, 그리고 프롬프트와 생성 파라미터를 담은 JSON 요청 본문.

curl -X POST "https://api.hiapi.ai/v1/models/kandinsky-6.0-pro/text-to-video/jobs" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A slow drone shot over a misty pine forest at sunrise, soft golden light, cinematic",
    "duration_seconds": 5,
    "aspect_ratio": "16:9"
  }'

응답을 주의 깊게 읽으세요. 찾아야 할 것은:

• 작업 식별자 — 폴링에 사용할 핸들. id, job_id 또는 유사한 이름일 수 있습니다.
• 초기 상태 필드, 보통 queued 또는 processing과 유사합니다.
• 요청 본문이 예상대로 파싱되었는지 확인하는 데 쓸 에코된 파라미터.

작업 식별자와 오류가 아닌 상태를 반환하는 응답은 요청이 수락되었음을 의미합니다. 해당 응답에 비디오 파일이 직접 포함되어 있다면 이 문서에서 설명하는 것과 다른 일이 발생한 것입니다.

계약을 기반으로 구축하기 전에 확인하세요

위의 필드 이름(엔드포인트 경로, duration_seconds, aspect_ratio, 식별자 키)은 모델과 시기에 따라 바뀔 가능성이 가장 큰 세부 사항입니다. 신뢰할 수 있는 진실의 원천은 해당 모델의 API 참조 페이지입니다. 한 번 확인하고 정확한 이름을 상수로 스크립트에 복사하고, 이름 변경이 코드베이스 전체 검색이 아닌 한 줄 수정이 되도록 코드를 구성하세요.

4xx를 받으면 오류 응답 본문이 상태 코드보다 더 많은 정보를 제공합니다. 401은 키가 잘못되었거나 없음을 의미합니다. 422 유형의 검증 오류는 보통 문제가 있는 필드를 지적합니다.

작업을 제출하고 완료될 때까지 폴링하기

제출 호출이 작동하면 수명 주기는 다음과 같습니다: 제출, 식별자 캡처, 폴링, 종료 상태에서 중지.

제출

이전 섹션의 POST가 작업을 생성합니다. 코드가 다음에 무엇을 하든 반환된 식별자를 영구 위치(스크립트의 변수, 작업 테이블의 행, 큐의 메시지)에 저장해야 합니다. 프로세스가 제출 응답을 받은 후 식별자를 영구 저장하기 전에 죽으면 해당 작업을 폴링할 능력을 잃게 됩니다.

폴링

폴링은 캡처한 식별자로 작업 리소스에 GET 요청을 보내는 것입니다:

curl "https://api.hiapi.ai/v1/models/kandinsky-6.0-pro/text-to-video/jobs/$JOB_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

응답은 작업의 현재 상태를 보고합니다. 실제 사용에서는 소수의 상태를 보게 됩니다: 대기 중 또는 보류 중, 처리 중, 완료됨, 그리고 어떤 형태의 실패 또는 취소. 정확한 문자열이 아니라 이러한 범주를 기준으로 루프를 설계하세요. API가 반환하는 모든 것을 코드의 running, done, failed에 매핑하면 이름 변경이 재시도 로직을 깨뜨리지 않습니다.

얼마나 기다릴지 결정하기

두 숫자가 중요합니다: 폴링 간격과 전체 타임아웃.

• 간격. 몇 초마다 폴링하고 타이트 루프를 돌지 마세요. 타이트 루프는 추가 이득이 없고 속도 제한을 유발할 수 있습니다. 비디오 작업의 경우 요청 간 몇 초의 간격이 합리적입니다.
• 타임아웃. 상한을 설정하세요. 비디오 생성에는 시간이 걸리지만 "영원히 기다림"은 프로덕션 스크립트에서 받아들일 수 있는 답이 아닙니다. 최대 실제 소요 시간 예산을 선택하고 초과를 기록하고 의도적으로 재시도할 실패로 처리하세요.

실제 사용을 견디는 패턴

프로덕션 환경에서는 폴링 단계가 보통 수면 중인 프로세스 안에 있는 대신 제출 단계와 분리됩니다. 작업자가 제출하고 작업을 기록한 후 종료합니다. 정기적 재확인이 미완료 작업을 픽업하여 폴링합니다. 이는 재시작에 더 견고하고 관찰하기도 더 쉽습니다. 이 튜토리얼에서는 단일 프로세스의 간단한 루프로 충분합니다. 인라인 코드가 아닌 함수로 구성하면 나중에 정기 스케줄 작업자로 옮기기가 간단합니다.

생성된 비디오 클립 다운로드하기

완료된 작업은 아직 디스크의 파일이 아닙니다. 완료된 작업의 상태 응답은 출력을 가리킵니다. 보통 URL이고 때로는 URL을 포함한 중첩 객체입니다. 해당 필드를 읽고 다운로드 단계의 입력으로 사용하세요.

curl -L "$OUTPUT_URL" -o output/clip.mp4

다운로드가 실제로 성공했는지 확인하기 위해 다음을 점검하세요:

• 리디렉션을 따르세요. 출력 URL은 자주 리디렉션을 통해 제공됩니다. curl은 -L로, Python은 allow_redirects=True로 처리합니다.
• 콘텐츠 유형을 확인하세요. 완료된 작업은 비디오 페이로드를 생성해야 합니다. clip.mp4로 저장된 것이 JSON이나 HTML 오류 페이지라면 생성 과정이 아니라 다운로드에 문제가 생긴 것입니다.
• 크기를 확인하세요. 0바이트 또는 의심스러울 정도로 작은 파일은 다운로드 실패입니다. 응답 헤더가 있으면 바이트 수를 헤더에 명시된 크기와 비교하세요.
• 만료 문제를 고려하세요. 출력 URL은 보통 시간 제한이 있습니다. 완료 후 즉시 다운로드하고, 영속성이 필요하면 URL을 영구 참조로 저장하는 대신 파일을 자체 스토리지에 복사하세요.

튜토리얼 외 목적에서는 전체 파일을 메모리에 로드하는 대신 대상으로 스트리밍하고, 임시 파일 이름에 먼저 쓴 후 이름을 바꾸세요. 이렇게 하면 미완료 다운로드가 다운스트림 코드에 완전한 파일처럼 보이지 않습니다.

Python으로 동일한 요청 구현하기

다음은 curl 흐름을 호출 가능한 함수로 재구성한 것입니다: 제출, 폴링, 다운로드. 조정이 필요한 이름은 상단에 상수로 모았습니다.

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1"
MODEL_PATH = "/models/kandinsky-6.0-pro/text-to-video"
API_KEY = os.environ["HIAPI_API_KEY"]

HEADERS = {"Authorization": f"Bearer {API_KEY}"}

RUNNING_STATES = {"queued", "pending", "processing", "running"}
DONE_STATES = {"completed", "succeeded", "done"}
FAILED_STATES = {"failed", "cancelled", "error"}


def generate_clip(prompt, out_path, timeout_s=600, interval_s=5):
    # 1. submit
    resp = requests.post(
        API_BASE + MODEL_PATH + "/jobs",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"prompt": prompt, "duration_seconds": 5, "aspect_ratio": "16:9"},
        timeout=30,
    )
    resp.raise_for_status()
    job = resp.json()
    job_id = job["id"]
    print(f"submitted job {job_id}")

    # 2. poll
    deadline = time.monotonic() + timeout_s
    while time.monotonic() < deadline:
        status_resp = requests.get(
            f"{API_BASE}{MODEL_PATH}/jobs/{job_id}",
            headers=HEADERS,
            timeout=30,
        )
        status_resp.raise_for_status()
        data = status_resp.json()
        state = str(data.get("status", "")).lower()

        if state in DONE_STATES:
            break
        if state in FAILED_STATES:
            raise RuntimeError(f"job {job_id} ended in state {state}: {data}")
        time.sleep(interval_s)
    else:
        raise TimeoutError(f"job {job_id} did not finish within {timeout_s}s")

    # 3. download
    url = data["output"]["url"] if isinstance(data.get("output"), dict) else data["output"]
    with requests.get(url, stream=True, allow_redirects=True, timeout=60) as r:
        r.raise_for_status()
        tmp = out_path + ".part"
        with open(tmp, "wb") as f:
            for chunk in r.iter_content(chunk_size=1 << 16):
                f.write(chunk)
        os.replace(tmp, out_path)
    print(f"saved {out_path}")
    return job_id


if __name__ == "__main__":
    generate_clip(
        "A slow drone shot over a misty pine forest at sunrise, soft golden light, cinematic",
        "output/clip.mp4",
    )

이렇게 작성한 이유

• 정확한 일치 대신 상태 집합 사용. 반환된 상태를 running/done/failed에 매핑하면 새로운 중간 상태가 루프를 깨뜨리지 않습니다.
• 단조 마감 시간. time.monotonic()은 시계 조정의 영향을 받지 않으므로 타임아웃이 정확합니다.
• 원자적 쓰기. .part에 쓰고 이름을 바꾸면 충돌한 다운로드가 유효해 보이는 잘린 파일을 남기지 않습니다.
• 작업 ID 반환. 호출자는 기록하고 저장하고 필요하면 다시 폴링할 수 있습니다. 폴링을 이 프로세스에서 꺼내는 첫 단계입니다.

엔드포인트 경로, 요청 필드 이름, 응답 키를 모델의 API 참조에 맞게 조정하세요. 나머지(루프, 타임아웃, 다운로드)는 모두 일반적입니다.

오류 상태 및 디버깅 체크리스트

실행이 실패하면 아무것도 변경하기 전에 단계를 먼저 분리하세요. 각 단계는 서로 다른 실패 특징을 가집니다.

인증 실패

제출 시 401 또는 403은 키가 없거나, 잘못되었거나, 전송되지 않았음을 의미합니다. 환경 변수가 코드를 실행하는 셸이나 프로세스에 실제로 설정되어 있는지 확인하세요. 한 터미널에서 내보낸 키는 cron 작업에 보이지 않습니다. 키의 처음 몇 문자를 출력해 파싱되었는지 확인하고, 전체 키는 절대 출력하지 마세요.

요청 형식 오류

제출 시 400 또는 422 유형 오류는 요청 본문이 검증을 통과하지 못했음을 의미합니다. 응답 본문은 보통 필드를 지적합니다. 일반적인 원인: 파라미터 철자 오류, 지원 범위를 벗어난 길이, 또는 빈 프롬프트. JSON을 API 참조와 필드별로 비교하세요. 이름이 바뀐 단일 키가 가장 흔한 원인입니다.

작업이 실행 상태에 멈춤

폴링이 영원히 종료 상태에 도달하지 않으면 세 가지를 확인하세요: 폴링하는 식별자가 제출한 것인지, 폴링 간격이 너무 빈번해 속도 제한을 받는 것은 아닌지, 타임아웃이 모델에 충분히 긴지. 각 폴링에서 원시 상태 응답을 기록하여 상태가 진행 중인지 멈췄는지 확인하세요.

작업은 완료되었지만 다운로드 실패

작업은 완료되었지만 다운로드가 실패하는 것은 생성 문제가 아니라 파일 처리 문제입니다. 리디렉션을 따르는지, URL이 만료되지 않았는지, 콘텐츠 유형이 JSON이 아닌 비디오인지 확인하세요. curl -L로 해당 URL을 별도로 시도하여 스크립트와 분리해 문제를 찾으세요.

동일한 프롬프트가 반복 실패

한 프롬프트가 지속적으로 실패하고 다른 것은 성공하면 인프라보다 콘텐츠 정책이나 프롬프트 길이를 먼저 의심하세요. 하나의 변수를 바꾸세요(프롬프트를 줄이거나 장면 설명을 단순화). 그런 다음 재시도하세요.

일반 규칙

각 작업에 대해 네 가지를 기록하세요: 작업 식별자, 최종 상태, 실제 소요 시간, 그리고 다운로드 HTTP 상태. 이 네 값은 대부분의 "작동하지 않음" 보고서를 1분 이내에 구체적이고 수정 가능한 단계로 바꿔 줍니다.