튜토리얼
HiAPI API로 muse-video-1.0/text-to-video 호출하기: curl 및 Python 가이드
요청 필드, 비동기 폴링, 실행 가능한 예시 요청
이 페이지에서
보내기 전에: 인증, 엔드포인트, 모델 식별자
muse-video-1.0/text-to-video는 텍스트 프롬프트를 생성된 비디오 클립으로 변환합니다. 프롬프트와 몇 가지 제어 파라미터를 보내면 서비스가 클립을 렌더링한 뒤 다운로드 가능한 URL 또는 참조를 반환합니다.
핵심 아키텍처 세부 사항은 이 호출이 비동기라는 점입니다. 비디오 렌더링은 시간이 오래 걸리며, API는 파일이 준비될 때까지 HTTP 연결을 계속 열어두지 않습니다. 따라서 흐름은 두 단계로 나뉩니다:
- 제출—프롬프트와 파라미터를 POST합니다. 응답은 빠르게 반환되며 작업 식별자와 초기 작업 상태가 포함됩니다.
- 폴링—식별자로 일정 간격을 두고 작업을 GET하여 상태가 최종 상태(성공 또는 실패)로 바뀌면 결과를 가져옵니다.
이 "먼저 제출한 뒤 폴링"하는 형태는 코드를 작성하기 전에 가장 먼저 체득해야 할 핵심입니다. 이는 애플리케이션 구조를 바꿉니다: 비디오는 제출 요청의 응답에 나타나지 않으며, 마주치는 모든 오류는 특정 단계—제출, 검증, 렌더링 또는 가져오기—에 속합니다. 자체 코드에서 이러한 단계를 구분하면(서로 다른 함수 사용, 별도 로깅) 이 가이드의 나머지 내용을 적용하기가 더 쉬워집니다.
전달하는 모델 문자열은 정확해야 합니다: muse-video-1.0/text-to-video. vendor/model 형식은 HiAPI의 여러 모델 엔드포인트에서 공통된 관례이며, API 라우팅은 이를 근거로 어느 생성기를 호출할지 판단합니다.
요청 구성: 프롬프트, 길이, 오디오 필드
첫 요청 전에 반드시 세 가지를 준비해야 합니다.
API 키
모든 요청은 bearer token으로 인증해야 합니다. 소스 코드가 아닌 환경 변수에 보관하여 커밋 기록에 유출되지 않도록 하세요:
export HIAPI_API_KEY="your_key_here"
Authorization: Bearer $HIAPI_API_KEY 헤더로 전송합니다. 요청이 인증 관련 오류로 실패하면 이 헤더를 먼저 확인하세요—변수 이름 오타, 끝의 공백, 또는 현재 셸에 값이 설정되지 않은 것이 가장 흔한 원인입니다.
기본 URL
모든 호출은 HiAPI 플랫폼의 하나의 기본 URL을 공유합니다. 계정 패널이나 API 참조의 현재 값을 사용하고, 오래된 코드 조각에서 복사하지 마세요. 변수에 저장하여 한 곳만 수정하면 되도록 하세요.
모델 식별자
모델 문자열은 muse-video-1.0/text-to-video입니다. 대소문자를 구분하는 리터럴로 취급하세요. 대소문자가 다르거나 접미사가 빠진 변형을 직접 조합하거나 추측하지 마세요—알 수 없는 모델 식별자는 폴백이 아니라 검증 오류입니다.
이 세 가지가 준비되면 요청 본문을 구성할 수 있습니다.
동작하는 curl 요청
요청 본문은 JSON입니다. 개념적으로 세 가지 필드 그룹을 포함합니다.
프롬프트
프롬프트는 창의적 지시이며 출력 품질의 대부분을 결정합니다. 효과적인 프롬프트는 형용사만 나열하지 않고 주체, 동작, 카메라 움직임, 조명, 스타일을 구체적으로 설명합니다. 이는 일반 문자열 필드입니다.
길이
텍스트-비디오 모델은 클립이 얼마나 길어야 하는지 알아야 합니다. 길이는 요청 필드이며 비용에도 영향을 줍니다: 생성은 출력 초 단위로 과금됩니다. 허용 범위와 기본값은 특정 시점에 모델이 정의하므로, 정확한 필드 이름과 허용 값을 추측하지 말고 muse-video-1.0/text-to-video의 실시간 API 참조에서 읽으세요. 범위를 벗어난 길이를 전달하면 검증 오류가 발생합니다.
오디오
muse-video-1.0/text-to-video는 시각 생성 외에도 오디오 관련 제어를 지원합니다. 이 역시 요청 필드이며—보통 토글이나 오디오 프롬프트 스타일의 입력—정확한 이름과 허용 값은 동일한 API 참조에 문서화되어 있습니다. 첫 통합 시에는 선택적 오디오 필드를 완전히 생략하고 비디오가 성공적으로 반환되는 것을 확인한 뒤 오디오 옵션을 하나씩 추가하는 것이 보수적인 방법입니다.
따라서 최소 요청 본문은 대략 다음과 같습니다(필드 이름은 예시일 뿐이니 참조와 대조하여 확인하세요):
{
"model": "muse-video-1.0/text-to-video",
"prompt": "해 뜰 무렵 안개 낀 소나무 숲을 천천히 지나가는 공중 샷, 부드러운 볼류메트릭 광, 시네마틱",
"duration": 5
}
파라미터 집합이 진화할 수 있으므로 신뢰할 수 있는 습관은 다음과 같습니다: 해당 모델의 참조 문서를 가져와 필드 이름을 그대로 복사하고, 보내기 전에 로컬에서 검증하세요.
Python에서의 동일한 요청
제출 호출은 HTTP POST입니다. 정확한 리소스 경로는 HiAPI API 참조에서 정의됩니다. 아래 예시는 일반적인 작업 엔드포인트를 사용하며 모델은 요청 본문에 넣습니다.
curl -sS -X POST "$HIAPI_BASE_URL/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "muse-video-1.0/text-to-video",
"prompt": "비 오는 네온 골목을 걸어가는 판지 로봇, 젖은 아스팔트 위의 반사, 35mm 필름 질감",
"duration": 5
}'
응답은 작고 빠르게 반환됩니다. 그중 중요한 것은 작업 식별자와 상태입니다. 일반적인 구조는 다음과 같습니다:
{
"id": "job_abc123",
"status": "queued"
}
id를 기록하세요—이후 모든 호출의 핸들입니다. status가 queued 또는 processing인 것은 정상이며, 문제가 생긴 것이 아니라 요청이 접수되었음을 의미합니다.
셸에서 수동으로 폴링:
curl -sS "$HIAPI_BASE_URL/v1/video/generations/job_abc123" \
-H "Authorization: Bearer $HIAPI_API_KEY"
일정 간격으로 몇 번 실행하여 status가 최종 상태로 변하는 것을 관찰하세요. 실제로는 이 루프를 터미널 기록이 아니라 코드에 두는 것이 좋습니다.
API를 과도하게 두드리지 않고 비동기 결과 및 폴링 처리하기
Python 버전은 동일한 두 가지—제출 후 폴링—을 수행하지만 타임아웃 처리, 제한된 재시도, 결과 저장을 추가하여 무인으로 안전하게 실행할 수 있습니다.
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}"}
MODEL = "muse-video-1.0/text-to-video"
def submit(prompt: str, duration: int) -> str:
resp = requests.post(
f"{BASE}/v1/video/generations",
headers={**HEADERS, "Content-Type": "application/json"},
json={"model": MODEL, "prompt": prompt, "duration": duration},
timeout=30,
)
resp.raise_for_status()
return resp.json()["id"]
def wait_for(job_id: str, max_wait: int = 900) -> dict:
deadline = time.time() + max_wait
interval = 5
while time.time() < deadline:
r = requests.get(
f"{BASE}/v1/video/generations/{job_id}",
headers=HEADERS,
timeout=30,
)
if r.status_code >= 500 or r.status_code == 429:
time.sleep(interval)
interval = min(interval * 2, 30)
continue
r.raise_for_status()
job = r.json()
if job["status"] == "succeeded":
return job
if job["status"] == "failed":
raise RuntimeError(job.get("error") or "generation failed")
time.sleep(interval)
interval = min(interval * 1.5, 30)
raise TimeoutError(f"job {job_id} did not finish in time")
def save(job: dict, path: str) -> None:
url = job["result"]["video_url"]
with requests.get(url, stream=True, timeout=120) as r:
r.raise_for_status()
with open(path, "wb") as f:
for chunk in r.iter_content(8192):
f.write(chunk)
if __name__ == "__main__":
job_id = submit(
"나무 테이블 위의 유리 미니어처 테라리움, 아침 햇살, 떠다니는 먼지 입자, 매크로",
5,
)
job = wait_for(job_id)
save(job, "output.mp4")
print("saved output.mp4")
여기에는 세 가지 의도적인 선택이 있습니다. 재시도는 루프 횟수가 아닌 마감 시간으로 제한되므로 무한정 멈추지 않습니다. 백오프는 일시적 실패 시 증가하고 성공 경로 폴링에서는 천천히 증가합니다. 다운로드는 별도의 스트리밍 요청으로 수행하여 대용량 파일이 JSON 경로를 거치지 않도록 합니다.
흔한 오류와 문제 해결 방법
폴링 빈도는 실제 설계 결정입니다. 200밀리초마다 폴링하면 불필요한 부하만 발생하고, 5분마다 폴링하면 렌더링이 끝난 뒤 실제 시간을 낭비합니다.
실용적인 전략:
- 적당한 간격(몇 초)으로 시작하여 점진적으로 늘리세요—폴링할 때마다 1.5배씩 곱하고 최대 약 30초로 제한하면 잘 작동합니다.
429및5xx응답에는 백오프를 더 강하게 적용하세요: 간격을 두 배로 늘리고 재시도하며, 이를 작업 상태가 아닌 용량 신호로 취급하세요.- 최대 총 대기 시간을 설정하고 초과 시 오류를 발생시켜 영원히 폴링하지 않도록 하세요. 더 긴 길이의 렌더링은 실제로 더 오래 걸리므로 상한은 자체 워크로드에 맞게 설정해야 합니다.
- 상태가 변할 때만 전환을 한 번 기록하고, 매 폴링마다 기록하지 마세요—시끄러운 로그는 실제 실패를 알아보기 어렵게 만듭니다.
완료된 작업의 응답은 보통 최종 status, 작업 id, 다운로드 가능한 비디오 URL이 포함된 결과 페이로드를 포함하며, 때로는 메타데이터와 URL 만료 시간이 함께 옵니다. 성공 후에는 파일을 제때 가져오세요. 작업이 failed를 보고하면 재시도 전에 응답의 오류 메시지를 읽으세요—검증 실패는 재시도해도 절대 성공하지 않지만, 내부 렌더링 오류는 성공할 수 있습니다.
다음 단계
최소 요청 본문으로 시작하여 한 번의 엔드투엔드 성공 실행을 확인한 다음, muse-video-1.0/text-to-video의 현재 참조 문서에 따라 길이와 오디오 제어를 추가하세요. 동일한 "먼저 제출한 뒤 폴링" 패턴은 다른 HiAPI 모델 엔드포인트에도 적용할 수 있으므로, 여기서 작성한 클라이언트 코드는 재사용할 수 있습니다.