블로그

튜토리얼

muse-video-1.0 이미지-투-비디오 API 튜토리얼: curl 및 Python Requests

Nov 13, 2026
muse-video-1.0 튜토리얼 커버 아트: 짙은 청록빛 배경 위에 청록색으로 표현된 평면 다면 광물 단면.
이 페이지에서

muse-video-1.0 이미지-투-비디오 엔드포인트가 요구하는 것

muse-video-1.0/image-to-video 엔드포인트는 단일 정적 이미지를 짧은 동영상으로 변환합니다. 첫 줄의 코드를 작성하기 전에 요청 구조를 이해하면 올바른 요청 페이로드를 한 번에 구성할 수 있습니다.

높은 수준에서 보면 한 번의 호출은 네 가지 측면을 포함합니다:

  • 모델 라우팅 —— HiAPI 통합 API를 통해 muse-video-1.0/image-to-video로 모델을 지정합니다.
  • 입력 이미지 —— 애니메이션의 시작점이 되는 정적 프레임입니다. 이는 필수적인 창작 입력입니다.
  • 생성 옵션 —— 오디오 동작과 길이 등급으로, 소스 소재가 아닌 출력 특성을 형성합니다.
  • 비동기 실행 —— 생성 결과가 인라인으로 반환되지 않습니다. 먼저 작업을 제출한 다음 폴링하여 결과를 가져옵니다.

마지막 사항은 개발자가 가장 자주 간과하는 부분입니다. 렌더링에 시간이 걸리기 때문에 이 엔드포인트는 작업 메커니즘을 기반으로 합니다: 초기 호출은 요청을 확인하고 핸들을 반환하며, 그 후 상태 조회로 후속 확인하여 비디오가 준비될 때까지 진행합니다. 폴링을 나중에 덧붙이는 것이 아니라 처음부터 이 2단계 흐름을 중심으로 클라이언트를 설계하세요.

요청 본문 자체는 JSON입니다. 필드는 그룹 구조로 이루어집니다: 이미지는 별도의 input 블록에 있고, 오디오와 길이는 생성 설정으로서 그와 나란히 위치합니다. 이 멘탈 모델(입력, 옵션, 작업 수명 주기의 분리)을 유지하면 이 튜토리얼의 나머지 부분은 간단해집니다.

인증

모든 요청은 HiAPI API 키로 인증하며, bearer 자격 증명 형태로 Authorization 요청 헤더에 넣습니다. 키는 기밀로 취급하세요: 공유할 수 있는 스크립트에 하드코딩하지 말고 환경 변수에서 로드하세요.

export HIAPI_API_KEY="your_api_key_here"

키를 내보낸 후에는 요청을 이해하는 데 필요한 모든 조건이 갖춰집니다. 다음 섹션에서는 요청 페이로드를 단계적으로 구성합니다.

첫 프레임 이미지 준비 및 업로드

첫 프레임 이미지는 전체 작업의 창작 기준점입니다. 제공한 내용이 0번째 프레임이 되고, 모델이 그로부터 앞으로 애니메이션을 생성합니다. 이를 올바르게 처리하면 생성 횟수를 낭비하지 않습니다.

소스 프레임에 대한 실용적인 조언

  • 선명하고 고품질의 정적 이미지를 사용하세요. 단일 프레임 이미지로 읽을 때 자연스러운 내용이 모델에 최상의 시작점을 제공합니다.
  • 목표 출력과 일치하는 가로세로 비율을 선택하세요. 가로로 넓은 이미지와 세로로 긴 이미지는 매우 다른 구도를 초래하므로 실제 업로드 전에 방향을 정해야 합니다.
  • 심한 모션 블러나 불분명한 주체를 피하세요. 시각적으로 안정적인 정적 이미지가 더 예측 가능한 애니메이션을 생성합니다.
  • 요청 시점에 파일에 접근 가능한지 확인하세요. URL을 전달하든 인코딩된 페이로드를 전달하든, 작업 제출 순간에 해당 참조에 접근할 수 있어야 합니다.

이미지가 요청에 들어가는 방식

이미지는 JSON 요청 본문의 input 블록에 제공됩니다. 최소한의 이미지 입력은 다음과 같습니다:

