블로그

튜토리얼

HiAPI API로 kling-3.0-omni/transformation 호출하는 방법: curl 및 Python 가이드

HiAPI에서 비디오 스타일 변환을 위한 사용 가능한 요청 전체 워크스루

Nov 12, 2026
HiAPI 블로그 커버 이미지: 짙은 인디고 배경 위에 중첩된 넓은 화살표가 계단식으로 나아가고, 살구색 앞쪽 가장자리가 신호 흐름을 표현합니다.
이 페이지에서

transformation 엔드포인트의 기능과 적용 시나리오

kling-3.0-omni/transformation은 HiAPI의 비디오 스타일 변환 엔드포인트입니다. 두 가지를 제공합니다: 소스 비디오와 자연어 스타일 지시. 이 엔드포인트는 소스 비디오의 내용은 유지하면서 요청한 시각적 스타일로 표현된 새 비디오를 반환합니다.

HTTP 호출 뒤에 숨겨진 후반 제작 단계라고 생각하면 됩니다. 모델을 훈련하거나 GPU 클러스터를 유지하거나 체크포인트 파일을 관리할 필요가 없습니다. 원하는 시각 효과를 설명하고 비디오를 지정하면 엔드포인트가 렌더링 결과를 생성합니다.

이 엔드포인트가 적합한 시나리오

  • 기존 소재에 스타일 추가. 이미 촬영된 장면이 있고 애니메이션, 수채화, 필름 그레인, 클레이 애니메이션 또는 기타 효과로 표현하고 싶을 때. 내용과 움직임은 비디오에서 비롯되고 엔드포인트는 표면 질감을 바꿉니다.
  • 일괄적으로 일관된 스타일 유지. 스타일이 지시 형태로 표현되므로 여러 소스 비디오에 동일한 프롬프트를 재사용하여 스타일이 일관된 결과물 세트를 얻을 수 있습니다.
  • 스타일 개발 프로토타이핑. 크리에이티브 팀은 더 무거운 제작 파이프라인에 투자하기 전에 저비용으로 스타일 방향을 반복할 수 있습니다.

적합하지 않은 시나리오

  • 처음부터 비디오를 생성해야 하는 경우(텍스트-비디오는 다른 작업입니다).
  • 프레임 단위로 정확한 편집, 컷팅 또는 합성이 필요한 경우. 변환은 스타일을 재구성할 뿐 편집하지는 않습니다.
  • 소스 소재가 오디오만 있거나 정적 이미지인 경우.

이 가이드의 나머지 부분에서는 요청 구조, 바로 실행 가능한 curl 호출, 대응하는 Python 버전, 그리고 4K 출력과 장시간 작업에 대한 운영 세부 사항을 단계별로 설명합니다.

요청 분석: 소스 비디오, 스타일 지시 및 출력 옵션

변환 요청은 복잡하지 않습니다. 코드를 작성하기 전에 세 가지 필드 그룹으로 나누십시오: 소스 비디오, 지시 및 출력 설정.

소스 비디오

엔드포인트는 입력에 접근할 수 있어야 합니다. 실제로는 플랫폼이 가져올 수 있는 URL을 전달하거나 HiAPI 파일 업로드 단계에서 반환된 식별자를 전달합니다. 실용적인 규칙은 소스 파일이 노트북이 아니라 서버에서 접근 가능해야 한다는 것입니다. localhost 경로나 VPN 뒤에 있는 파일은 작동하지 않습니다.

소스 형식은 보수적으로 유지하십시오—널리 지원되는 컨테이너와 코덱을 사용하세요. 비디오가 특수한 프로세스로 생성되어 검증을 통과하지 못하면 먼저 표준 H.264 MP4로 재인코딩하십시오. 이 단계만으로도 입력 오류의 상당 부분이 해결됩니다.

스타일 지시

목표 시각 효과에 대한 자연어 설명입니다. 요청에서 가장 영향력 있는 필드이자 가장 반복적으로 다듬을 가치가 있는 필드입니다.

  • 내용이 아닌 시각적 처리를 설명하십시오. 내용은 비디오에서 비롯되므로 이미 화면에 있는 것을 모델에 알려주는 것은 프롬프트 예산을 낭비할 뿐입니다.
  • 매체와 질감을 구체적으로 표현하십시오: "지문 자국이 보이는 스톱모션 클레이 애니메이션"이 "애니메이션"보다 더 많은 정보를 전달합니다.
  • 중요할 때는 무엇을 유지해야 하는지 명시하십시오: "얼굴을 식별 가능하게 유지하고 카메라 움직임을 변경하지 마십시오".
  • 초점이 있는 한 단락으로 제한하십시오. 길고 모순된 프롬프트는 평범한 결과로 평균화되는 경향이 있습니다.

