Comment utiliser happyhorse-1.1 via l'API hiapi : texte-vers-vidéo, image-vers-vidéo et référence-vers-vidéo

Si vous cherchez comment utiliser happy horse 1.1, voici la version courte : happyhorse-1.1 n'est pas un seul point de terminaison de modèle, mais trois, tous fournis via l'API de tâches asynchrones unifiée de hiapi :

Point de terminaison (ID de modèle)	Fonction	Entrée requise
happyhorse-1.1/text-to-video	Générer une vidéo à partir d'un prompt texte	prompt
happyhorse-1.1/image-to-video	Animer une image statique	image_urls
happyhorse-1.1/reference-to-video	Générer une vidéo guidée par des images de référence et un prompt	prompt, reference_image

Ces trois points de terminaison partagent le même cycle de vie : soumission via POST /v1/tasks → obtention d'un taskId → interrogation de GET /v1/tasks/<id> (ou réception d'un callback) → téléchargement de output[0].url. Chaque tableau de paramètres et chaque message d'erreur ci-dessous ont été vérifiés sur l'API en production — rien n'est issu de suppositions.

Prérequis

Vous n'avez besoin que d'une seule chose : une clé API hiapi. Obtenez-la depuis votre console hiapi — elle ressemble à sk-... et se place dans l'en-tête Authorization: Bearer. La génération vidéo est facturée à la seconde de sortie ; consultez la page de tarification pour le tarif actuel par seconde de chaque point de terminaison.

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

Exemple minimal exécutable (texte-vers-vidéo)

Soumettre une tâche :

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 réponse vous fournit un ID de tâche sous data.taskId. Interrogez-le :

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

Lorsque data.status passe à success, l'URL de la vidéo se trouve dans data.output[0].url. Téléchargez-la immédiatement — les URL de sortie portent un horodatage expireAt et résident sur un stockage temporaire ; considérez-les donc comme une fenêtre de récupération, et non comme un hébergement permanent.

Voici le script Python complet du même flux (bibliothèque standard uniquement) :

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

Paramètres de chaque point de terminaison

Le schéma d'entrée est strict : les champs inconnus sont rejetés avec un code 400, au lieu d'être silencieusement ignorés. Des champs comme size, seed, negative_prompt et audio renvoient tous additional properties ... not allowed. Voici les paramètres exactement acceptés par chaque point de terminaison.

happyhorse-1.1/text-to-video

Champ	Requis	Type	Valeurs autorisées
prompt	✅	string	Votre description de scène
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 (secondes)

Guide complet avec astuces de rédaction de prompts : tutoriel texte-vers-vidéo happyhorse-1.1.

happyhorse-1.1/image-to-video

Champ	Requis	Type	Valeurs autorisées
image_urls	✅	tableau de chaînes	exactement 1 URL d'image accessible publiquement (maxItems: 1)
prompt	—	string	Guidage de mouvement/scène pour l'animation
resolution	—	string	720p, 1080p
duration	—	integer	3–15 (secondes)

