Guia da API MiniMax H3: integração com PoYo, preços e prompts

Com a API MiniMax H3 do PoYo, você pode gerar vídeos 2K de 5–15 segundos a partir de texto, quadros inicial e final ou mídias de referência. Sem referências, um vídeo de 5 segundos tem custo estimado de 105 créditos ($0.525).

Este guia começa com sua primeira requisição e depois aborda preços, modos de entrada, exemplos em Python e Node.js e prompts para diferentes cenas. Todos os endpoints e preços apresentados se aplicam ao PoYo.

Início rápido: envie uma tarefa e obtenha o vídeo

1. Envie uma tarefa de vídeo de 5 segundos

Obtenha uma chave de API no console do PoYo, substitua YOUR_POYO_API_KEY abaixo e execute o comando em um terminal ou no servidor. Mantenha a chave no servidor; não a inclua no código do navegador nem em repositórios públicos.

Nas requisições ao PoYo, o valor de model para MiniMax H3 é hailuo-03. O exemplo a seguir envia uma tarefa de geração paga.

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"
    }
  }'

Após o envio bem-sucedido, leia o ID da tarefa em data.task_id. Este exemplo mostra a estrutura da resposta com um ID fictício:

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

2. Consulte o resultado da tarefa

Defina TASK_ID com o ID retornado e use a mesma chave de 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}"

Um envio bem-sucedido significa que a tarefa foi aceita; ainda é preciso esperar a geração terminar. O campo data.status da resposta de consulta pode ter quatro valores:

Veja um exemplo de resposta após a conclusão. A URL e a data são ilustrativas:

{
  "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
  }
}

Consulte as definições dos campos e os exemplos dos demais estados na documentação de consulta de tarefas do PoYo. Se uma consulta falhar temporariamente ou o período de espera terminar, mantenha o ID e consulte novamente mais tarde; não envie automaticamente outra geração paga.

Como funciona a cobrança do MiniMax H3 no PoYo

Os preços abaixo foram verificados em 21 de setembro de 2026. Todos os valores estão em USD, com 1 crédito = $0.005. Antes de gerar em lote, confirme os preços atuais na página do modelo.

Créditos estimados = 21 × (segundos de saída + segundos faturáveis de vídeo de referência) + 6.4 × número de imagens de referência além de 5. Com 5 imagens ou menos, o custo adicional de imagens é 0. Multiplique os créditos estimados por $0.005 para obter o custo em USD. Quando o vídeo de referência inclui frações de segundo, a cobrança usa a duração determinada pelo servidor.

O último exemplo usa 21 × (10 + 5) + 6.4 × (7 − 5). Esses custos são por geração; se uma tomada exigir várias tentativas, inclua cada geração no orçamento.

Escolha o modo de entrada e as referências

Os campos de mídia enviados determinam o modo de entrada. O exemplo de início rápido usa texto para vídeo. Adicione os campos correspondentes quando precisar definir quadros inicial e final ou usar referências.

Não combine image_urls com nenhum campo reference_*_urls. Todas as URLs de mídia devem ser públicas e permitir download direto.

Limites de parâmetros e mídias

Os limites a seguir vêm da documentação da API MiniMax H3 do PoYo:

• prompt é obrigatório e aceita até 2000 caracteres.
• duration é um inteiro de 5–15 segundos, com padrão 5; resolution aceita apenas 2K.
• Texto para vídeo aceita 21:9, 16:9, 4:3, 1:1, 3:4 e 9:16, com padrão 16:9. O modo de referência também aceita adaptive e o usa por padrão.
• Você pode enviar até 9 imagens, 3 vídeos e 3 clipes de áudio de referência. Cada vídeo ou áudio deve durar 2–15 segundos; a duração total dos vídeos e a dos áudios não podem exceder, separadamente, 15 segundos.

Exemplo de requisição com quadros inicial e final

Use o JSON abaixo como corpo de POST /api/generate/submit. As URLs em example.com são exemplos: substitua-as por suas próprias mídias disponíveis para download antes do envio. Para usar apenas um quadro inicial, remova a segunda URL do array.

{
  "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"
    ]
  }
}

Exemplo combinando referências de imagem e vídeo

Use Image 1 para definir a aparência do personagem e Video 1 para o movimento de câmera desejado. Eles correspondem ao primeiro item do array de imagens e do array de vídeos, respectivamente. Substitua as URLs e verifique a duração do vídeo de referência antes do envio.

{
  "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"
    ]
  }
}

Exemplos de integração em Python e Node.js

Os exemplos separam envio e consulta em duas funções: primeiro obtenha e salve o ID da tarefa, depois aguarde o resultado. Se a consulta for interrompida, retome-a com o ID original sem gerar novamente. Apenas as consultas de status repetem tentativas após erros de conexão, timeouts, HTTP 429 e determinados erros 5xx; o envio não é repetido automaticamente.

As duas implementações esperam 10 segundos entre consultas, fazem no máximo 60 consultas e definem um timeout de 30 segundos por requisição. A espera total também inclui a duração das requisições. Esses valores são configurações dos exemplos, não uma garantia de tempo de geração. Ajuste os intervalos e as tentativas às necessidades da aplicação.

Python: envie uma tarefa e consulte o resultado

Instale a dependência com python -m pip install requests e configure a variável de ambiente POYO_API_KEY como descrito acima. Este script Python síncrono consulta periodicamente uma tarefa de geração assíncrona.

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))

