Come usare happyhorse-1.1 tramite l'API hiapi: text-to-video, image-to-video e reference-to-video

Se stai cercando come usare happy horse 1.1, ecco la versione breve: happyhorse-1.1 non è un unico endpoint per modelli, ma tre, tutti erogati tramite l'API asincrona unificata di task di hiapi:

Endpoint (ID modello)	Funzionalità	Input obbligatorio
happyhorse-1.1/text-to-video	Genera video da un prompt testuale	prompt
happyhorse-1.1/image-to-video	Anima un'immagine statica	image_urls
happyhorse-1.1/reference-to-video	Genera video guidato da immagini di riferimento più un prompt	prompt, reference_image

Questi tre endpoint condividono lo stesso ciclo di vita: invio con POST /v1/tasks → ottieni taskId → esegui polling su GET /v1/tasks/<id> (oppure ricevi un callback) → scarica output[0].url. Ogni tabella di parametri e ogni messaggio di errore riportati di seguito sono stati verificati sull'API in produzione: nulla è frutto di supposizioni.

Prerequisiti

Ti serve una sola cosa: una chiave API di hiapi. Ottienila dalla tua console hiapi: ha un aspetto simile a sk-... e va inserita nell'intestazione Authorization: Bearer. La generazione di video viene fatturata in base ai secondi di output; le tariffe al secondo attuali per ciascun endpoint sono indicate nella pagina dei prezzi.

export HIAPI_KEY="sk-your-key-here"

Esempio minimo eseguibile (text-to-video)

Invia il task:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/text-to-video",
    "input": {
      "prompt": "A golden retriever puppy runs through a sunlit meadow, slow motion, cinematic",
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "duration": 5
    }
  }'

La risposta ti fornisce un ID task sotto data.taskId. Esegui il polling:

curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer $HIAPI_KEY"

Quando data.status diventa success, l'URL del video si trova in data.output[0].url. Scaricalo immediatamente: gli URL di output includono un timestamp expireAt e risiedono in uno spazio di archiviazione temporaneo, quindi trattali come una finestra di ritiro, non come un hosting permanente.

Di seguito è riportato uno script Python completo per lo stesso flusso (solo libreria standard):

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-your-key-here"

def api(method, url, payload=None):
    req = urllib.request.Request(url, method=method)
    req.add_header("Authorization", f"Bearer {KEY}")
    req.add_header("Content-Type", "application/json")
    data = json.dumps(payload).encode() if payload else None
    with urllib.request.urlopen(req, data=data) as resp:
        return json.loads(resp.read())

# 1. Submit
task = api("POST", API, {
    "model": "happyhorse-1.1/text-to-video",
    "input": {
        "prompt": "A golden retriever puppy runs through a sunlit meadow, cinematic",
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "duration": 5,
    },
})
task_id = task["data"]["taskId"]
print("submitted:", task_id)

# 2. Poll until terminal state
while True:
    data = api("GET", f"{API}/{task_id}")["data"]
    status = data["status"]
    if status == "success":
        video_url = data["output"][0]["url"]
        break
    if status == "fail":
        raise RuntimeError(f"task failed: {data.get('error')}")
    time.sleep(5)

# 3. Download before the URL expires
urllib.request.urlretrieve(video_url, "output.mp4")
print("saved output.mp4")

Parametri per ciascun endpoint

Lo schema di input è rigoroso: i campi sconosciuti vengono rifiutati con un 400, non ignorati silenziosamente. Campi come size, seed, negative_prompt e audio restituiscono tutti l'errore additional properties ... not allowed. Ecco i parametri esattamente accettati da ciascun endpoint.

happyhorse-1.1/text-to-video

Campo	Obbligatorio	Tipo	Valori consentiti
prompt	✅	string	La descrizione della tua scena
aspect_ratio	—	string	16:9, 9:16, 3:4, 4:3, 4:5, 5:4, 1:1, 9:21, 21:9
resolution	—	string	720p, 1080p
duration	—	integer	3–15 (secondi)

Guida completa con tecniche per i prompt: tutorial text-to-video di happyhorse-1.1.

happyhorse-1.1/image-to-video

Campo	Obbligatorio	Tipo	Valori consentiti
image_urls	✅	array di stringhe	esattamente 1 URL di immagine accessibile pubblicamente (maxItems: 1)
prompt	—	string	Guida al movimento/scena per l'animazione
resolution	—	string	720p, 1080p
duration	—	integer	3–15 (secondi)

Qui ci sono due trappole comuni. Innanzitutto, image_urls è un array, ma attualmente accetta un solo elemento: passa ["https://..."], non una stringa nuda né più URL. In secondo luogo, questo endpoint non ha aspect_ratio (l'API lo rifiuta); il formato di output segue l'immagine di origine.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/image-to-video",
    "input": {
      "image_urls": ["https://your-cdn.example.com/product-shot.jpg"],
      "prompt": "slow camera push-in, soft studio lighting",
      "resolution": "720p",
      "duration": 5
    }
  }'

Approfondimento: tutorial image-to-video di happyhorse.

happyhorse-1.1/reference-to-video

Campo	Obbligatorio	Tipo	Valori consentiti
prompt	✅	string	Descrizione della scena
reference_image	✅	array di stringhe	da 1 a 9 URL di immagini accessibili pubblicamente (maxItems: 9)
aspect_ratio	—	string	Gli stessi 9 rapporti del text-to-video
resolution	—	string	720p, 1080p
duration	—	integer	3–15 (secondi)

