hiapi API로 lyria-3.5 사용하는 방법: curl, Python 및 실제로 동작하는 요청

lyria-3.5는 hiapi의 텍스트-투-뮤직 모델입니다. 음악 설명, 가사 또는 둘 다 보내면 완성된 트랙을 얻을 수 있으며, 선택적으로 제목, 템포 가이드, 길이 제어를 지정할 수 있습니다. 이 가이드에서는 입력 스키마, 실제 트랙을 반환하는 요청, 그리고 일회성 테스트 후 프로덕션에 투입하기 위해 필요한 세부 사항을 모두 설명합니다.

준비물

• hiapi API key. dashboard에서 얻을 수 있습니다. key는 sk-로 시작합니다.
• curl 또는 Python의 requests. SDK는 필요 없습니다. hiapi는 순수 REST를 사용합니다.

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

전체 입력 스키마

lyria-3.5는 단순한 prompt 하나보다 훨씬 많은 것을 받습니다. 최소한 prompt 또는 lyrics 중 하나를 반드시 제공해야 한다는 점을 제외하면 모든 필드는 선택 사항입니다:

필드	타입	설명
prompt	string	장르, 악기, 분위기, 보컬, 곡 구조. prompt 또는 lyrics를 제공하세요.
lyrics	string	한 줄에 한 문장씩. 섹션 태그 [Intro], [Verse], [Chorus], [Bridge], [Outro]는 각각 한 줄을 차지하고 그 뒤에 가사가 이어집니다. 반복되는 섹션은 [Verse 1], [Verse 2]처럼 번호를 매기세요.
title	string	생성되는 곡의 제목.
bpm	string	템포 가이드. 숫자문자열이어야 하며, 예: "90".
length	integer	요청 길이(초), 1–240. 길이를 유도하는 데 사용되며 실제 길이는 다를 수 있습니다. 생략하면 지정하지 않습니다.
seed	string	숫자 문자열 시드, 예: "00123". seed가 같아도 완전히 동일한 오디오가 보장되지는 않습니다.

미리 알려둘 두 가지가 있습니다. bpm과 seed는 숫자가 아니라 문자열입니다. 90이 아니라 "90"을 보내세요. 그렇지 않으면 API가 400(got number, want string)을 반환합니다. 그리고 스키마는 엄격합니다. 위 표에 없는 필드(duration, style, genre, negative_prompt 등)는 모두 additional properties '...' not allowed와 함께 400으로 반환됩니다.

최소 동작 예제

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.5",
    "input": {
      "prompt": "Warm instrumental indie folk, fingerpicked acoustic guitar, soft brushed drums, quiet morning",
      "bpm": "90",
      "length": 30
    }
  }'

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

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

2. 결과 폴링

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

첫 폴링 전에 몇 초 기다린 후, 이후 3–5초마다 확인하세요. status는 먼저 handling을 거친 뒤 종료 상태로 진입합니다. 다음은 위 요청을 보낸 약 100초 후의 실제 응답입니다:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M2HCSKAP77MTH1ANKQXE1DT2",
    "model": "lyria-3.5",
    "status": "success",
    "created": 1789437730,
    "completed": 1789437829,
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M2HCSKAP77MTH1ANKQXE1DT2-0.m4a",
        "expireAt": 1790042629
      }
    ]
  }
}

출력 컨테이너 형식은 요청에 따라 달라질 수 있습니다(여기서는 .m4a, hiapi의 다른 음악 모델은 .mp3 반환). 확장자를 하드코딩하지 말고 output[0].type/URL을 읽으세요. output[0].url은 즉시 다운로드하세요. 기본 temp 스토리지 계층은 약 7일 후 만료됩니다(expireAt은 Unix 타임스탬프). 실패 시 status는 fail이고, output 대신 data.error에 { 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.5",
    "input": {
        "title": "Carry the Morning",
        "lyrics": (
            "[Verse 1]\n"
            "Light through the window, coffee still warm\n"
            "[Chorus]\n"
            "Carry the morning, carry it slow\n"
        ),
        "bpm": "96",
        "length": 45,
    },
}

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

