API MiniMax H3: интеграция с PoYo, цены и промпты

С помощью API MiniMax H3 от PoYo можно создавать видео 2K длительностью 5–15 секунд по тексту, начальному и конечному кадрам или референсам. Без референсов примерная стоимость видео на 5 секунд составляет 105 кредитов ($0.525).

Руководство начинается с первого запроса, затем рассматриваются цены, режимы ввода, примеры на Python и Node.js и промпты для разных сцен. Все указанные эндпоинты и цены относятся к PoYo.

Быстрый старт: отправка задачи и получение видео

1. Отправьте задачу на создание видео длительностью 5 секунд

Получите API-ключ в консоли PoYo, замените YOUR_POYO_API_KEY ниже и выполните команду в терминале или на сервере. Храните ключ на сервере, не добавляйте его в браузерный код или публичные репозитории.

В запросах PoYo значение model для MiniMax H3 — hailuo-03. Следующий пример отправляет платную задачу генерации.

export POYO_API_KEY="YOUR_POYO_API_KEY"

curl --fail-with-body --max-time 30 \
  --request POST 'https://api.poyo.ai/api/generate/submit' \
  --header "Authorization: Bearer ${POYO_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "hailuo-03",
    "input": {
      "prompt": "A golden retriever walks through a sunlit autumn park. One slow tracking shot, natural movement, warm afternoon light.",
      "duration": 5,
      "resolution": "2K",
      "aspect_ratio": "16:9"
    }
  }'

После успешной отправки прочитайте ID задачи из data.task_id. Ниже показана структура ответа с условным ID:

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "YOUR_TASK_ID"
  }
}

2. Запросите результат задачи

Запишите полученный ID в TASK_ID и используйте тот же API-ключ:

TASK_ID="YOUR_TASK_ID"

curl --fail-with-body --max-time 30 \
  --request GET "https://api.poyo.ai/api/generate/status/${TASK_ID}" \
  --header "Authorization: Bearer ${POYO_API_KEY}"

Успешная отправка означает, что задача принята; завершения генерации ещё нужно дождаться. Поле data.status в ответе на запрос состояния принимает четыре значения:

Ниже приведён пример ответа после завершения. URL и время указаны для иллюстрации:

{
  "code": 200,
  "data": {
    "task_id": "YOUR_TASK_ID",
    "status": "finished",
    "credits_amount": 105,
    "files": [
      {
        "file_url": "https://example.com/generated/video.mp4",
        "file_type": "video"
      }
    ],
    "created_time": "2026-09-22T08:30:00",
    "progress": 100,
    "error_message": null
  }
}

Описание полей и примеры других состояний доступны в документации PoYo по проверке задач. Если запрос временно не удался или срок ожидания истёк, сохраните ID и проверьте задачу позже; не отправляйте автоматически новую платную генерацию.

Как рассчитывается стоимость MiniMax H3 в PoYo

Цены ниже проверены 21 сентября 2026 года. Все суммы указаны в долларах США, из расчёта 1 кредит = $0.005. Перед массовой генерацией уточните актуальные цены на странице модели.

Оценка в кредитах = 21 × (секунды результата + оплачиваемые секунды референсного видео) + 6.4 × число референсных изображений сверх 5. При 5 изображениях или меньше доплата за них равна 0. Умножьте оценку в кредитах на $0.005, чтобы получить стоимость в USD. Если длительность референсного видео содержит доли секунды, используется длительность, определённая сервером для расчёта оплаты.

Последний пример рассчитывается как 21 × (10 + 5) + 6.4 × (7 − 5). Это стоимость одной генерации. Если для кадра требуется несколько попыток, учитывайте каждую в бюджете.

Выбор режима ввода и референсов

Режим ввода определяется переданными полями медиа. Пример быстрого старта использует генерацию по тексту. Добавьте соответствующие поля, если нужно задать начальный и конечный кадры или использовать референсы.

Не сочетайте image_urls с полями reference_*_urls. Все URL медиа должны быть общедоступными и допускать прямое скачивание.

Ограничения параметров и медиа

Следующие ограничения взяты из документации API MiniMax H3 от PoYo:

