Как вызывать API mirelo-sfx-2.0 через HiAPI: curl, Python и асинхронный опрос

Возможности mirelo-sfx-2.0 и сценарии применения

mirelo-sfx-2.0 — это модель преобразования текста в звуковые эффекты, доступная через HiAPI. Вы передаёте ей описание на естественном языке — например, «тяжёлая деревянная дверь медленно скрипит, открываясь» или «монета падает на мраморный стол» — и она генерирует короткий аудиофрагмент, соответствующий подсказке.

Это тот самый эндпоинт, который стоит использовать, когда вам нужен звуковой дизайн по запросу, а не лицензирование из библиотек сэмплов:

• Прототипирование игр и приложений: генерация временных или финальных звуков для взаимодействий, событий UI и циклического окружения.
• Постпродакшн видео и подкастов: заполнение пустот аудио в стиле фоули без необходимости бронировать студию звукозаписи.
• Генеративные конвейеры: получение подсказок из сценариев, раскадровок или пользовательского ввода и прикрепление сгенерированного WAV к выходным данным.

Модель показывает лучшие результаты, когда описание звука чёткое, а длительность короткая. Если вам нужна музыка, речь или длинное аудио — это другая линейка моделей; mirelo-sfx-2.0 специализируется на дискретных звуковых эффектах.

Поскольку генерация асинхронна, планируйте интеграцию на основе задач, а не блокирующих HTTP-вызовов. Остальная часть этого руководства построит такую интеграцию — от сырого запроса curl до Python-клиента, который опрашивает статус и получает готовый WAV.

Предварительные требования и настройка аутентификации

Перед первым вызовом убедитесь, что у вас есть:

• Учётная запись HiAPI и API-ключ. Вы можете создавать и управлять ключами в консоли HiAPI. Обращайтесь с ключом как с паролем: загружайте его из переменных окружения или менеджера секретов и никогда не коммитьте в репозиторий кода.
• Инструмент для отправки HTTP-запросов. Для этого руководства достаточно curl; примеры кода используют Python 3.8+.
• HTTP-клиент для Python. Примеры для краткости используют requests, но подойдёт любой клиент, умеющий отправлять JSON и заголовки.

HiAPI использует единый базовый URL и единый способ аутентификации для всех моделей, поэтому соглашения, которые вы здесь освоите, применимы и к другим эндпоинтам:

export HIAPI_API_KEY="your-api-key-here"

Каждый запрос отправляет ключ в заголовке Authorization:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Идентификатор модели передаётся в теле запроса через "model": "mirelo-sfx-2.0". Отдельный SDK устанавливать не нужно — если ваш HTTP-клиент может обращаться к базовому URL HiAPI, он может вызывать эту модель.

Практический совет: храните базовый URL в конфигурационной переменной, а не хардкодьте его в разных файлах. При переходе от локального скрипта к стейджингу или продакшн-сервису вы захотите менять его в одном месте.

Пошаговый разбор запроса curl

Запрос на генерацию — это аутентифицированный HTTP POST к эндпоинту создания задачи HiAPI. Вот полный вызов:

curl -sS -X POST "$HIAPI_BASE_URL/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mirelo-sfx-2.0",
    "input": {
      "prompt": "heavy wooden door creaking open slowly, old house ambience"
    }
  }'

Разбор по частям:

• -X POST — создание задачи является операцией записи. Использование GET для этого пути не запустит задачу.
• URL — этот эндпоинт принимает новые задачи генерации. Базовый URL хранится в HIAPI_BASE_URL, поэтому одна и та же команда работает в любом окружении.
• Authorization — bearer-токен идентифицирует вашу учётную запись и служит основой для биллинга. Отсутствующий или неверно отформатированный заголовок — самая частая причина 401.
• Content-Type: application/json — тело запроса является JSON; без этого заголовка сервер отклонит или неправильно распарсит полезную нагрузку.
• model — выбирает mirelo-sfx-2.0. Поскольку HiAPI маршрутизирует на основе этого поля, вы можете переключать модели без изменения URL.
• input.prompt — текстовое описание звука. Конкретные, физические описания (материал, действие, окружение) дают лучшие результаты, чем абстрактные.