{
  "input": {
    "image": "https://your-host.example/first-frame.jpg"
  }
}

소스 이미지가 로컬에 있다면 요청에서 접근 가능한 위치에 호스팅하거나 엔드포인트가 허용하는 인코딩 형태로 전달하세요. 핵심 규칙은: input.image의 값은 작업 생성 시점에 실제 이미지 콘텐츠로 해석되어야 한다는 것입니다 —— 손상되거나 만료된 링크는 폴링이 아닌 제출 시점에 실패하며, 이는 실제로 유용한 조기 신호입니다.

생성 전 검증

빠른 정상성 검사는 가치가 있습니다: 브라우저에서 이미지 URL을 열어 로드되는지 확인하고, 크기가 의도한 출력에 적합한지 확인하세요. 여기서 2초를 투자하면 나중에 혼란스러운 디버깅을 피할 수 있습니다.

첫 프레임이 준비되고 접근 가능해지면 생성 옵션 처리를 계속할 수 있습니다.

오디오 매개변수와 길이 등급 설정

이미지 외에도 muse-video-1.0/image-to-video는 출력 특성을 변경하는 두 가지 옵션 유형을 제공합니다: 오디오 동작과 길이입니다.

오디오 매개변수

오디오는 요청 본문에서 input과 나란히 위치하는 하나의 필드로 표현됩니다. 호출 전에 의도를 정하세요:

  • 무음 출력 —— 나중에 자체 배경 음악을 추가하거나 깨끗한 비디오 트랙이 필요한 경우 오디오를 끄세요.
  • 오디오 활성화 —— 클립에 자체 사운드가 있어야 하는 경우 오디오를 켜세요. 기본값을 가정하지 말고 요청 페이로드에서 해당 옵션을 명시적으로 확인하세요.

오디오 처리는 후처리 단계가 아니라 요청 자체의 속성이므로 규모를 확장하기 전에 확정하는 것이 좋습니다. 파이프라인이 무음 클립과 오디오가 있는 클립을 혼합한다면 클라이언트 코드에서 그 선택을 명시적 매개변수로 모델링하여 실수로 어긋나지 않도록 하세요.

길이 등급

이 엔드포인트는 클립의 길이 등급을 선택할 수 있게 합니다. 길이는 의도적인 창작 및 비용 결정으로 취급하세요:

  • 짧은 등급은 빠른 미리보기, 소셜 클립, 스토리보드 테스트에 적합하며, 많은 소스 이미지에서 빠르게 피드백을 받고 싶을 때 유용합니다.
  • 긴 등급은 애니메이션에 더 많은 발전 공간을 주며, 메인 비주얼 샷이나 호흡이 필요한 시퀀스에 더 적합합니다.

길이는 출력 초 단위로 과금되므로 선택한 등급이 소비에 직접 영향을 미칩니다. 단순한 시각적 확인을 위해 긴 클립을 렌더링하는 것은 아무 이점이 없습니다 —— 첫 프레임을 반복할 때는 짧은 등급을 사용하고, 승리한 설정을 더 긴 등급으로 승격하세요.

이 옵션들을 함께 구성하기

JSON에서 오디오와 길이 설정은 input 블록과 나란히 위치합니다:

{
  "input": {
    "image": "https://your-host.example/first-frame.jpg"
  },
  "audio": true,
  "duration": "<duration_tier>"
}

값을 추측하지 말고 엔드포인트 문서에 나온 정확한 등급 식별자를 사용하세요. 다음 섹션에서 이를 실행 가능한 요청으로 만듭니다.

실행 가능한 curl 요청

요청 페이로드가 구성되면 다음은 초기 제출용 curl 명령입니다. 이 명령은 작업을 생성하며 완성된 비디오를 반환하지 않습니다.

curl -X POST "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "image": "https://your-host.example/first-frame.jpg"
    },
    "audio": true,
    "duration": "<duration_tier>"
  }'

이 명령에 대한 몇 가지 설명:

  • URL이 모델을 이름으로 지정합니다. 모델별로 별도의 클라이언트를 준비할 필요가 없습니다; 경로가 이미 muse-video-1.0/image-to-video를 식별합니다.
  • 요청 헤더가 키를 전달합니다. $HIAPI_API_KEY는 앞서 내보낸 환경 변수에서 확장되므로 키가 스크립트 자체에 나타나지 않습니다.
  • 요청 본문은 방금 구성한 페이로드입니다. 이미지 URL, 오디오 플래그, 길이 등급이 함께 전달됩니다.

