hiapi API로 lyria-3-pro 사용하는 방법: curl, Python 및 실행 가능한 요청 예시

lyria-3-pro는 hiapi API로 제공되는 음악 생성 모델입니다. 텍스트 프롬프트를 보내면 완성된 오디오 트랙을 얻을 수 있습니다. 이 가이드는 실제로 taskId를 반환하는 요청 흐름을 단계별로 안내하고, 전체(아주 간단한) 입력 스키마와 일회성 테스트를 벗어난 후 필요한 프로덕션 환경 세부 사항을 설명합니다.

준비물

• hiapi API key. 콘솔에서 발급받을 수 있으며, key는 sk-로 시작합니다.
• curl 또는 Python의 requests. SDK는 필요 없습니다. hiapi는 표준 REST를 사용합니다.

lyria-3-pro는 hiapi의 통합 비동기 작업 API에서 실행됩니다. 작업을 POST하면 즉시 taskId를 받고, 이후 결과를 폴링하거나 트랙이 준비되면 콜백을 받습니다.

최소 실행 예시

1. 작업 생성

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lyria-3-pro",
    "input": {
      "prompt": "Warm lo-fi piano loop with soft vinyl crackle, relaxed tempo, calm evening mood"
    }
  }'

정상 응답은 트랙이 실제로 렌더링을 완료하기 전에 즉시 반환됩니다:

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01M0T17T7RERV481QJC3DRZCRS" }
}

2. 결과 폴링

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M0T17T7RERV481QJC3DRZCRS" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

첫 폴링 전에 몇 초 기다린 후, 3–5초마다 확인하세요. status는 archiving 같은 중간 상태를 거쳐 최종 상태로 진입합니다:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M0T17T7RERV481QJC3DRZCRS",
    "model": "lyria-3-pro",
    "status": "success",
    "created": 1787580115,
    "completed": 1787580157,
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M0T17T7RERV481QJC3DRZCRS-0.mp3",
        "expireAt": 1788184956
      }
    ]
  }
}

output[0].url을 가능한 한 빨리 다운로드하세요. 기본 temp 스토리지 계층은 약 7일 후 만료됩니다(expireAt은 Unix 타임스탬프). 실패 시 status는 fail이며, data.error에 output 대신 { code, message }가 포함됩니다.

3. Python에서의 동일한 요청

import time
import requests

API_KEY = "sk-YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

payload = {
    "model": "lyria-3-pro",
    "input": {
        "prompt": "Warm lo-fi piano loop with soft vinyl crackle, relaxed tempo, calm evening mood",
    },
}

create = requests.post("https://api.hiapi.ai/v1/tasks", headers=HEADERS, json=payload)
task_id = create.json()["data"]["taskId"]

while True:
    time.sleep(3)
    detail = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS).json()
    status = detail["data"]["status"]
    if status == "success":
        print(detail["data"]["output"][0]["url"])
        break
    if status == "fail":
        raise RuntimeError(detail["data"]["error"])

전체 입력 스키마

input은 정확히 두 개의 필드만 허용합니다. 이 목록 외의 모든 내용은 400 INVALID_REQUEST와 함께 거부됩니다:

필드	타입	필수 여부	설명
prompt	string	필수	장르, 편성, 분위기, 템포를 설명하세요. 더 구체적일수록 결과가 더 일관적입니다.
seed	integer	선택	최솟값은 0입니다. 동일한 prompt와 동일한 seed를 재사용하면 더 재현 가능한 결과를 얻을 수 있습니다.

prompt는 필수입니다. 생략하면 작업이 아예 생성되지 않습니다:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}

그 외의 필드——duration, negative_prompt, sample_count 및 일부 다른 음악 모델이 허용하는 유사한 필드——를 보내면 요청이 즉시 거부됩니다:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: <root>: additional properties 'negative_prompt' not allowed"}

출력 트랙의 길이는 모델 자체에서 고정되며, 이를 설정할 수 있는 duration 파라미터는 없습니다.

프로덕션 환경 고려 사항

폴링보다 콜백이 좋습니다. 빠른 테스트를 제외하고는 루프에서 폴링하는 대신 최상위 callback을 전달하세요:

{
  "model": "lyria-3-pro",
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" },
  "input": { "prompt": "..." }
}

작업이 최종 상태(success 또는 fail)에 도달하면 hiapi가 callback.url로 POST를 한 번 전송합니다. 폴링 루프를 계속 열어둘 필요가 없습니다. 다만 콜백 전달이 실패할 경우를 대비해 폴링은 여전히 폴백으로 유지하세요.

멱등성. 호출자가 동일한 요청을 재시도할 가능성이 있다면 Idempotency-Key 헤더(최대 255바이트)를 보내세요. 동일한 계정에서 동일한 key로 재시도하면 중복 트랙을 생성(및 과금)하지 않고 원래 taskId를 반환합니다.

출력을 7일 이상 보관하기. 출력 스토리지는 기본적으로 temp(약 7일)입니다. 생성 시 최상위 "storage": "persistent"를 설정하면 트랙을 장기 보관할 수 있으며(용량 기준 과금), 또는 나중에 temp 출력을 승격할 수도 있습니다.

오류 처리. 잘못되었거나 권한이 없는 key는 HTTP 401을 반환합니다:

{"error":{"code":"permission_denied","message":"This API key cannot use the selected model. Please check permissions or use another key.","type":"hiapi_error"}}

형식이 잘못된 입력은 error_code: INVALID_REQUEST와 함께 400을 반환하고(위 참조), 잔액 부족은 402, JSON이 아닌 Content-Type은 415를 반환합니다. 간헐적인 503이 발생하면 백오프 후 재시도하세요. 이는 요청에 문제가 있다는 것이 아니라 플랫폼이 일시적으로 사용 불가함을 의미합니다.

lyria-3-pro(및 플랫폼의 다른 모든 모델)의 가격은 요금제가 변경될 수 있으므로 여기에 하드코딩하지 않고 hiapi 가격 페이지에 명시되어 있습니다.

관련 리소스

• lyria-3-pro 모델 참조 — 해당 모델의 가격 및 플레이그라운드.
• 작업 생성 / 작업 상세 조회(통합 비동기 API) — hiapi의 모든 모델이 사용하는 공통 요청/응답 계약.
• minimax-music-3 API: curl 및 Python 가이드 — 출력 스타일을 비교해 볼 수 있는 또 다른 텍스트-투-뮤직 모델.
• MiniMax Music API(minimax-music-1.5) 사용 방법 — 비용/품질 비교에 적합한 이전 MiniMax 음악 생성 모델.

자주 묻는 질문

생성되는 트랙의 길이를 설정할 수 있나요? 아니요. lyria-3-pro의 input 스키마는 prompt와 seed만 허용하며, duration 필드가 없고 트랙 길이는 모델이 자체적으로 결정합니다.

lyria-3-pro는 네거티브 프롬프트나 스타일 참조 오디오를 지원하나요? 아니요. 플랫폼의 다른 일부 모델과 달리 lyria-3-pro의 스키마는 엄격히 prompt와 seed로만 제한됩니다. negative_prompt나 참조 오디오 필드를 보내면 400 INVALID_REQUEST가 반환됩니다.

출력 파일은 어떤 형식인가요? MP3이며, output[0].url로 반환되고 type은 "audio"입니다. 해당 URL은 임시 링크로, "storage": "persistent"를 설정하지 않으면 output[0].expireAt에 따라 만료됩니다.

재현 가능한 결과를 얻으려면 어떻게 해야 하나요? 동일한 prompt를 사용하고 동일한 seed(음이 아닌 정수)를 전달하세요. seed를 생략하면 호출할 때마다 다른 결과가 나올 수 있습니다.

계속해서 400을 반환하는 요청을 디버깅하는 가장 빠른 방법은 무엇인가요? message를 읽으세요. 어떤 필드가 누락되었거나 유효하지 않은지 정확히 알려줍니다. 이 스키마는 엄격합니다. 이 모델이 허용하지 않는 필드(예: 플랫폼의 다른 음악 모델이 실제로 허용하는 duration)를 보내면 "additional properties not allowed" 오류와 함께 400이 반환됩니다.