• prompt обязателен и допускает до 2000 символов.
• duration — целое число от 5 до 15 секунд, по умолчанию 5; resolution поддерживает только 2K.
• Генерация по тексту поддерживает 21:9, 16:9, 4:3, 1:1, 3:4 и 9:16, по умолчанию 16:9. Режим референсов также поддерживает adaptive и использует его по умолчанию.
• Можно передать до 9 референсных изображений, 3 видео и 3 аудиофрагментов. Каждый видео- или аудиофрагмент должен длиться 2–15 секунд; суммарная длительность видео и суммарная длительность аудио не должны превышать 15 секунд каждая.

Пример запроса с начальным и конечным кадрами

Используйте JSON ниже как тело POST /api/generate/submit. URL медиа на example.com — заглушки: перед отправкой замените их своими доступными для скачивания материалами. Для использования только начального кадра удалите второй URL из массива.

{
  "model": "hailuo-03",
  "input": {
    "prompt": "The camera slowly moves through the temple doorway, starting at the entrance and ending inside the hall. Dust floats in the sunlight.",
    "duration": 6,
    "resolution": "2K",
    "image_urls": [
      "https://example.com/assets/temple-entrance.jpg",
      "https://example.com/assets/temple-interior.jpg"
    ]
  }
}

Пример сочетания изображения и видео в качестве референсов

Укажите Image 1 для внешности персонажа и Video 1 для желаемого движения камеры. Они обозначают первый элемент массива изображений и массива видео соответственно. Перед отправкой замените URL и проверьте длительность референсного видео.

{
  "model": "hailuo-03",
  "input": {
    "prompt": "Use Image 1 for the character appearance and outfit. The character turns and walks toward the window. Use Video 1 as the camera movement reference.",
    "duration": 8,
    "resolution": "2K",
    "aspect_ratio": "adaptive",
    "reference_image_urls": [
      "https://example.com/assets/character.png"
    ],
    "reference_video_urls": [
      "https://example.com/assets/camera-motion.mp4"
    ]
  }
}

Примеры интеграции на Python и Node.js

В примерах отправка и проверка разделены на две функции: сначала получите и сохраните ID задачи, затем ожидайте результат. Если проверка прервётся, её можно продолжить с исходным ID без повторной генерации. Только запросы состояния повторяются при ошибках соединения, тайм-аутах, HTTP 429 и некоторых ошибках 5xx; отправка автоматически не повторяется.

Обе реализации ждут 10 секунд между проверками, выполняют не более 60 проверок и задают тайм-аут 30 секунд на запрос. Поэтому общее ожидание включает и время выполнения запросов. Это настройки приложения в примерах, а не гарантия длительности генерации. Меняйте интервалы и правила повторов с учётом требований приложения.

Python: отправка задачи и опрос результата

Установите зависимость командой python -m pip install requests и задайте переменную окружения POYO_API_KEY, как описано выше. Этот синхронный скрипт Python опрашивает асинхронную задачу генерации.

import os
import time
import requests

BASE_URL = "https://api.poyo.ai"
API_KEY = os.environ["POYO_API_KEY"]
if not API_KEY.strip():
    raise ValueError("Set POYO_API_KEY")
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
RETRYABLE_HTTP = {429, 500, 502, 503, 504}


def response_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200 or not isinstance(body.get("data"), dict):
        raise RuntimeError(f"Unexpected API response: {body}")
    return body["data"]


def submit_h3(prompt, duration=5):
    response = requests.post(
        f"{BASE_URL}/api/generate/submit",
        headers=HEADERS,
        json={"model": "hailuo-03", "input": {
            "prompt": prompt, "duration": duration,
            "resolution": "2K", "aspect_ratio": "16:9",
        }},
        timeout=30,
    )
    task_id = response_data(response).get("task_id")
    if not isinstance(task_id, str) or not task_id:
        raise RuntimeError("Submission response is missing a task ID; check records instead of resubmitting automatically")
    return task_id


def wait_for_h3(task_id, max_polls=60):
    for _ in range(max_polls):
        time.sleep(10)
        try:
            response = requests.get(
                f"{BASE_URL}/api/generate/status/{task_id}",
                headers=HEADERS, timeout=30,
            )
        except (requests.Timeout, requests.ConnectionError):
            continue
        if response.status_code in RETRYABLE_HTTP:
            continue
        task = response_data(response)
        status = task.get("status")
        if status == "finished":
            for item in task.get("files") or []:
                if item.get("file_type") == "video" and item.get("file_url"):
                    return item["file_url"]
            raise RuntimeError(f"Task {task_id} finished, but the response has no video URL")
        if status == "failed":
            raise RuntimeError(f"Task {task_id} failed: {task.get('error_message')}")
        if status not in {"not_started", "running"}:
            raise RuntimeError(f"Task {task_id} returned an unknown status: {status}")
    raise TimeoutError(f"Query limit reached; keep the task ID and query again later: {task_id}")