Успешная отправка не возвращает аудио. Она возвращает объект задачи с идентификатором (обычно поле id), который вы используете для проверки статуса. Захватите этот ID из ответа; это ваш ключ к последующему получению WAV.

Если вы хотите подтвердить структуру запроса перед интеграцией в код, сначала выполните эту точную команду в терминале. Как только она сработает, преобразование в Python станет механической работой.

Тот же вызов на Python

Python-версия сохраняет тот же URL, заголовки и тело запроса — просто представляет их в виде словарей и вызова клиента:

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]

def create_sfx_task(prompt: str) -> str:
    response = requests.post(
        f"{BASE_URL}/v1/tasks",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model": "mirelo-sfx-2.0",
            "input": {"prompt": prompt},
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["id"]

Отличия от shell-версии:

• Доступ к окружению — os.environ заменяет раскрытие shell, поэтому ключ никогда не появляется в исходном коде.
• json= вместо -d — requests сериализует словарь за вас и устанавливает тип содержимого. Вы можете убрать ручной заголовок, хотя оставить его тоже можно.
• raise_for_status() — превращает не-2xx ответы в исключения; обработку ошибок следует размещать здесь.
• timeout — тайм-аут клиента предотвращает зависание рабочего процесса из-за застрявшего соединения. Создание задачи выполняется быстро; долгое ожидание происходит во время опроса.

Возвращаемое значение — ID задачи. Сохраните его — это ваш единственный дескриптор для данной генерации. На этом пути Python и curl сходятся: обоим нужен шаг опроса, прежде чем аудио будет доступно.

Поскольку тело запроса — это просто данные, вы можете параметризовать подсказку и перебирать список описаний для пакетной генерации звуковых эффектов, создавая задачу для каждой подсказки и собирая ID.

Работа с асинхронными задачами и опрос результатов

Генерация звука требует времени — секунды, а не миллисекунды — поэтому HiAPI моделирует её как задачу. Вызов создания немедленно возвращает ID; второй эндпоинт сообщает, выполняется ли задача, завершена или завершилась ошибкой.

Типичный цикл:

1. Создайте задачу и захватите ID.
2. Опрашивайте эндпоинт статуса задачи с этим ID.
3. Если статус всё ещё «обрабатывается», подождите немного и опросите снова.
4. Когда статус сообщает об успехе, прочитайте вывод из ответа.
5. Если статус сообщает об ошибке, остановитесь и выбросьте исключение.

На Python:

import time

def wait_for_task(task_id: str, timeout_s: int = 300) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/v1/tasks/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()

        status = task.get("status")
        if status == "succeeded":
            return task
        if status == "failed":
            raise RuntimeError(task.get("error", "task failed"))

        time.sleep(2)

    raise TimeoutError(f"task {task_id} did not finish in time")

Несколько моментов стоит подчеркнуть:

• Интервал опроса. Две секунды — разумное значение по умолчанию для звуковых эффектов. Плотный цикл опроса тратит квоту и может вызвать ограничение скорости, не приближая результат.
• Общий дедлайн. Всегда устанавливайте верхнюю границу для цикла. Застрявшая задача должна приводить к ошибке вашей программы, а не к вечному зависанию рабочего процесса.
• Значения статуса. Считайте неизвестные значения статуса «всё ещё обрабатывается», а не предполагайте успех, и явно ветвитесь по статусам успеха и ошибки.
• Webhook (если доступны). Если ваша учётная запись HiAPI поддерживает колбэки завершения, в серверном продакшн-коде предпочитайте их опросу; для скриптов и прототипов опрос остаётся самым простым вариантом.

Сохраняйте ID задачи вместе с подсказкой в собственной базе данных, чтобы позже можно было повторить, провести аудит или повторно получить вывод без повторной генерации.

Чтение возвращённого WAV-ответа

Когда задача сообщает об успехе, ответ содержит сгенерированное аудио. В зависимости от версии эндпоинта вывод может быть в виде URL WAV-файла или встроенных аудиоданных; рассматривайте оба случая как «сохраняемые байты».

Успешный объект задачи несёт вывод в поле вроде output, обычно вместе с метаданными, такими как имя модели, исходная подсказка и информация о времени. Само аудио — стандартный контейнер WAV, что означает, что вы можете передать его любой аудиотеке без специального декодера.

Чтобы сохранить результат на основе URL:

result = wait_for_task(task_id)
audio_url = result["output"]["audio_url"]

wav_bytes = requests.get(audio_url, timeout=60).content
with open(f"{task_id}.wav", "wb") as f:
    f.write(wav_bytes)

Если аудио приходит в виде декодированных данных, выполните base64-декодирование перед записью:

import base64

wav_bytes = base64.b64decode(result["output"]["audio_base64"])
with open(f"{task_id}.wav", "wb") as f:
    f.write(wav_bytes)

Получив байты:

• Проверьте заголовок файла. WAV-файлы начинаются с магического числа RIFF. Проверка первых четырёх байтов позволяет обнаружить усечённую загрузку до того, как она попадёт в хранилище.
• Постоянное хранение. Записывайте в объектное хранилище и сохраняйте ключ вместе с ID задачи в базе данных. Рассматривайте сгенерированное аудио как кэшируемый артефакт, а не временный ответ.
• Воспроизведение или обработка. Стандартные инструменты — wave, soundfile или любой аудиоплеер — могут открыть файл напрямую. Затем можно обрезать тишину, нормализовать громкость или конвертировать в другой формат для доставки.

Поскольку файл — обычный WAV, его подключение к веб-эндпоинту или конвейеру ассетов игрового движка не требует специальной обработки.

Частые точки отказа и способы их устранения

Большинство проблем интеграции попадают в несколько предсказуемых категорий.

Ошибки аутентификации (401 / 403)

401 почти всегда означает, что заголовок Authorization отсутствует, неверно отформатирован или построен из пустой переменной окружения. Убедитесь, что HIAPI_API_KEY экспортирован в shell, где работает процесс — а не только в редакторе — и что заголовок читается как Bearer <key> с одним пробелом посередине. 403 обычно означает, что ключ действителен, но не имеет доступа к этой модели; проверьте права вашей учётной записи на модель.

Некорректная полезная нагрузка (400 / 422)

Самая частая причина — тело запроса не является валидным JSON; типичный пример — непарные кавычки в команде curl. Проверьте с помощью JSON-валидатора перед отправкой. Вторая по частоте причина — отсутствие поля model или неправильный уровень вложенности подсказки; модель ожидает input.prompt, а не prompt верхнего уровня. Наконец, проверьте, что подсказка не пуста и её длина в пределах ограничений, указанных в документации модели.

Слишком частый опрос

Плотный цикл while без сна генерирует массу запросов статуса, может вызвать ограничение скорости и замедлить задачу, которую вы ждёте. Используйте фиксированный интервал в одну-две секунды, добавляйте джиттер при параллельном запуске нескольких задач и всегда задавайте максимальное время ожидания.

Восприятие создания как завершения

Ответ на создание выглядит как успех и возвращает 200, но не содержит аудио. Если ваш код сразу читает поле output, он либо потерпит неудачу, либо запишет пустой файл. Всегда проходите через эндпоинт статуса, прежде чем обращаться к результату.

Тихие тайм-ауты и повторные попытки

Повтор при сетевом тайм-ауте во время создания задачи безопасен, но повторный вызов создания после тайм-аута, когда задача на самом деле уже создана, породит дублирующую задачу. Если эндпоинт поддерживает ключи идемпотентности, используйте их; в противном случае перед повтором проверьте список последних задач.

Краевые случаи диска и хранилища

При записи байтов WAV открывайте файл в бинарном режиме ("wb"). Текстовый режим повредит заголовок файла. Если вы сохраняете вывод по имени подсказки, две задачи с одинаковой подсказкой перезапишут друг друга — используйте ID задачи в качестве ключа файла.

С этими мерами предосторожности интеграция mirelo-sfx-2.0 представляет собой короткий конвейер: создать, опросить, сохранить. Начните с вызова curl, перенесите в Python и используйте ID задачи как источник истины.