So verwendest du die Creatify Boreal API: Videos aus Text, Bildern und Audio generieren

creatify-boreal ist ein Videomodell auf hiapi, das fertige Clips mit bereits gemischtem Sprecher- und Geräuschton zurückgibt. Eine Modell-ID deckt drei Ausgangspunkte ab: nur Prompt, Prompt plus Referenzbild oder Prompt plus deine eigene Voiceover-Audiodatei. Dieser Leitfaden zeigt die Anfrage, die Polling-Schleife und das Ergebnis eines echten Generierungslaufs, den ich tatsächlich ausgeführt habe.

Du benötigst einen API-Schlüssel aus dem hiapi-Dashboard. Alle Aufrufe laufen über den einheitlichen Task-Endpunkt POST /v1/tasks.

Eingabefelder

Diese Felder wurden mit der Live-Modellseite abgeglichen und durch Senden absichtlich ungültiger Werte an /v1/tasks überprüft; ungültige Werte geben 400 zurück und werden nicht in Rechnung gestellt.

Feld	Erforderlich	Akzeptierte Werte
prompt	Ja	Text, maximal 5000 Zeichen
image_url	Nein	JPG/PNG/WebP, 10 MB; legt Motiv und Bildkomposition fest
audio_url	Nein	MP3/WAV/M4A, 15 MB; nur die ersten duration Sekunden werden verwendet
negative_prompt	Nein	Maximal 2000 Zeichen
resolution	Nein	720p, 1080p, 2k
aspect_ratio	Nein	auto, 16:9, 9:16, 1:1, 4:3, 3:4
duration	Nein	Ganzzahlige Sekunden, 1 bis 20

Diese drei Modi sind keine separaten Modell-IDs. Bei Text-zu-Video lässt du image_url und audio_url weg; bei Bild-zu-Video fügst du image_url hinzu; durch Hinzufügen von audio_url (üblicherweise zusammen mit einem Bild) folgt die sprechende Person deinem Voiceover.

Minimal funktionierende Anfrage

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": "Hochformat-Selfie-UGC-Video: Eine junge Frau hält in einem hellen Schlafzimmer einen zartrosa Lippenstift hoch und sagt in die Kamera: \"Okay, das ist der einzige Lippenstift, der meinen Winter überlebt hat.\" Natürliche Raumgeräusche.",
      "resolution": "720p",
      "aspect_ratio": "9:16",
      "duration": 4
    }
  }'

Die Antwort liefert eine Task-ID:

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

Python: Senden und Pollen

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)  # Kurzzeitiger Netzwerkfehler: dieselbe ID weiter pollen
            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": "Hochformat-Selfie-UGC-Video: Eine junge Frau hält einen zartrosa Lippenstift hoch und sagt in die Kamera: \"Okay, das ist der einzige Lippenstift, der meinen Winter überlebt hat.\" Natürliche Raumgeräusche.",
        "resolution": "720p",
        "aspect_ratio": "9:16",
        "duration": 4,
    },
})
result = wait(task_id)
print(result["output"][0]["url"])

Der Status durchläuft handling, archiving und dann success. Die Video-URL befindet sich unter data.output[0].url.

Bild- und Audiomodus

Bild-zu-Video fügt ein zusätzliches Feld hinzu:

{"model": "creatify-boreal",
 "input": {"prompt": "Diese Frau lächelt und spricht in einer Küche in die Kamera: \"Ich habe meinen Kaffee gegen diesen Oat-Latte-Mix getauscht.\" Natürliche Küchengeräusche.",
           "image_url": "https://your-cdn.example/presenter.jpg",
           "resolution": "720p", "duration": 8}}

Der audiogesteuerte Modus fügt eine audio_url hinzu, die auf die Voiceover-Datei verweist. Die Modellseite beschreibt es so, dass das Voiceover im Video erhalten bleibt, die Lippen der Voiceover-Bewegung folgen, und dass nur die ersten duration Sekunden des Audios verwendet werden – setze duration also auf die gewünschte Clip-Länge. Das Audio-Beispiel auf der Modellseite kombiniert Audio mit einem Referenzbild; ich selbst habe keine Generierung mit Bild plus Audio ausgeführt, daher ist diese Kombination in diesem Artikel dokumentiert und nicht verifiziert.