if __name__ == "__main__":
    task_id = submit_h3("A golden retriever walks through a sunlit autumn park.")
    # In your application, save task_id to the database here before polling.
    print(f"Task ID: {task_id}", flush=True)
    print(wait_for_h3(task_id))

Для возобновления проверки вызовите wait_for_h3(saved_task_id) напрямую. HTTP-ошибки, например 401 и 403, ошибки API и неожиданные ответы прекращают опрос; сначала устраните их причину.

Node.js: использование встроенного fetch

Следующий JavaScript использует встроенный fetch из Node.js 20 или новее, поэтому отдельный HTTP-клиент не нужен. Сохраните код в файл .mjs и запускайте на сервере.

const BASE_URL = 'https://api.poyo.ai';
const apiKey = process.env.POYO_API_KEY;
if (!apiKey?.trim()) throw new Error('Set POYO_API_KEY');
const headers = {
  Authorization: `Bearer ${apiKey}`,
  'Content-Type': 'application/json',
};
const retryableHttp = new Set([429, 500, 502, 503, 504]);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function responseData(response) {
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const body = await response.json();
  if (body.code !== 200 || !body.data || typeof body.data !== 'object') {
    throw new Error(`Unexpected API response: ${JSON.stringify(body)}`);
  }
  return body.data;
}

export async function submitH3(prompt, duration = 5) {
  const response = await fetch(`${BASE_URL}/api/generate/submit`, {
    method: 'POST', headers,
    body: JSON.stringify({
      model: 'hailuo-03',
      input: { prompt, duration, resolution: '2K', aspect_ratio: '16:9' },
    }),
    signal: AbortSignal.timeout(30_000),
  });
  const data = await responseData(response);
  if (typeof data.task_id !== 'string' || !data.task_id) {
    throw new Error('Submission response is missing a task ID; check records instead of resubmitting automatically');
  }
  return data.task_id;
}

export async function waitForH3(taskId, maxPolls = 60) {
  for (let attempt = 0; attempt < maxPolls; attempt++) {
    await sleep(10_000);
    let response;
    try {
      response = await fetch(
        `${BASE_URL}/api/generate/status/${encodeURIComponent(taskId)}`,
        { headers, signal: AbortSignal.timeout(30_000) },
      );
    } catch (error) {
      if (error instanceof Error &&
          (error.name === 'TimeoutError' || error.name === 'TypeError')) {
        continue;
      }
      throw error;
    }
    if (retryableHttp.has(response.status)) {
      await response.body?.cancel();
      continue;
    }
    const task = await responseData(response);
    if (task.status === 'finished') {
      const video = task.files?.find((file) => file.file_type === 'video' && file.file_url);
      if (!video) throw new Error(`Task ${taskId} finished, but the response has no video URL`);
      return video.file_url;
    }
    if (task.status === 'failed') {
      throw new Error(`Task ${taskId} failed: ${task.error_message || 'No error details provided'}`);
    }
    if (!['not_started', 'running'].includes(task.status)) {
      throw new Error(`Task ${taskId} returned an unknown status: ${task.status}`);
    }
  }
  throw new Error(`Query limit reached; keep the task ID and query again later: ${taskId}`);
}

const taskId = await submitH3('A golden retriever walks through a sunlit autumn park.');
// In your application, save taskId to the database here before polling.
console.log(`Task ID: ${taskId}`);
console.log(await waitForH3(taskId));

Для возобновления проверки замените вызовы отправки и опроса в конце файла на waitForH3(savedTaskId). Пример подходит для скриптов и фоновых задач. В веб-приложении возвращайте ID во frontend и отслеживайте генерацию в фоне, не удерживая запрос страницы в ожидании.

Получение результатов через webhook

Можно также передать callback_url на верхнем уровне запроса отправки, рядом с model и input, например https://your-domain.com/webhooks/poyo. PoYo отправит результат на этот URL при успешном завершении или сбое задачи.

Получатель должен сверять ID с локальными записями и обрабатывать повторные уведомления по ID задачи, чтобы не выполнять последующие операции повторно. Скачивание и перекодирование видео можно перенести в фон. Во время интеграции callback можно по-прежнему проверять результаты через запросы состояния.

Промпты и примеры сцен

