Guia de prompts do MiniMax H3: como criar movimentos de câmera cinematográficos pela API
Modelo alvo:
minimax-h3
Endpoint de inferência:https://api.toapis.com/v1/videos/generations
Relacionado: Guia da API MiniMax H3 · Escolha entre H3 e Turbo · Pipeline R2V automatizado
1. Resumo e visão geral de desempenho
- Trabalho: transformar uma lista de planos em prompts repetíveis do MiniMax H3 (sujeito, ação, trajetória de câmera, lente e iluminação) e enviá-los ao endpoint de gerações da ToAPIs.
- Arte do prompt: comece pela intenção de câmera e depois pelo sujeito. Combine uma frase direcional com uma distância focal (por exemplo 35 mm versus 85 mm) e uma indicação de iluminação.
- Contrato: o
minimax-h3base aceita clipes inteiros de 4–15 s. Useratio(16:9,9:16e as outras proporções listadas abaixo). Este é o contrato de requisição do frontend, não um benchmark de latência ou de qualidade. - Cuidado com a sintaxe: etiquetas entre colchetes são auxílios de prompt. Não trate
[Pan Left]como comando nativo documentado, a menos que a documentação do modelo upstream diga isso. - Protocolo: REST com Bearer. Envie uma única vez, guarde o identificador da tarefa e consulte o endpoint de status documentado com um prazo limitado.
2. Padrões de prompt para movimentos de câmera
Um prompt útil para o H3 descreve uma cena e uma ação principal antes de acrescentar direção de câmera, lente ou estilo. Mantenha essas partes estáveis quando fizer um teste A/B de modelo ou de duração; caso contrário, uma mudança de redação pode explicar uma tomada diferente.
As etiquetas da tabela abaixo são auxílios de prompt, não uma gramática de comandos garantida. O contrato do frontend da ToAPIs valida o prompt como texto (até 7.000 caracteres Unicode). Ele não confirma que strings como [Pan Left] sejam comandos nativos do H3. Use-as como vocabulário consistente nos seus modelos e depois revise a saída.
| Auxílio de prompt | Trajetória visual | Uso típico |
|---|---|---|
[Pan Left] / [Pan Right] | Rotação horizontal em um eixo fixo | Revelações de paisagem, varreduras de horizonte urbano |
[Tilt Up] / [Tilt Down] | Inclinação vertical a partir de uma posição fixa | Torres, sujeitos altos, revelações de céu |
[Dolly In] / [Dolly Out] | A câmera se aproxima ou se afasta do sujeito | Reforçar a ênfase emocional |
[Truck Left] / [Truck Right] | Movimento lateral de acompanhamento | Seguir ao lado de um veículo ou de alguém andando |
[Crane Shot] / [Pedestal Up] | Elevação vertical da câmera | Planos gerais em ângulo alto |
[Orbit 180] / [Arc Shot] | Movimento semicircular ao redor do sujeito | Giro de produto, revelação de herói |
[Hitchcock Zoom] | Dolly in enquanto faz zoom out (ou o contrário) | Choque psicológico, percepção súbita |