status = None
while status not in ("success", "fail"):
    time.sleep(4)
    poll = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS).json()
    status = poll["data"]["status"]

if status == "success":
    print(poll["data"]["output"][0]["url"])
else:
    print(poll["data"]["error"])

순수 음악을 원하는지 보컬 트랙을 원하는지에 따라 lyrics를 prompt로 바꾸세요(또는 둘 다 보내세요).

프로덕션 환경 고려 사항

• 폴링 대신 콜백 사용. 최상위 callback 객체를 추가하세요: {"url": "https://yourapp.com/hook", "when": "final"}. when은 "final"만 허용합니다. 작업이 종료 상태에 들어갈 때 진행 상황 업데이트가 아니라 한 번의 호출을 받습니다.
• 멱등성. 작업 API는 클라이언트 제공 멱등성 키를 받지 않으므로 애플리케이션 계층에서 재시도 문제를 방지해야 합니다: taskId를 받은 즉시 영속화하고, 재시도 전에 작업 상태를 확인하여 중복 요청을 보내지 마세요.
• 오류. API key가 없거나 유효하지 않으면 HTTP 401과 error_code: "permission_denied"가 반환됩니다. 스키마를 위반하면 HTTP 400과 error_code: "INVALID_REQUEST"가 반환되며, 메시지에 문제가 된 필드가 명시됩니다. 이는 프로덕션 진입 전에 불필요한 duration이나 숫자 타입의 bpm을 발견하는 데 도움이 됩니다.
• 스토리지. 성공적인 폴링이나 콜백 수신 후 즉시 output[0].url을 자체 스토리지로 옮기세요. temp 계층을 expireAt 이후까지 신뢰하지 마세요.

관련 글

• lyria-3-pro API 튜토리얼——hiapi의 또 다른 Lyria 모델로, 가사나 템포 제어가 필요 없다면 prompt만 필요한 더 간단한 스키마를 가집니다.
• MiniMax Music API 가이드——hiapi의 또 다른 텍스트-투-뮤직 모델로, 자체적인 가사 및 샘플링 옵션 세트를 가집니다.
• lyria-3.5 모델 레퍼런스——권위 있는 파라미터 문서.
• hiapi 가격——현재 모델별 요금.

FAQ

prompt와 lyrics를 모두 보내야 하나요?아니요. API는 둘 중 최소 하나만 요구합니다. prompt만 보내면 순수 음악 트랙을, lyrics만 보내면 가사가 전적으로 주도하는 트랙을, 또는 둘 다 함께 보낼 수 있습니다.

lyria-3.5는 어떤 오디오 형식을 반환하나요?요청에 따라 다릅니다. output[0].type과 URL의 확장자를 확인하세요. .mp3나 .m4a라고 가정하지 마세요.

정확한 템포를 강제할 수 있나요?bpm은 가이드일 뿐 강제 제약이 아니며, 반드시 문자열로 보내야 합니다(90이 아니라 "90").

생성되는 트랙은 얼마나 길 수 있나요?length는 1–240초를 허용하지만 모델을 유도할 뿐 정확한 길이를 보장하지는 않습니다. 반환된 파일의 실제 재생 길이를 확인하세요.

같은 seed를 쓰면 두 번 모두 같은 트랙을 얻나요?아니요. seed는 생성 결과를 미세 조정하는 숫자 문자열이지만, hiapi 문서는 오디오가 완전히 동일하다고 보장하지 않는다고 명시합니다.

genre나 duration처럼 인식되지 않는 필드를 보내면 어떻게 되나요?스키마는 엄격합니다. 해당 필드가 조용히 무시되는 것이 아니라 400과 additional properties '<field>' not allowed를 받게 됩니다.