Сначала опишите субъект и действие, затем движение камеры, окружение, свет и звук. При использовании референсов укажите роль Image 1, Video 1 или Audio 1, чтобы один материал не задавал противоречивые требования.

Четыре примера на английском показывают, как составлять промпты; проверенные результаты генерации к ним не приложены. Английские термины удобны для повторного использования, но это не означает, что английский обязательно работает лучше китайского. Время и указания по сохранению внешности описывают желаемый результат; проверяйте фактический вывод.

Реклама продукта: 8 секунд, режим референсного изображения

Поместите изображение продукта первым в input.reference_image_urls, задайте duration: 8 и aspect_ratio: "16:9", а текст ниже используйте как prompt. Возьмите структуру запроса режима референсов выше; удалите reference_video_urls, если референсное видео не нужно.

Use Image 1 as the product reference. A clear glass perfume bottle rests on
wet black stone after rain. Preserve the bottle shape, cap, and label placement.
One continuous 8-second shot: begin close to the water droplets, then slowly
pull back to reveal the bottle in warm rim light. Realistic glass reflections,
no added text. Soft rain ambience.

Начните с простого плана, чтобы проверить стабильность флакона и этикетки, затем пробуйте более сложное движение камеры по орбите.

Диалог персонажа: 8 секунд, режим референсного изображения

Поместите изображение персонажа первым в input.reference_image_urls и задайте duration: 8 и aspect_ratio: "16:9". Короткая реплика упрощает проверку синхронизации губ, темпа речи и внешности.

Use Image 1 as the character reference. An 8-second medium close-up of a pastry
chef in a quiet kitchen at sunrise. She looks into the camera and says:
"Every detail matters in baking." Natural breathing, a subtle smile,
soft window light. Preserve her face, hairstyle, and apron. A steady camera,
clear speech, quiet room tone.

Вертикальная реклама игры: 10 секунд, видео по тексту

Задайте duration: 10 и aspect_ratio: "9:16". Временные интервалы передают желаемый порядок действий; если сцена перегружена, сначала сократите число действий и персонажей.

A 10-second vertical fantasy game trailer.
0-3s: An armored knight walks through a ruined stone gate.
3-6s: One creature charges; the knight blocks once with a shield.
6-9s: The camera rises to reveal the fortress walls.
9-10s: Hold the final composition.
Readable action, consistent armor, wind and impact sounds, no UI or captions.

Непрерывный следящий план: 10 секунд, видео по тексту

Задайте duration: 10 и aspect_ratio: "16:9". Постройте план вокруг одного субъекта и одного маршрута, затем проверьте, нет ли склеек, изменений субъекта или прерывистого движения.

One unbroken 10-second tracking shot follows a cyclist through a night market.
Begin behind the rear wheel, rise to shoulder height, then move alongside
without cutting. Wet pavement reflections, a clear path between stalls,
consistent bicycle geometry, no speed ramps or scene transitions.
Natural street ambience and bicycle tires rolling on wet pavement.

Частые вопросы и устранение проблем

Можно ли напрямую использовать формат запросов собственного API MiniMax?

Примеры используют эндпоинты PoYo POST /api/generate/submit и GET /api/generate/status/{task_id}. Адреса, идентификаторы моделей и структура полей могут различаться между платформами; следуйте документации той, которую используете.

Нужно ли повторно отправлять задачу, если она остаётся в not_started?

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

Что делать, если отправка завершилась по тайм-ауту до получения ID?

Тайм-аут не доказывает, что сервер не принял задачу. Сначала проверьте записи задач; при необходимости обратитесь в поддержку, указав, например, время отправки. Для запроса состояния нужен ID задачи. Не используйте повторную отправку как способ исправить неудачную проверку.

Можно ли сочетать изображения, видео и аудио как референсы?

Да, в режиме референсов с соблюдением указанных ограничений количества и длительности. Для аудиореференса требуется изображение или видео. Эти поля нельзя сочетать с image_urls режима начального и конечного кадров.

Сколько стоит видео на 10 секунд?

По указанным ценам, без референсов, стоимость составляет 10 × 21 = 210 кредитов, то есть $1.05. Референсные видео и изображения сверх первых 5 увеличивают стоимость.

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

Попробуйте генерацию на странице модели MiniMax H3 или перейдите на страницу API-ключей, чтобы начать интеграцию. Подробнее о моделях — в обзоре MiniMax H3 и сравнении MiniMax H3 с Seedance 2.5.