Figura 1: trate pan, tilt, dolly e órbita como trajetórias no espaço do prompt ao redor de um sujeito e depois envie uma única requisição de geração pelo gateway da ToAPIs.
Um modelo compacto que continua testável:
[CAMERA] SUBJECT and ACTION, LIGHTING, shot on LENS, STYLE NOTES
Exemplo: [Orbit 180 + Slow Dolly In] Matte black mechanical wristwatch resting on volcanic stone, moody low-key rim lighting, subtle steam haze, shot on 85mm macro lens, photorealistic, cinematic motion blur.
Para trabalhos de primeiro quadro (R2V), a mesma linguagem de prompt descreve como a câmera deve se mover ao redor da imagem âncora ou se afastar dela. Consulte o tutorial do pipeline R2V para ver os campos da requisição. Entradas de quadro e mídia de referência continuam sendo modos mutuamente exclusivos.
Os valores de ratio aceitos no frontend atual são adaptive, 21:9, 16:9, 4:3, 1:1, 3:4 e 9:16. Entradas de quadro forçam adaptive. Não envie aspect_ratio; o campo do contrato é ratio.
3. Implementação em produção: cURL e Python
Passo 1: envio com cURL
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3",
"prompt": "[Orbit 180 + Slow Dolly In] Matte black mechanical wristwatch resting on volcanic stone, moody low-key rim lighting, subtle steam haze, shot on 85mm macro lens, photorealistic, cinematic motion blur",
"duration": 6,
"ratio": "16:9"
}'
Passo 2: auxílio de prompt e sondagem em Python
Ajuste os nomes de campo e o envelope de resposta à referência da API da sua conta. O trecho abaixo usa o caminho de status de tarefa que também aparece em outros guias de vídeo da ToAPIs; confirme task_id, status e video_url contra esse esquema antes de publicar.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
ENDPOINT = "https://api.toapis.com/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def build_cinematic_prompt(
subject: str,
camera_move: str,
lighting: str,
lens: str = "35mm anamorphic",
) -> str:
return (
f"[{camera_move}] {subject}, {lighting}, "
f"shot on {lens}, photorealistic, cinematic motion blur."
)
def dispatch_camera_shot(prompt: str, duration: int = 6, ratio: str = "16:9") -> str:
payload = {
"model": "minimax-h3",
"prompt": prompt,
"duration": duration,
"ratio": ratio,
}
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("task_id") or data.get("id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 180) -> str:
poll_url = f"https://api.toapis.com/v1/videos/tasks/{task_id}"
interval = 3.0
start = time.time()
while time.time() - start < deadline_s:
time.sleep(interval)
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status in {"succeeded", "success"}:
return data["video_url"]
if status in {"failed", "error"}:
raise RuntimeError(f"Generation failed: {data.get('error')}")
interval = min(interval * 1.5, 8.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
prompt = build_cinematic_prompt(
subject="Matte black mechanical wristwatch resting on volcanic stone",
camera_move="Orbit 180 + Slow Dolly In",
lighting="Moody low-key rim lighting, subtle steam haze",
lens="85mm macro lens",
)
task_id = dispatch_camera_shot(prompt)
print("Task:", task_id)
print("Video:", poll_task(task_id))
Guarde a versão do modelo de prompt junto ao registro da tarefa, para distinguir uma mudança de modelo de uma mudança de redação. Um tempo esgotado no lado do cliente não prova que a tarefa upstream falhou; verifique o status antes de enviar um segundo trabalho faturável.
A duração do H3 base é um inteiro de 4 a 15 segundos. Os IDs da família Max começam em 5 segundos e têm suas próprias listas de resolução; o Turbo não aceita mídia de referência. Consulte o guia da API antes de trocar de ID.
4. Tratamento de erros e matriz de status
As categorias abaixo são pontos de partida para diagnóstico, não uma garantia dos códigos de erro exatos da ToAPIs.
| Status HTTP | Categoria comum | Ação recomendada |
|---|---|---|
400 | Campo inválido, valor não aceito ou conflito de modo de mídia | Verifique o ID de modelo, a duração, o ratio, a resolução e se entradas de quadro não estão misturadas com mídia de referência |
401 | Chave de API ausente ou inválida | Rotacione a chave no painel da ToAPIs e confirme o cabeçalho Authorization |
429 | Limite de taxa ou de concorrência | Recue com variação aleatória; repita apenas quando for seguro |
5xx ou tempo esgotado na rede | Problema temporário do gateway ou do upstream | Verifique o status da tarefa antes de reenviar; use uma política de repetição limitada |
5. Preços e retorno de FinOps
- Não reutilize preços unitários de rascunhos de planejamento. Tarifas por segundo, unidades de cobrança e tratamento de tarefas com falha variam por modelo, rota e conta. Leia o catálogo atual da ToAPIs e a cotação da sua conta antes de prever uma lista de planos.
- Contratos oficiais de fornecedores normalmente acrescentam compromissos anuais, cotas por usuário e mínimos de pré-pagamento. A cobrança da ToAPIs costuma ser pagamento conforme o uso: confirme os termos ativos na sua conta.
- Controle o gasto na camada de prompt: mantenha um modelo versionado, mude uma variável por vez e evite reenviar depois de um tempo esgotado no cliente até verificar o status da tarefa.
- Para pesar variantes (H3 base, Max canônico, Turbo), use o guia de escolha em vez de uma pontuação de velocidade ou de qualidade não verificada.
6. Perguntas frequentes
Consulte o bloco de perguntas frequentes do frontmatter. Em resumo: coloque a intenção de câmera no início do prompt; a linguagem de câmera composta é texto de prompt, não uma gramática garantida; a mesma redação se aplica no modo de primeiro quadro; etiquetas entre colchetes não são parâmetros oficiais da API.
7. Checklist de ações
- Crie uma chave no Portal de desenvolvedores da ToAPIs.
- Faça um teste rápido do trecho cURL com
minimax-h3,ratio: "16:9"e duração de 6 segundos. - Adote o auxílio de prompt, guarde as versões do modelo e consulte com um prazo de 180 s.
- Próximo passo: o contrato de requisição da API do H3 e o pipeline R2V automatizado.