출력 옵션

출력 설정은 해상도와 기타 전달 세부 사항을 제어합니다. 주요 결정은 4K를 요청할지 표준 해상도를 요청할지입니다. 더 높은 해상도는 더 많은 연산을 소비하고 더 오래 걸리므로 기본값이 아닌 의식적인 결정으로 간주해야 합니다. 이 엔드포인트는 일반적으로 비동기 작업으로 실행되므로 요청은 보통 완성된 파일을 직접 반환하지 않고 작업 참조를 반환하며, 폴링하거나 기다려야 합니다.

입력을 이 세 가지 필드 그룹에 먼저 매핑하면 실제 JSON 요청 본문이 명확해집니다.

처음부터 사용 가능한 curl 요청

이해를 확인하는 가장 빠른 방법은 최소한의 호출입니다. 아래 형식은 소스 비디오 URL과 스타일 지시를 보내고 표준 해상도 결과를 요청합니다. 자리 표시자 값을 자신의 값으로 바꾸십시오.

curl -X POST "https://api.hiapi.ai/v1/kling-3.0-omni/transformation" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://your-cdn.example.com/clips/source.mp4",
    "prompt": "수채화 수작업 애니메이션으로 변환하고, 가장자리는 부드럽게 번지며, 종이 질감이 보이고, 따뜻하고 제한된 색조 팔레트를 사용하십시오. 얼굴과 카메라 움직임을 유지하십시오.",
    "resolution": "1080p"
  }'

각 부분의 역할

  • URL 경로는 엔드포인트를 지정합니다. 정확히 일치해야 하며, 여기서의 오타는 검증 오류가 아닌 라우팅 오류를 반환합니다.
  • Authorization 헤더는 HiAPI 키를 전달합니다. 셸 기록에 붙여넣지 말고 환경 변수로 내보내십시오.
  • video_url은 소스 비디오입니다. 서버에서 가져올 수 있어야 합니다.
  • prompt는 스타일 지시입니다. 가장 자주 수정하게 될 필드입니다.
  • resolution은 출력 설정입니다. 반복 작업 시에는 낮은 해상도로 시작하고 효과가 확정되면 높이십시오.

응답 해석

성공적인 응답은 작업 객체를 제공합니다. 작업 식별자와 상태 필드를 기록하십시오:

{
  "id": "job_abc123",
  "status": "queued"
}

정확한 필드 이름은 가정하지 말고 실제 응답에서 읽어야 합니다. 중요한 습관은 모든 언어에서 동일합니다: JSON을 파싱하고 작업 ID를 추출하며, 완성된 비디오는 나중에 도착하는 것으로 취급하십시오. 첫 응답에 재생 가능한 파일이 포함되어 있다고 가정하는 코드를 작성하지 마십시오.

동일한 요청을 Python으로

Python 버전은 curl 호출을 JSON 본문을 딕셔너리로 표현한 것입니다. requests를 사용하면 가독성을 유지하고 의존성을 가볍게 할 수 있습니다.

import os
import time
import requests

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

payload = {
    "video_url": "https://your-cdn.example.com/clips/source.mp4",
    "prompt": (
        "수채화 수작업 애니메이션으로 변환하고, 가장자리는 부드럽게 번지며, "
        "종이 질감이 보이고, 따뜻하고 제한된 색조 팔레트를 사용하십시오. "
        "얼굴과 카메라 움직임을 유지하십시오."
    ),
    "resolution": "1080p",
}

resp = requests.post(
    f"{BASE}/kling-3.0-omni/transformation",
    headers=HEADERS,
    json=payload,
    timeout=60,
)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]
print("submitted", job_id, job.get("status"))

작업이 완료될 때까지 폴링

렌더링이 비동기이므로 대기를 제한된 시도 횟수와 검사 간 수면 시간을 가진 루프로 감싸십시오. API를 너무 자주 요청하지 않도록 수면 시간을 충분히 넉넉히 설정하고, 멈춘 작업이 워커 프로세스를 매달리게 하지 않도록 총 대기 시간 상한을 설정하십시오.

def wait_for_job(job_id, max_attempts=60, interval=10):
    for _ in range(max_attempts):
        r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "succeeded":
            return data
        if status == "failed":
            raise RuntimeError(data.get("error") or "job failed")
        time.sleep(interval)
    raise TimeoutError(f"job {job_id} did not finish in time")

result = wait_for_job(job_id)
print(result.get("output") or result)

