Scrivere prompt multi-angolazione per la generazione video da immagine con minimax-h3-max tramite l'API hiapi

minimax-h3-max può trasformare una foto in un video di 5–15 secondi, ma il suo endpoint non ha affatto parametri per "angolo di ripresa", "multi-vista" o "numero di inquadrature" — i campi di input supportati elencati nella riferimento dei parametri sono prompt, first_frame_image, last_frame_image, duration, resolution e aspect_ratio. Le istruzioni di ripresa vanno scritte in prompt, che accetta fino a 7.000 caratteri.

Quindi, un clip "multi-angolazione" — che passa da un'inquadratura grandangolare di stabilimento a un primo piano, poi a un'inquadratura inseguita — non è un parametro che imposti, ma il prompt che scrivi. Questo tutorial copre la struttura della richiesta, gli schemi di prompt per richiedere più angolazioni di ripresa all'interno di un singolo clip generato, e il flusso di lavoro di livello produttivo che lo circonda.

Genera con questo prompt → scegli 10 secondi e 768P. Per la generazione da immagine, aggiungi le tue immagini di frame e ometti aspect_ratio.

Prerequisiti

Ottieni una chiave API dalla tua console hiapi. Ogni chiamata qui sotto autentica con Authorization: Bearer YOUR_API_KEY verso l'endpoint condiviso per attività asincrone POST https://api.hiapi.ai/v1/tasks.

Esempio minimo: una foto, tre angolazioni di ripresa

first_frame_image ancora il soggetto e la scena, così il modello ha contenuto concreto da cui staccare e a cui tornare. Il prompt descrive ogni inquadratura come uno stacco numerato esplicito. Questo prompt della motocicletta è un esempio di codice, senza esempi di rendering allegati.

Una motocicletta vintage rossa parcheggiata su una strada urbana bagnata al crepuscolo, insegne al neon riflesse sul selciato. Inquadratura 1 - grandangolare dal basso: la camera mantiene un'inquadratura grandangolare statica dell'intera motocicletta, con pioggia leggera che cade. Stacco all'inquadratura 2 - primo piano: la camera si avvicina stretta sul faro cromato e sulla ruota anteriore, inseguendo lentamente verso destra. Stacco all'inquadratura 3 - dall'alto a piombo: la camera guarda dritto verso il basso sulla motocicletta dall'alto, ruotando lentamente. Nessun testo o sottotitolo.

Genera con questo prompt → aggiungi la tua immagine della motocicletta accessibile pubblicamente, scegli 10 secondi e 768P, e ometti aspect_ratio.

import os
import requests
import time

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

payload = {
    "model": "minimax-h3-max",
    "input": {
        "prompt": (
            "A red vintage motorcycle parked on a wet city street at dusk, neon signs reflecting on the pavement. "
            "Shot 1 - low wide angle: the camera holds a static wide shot of the full motorcycle, rain lightly falling. "
            "Cut to Shot 2 - close-up: the camera pushes in tight on the chrome headlight and front wheel, tracking slowly right. "
            "Cut to Shot 3 - overhead top-down: the camera looks straight down at the motorcycle from above, slowly rotating. "
            "No text or subtitles."
        ),
        "first_frame_image": "https://your-cdn.example.com/motorcycle-source.jpg",
        "duration": 10,
        "resolution": "768P",
    },
}

# Frame images and aspect_ratio are mutually exclusive.
def response_data(response):
    response.raise_for_status()
    body = response.json()
    if not isinstance(body, dict) or body.get("code") != 200:
        raise ValueError("Expected a JSON object with code=200")
    data = body.get("data")
    if not isinstance(data, dict):
        raise ValueError("Expected data to be an object")
    return data

# Submit once. An uncertain POST response is not a reason to submit again.
try:
    resp = requests.post(
        f"{BASE}/tasks", headers=HEADERS, json=payload, timeout=(10, 60)
    )
    created = response_data(resp)
    task_id = created.get("taskId")
    if not isinstance(task_id, str) or not task_id.strip():
        raise ValueError("Missing data.taskId")
except (requests.RequestException, ValueError) as exc:
    raise RuntimeError(
        "Could not confirm task creation. Check task records before resubmitting."
    ) from exc

print("taskId:", task_id, flush=True)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    try:
        resp = requests.get(
            f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=(10, 60)
        )
        task = response_data(resp)
    except (requests.RequestException, ValueError) as exc:
        raise RuntimeError(
            f"Query failed; retain taskId={task_id} and resume GET for this ID."
        ) from exc

    state = task.get("status")
    if state == "fail":
        raise RuntimeError(f"Task {task_id} failed: {task.get('error')}")
    if state == "success":
        outputs = task.get("output")
        if not isinstance(outputs, list):
            raise RuntimeError(f"Task {task_id}: missing output array")
        video = next(
            (item for item in outputs
             if isinstance(item, dict) and item.get("type") == "video"
             and isinstance(item.get("url"), str) and item["url"]),
            None,
        )
        if video is None:
            raise RuntimeError(f"Task {task_id}: no video URL in output")
        print(video["url"])
        print("expireAt (Unix seconds):", video.get("expireAt"))
        break
    if state not in {"queued", "handling", "archiving"}:
        raise RuntimeError(f"Task {task_id}: unexpected status {state!r}")
    time.sleep(min(3, max(0, deadline - time.monotonic())))
else:
    raise TimeoutError(f"Polling timed out; continue GET with taskId={task_id}")

Sostituisci first_frame_image con un URL HTTPS reale e accessibile pubblicamente dell'immagine, oppure rimuovilo del tutto per generare la stessa sequenza multi-angolazione solo dal testo — minimax-h3-max gestisce sia la generazione da testo che da immagine tramite lo stesso campo prompt.

