Comment utiliser l'API Creatify Boreal : générer des vidéos à partir de texte, d'images et d'audio

creatify-boreal est un modèle vidéo disponible sur hiapi qui renvoie un clip finalisé avec la voix et le son déjà mixés. Un seul identifiant de modèle couvre trois points de départ : une invite seule, une invite avec une image de référence, ou une invite avec votre propre audio de narration. Ce guide présente la requête, la boucle de polling, et le résultat d'une génération réelle que j'ai exécutée.

Vous devez obtenir une clé API depuis le tableau de bord hiapi. Tous les appels passent par le point de terminaison de tâche unifié POST /v1/tasks.

Champs d'entrée

Ces champs ont été vérifiés par rapport à la page du modèle en direct, et validés en envoyant des valeurs volontairement invalides à /v1/tasks ; les valeurs invalides renvoient une erreur 400 sans facturation.

Champ	Obligatoire	Valeurs acceptées
prompt	Oui	Texte, jusqu'à 5000 caractères
image_url	Non	JPG/PNG/WebP, 10 Mo ; définit le sujet et la composition
audio_url	Non	MP3/WAV/M4A, 15 Mo ; seules les premières duration secondes sont utilisées
negative_prompt	Non	Jusqu'à 2000 caractères
resolution	Non	720p, 1080p, 2k
aspect_ratio	Non	auto, 16:9, 9:16, 1:1, 4:3, 3:4
duration	Non	Secondes entières, de 1 à 20

Ces trois modes ne sont pas des identifiants de modèle distincts. Pour le texte vers vidéo, omettez image_url et audio_url ; pour l'image vers vidéo, ajoutez image_url ; ajoutez audio_url (généralement avec une image) pour que le présentateur suive votre narration.

Requête minimale fonctionnelle

curl -X POST 'https://api.hiapi.ai/v1/tasks' \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "creatify-boreal",
    "input": {
      "prompt": "Vidéo UGC style selfie vertical : une jeune femme dans une chambre lumineuse tient un rouge à lèvres rose poudré et dit face caméra : \"Bon, c'est le seul rouge à lèvres qui m'a tenu tout l'hiver.\" Sons ambiants naturels de la pièce.",
      "resolution": "720p",
      "aspect_ratio": "9:16",
      "duration": 4
    }
  }'

La réponse renvoie l'identifiant de tâche :

{"code":200,"data":{"taskId":"tk-hiapi-01M5MJC8NG8E1E0XN9NEJRDBQH"},"message":"success"}

Python : soumission et polling

import os, time, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def create(payload: dict) -> str:
    r = requests.post(BASE, headers=HEADERS, json=payload, timeout=30)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait(task_id: str, every: int = 10, limit: int = 900) -> dict:
    start = time.time()
    while time.time() - start < limit:
        try:
            d = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except (requests.RequestException, ValueError):
            time.sleep(every)  # erreur réseau transitoire : continuer à interroger le même id
            continue
        if d["status"] == "success":
            return d
        if d["status"] == "fail":
            raise RuntimeError(d.get("error"))
        time.sleep(every)
    raise TimeoutError(task_id)

task_id = create({
    "model": "creatify-boreal",
    "input": {
        "prompt": "Vidéo UGC style selfie vertical : une jeune femme tient un rouge à lèvres rose poudré et dit face caméra : \"Bon, c'est le seul rouge à lèvres qui m'a tenu tout l'hiver.\" Sons ambiants naturels de la pièce.",
        "resolution": "720p",
        "aspect_ratio": "9:16",
        "duration": 4,
    },
})
result = wait(task_id)
print(result["output"][0]["url"])

Le statut passe successivement par handling, archiving, puis success. L'URL de la vidéo se trouve dans data.output[0].url.

Modes image et audio

L'image vers vidéo ajoute un champ supplémentaire :

{"model": "creatify-boreal",
 "input": {"prompt": "Cette femme dans une cuisine sourit et parle face caméra : \"J'ai remplacé mon café par cette boisson à l'avoine latte.\" Sons ambiants naturels de cuisine.",
           "image_url": "https://your-cdn.example/presenter.jpg",
           "resolution": "720p", "duration": 8}}