프로덕션 환경에서 안전하게 만들기

  • API 응답 문서에서 엔드포인트 경로와 폴링 라우트를 읽고, 변경될 수 있는 가정을 하드코딩하지 마십시오.
  • 제출 시 작업 ID를 기록하십시오. 다운스트림에서 문제가 발생하면 이것이 유일한 단서입니다.
  • failed와 시간 초과를 서로 다른 결과로 취급하십시오. 실패한 작업은 보통 매개변수 문제이고, 시간 초과는 보통 용량 또는 길이 문제입니다.

4K 출력과 장시간 실행 작업 처리

두 가지 변수가 이 엔드포인트의 운영 동작을 지배합니다: 출력 해상도와 입력 길이. 둘 다 명확히 계획하십시오.

4K 출력

4K는 기본값이 아니라 전달 결정입니다. 모든 출력 픽셀이 연산을 소비하며, 표준 해상도에서 4K로의 상대적 도약은 큽니다. 합리적인 워크플로:

  1. 낮은 해상도에서 스타일 지시를 반복하십시오. 프롬프트 품질은 해상도와 무관하므로 먼저 저비용으로 효과를 맞추십시오.
  2. 프롬프트와 소스 비디오를 확정하십시오.
  3. 전달용으로 4K에서 한 번 다시 실행하십시오.

문구를 조정하면서 4K 변형을 촘촘한 루프에서 생성하지 마십시오—결국 버릴 렌더링에 예산을 낭비하는 가장 흔한 방법입니다.

장시간 실행 작업

더 긴 소스 비디오는 변환에 더 오래 걸리며, 엔드포인트는 완성된 파일이 아닌 작업 참조를 반환합니다. 이 현실에 맞춰 클라이언트를 구축하십시오:

  • 웹 요청이 렌더링에 블로킹되게 절대 두지 마십시오. 제출하고 작업 ID를 저장한 다음 즉시 호출자에게 반환하십시오.
  • 제출과 가져오기를 분리하십시오. 큐와 폴링 워커가 인라인 대기보다 견고하며 프로세스 재시작을 견딥니다.
  • 작업 상태를 영속화하십시오. 워커가 폴링 중에 죽어도 작업은 사라지지 않으며, 저장된 ID로 복구할 수 있습니다.
  • 계정이 웹훅을 지원하면 사용하고, 폴링을 폴백 경로로 유지하십시오.
  • 총 대기 예산을 설정하고 임의의 숫자가 아닌 예상 최장 비디오를 반영하십시오.

실용적인 패턴

일반적인 길이를 초과하는 소스 비디오를 세그먼트로 나누어 각각 변환한 뒤 결과를 이어 붙이십시오. 이렇게 하면 단일 대기 시간이 짧아지고 전체 렌더링 대신 특정 세그먼트만 재시도할 수 있으며 실패 비용이 저렴해집니다. 세그먼트 경계가 빠른 움직임을 가로지르지 않도록 확인하십시오. 그렇지 않으면 이음새가 눈에 띕니다.

일반적인 장애 해결

대부분의 장애는 세 가지 범주에 속합니다: 소스 비디오를 읽을 수 없음, 매개변수 거부, 또는 작업이 완료되지 않음. 무엇이든 변경하기 전에 문제 범주를 먼저 분리하십시오.

업로드 및 소스 접근 오류

증상: 제출 실패, 또는 작업이 입력 오류로 거의 즉시 실패.

  • URL에 공개적으로 접근할 수 없음. 네트워크 외부의 머신에서 테스트하십시오. 제출과 가져오기 사이에 서명된 URL이 만료되는 것이 전형적인 원인입니다.
  • 지원되지 않는 형식. 표준 H.264 MP4로 재인코딩한 후 다시 시도하십시오.
  • 파일이 잘리거나 손상됨. 직접 다운로드하여 처음부터 끝까지 재생해 보십시오.
  • 요청이 너무 큼. 파일 바이트를 URL이 아닌 인라인으로 보내는 경우 업로드 흐름으로 전환하고 반환된 식별자를 전달하십시오.

매개변수 오류

증상: 제출 시 4xx 응답 반환.

  • JSON 형식 오류. 린트 도구로 요청 본문을 검사하십시오. 후행 쉼표와 이스케이프되지 않은 따옴표는 수작업 curl 호출에서 흔한 실수입니다.
  • 필드 이름 또는 타입 오류. 현재 요청 스키마와 대조하십시오; 해상도를 문자열로 기대하는데 숫자로 전달하면 실패합니다.
  • 프롬프트가 비어 있거나 모순됨. 지시가 아무것도 설명하지 않거나 상호 배타적인 스타일을 요구하면 출력이 약하거나 거부될 것으로 예상하십시오. 명확한 시각적 방향을 중심으로 다시 작성하십시오.
  • API 키 누락 또는 무효. 헤더 값을 확인하고 키가 해당 엔드포인트에 유효한지 확인하십시오.

