Как использовать lyria-3.5 через hiapi API: curl, Python и рабочий запрос

lyria-3.5 — это модель hiapi для генерации музыки по тексту: отправьте описание музыки, текст песни или и то и другое, и получите готовый трек — с возможностью указать название, ориентир по темпу и управление длительностью. В этом руководстве полностью разобраны входная schema, запрос, возвращающий реальный трек, и детали, необходимые для вывода в продакшен после разового тестирования.

Что вам понадобится

• API-ключ hiapi. Получить можно в dashboard — ключ начинается с sk-.
• curl или Python-библиотека requests. SDK не нужен; hiapi использует чистый REST.

lyria-3.5 работает на унифицированном асинхронном API задач hiapi: вы отправляете задачу через POST, сразу получаете taskId, а затем опрашиваете результат или получаете callback, когда трек будет готов.

Полная входная schema

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). Кроме того, schema строгая: любое поле, отсутствующее в таблице выше (duration, style, genre, negative_prompt и т. п.), вернёт 400 с additional properties '...' not allowed.

Минимальный рабочий пример

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, а в data.error будет { code, message } вместо output.

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 вместо опроса. Добавьте объект верхнего уровня callback: {"url": "https://yourapp.com/hook", "when": "final"}. when принимает только "final" — вы получите один вызов, когда задача достигнет терминального состояния, а не обновления о прогрессе.
• Идемпотентность. API задач не принимает идемпотентные ключи от клиента, поэтому предотвращайте проблемы с повторами на уровне приложения: сохраняйте taskId сразу после получения и проверяйте статус задачи перед повтором, чтобы не отправлять дублирующиеся запросы.
• Ошибки. Отсутствующий или недействительный API-ключ вернёт HTTP 401 и error_code: "permission_denied". Нарушение schema вернёт HTTP 400 и error_code: "INVALID_REQUEST", а в сообщении будет указано проблемное поле — это помогает выявить лишний duration или числовой bpm ещё до запуска в продакшен.
• Хранение. После успешного опроса или получения callback немедленно перенесите output[0].url в своё хранилище; не полагайтесь на уровень temp дольше его expireAt.

См. также

• Руководство по API lyria-3-pro — другая модель Lyria на hiapi; если вам не нужны текст песни или управление темпом, её schema проще и требует только 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? Schema строгая — вы получите 400 и additional properties '<field>' not allowed, а не молчаливое игнорирование поля.