응답은 작업 확인으로, 방금 생성한 작업의 식별자를 포함합니다. 해당 식별자를 복사하세요 —— 폴링 단계에서 사용됩니다. 단순히 탐색 중이라면 JSON 포매터로 응답을 처리하여 job ID를 더 쉽게 찾을 수 있습니다.

제출이 실패하면 오류는 보통 즉각적이고 구체적입니다: JSON 요청 본문 형식 오류, 이미지 참조 누락, 또는 인식할 수 없는 옵션 값. 이러한 빠른 피드백 루프가 폴링을 연결하기 전에 제출을 단독으로 테스트할 가치가 있는 이유입니다.

같은 요청을 Python으로 구현하기

대부분의 통합은 결국 Python으로 귀결되므로, 표준 라이브러리를 사용한 동등한 제출을 소개합니다 —— 서드파티 SDK가 필요 없습니다.

import json
import os
import urllib.request

API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video"

payload = {
    "input": {
        "image": "https://your-host.example/first-frame.jpg"
    },
    "audio": True,
    "duration": "<duration_tier>",
}

request = urllib.request.Request(
    ENDPOINT,
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    method="POST",
)

with urllib.request.urlopen(request) as response:
    result = json.loads(response.read().decode("utf-8"))

job_id = result["id"]
print("Submitted job:", job_id)

이 스크립트는 curl 호출에 필드별로 대응합니다. 들여두면 좋은 몇 가지 습관:

  • 요청 페이로드를 딕셔너리에 보관하세요. Python 딕셔너리로 구성하면 같은 구조를 어떤 HTTP 라이브러리든 —— urllib, requests, 비동기 클라이언트 —— 논리를 다시 작성하지 않고 전달할 수 있습니다.
  • 키를 환경에서 읽으세요. os.environ은 자격 증명을 소스 제어에서 멀리 떨어뜨립니다.
  • 응답을 즉시 JSON으로 파싱하세요. job ID를 명명된 변수로 추출하면 폴링 단계가 더 명확하게 읽힙니다.

requests 라이브러리를 선호한다면 유일한 변화는 전송 계층을 바꾸는 것입니다: 동일한 payload 딕셔너리를 구성하고 요청 헤더 세트로 전송한 다음 응답에 .json()을 호출하세요. 엔드포인트, 요청 헤더, 요청 본문은 완전히 동일하게 유지됩니다.

작업이 제출되고 식별자가 캡처되면 남은 일은 올바른 방식으로 결과를 기다리는 것입니다.

비동기 작업을 폴링하고 비디오 가져오기

비디오 생성은 즉각적이지 않으므로 이 엔드포인트는 비동기입니다. 제출 후 작업 상태를 폴링하여 렌더링이 언제 완료되는지 확인한 다음 출력을 가져옵니다.

폴링 루프

견고한 루프는 세 가지를 합니다: 검사 사이에 대기하고, 무한 실행을 피하기 위해 상한을 설정하며, "아직 처리 중", "완료", "실패"를 구분합니다.

import time
import urllib.request

STATUS_ENDPOINT = "https://api.hiapi.ai/v1/jobs/{job_id}"