Wie ein echter Lauf aussieht

Ich habe die obige Anfrage ausgeführt (reiner Text, 720p, 9:16, 4 Sekunden).

• Generierungszeit: Die Task verbrachte etwa 283 Sekunden im Status handling und dann etwa 10 Sekunden im Status archiving. Plane selbst für einen 4-Sekunden-Clip in Minuten, nicht in Sekunden. Polle alle 10 Sekunden oder verwende einen Callback statt kurzer Timeouts.
• Ausgabedatei: MP4 mit 720x1280, H.264-Video mit 24 fps plus AAC-Tonspur, Dauer 4,04 Sekunden. Obwohl die Anfrage kein Audiofeld enthielt, ist Audio vorhanden – das entspricht dem nativen Sounddesign des Modells.
• Temporäre URL: Die Ausgabe-URL liegt auf temp.hiapi.ai und hat ein expireAt mit Ablauf nach etwa 7 Tagen. Lade die Datei herunter und speichere sie selbst, statt sie von der Seite aus zu verlinken.
• Kostenform: Die Abrechnung erfolgt pro Sekunde und hängt von der resolution ab (siehe Preisseite). Die günstigste Art, Prompts zu iterieren, ist daher 720p mit kurzer duration, und anschließend das finale Rendern mit 1080p oder 2k.

Stolpersteine, auf die ich gestoßen bin

• Falsche Werte scheitern schnell und kostenlos. Das Senden von aspect_ratio: "7:5", duration: 25 oder resolution: "4k" liefert jeweils HTTP 400 INVALID_REQUEST, wobei die Meldung die erlaubten Werte auflistet ('auto', '16:9', '9:16', '1:1', '4:3', '3:4', maximal 20 sowie '720p', '1080p', '2k'). Nutze das, um deine eigenen Formulare vor dem Absenden zu validieren.
• Falsche Medien-URLs scheitern später beim Polling. Ich habe audio_url: "https://example.com/a.mp3" gesendet (keine echte Audiodatei). Der Create-Aufruf gab HTTP 200 und eine Task-ID zurück, und etwa 15 Sekunden später endete die Task mit status: "fail" und error.code: "INVALID_REQUEST". Ein 200 beim Erstellen bedeutet also nicht, dass deine Medien verfügbar sind; prüfe immer den finalen Status und lies data.error. In diesem Fall erschien der Fehler innerhalb einer HTTP-200-Polling-Antwort und nicht als HTTP-Fehler.
• Fehler sind status: "fail", kein HTTP-Status. Die Polling-Anfrage selbst gibt 200 zurück, prüfe daher data.status.

Verwandte Seiten

• Creatify Boreal Modellseite: Playground, Live-Preise und Beispielclips
• hiapi-Preise
• hiapi-Dokumentation
• So verwendest du die OmniHuman 1.5 API: ein weiteres Videomodell im Sprecher-Stil
• Ray 3.2 Bild-zu-Video API
• Wan 3.0 Video-API-Leitfaden

Häufig gestellte Fragen

Brauchen Text-, Bild- und Audioeingaben separate Modell-IDs? Nein. Alle drei verwenden creatify-boreal; die Felder, die du in input angibst, bestimmen den Modus.

Wie lang kann ein Clip maximal sein? Ganzzahlige Sekunden von 1 bis 20. Der Wert 25 wird mit HTTP 400 abgelehnt.

Enthält die Ausgabe Ton? Ja. Der 4-sekündige Testclip enthielt auch ohne Audioeingabe eine AAC-Tonspur.

Welche Auflösungen sind verfügbar? 720p, 1080p und 2k. Die Abrechnung variiert je nach Auflösung; siehe Preisseite.

Wie lange sollte ich warten? Mein Test mit 4 Sekunden und 720p dauerte von Anfang bis Ende etwa fünf Minuten. Verwende Polling mit großzügigem Limit oder einen Callback.