Le mode piloté par l'audio ajoute audio_url pointant vers un fichier de narration. La page du modèle le décrit comme suit : la narration est conservée dans la vidéo, les lèvres suivent la narration, et seules les premières duration secondes de l'audio sont utilisées ; définissez donc duration sur la longueur de clip souhaitée. L'exemple audio de la page du modèle associe l'audio à une image de référence ; je n'ai personnellement pas exécuté de génération image + audio, cette combinaison est donc documentée et non vérifiée dans cet article.

À quoi ressemble une exécution réelle

J'ai exécuté la requête ci-dessus (texte seul, 720p, 9:16, 4 secondes).

• Temps de génération : la tâche est restée en statut handling environ 283 secondes, puis en statut archiving environ 10 secondes. Même pour un clip de 4 secondes, prévoyez des minutes plutôt que des secondes. Interrogez toutes les 10 secondes ou utilisez un callback, plutôt qu'un timeout court.
• Fichier de sortie : MP4 720x1280, vidéo H.264 à 24 fps avec piste audio AAC, durée 4,04 secondes. Bien que la requête n'ait pas de champ audio, l'audio est présent, ce qui correspond à la conception sonore native du modèle.
• URL temporaire : l'URL de sortie se trouve sur temp.hiapi.ai, avec un expireAt expirant après environ 7 jours. Téléchargez le fichier et stockez-le vous-même, plutôt que de le lier depuis la page.
• Structure des coûts : la facturation est à la seconde et dépend de la resolution (voir la page de tarification), donc la façon la moins chère d'itérer sur les invites est 720p avec une duration courte, puis de re-rendre la version finale en 1080p ou 2k.

Pièges que j'ai rencontrés

• Les valeurs invalides échouent rapidement et gratuitement. Envoyer aspect_ratio: "7:5", duration: 25 ou resolution: "4k" renvoie HTTP 400 INVALID_REQUEST, avec un message listant les valeurs autorisées ('auto', '16:9', '9:16', '1:1', '4:3', '3:4', max 20, et '720p', '1080p', '2k'). Utilisez cela pour valider vos propres formulaires avant soumission.
• Une URL de média invalide échoue plus tard lors du polling. J'ai soumis audio_url: "https://example.com/a.mp3" (qui n'est pas un vrai fichier audio). L'appel de création a renvoyé HTTP 200 avec un identifiant de tâche, et environ 15 secondes plus tard la tâche s'est terminée avec status: "fail" et error.code: "INVALID_REQUEST". Ainsi, un 200 à la création ne signifie pas que votre média est disponible ; vérifiez toujours le statut final et lisez data.error. Dans ce cas, l'échec se présente dans une réponse de polling HTTP 200, et non comme une erreur HTTP.
• L'échec est status: "fail", pas un statut HTTP. La requête de polling elle-même renvoie 200, donc vérifiez data.status.

Pages associées

• Page du modèle Creatify Boreal : Playground, tarification en direct et exemples de clips
• Tarification hiapi
• Documentation hiapi
• Comment utiliser l'API OmniHuman 1.5 : un autre modèle vidéo de style présentateur
• API Ray 3.2 image vers vidéo
• Guide de l'API vidéo Wan 3.0

Questions fréquentes

Les entrées texte, image et audio nécessitent-elles des identifiants de modèle distincts ? Non. Les trois utilisent creatify-boreal ; les champs que vous incluez dans input déterminent le mode.

Quelle est la durée maximale d'un clip ? De 1 à 20 secondes entières. La valeur 25 est rejetée avec HTTP 400.

La sortie contient-elle du son ? Oui. Le clip de test de 4 secondes comportait une piste AAC même sans entrée audio fournie.

Quelles résolutions sont disponibles ? 720p, 1080p et 2k. La facturation varie selon la résolution ; consultez la page de tarification.

Combien de temps dois-je attendre ? Mon test de 4 secondes en 720p a pris environ cinq minutes de bout en bout. Utilisez un polling avec une limite généreuse ou un callback.