시간 초과 및 멈춘 작업

증상: 작업이 대기 예산 이후에도 대기 중 또는 실행 중 상태로 남거나 클라이언트가 포기함.

  • 클라이언트 시간 초과와 작업 실패를 구분하십시오. 제출 시 짧은 HTTP 시간 초과는 작업이 시작되지 않았다는 의미가 아닙니다; 재제출 전에 작업 ID가 있는지 확인하십시오. 그렇지 않으면 중복 렌더링이 발생할 수 있습니다.
  • 긴 입력과 4K 출력은 실행 시간을 연장합니다. 지속적으로 시간 초과가 발생하면 해상도를 낮추거나 비디오를 줄여 흐름이 작동하는지 확인한 후 단계적으로 되돌리십시오.
  • 작업이 failed를 보고하면 재시도 전에 오류 메시지를 읽으십시오. 확정적인 매개변수 오류에 대한 맹목적 재시도는 비용만 배가시킵니다.

효과적인 디버깅 순서

가능한 한 작은 요청부터 시작하십시오: 짧은 표준 해상도 비디오와 한 문장의 프롬프트. 성공하면 실제 프롬프트, 실제 길이, 마지막으로 4K를 하나씩 재도입하여 한 번에 하나의 변수만 변경하십시오. 오류가 발생한 단계가 어떤 변수가 원인인지 알려줍니다.

계획해야 할 비용과 지연의 트레이드오프

요청이 사용 가능해지면 남은 결정은 모두 운영 차원입니다. 세 가지 레버가 비용과 지연에 동시에 영향을 미치며 상호 작용합니다.

해상도

출력 해상도는 가장 큰 단일 레버입니다. 청구는 렌더링 실행 작업량과 연동되며, 더 높은 해상도 출력은 더 많은 작업을 의미합니다. 경험 법칙: 낮은 해상도로 반복, 높은 해상도로 전달. 스타일 실험을 절대 4K로 실행하지 마십시오.

입력 길이

더 긴 소스 비디오는 변환할 프레임이 더 많다는 의미이며, 더 많은 연산과 더 많은 실제 시간을 의미합니다. 사용 사례가 허용하면 전체 클립 대신 짧은 하이라이트 비디오를 변환하거나, 긴 소재를 나누어 처리해야 할 부분만 변환하십시오.

재시도

작업이 시작되기 전에 실패하지 않는 한 모든 재시도는 전체 렌더링입니다. 이것이 디버깅 순서가 중요한 이유입니다: 렌더링에 비용을 쓰기 전에 매개변수를 저비용으로 검증하십시오. 작업 ID를 기록하고 클라이언트 시간 초과 후 재제출 전에 확인하여 중복 제출을 방지하십시오.

일괄 처리와 병렬 처리

병렬 작업은 실제 시간을 줄이지만 총 비용은 줄이지 않으며—동시성 제한에 도달할 수 있습니다. 배치 작업에는 제어된 병렬성의 적당한 큐가 보통 팬아웃보다 낫습니다. 속도 제한 아래에 머물게 하고, 실패를 개별적으로 쉽게 재시도할 수 있으며, 예측 가능한 지출 곡선을 제공합니다.

예산 체크리스트

  • 전달 렌더링 전에 낮은 해상도에서 프롬프트를 확정하십시오.
  • 완료된 출력을 캐시하십시오; 동일한 입력을 다시 렌더링하지 마십시오.
  • 작업별 및 배치별 지출 예상을 설정하고 배치가 초과하면 경고하십시오.
  • 작업 시간과 해상도 및 입력 길이의 관계를 추적하여 과거 실행에서 새 작업을 예측하십시오.
  • 4K를 대화형 모드가 아닌 프로세스의 마지막 단계로 취급하십시오.

이 엔드포인트의 가격은 HiAPI 웹사이트에 나열되어 있으므로 배치 규모를 계획하기 전에 현재 요금을 확인하십시오. 먼저 최소 요청을 작동시킨 후 의식적으로 해상도와 길이를 확장하십시오—이 순서가 지연과 청구를 모두 예측 가능하게 유지합니다.

영구 AI 아티팩트로 빌드 시작하기

API 키를 받아 태스크 기반의 하나의 API로 이미지, 비디오, 오디오 모델을 호출하세요.

API 문서 보기