Deux pièges fréquents ici. Premièrement, image_urls est un tableau, mais un seul élément est actuellement accepté — passez ["https://..."], et non une chaîne nue ni plusieurs URL. Deuxièmement, ce point de terminaison n'a pas d'aspect_ratio (l'API le rejetterait) ; le format de sortie suit votre image source.

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

Pour aller plus loin : tutoriel image-vers-vidéo happyhorse.

happyhorse-1.1/reference-to-video

Champ	Requis	Type	Valeurs autorisées
prompt	✅	string	Description de scène
reference_image	✅	tableau de chaînes	1 à 9 URL d'images accessibles publiquement (maxItems: 9)
aspect_ratio	—	string	Les mêmes 9 ratios que le texte-vers-vidéo
resolution	—	string	720p, 1080p
duration	—	integer	3–15 (secondes)

C'est le point de terminaison « gardez mon personnage/produit cohérent » : les images de référence ancrent l'identité et le style, tandis que le prompt pilote l'action. Contrairement à l'image-vers-vidéo, le contrôle d'aspect_ratio est ici de nouveau disponible, et vous pouvez fournir jusqu'à 9 images de référence.

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

Pour aller plus loin : tutoriel référence-vers-vidéo happyhorse-1.1.

Quel point de terminaison choisir ?

• Vous n'avez qu'une idée → text-to-video. Le chemin le plus rapide du texte au mouvement.
• Vous avez l'image exacte à animer (photo produit, illustration, photographie) → image-to-video. L'image source est la première image.
• Vous devez conserver le même sujet sur plusieurs clips (un personnage, une mascotte, plusieurs angles d'un produit) → reference-to-video. Les images de référence verrouillent l'identité ; le prompt varie d'un clip à l'autre.

Modèles de bonnes pratiques en production

Utiliser un callback plutôt que l'interrogation répétée

Pour tout usage allant au-delà d'un script, enregistrez un webhook lors de la création de la tâche — les tâches vidéo sont longues, et l'interrogation répétée dans un gestionnaire de requêtes web finira par expirer :

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

Seule la valeur "when": "final" est prise en charge — vous ne recevez qu'un seul POST lorsque la tâche atteint un état terminal (toute autre valeur renvoie invalid callback.when: only 'final' is supported). Concevez votre récepteur comme idempotent sur taskId : stockez l'ID de tâche à la soumission et traitez les callbacks dupliqués ou déjà traités comme des opérations sans effet. Conservez un balayeur d'interrogation à basse fréquence comme filet de sécurité en cas de callback perdu à cause d'une instabilité réseau.

Gestion des erreurs : trois catégories d'échec

1. Erreurs de validation (HTTP 400, INVALID_REQUEST). Les messages sont très précis — lisez-les, ils indiquent le champ exact :

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

2. Erreurs d'authentification/permission (HTTP 401, permission_denied). La clé est incorrecte, ou la clé n'a pas accès à ce modèle :

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

Vérifiez la clé dans la console et, si vous contactez le support, joignez le request_id.

3. Échec de génération (tâche status: "fail"). La soumission a réussi mais la génération a échoué ; lors de l'interrogation ou de la réception du callback, les détails de l'erreur se trouvent dans le champ error de l'objet tâche. Ce type d'erreur mérite une nouvelle tentative avec un backoff — contrairement aux erreurs de validation et d'authentification.

Maîtrise des coûts

La facturation se fait à la seconde de vidéo générée, donc duration est votre principal levier de coût — un clip de 15 secondes coûte 3 fois plus qu'un clip de 5 secondes, tandis que resolution a un impact moindre. Itérez sur vos prompts avec duration: 3 et 720p, puis générez la version finale à la longueur complète. Consultez la page de tarification pour les tarifs actuels.

Lectures associées

• happyhorse-1.1 texte-vers-vidéo — page du modèle et aire de test
• happyhorse-1.1 image-vers-vidéo — page du modèle et aire de test
• happyhorse-1.1 référence-vers-vidéo — page du modèle et aire de test
• Flux de travail pour vidéos courtes avec happyhorse-1.1
• Documentation hiapi

Questions fréquentes

Puis-je utiliser à la fois une image et un prompt texte ? Oui — image-to-video accepte un prompt facultatif en plus de l'image_urls requis, et reference-to-video exige à la fois prompt et reference_image. Seul text-to-video fonctionne uniquement avec un prompt.

Combien d'images puis-je fournir ? image-to-video : exactement une (image_urls est limité à 1 élément). reference-to-video : jusqu'à neuf dans reference_image. Les deux acceptent un tableau d'URL accessibles publiquement, et non des fichiers téléversés ou du base64.

happyhorse-1.1 prend-il en charge les paramètres seed, negative_prompt ou audio ? Non. Le schéma d'entrée est strict et rejette ces trois paramètres avec une erreur 400 additional properties not allowed. Si vous avez besoin de reproductibilité, gardez le prompt et les paramètres strictement identiques et gérez les versions de votre côté.

Quelles résolutions et durées sont disponibles ? Pour les trois points de terminaison : 720p ou 1080p, et de 3 à 15 secondes (entier). Si vous les omettez, les valeurs par défaut s'appliquent.

Pourquoi est-ce que je reçois une erreur 401 permission_denied avec une clé qui semble valide ? La clé existe, mais elle ne peut pas utiliser ce modèle — c'est fréquent avec les clés restreintes ou d'essai. Vérifiez les permissions de modèle de cette clé dans la console, ou générez une nouvelle clé sans restriction.

Comment savoir quand la vidéo est prête sans interroger l'API ? Passez callback: {"url": "...", "when": "final"} à la soumission. Lorsque la tâche atteint success ou fail, hiapi envoie un unique POST à votre URL. N'oubliez pas que les URL de sortie expirent — téléchargez le fichier dans votre gestionnaire de callback, ne le liez pas en hotlink.