def wait_for_video(job_id, max_attempts=60, interval=5):
    for attempt in range(max_attempts):
        url = STATUS_ENDPOINT.format(job_id=job_id)
        request = urllib.request.Request(
            url,
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        with urllib.request.urlopen(request) as response:
            status = json.loads(response.read().decode("utf-8"))

        state = status.get("status")
        if state == "succeeded":
            return status.get("output")
        if state == "failed":
            raise RuntimeError(f"Job {job_id} failed: {status}")

        time.sleep(interval)

    raise TimeoutError(f"Job {job_id} did not finish in time")

프로덕션 환경을 위한 설계 포인트

  • 합리적인 간격을 사용하세요. 5초는 합리적인 시작점입니다; 상태 엔드포인트를 공격적으로 호출하지 마세요.
  • 항상 시도 횟수를 제한하세요. max_attempts 상한은 무한 대기를 기록하고 경고할 수 있는 명확한 오류로 바꿉니다.
  • 실패 상태를 명시적으로 처리하세요. 실패한 작업에는 진단 정보가 포함됩니다 —— 동일한 입력으로 조용히 재시도하지 말고 이를 노출하세요.
  • job ID를 영속화하세요. 프로세스가 재시작되면 다시 생성하는 비용을 들이지 않고 폴링을 재개할 수 있습니다.

출력 가져오기

작업이 성공하면 상태 응답은 완성된 비디오의 출력 참조를 포함합니다. 장기 유효 링크에 의존하지 말고 자체 스토리지로 즉시 다운로드하세요. 파일이 로컬이나 버킷에 있으면 파이프라인 관점에서 생성이 완료된 것입니다.

이것이 전체 수명 주기입니다: 제출, 폴링, 가져오기. 코드에서 두 단계를 분리하면 각 단계가 단순하게 유지됩니다.

흔한 함정과 디버깅 팁

muse-video-1.0/image-to-video를 사용할 때 대부분의 통합 문제는 몇 가지 범주로 귀결됩니다. 문제가 생겼을 때 확인해야 할 사항은 다음과 같습니다.

이미지 입력 문제

  • 이미지 참조에 접근 불가. URL에 인증이 필요하거나 만료되었다면 작업이 제출 시점에 실패합니다. 요청 중에는 프레임을 공개적으로 읽을 수 있는 위치에 호스팅하세요.
  • 가로세로 비율 불일치. 세로 정적 이미지를 가로 출력에 강제로 사용하면 어색한 자르기나 검은 여백이 생깁니다. 소스 방향을 목표에 맞게 설정하세요.
  • 잘못된 콘텐츠. 실제 프레임이 아닌 축소판이나 자리 표시자 이미지를 가리키기 쉽습니다. URL이 의도한 이미지를 여는지 확인하세요.

매개변수 오류

  • 길이 값을 추측하기. 엔드포인트 문서에 정확히 나온 등급 식별자를 사용하세요. 인식할 수 없는 값은 흔한 거부 원인입니다.
  • 오디오 플래그 누락. 오디오 설정을 생략하면서 소리를 기대하면 무음 클립을 얻을 수 있습니다. 오디오 필요 여부를 명시적으로 표현하세요.
  • 최상위 필드와 input 필드 혼동. 이미지는 input 내부에 속합니다; 오디오와 길이는 input의 형제 노드이지 자식이 아닙니다. 잘못된 중첩은 혼란스러운 검증 메시지를 생성합니다.

폴링 오류

  • 제출을 완료로 착각하기. 첫 응답은 확인일 뿐 비디오가 아닙니다. 항상 상태 확인으로 후속 조치하세요.
  • 무제한 폴링. 상한 없는 루프는 작업이 정체될 때 워커를 멈추게 합니다. 상한과 타임아웃 오류를 추가하세요.
  • 실패 무시하기. 실패 상태로 끝난 작업은 결코 비디오를 생성하지 않습니다; 계속 기다리지 말고 이를 캡처하여 진단 정보를 확인하세요.
  • 잘못된 입력으로 오래 대기하기. 렌더링이 계속 실패하면 재생성을 중단하세요. 먼저 소스 프레임이나 매개변수를 수정한 다음 다시 제출하세요.

효과적인 디버깅 순서

  1. 브라우저에서 이미지 URL이 로드되는지 확인합니다.
  2. 매개변수 문제를 분리하기 위해 이미지만으로 최소 페이로드를 제출합니다.
  3. job ID가 깨끗하게 반환되는지 검증합니다.
  4. 먼저 수동으로 폴링하여 상태 전환을 관찰합니다.
  5. 그 후에만 루프를 자동화하고 일시적 네트워크 오류에 대한 재시도를 추가합니다.

이 단계를 순서대로 처리하면 문제를 한 계층 —— 이미지, 옵션 또는 수명 주기 —— 으로 빠르게 좁혀 통합을 계속 진행할 수 있습니다. 요청 구조, 옵션, 폴링 흐름을 이해했으므로 이제 이 엔드포인트를 대상으로 구축할 준비가 되었습니다.

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

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

API 문서 보기