Questo è l'endpoint che dice "mantieni coerente il mio personaggio/prodotto": le immagini di riferimento ancorano identità e stile, mentre il prompt guida l'azione. A differenza di image-to-video, qui si riacquisisce il controllo di aspect_ratio e si possono passare fino a 9 immagini di riferimento.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/reference-to-video",
    "input": {
      "prompt": "the character waves at the camera and smiles, city street at dusk",
      "reference_image": ["https://your-cdn.example.com/character-front.jpg",
                          "https://your-cdn.example.com/character-side.jpg"],
      "aspect_ratio": "9:16",
      "resolution": "720p",
      "duration": 5
    }
  }'

Approfondimento: tutorial reference-to-video di happyhorse-1.1.

Quale endpoint scegliere?

• Hai solo un'idea → text-to-video. Il percorso più rapido dal testo al movimento.
• Hai l'immagine esatta che vuoi animare (foto di prodotto, illustrazione, fotografia) → image-to-video. L'immagine di origine è l'aspetto del primo fotogramma.
• Devi mantenere lo stesso soggetto attraverso più clip (un personaggio, una mascotte, più angolazioni di un prodotto) → reference-to-video. Le immagini di riferimento bloccano l'identità; il prompt cambia da clip a clip.

Modelli di produzione

Usa i callback invece del polling

Per qualsiasi utilizzo che vada oltre uno script, registra un webhook al momento della creazione del task: i task video richiedono tempo e il polling all'interno di un gestore di richieste web finirà prima o poi per andare in timeout:

{
  "model": "happyhorse-1.1/text-to-video",
  "input": { "prompt": "..." },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

È supportato solo "when": "final": riceverai un solo POST quando il task raggiunge lo stato finale (qualsiasi altro valore restituisce invalid callback.when: only 'final' is supported). Progetta il tuo endpoint di ricezione in modo che sia idempotente basato su taskId: memorizza l'ID del task al momento dell'invio e tratta i callback duplicati o già elaborati come operazioni nulle. Mantieni un processo di sweep a bassa frequenza basato sul polling come fallback per i callback persi a causa di problemi di rete.

Gestione degli errori: tre tipi di errore

1. Errori di validazione (HTTP 400, INVALID_REQUEST). I messaggi sono molto precisi: leggili, indicano il campo esatto:

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: duration: maximum: got 99, want 15; resolution: value must be one of '720p', '1080p'"
}

2. Errori di autenticazione/permessi (HTTP 401, permission_denied). La chiave è errata oppure non ha i permessi per accedere a questo modello:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. ...",
    "request_id": "2026..."
  }
}

Controlla la chiave nella console e, se contatti il supporto, includi il request_id.

3. Errore di generazione (task status: "fail"). L'invio è riuscito ma la generazione è fallita; durante il polling o la ricezione del callback, i dettagli dell'errore si trovano nel campo error dell'oggetto task. Vale la pena ritentare questo tipo di errore con backoff esponenziale, mentre gli errori di validazione e di autenticazione no.

Controllo dei costi

La fatturazione avviene in base ai secondi di video generati, quindi duration è la tua leva principale sui costi: una clip di 15 secondi costa 3 volte una clip di 5 secondi, mentre resolution ha un impatto minore. Itera sui prompt con duration: 3 e 720p, poi esegui il rendering della versione finale a lunghezza completa. Le tariffe attuali sono nella pagina dei prezzi.

Letture correlate

• happyhorse-1.1 text-to-video — pagina del modello e playground
• happyhorse-1.1 image-to-video — pagina del modello e playground
• happyhorse-1.1 reference-to-video — pagina del modello e playground
• Workflow per video brevi con happyhorse-1.1
• Documentazione hiapi

Domande frequenti

Posso usare insieme immagini e prompt testuali? Sì: image-to-video accetta un prompt facoltativo oltre all'image_urls obbligatorio, mentre reference-to-video richiede sia prompt che reference_image. Solo text-to-video è esclusivamente basato su prompt.

Quante immagini posso passare? image-to-video: esattamente una (image_urls è limitato a 1 elemento). reference-to-video: fino a nove in reference_image. Entrambi accettano array di URL accessibili pubblicamente, non file caricati o base64.

happyhorse-1.1 supporta i parametri seed, negative_prompt o audio? No. Lo schema di input è rigoroso e rifiuta tutti e tre con un errore 400 additional properties not allowed. Se hai bisogno di riproducibilità, mantieni prompt e parametri identici e gestisci il versionamento dalla tua parte.

Quali risoluzioni e durate sono disponibili? Tutti e tre gli endpoint: 720p o 1080p, e da 3 a 15 secondi (interi). Se omessi, vengono applicati i valori predefiniti.

Perché ricevo 401 permission_denied con una chiave che sembra valida? La chiave esiste, ma non può usare questo modello: è comune con chiavi con ambito limitato o di prova. Verifica i permessi del modello della chiave nella console oppure genera una nuova chiave senza restrizioni.

Come faccio a sapere quando il video è pronto senza polling? Passa callback: {"url": "...", "when": "final"} al momento dell'invio. Quando il task raggiunge success o fail, hiapi invierà un singolo POST al tuo URL. Ricorda che gli URL di output scadono: scarica il file nel gestore del callback, non fare hotlinking.