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

lyria-3-pro — это модель генерации музыки, доступная через API hiapi: отправьте текстовый промпт и получите готовую звуковую дорожку. Это руководство проведёт вас по реальному сценарию запроса, который действительно возвращает taskId, объяснит полную (очень короткую) схему входных данных и расскажет о деталях для продакшена, которые понадобятся после того, как вы закончите с разовыми тестами.

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

• Ключ API hiapi. Его можно получить в консоли — ключ начинается с sk-.
• curl или Python-библиотека requests. SDK не требуется: hiapi использует стандартный REST.

lyria-3-pro работает на едином асинхронном API задач hiapi: вы выполняете 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 содержит { 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-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. Повторное использование одного и того же seed с тем же prompt даёт более воспроизводимый результат.

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 отправляет один POST на callback.url — держать цикл опроса включённым не нужно. Всё же сохраняйте опрос как запасной вариант на случай, если доставка колбэка не удастся.

Идемпотентность. Если вызывающая сторона может повторить тот же запрос, отправьте заголовок Idempotency-Key (до 255 байт) — повтор с тем же ключом в рамках одной учётной записи вернёт исходный taskId, а не создаст (и не спишет оплату за) дублирующую дорожку.

Хранение результатов дольше 7 дней. По умолчанию результаты хранятся в temp (около 7 дней). Установите "storage": "persistent" верхнего уровня при создании, чтобы сохранить дорожку надолго (оплата по размеру), или переведите temp-результат на более высокий уровень позже.

Обработка ошибок. Ошибочный или неавторизованный ключ возвращает 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"}}

Некорректные входные данные возвращают 400 с error_code: INVALID_REQUEST (как показано выше); недостаточный баланс возвращает 402; не-JSON Content-Type возвращает 415. При периодических 503 повторяйте с экспоненциальной задержкой — это означает временную недоступность платформы, а не ошибку в вашем запросе.

Цены lyria-3-pro (как и всех остальных моделей на платформе) указаны на странице цен hiapi, а не захардкожены здесь, поскольку тарифы могут меняться.

Связанные ресурсы

• Справочник по модели lyria-3-pro — цены и песочница для этой модели.
• Создание задачи / получение деталей задачи (единый асинхронный API) — общий контракт запроса/ответа, используемый каждой моделью на hiapi.
• API minimax-music-3: руководство по curl и Python — ещё одна модель текст-в-музыку, с которой можно сравнить стиль вывода.
• Как использовать MiniMax Music API (minimax-music-1.5) — более ранняя модель генерации музыки MiniMax, подходит для сравнения стоимости и качества.

Часто задаваемые вопросы

Можно ли задать длительность генерируемой дорожки? Нет. Схема input для lyria-3-pro принимает только prompt и seed — поля duration нет, длительность дорожки определяет сама модель.

Поддерживает ли lyria-3-pro негативные промпты или аудио-референсы стиля? Нет. В отличие от некоторых других моделей на платформе, схема lyria-3-pro строго ограничена prompt и seed; отправка negative_prompt или любого поля с аудио-референсом вернёт 400 INVALID_REQUEST.

В каком формате выходной файл? MP3, возвращается в output[0].url с type равным "audio". Этот URL — временная ссылка, которая истекает согласно output[0].expireAt, если не задано "storage": "persistent".

Как получить воспроизводимые результаты? Используйте тот же prompt и передавайте тот же seed (неотрицательное целое число). Если seed не указан, каждый вызов может давать разный результат.

Как быстрее всего отладить запрос, который постоянно возвращает 400? Прочитайте message — там указано конкретное отсутствующее или недопустимое поле. Схема строгая: отправка полей, которые не принимает эта модель (например, duration, который действительно принимают другие музыкальные модели на платформе), вернёт 400 с ошибкой "additional properties not allowed".