Scrivere il prompt: lo schema delle inquadrature numerate

Tre scelte rendono chiara la sequenza di inquadrature che desideri:

1. Una frase che stabilisce la scena, poi inquadrature numerate. Descrivi una volta il soggetto e la scena, poi elenca ogni angolazione di ripresa come un proprio beat etichettato: Inquadratura 1 - [composizione]: [azione]. Stacco all'inquadratura 2 - [composizione]: [azione]. "Stacco all'inquadratura N" richiede esplicitamente un cambio di angolazione.
2. Usa un vocabolario cinematografico standard. inquadratura grandangolare dal basso, inquadratura dall'alto a piombo, primo piano, lento carrello in avanti, inquadratura inseguita laterale, a mano — queste parole indicano la composizione e il movimento che desideri. Espressioni vaghe come "un'altra angolazione figa" producono risultati incoerenti.
3. Pianifica il numero di inquadrature in base alla durata. duration è un numero intero da 5 a 15 secondi. Due o tre inquadrature sono realistiche; stipare cinque angolazioni diverse in un clip di 5 secondi significa meno di un secondo per inquadratura, e spesso sembra un glitch piuttosto che uno stacco.

first_frame_image e last_frame_image sono entrambi opzionali e indipendenti l'uno dall'altro — puoi impostarne uno, entrambi o nessuno. Quando fornisci uno di questi, ometti aspect_ratio: questi campi sono mutuamente esclusivi e le immagini di frame determinano le proporzioni dell'output. Nota inoltre che tra le angolazioni non è garantita una rigorosa coerenza tridimensionale o geometrica — questo è un modello video generativo, non una pipeline di fotogrammetria, quindi anche con l'ancoraggio del primo frame, aspettati leggere derive nei dettagli del soggetto tra gli stacchi.

Renderlo adatto alla produzione

• Oltre la scala di uno script, preferisci i callback al polling. Aggiungi "callback": {"url": "https://your-domain.com/hiapi/callback", "when": "final"} al corpo della richiesta, e hiapi invierà una POST di notifica quando l'attività raggiunge lo stato terminale, invece di interrogare GET /v1/tasks/{taskId} in un ciclo.
• Deduplica per taskId. Le risposte di polling e i callback sono entrambi indicizzati dallo stesso taskId — tratta le notifiche ripetute dello stato terminale per lo stesso ID come idempotenti, non come più attività distinte.
• Scarica l'output immediatamente. Le attività riuscite restituiscono data.output[].url per l'archiviazione temporanea. Seleziona l'elemento di output con type pari a video e controlla il suo timestamp Unix expireAt (secondi). Ricaricalo sul tuo storage nello stesso handler che elabora lo stato terminale.
• Gestisci le due forme di errore. Un corpo di richiesta errato (campi non supportati, duration fuori intervallo, URL immagine malformato) fallisce rapidamente al momento dell'invio con 400 INVALID_REQUEST. I problemi di autenticazione restituiscono 401 con error.code: "permission_denied". Le attività che falliscono durante la generazione riportano invece "status": "fail" nella risposta di polling/callback — controlla status prima di fidarti di output.

Letture correlate

• Pagina del modello minimax-h3-max — prezzi in tempo reale, parametri e un playground per testare i prompt nel browser prima di collegarli al codice.
• Documentazione API di minimax-h3-max — riferimento completo dei parametri e dettagli sui callback.
• Prezzi di H3 e H3 Max — tariffe per risoluzione e budget per video brevi.
• Prezzi hiapi — tariffe correnti al secondo per ogni modello.

Domande frequenti

minimax-h3-max ha un parametro dedicato per multi-angolazione o multi-camera? No. I campi di input documentati sono prompt, first_frame_image, last_frame_image, duration, resolution e aspect_ratio. Descrivi le inquadrature multiple all'interno di prompt, invece di aggiungere un campo per l'angolo di ripresa.

Posso impostare aspect_ratio insieme a first_frame_image o last_frame_image? No. aspect_ratio è mutuamente esclusivo con entrambi i campi immagine di frame. L'immagine fornita determina le proporzioni dell'output. Se passi una qualsiasi immagine di frame, ometti aspect_ratio.

Quanto può essere lungo un clip multi-angolazione? duration accetta un numero intero di secondi da 5 a 15. Due o tre diverse angolazioni di ripresa si adattano con un certo margine a questa finestra; superare questo numero tende a comprimere ogni inquadratura in una frazione di secondo.

Il soggetto rimarrà perfettamente coerente tra le diverse angolazioni? Non è garantito. minimax-h3-max è un modello video generativo, quindi anche se first_frame_image ancora il frame iniziale, i dettagli (texture precise, proporzioni sottili) possono derivare tra gli stacchi. Considerala una forte coerenza creativa, non una ricostruzione multi-vista pixel-perfect.

Posso generare un clip multi-angolazione solo dal testo, senza immagine sorgente? Sì — ometti first_frame_image e last_frame_image e descrivi la scena e le inquadrature in prompt. La generazione puramente testuale usa la tela orizzontale predefinita. Per una composizione verticale, fornisci un'immagine di frame verticale senza impostare aspect_ratio, oppure ritaglia/riempi il video salvato nell'editor.

Come si presenta un errore di autenticazione? HTTP 401, con un corpo di risposta simile a {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"..."}}. Controlla attentamente l'intestazione Authorization: Bearer e se la chiave è stata revocata dalla console.

Copia la sequenza di inquadrature della motocicletta e genera con questo prompt → scegli 10 secondi e 768P; aggiungi la tua immagine di frame per guidare la composizione iniziale.