Para retomar a consulta, chame wait_for_h3(saved_task_id) diretamente. Erros HTTP como 401 e 403, erros da API ou respostas inesperadas interrompem as consultas; resolva a causa antes de continuar.

Node.js: use o fetch integrado

O JavaScript abaixo usa o fetch integrado ao Node.js 20 ou posterior, sem instalar uma dependência de cliente HTTP. Salve-o como arquivo .mjs e execute no servidor.

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));

Para retomar a consulta, substitua as chamadas de envio e consulta no fim do arquivo por waitForH3(savedTaskId). O exemplo é adequado para scripts ou tarefas em segundo plano. Em uma aplicação web, retorne o ID ao frontend e acompanhe a geração em segundo plano, sem manter uma requisição de página aguardando.

Receba resultados por webhook

Você também pode passar callback_url no nível superior da requisição de envio, ao lado de model e input, por exemplo https://your-domain.com/webhooks/poyo. O PoYo envia o resultado a essa URL quando a tarefa é concluída com sucesso ou falha.

O receptor deve conferir o ID com os registros locais e tratar notificações duplicadas pelo ID da tarefa, evitando repetir operações posteriores. Trabalhos demorados, como download ou transcodificação, podem ser executados em segundo plano. Durante a integração dos callbacks, você ainda pode consultar o status para verificar os resultados.

Prompts e exemplos de cenas

Descreva primeiro o sujeito e a ação; depois acrescente movimento de câmera, ambiente, iluminação e som. Ao usar referências, indique a função de Image 1, Video 1 ou Audio 1 para não atribuir requisitos conflitantes à mesma mídia.

Os quatro exemplos em inglês mostram como escrever prompts; não incluem resultados de geração testados. Os termos em inglês facilitam a reutilização, mas não significam que o inglês necessariamente funcione melhor que o chinês. Tempos e instruções para preservar a aparência descrevem objetivos; verifique o resultado real.

Anúncio de produto: 8 segundos, modo de imagem de referência

Coloque a imagem do produto como primeiro item de input.reference_image_urls, defina duration: 8 e aspect_ratio: "16:9" e use o texto abaixo como prompt. Siga a estrutura de requisição do modo de referência acima; remova reference_video_urls se não precisar de vídeo de referência.

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.

Comece com uma tomada simples para verificar se o frasco e o rótulo permanecem consistentes; depois experimente movimentos orbitais mais complexos.

Diálogo de personagem: 8 segundos, modo de imagem de referência

Coloque a imagem do personagem como primeiro item de input.reference_image_urls e defina duration: 8 e aspect_ratio: "16:9". Uma fala curta facilita verificar sincronização labial, velocidade da fala e aparência.

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.

Anúncio vertical de jogo: 10 segundos, texto para vídeo

Defina duration: 10 e aspect_ratio: "9:16". Os segmentos de tempo expressam a sequência desejada de ações; se a cena ficar sobrecarregada, comece reduzindo a quantidade de ações e personagens.

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.

Plano contínuo de acompanhamento: 10 segundos, texto para vídeo

Defina duration: 10 e aspect_ratio: "16:9". Organize a tomada em torno de um sujeito e um trajeto, depois verifique cortes, alterações no sujeito ou movimentos descontínuos.

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.

Perguntas frequentes e solução de problemas

Posso usar diretamente o formato de requisição da API da MiniMax?

Os exemplos usam POST /api/generate/submit e GET /api/generate/status/{task_id} do PoYo. Endpoints, identificadores de modelo e estruturas de campos podem variar entre plataformas; siga a documentação da plataforma utilizada.

Devo reenviar uma tarefa que permanece em not_started?

not_started significa que a tarefa aguarda processamento; não é, por si só, uma falha. Mantenha o ID e continue consultando. Se o limite de espera da aplicação for atingido, registre a tarefa e confira mais tarde. Se necessário, contate o suporte com o ID.

E se o envio expirar antes de eu receber um ID de tarefa?

Um timeout não comprova que o servidor deixou de aceitar a tarefa. Confira primeiro os registros; se necessário, contate o suporte com detalhes como o horário de envio. É preciso ter um ID para usar o endpoint de consulta de status. Não use o reenvio como solução para uma consulta que falhou.

Posso combinar imagens, vídeo e áudio como referências?

Sim, no modo de referência, respeitando os limites de quantidade e duração apresentados. Áudio de referência exige uma imagem ou um vídeo de referência. Esses campos não podem ser combinados com image_urls do modo de quadros inicial e final.

Quanto custa um vídeo de 10 segundos?

Com os preços indicados, sem referências, o custo é de 10 × 21 = 210 créditos, ou $1.05. Vídeos de referência e imagens além das primeiras 5 aumentam o custo.

Antes de integrar à aplicação, confirme que as URLs permitem download direto, salve os IDs e defina limites adequados de geração e concorrência por usuário. Antes de publicar um vídeo, verifique se aparência dos personagens, forma dos produtos, texto, movimento e som são adequados ao uso previsto.

Experimente a geração na página do modelo MiniMax H3 ou acesse a página de chaves de API para iniciar a integração. Para conhecer melhor os modelos, leia a análise do MiniMax H3 e a comparação entre MiniMax H3 e Seedance 2.5.