Vidu

Vidu Q3

vidu-q3-ad/reference-to-video

Ein Modell zur Videogenerierung aus Referenzbildern für Werbung und kurze Social-Media-Videos, das das Erscheinungsbild des Motivs und die Bildkomposition festlegt – ideal für schnelle Produktionen und die Iteration mehrerer Versionen

vidu-q3-ad/reference-to-video vidu-q3-mix/reference-to-video

vidu-q3-ad/reference-to-video ausprobieren

Eingabe

Ausgabe

Fülle die Parameter aus und generiere – die Ergebnisse erscheinen hier.

Preise

vidu-q3-ad/reference-to-video per second

Spezifikationen	Einzelpreis
1280*720	$0.149
1280*960	$0.149
1280*1280	$0.149
960*1280	$0.149
720*1280	$0.149
1920*1080	$0.180
1920*1440	$0.180
1808*1808	$0.180
1440*1920	$0.180
1080*1920	$0.180

Positionsprofil

Der Referenz-zu-Video-Pfad von Vidu Q3 richtet sich an die Kurzvideoproduktion, die kontrollierbare Bilder und stabile Motive benötigt. Entwickler übermitteln 1 bis 7 Referenzbilder sowie einen Prompt und erzeugen damit ein Video von 3 bis 15 Sekunden. Die Referenzbilder werden in der Reihenfolge des Arrays im Prompt als Image1, Image2 referenziert, um Charaktere, Objekte oder den Bildstil zu steuern. Die Ausgabe unterstützt zwei Stufen, 720P und 1080P, mit insgesamt zehn Bildformaten, optional kann Audio synchron zum Bild erzeugt werden, und ein fester Seed ermöglicht die Reproduktion der Ergebnisse. Geeignet für Teams, die Werbematerial, Produktdemos, kurze Charaktersequenzen und ähnliches benötigen und schnell mehrere Versionen testen möchten.

Zentrale Highlights

Mehrere Referenzbilder steuern Motiv und Stil – bis zu 7 Referenzbilder können gleichzeitig übergeben werden und werden in der Reihenfolge als Image1, Image2 im Prompt adressiert, um jeweils Charaktere, Objekte oder den Bildstil zu steuern.
Bild und Audio in einem Durchgang – nach Aktivierung von audio wird das Video synchron mit passendem Ton erzeugt; standardmäßig deaktiviert wird ein stummes Video ausgegeben, das sich anschließend selbst vertonen lässt.
Dauer und Bildformat nach Bedarf kombinierbar – wählbare Dauer von 3 bis 15 Sekunden, die Stufen 720P und 1080P umfassen jeweils fünf Bildformate: 16:9, 4:3, 1:1, 3:4 und 9:16.
Fester Seed für einfache Reproduktion und Iteration – ein Zufallsseed von 0 bis 2147483647 kann angegeben werden; bei identischer Konfiguration sind Ergebnisse reproduzierbar, was den Vergleich von Prompt-Änderungen erleichtert.

Funktionsbeschreibung

Generierung über mehrere Referenzbilder: akzeptiert 1 bis 7 öffentlich zugängliche Bilder im Format JPG, PNG oder WEBP mit maximal 50 MB pro Bild und einem Seitenverhältnis von 1:4 bis 4:1, um Charaktere, Objektaussehen oder den Gesamtstil festzulegen.

Prompt steuert Szene und Kameraführung: ein Prompt von bis zu 5000 Zeichen kann Szene, Aktion, Kamerabewegung und Ton beschreiben und über die Indizes Image1, Image2 konkrete Referenzbilder adressieren, sodass jede Abbildung eine eigene Aufgabe erhält.

Optionale Audioerzeugung: Der audio-Schalter steuert, ob passendes Audio zum Bild erzeugt wird; bei Deaktivierung wird ein stummes Video ausgegeben, was die Anbindung an eigene Vertonungs- oder Musikprozesse erleichtert.

Auflösungs- und Bildformatwahl: Der size-Parameter bietet die Stufen 720P und 1080P, die jeweils Querformat, Hochformat, Quadrat und zwei vertikale Seitenverhältnisse abdecken und so zu den Spezifikationen unterschiedlicher Platzierungen passen.

Dauer- und Wasserzeichensteuerung: duration liegt zwischen 3 und 15 Sekunden, watermark legt optional fest, ob unten rechts ein KI-Generierungshinweis eingeblendet wird; die Abrechnung erfolgt nach Ausgabesekunden.

Anwendungsfälle

Marken- und Kampagnenteams: mehrere Produktbilder + Verkaufsargumente – erzeugt kurze Werbeclips im gewünschten Bildformat für Social-Media-Kampagnen und Material für Produktdetailseiten im E-Commerce.
Charakter-Content-Ersteller: Charakterdesigns + Handlungsbeschreibung – erzeugt kurze Story-Shots mit konsistentem Charakteraussehen für Kurzserien, Konzeptvalidierung im Anime-Stil und Storyboard-Vorschauen.
Kreativteams: Stilreferenzen + Konzeptbeschreibung – erzeugt schnell mehrere Testversionen für A/B-Vergleiche, hält Variablen über einen festen Seed konstant und geht erst nach der Auswahl in die finale Produktion.
Produktdemo-Produktion: Produktfotos + Nutzungsszenariobeschreibung – verwandelt statische Produktbilder in Demo-Videos mit Kameraführung für Website, Produktpräsentationen und Schulungsmaterial.

Einschränkungen und Auswahlhinweise

Die Ausgabedauer pro Durchlauf ist auf 3 bis 15 Sekunden begrenzt und kann lange Videos oder durchgehende Multi-Shot-Erzählungen nicht direkt abdecken; das fertige Video muss noch manuell geschnitten und zusammengefügt werden. Referenzbilder müssen öffentlich zugänglich sein, pro Bild höchstens 50 MB groß; Bilder in privaten Speichern müssen zunächst in eine zugängliche Adresse umgewandelt werden. Audio ist optional; wenn Dialoge oder Vertonung präzise auf das Bild abgestimmt werden müssen, ist eine stumme Ausgabe mit separater Nachbearbeitung kontrollierbarer. Derzeit wird nur die Referenzbildsteuerung unterstützt, reine Texteingabe ist nicht möglich; für Ideen ohne Referenzmaterial sollte der Text-zu-Video-Pfad gewählt werden.

Generierungsaufgabe erstellen

POST https://api.hiapi.ai/v1/tasks

Header

AuthorizationstringPflicht

Account-API-Schlüssel. Bei jeder Anfrage erforderlich. Beispiel: Bearer YOUR_HIAPI_API_KEY. API-Schlüssel holen

Content-TypestringOptional

Der Anfragekörper wird immer als JSON geparst; beim Senden ist nur application/json (optional mit charset) zulässig — andere Werte liefern 415. Beispiel: application/json.

Idempotency-KeystringOptional

Idempotenz-Schlüssel, bis 255 Bytes. Wiederholungen mit demselben Schlüssel desselben Kontos erstellen die Aufgabe nur einmal; Replays liefern die ursprüngliche taskId.

Idempotenz-Schlüssel

Bei Netzwerk-Timeouts oder Client-Wiederholungen erstellt derselbe Schlüssel die Aufgabe nur einmal — keine doppelte Abbuchung (Geltungsbereich = das Konto des API-Schlüssels). Empfohlen: geschäftsseitig eindeutige Kennung (z. B. "order-42"); Replays liefern die ursprüngliche taskId, Schlüssel laufen 24 Stunden nach der ersten Anfrage ab. Die vollständige Szenariomatrix steht in der Übersicht der Unified Async API.

Body

modelstringPflicht

Aktueller Festwert: vidu-q3-ad/reference-to-video

routestringOptional

Aktueller Festwert: default

inputobjectPflicht

Geschäftsparameter für vidu-q3-ad/reference-to-video und Route default — siehe Parametertabelle unten.

seedintegerOptionalmin 0max 2147483647

Zufälliger Startwert zur Reproduktion der Generierungsergebnisse, gültige Werte von 0 bis 2147483647.

sizestringOptionalStandard: "1280*720"

Auflösung des Ausgabevideos im Format BREITE*HÖHE, in den Stufen 720P und 1080P; jede Stufe unterstützt 16:9, 4:3, 1:1, 3:4 und 9:16; der sekundenbasierte Preis variiert je nach Stufe. Standard: 1280*720.

Optionen:1280*7201280*9601280*1280960*1280720*12801920*10801920*14401808*1808

Alle anzeigen (2)

1440*19201080*1920

audiobooleanOptionalStandard: false

Ob eine zum Bild passende Tonspur generiert wird; bei Deaktivierung wird ein stummes Video ausgegeben. Standard: false.

promptstringPflichtminLength 1maxLength 5000

Beschreibt Szene, Bewegung, Kamera und Ton; Referenzbilder werden in der Reihenfolge des Arrays als Image1, Image2 usw. im Prompt referenziert.

durationintegerPflichtStandard: 5min 3max 15

Dauer des Ausgabevideos in Sekunden, gültige Werte von 3 bis 15. Standard: 5.

watermarkbooleanOptionalStandard: false

Ob in der unteren rechten Ecke ein KI-Generierungswasserzeichen hinzugefügt wird; standardmäßig deaktiviert. Standard: false.

reference_image_urlsarrayPflichtminItems 1maxItems 7

Array von Referenzbildern mit 1 bis 7 Bildern (Personen, Objekte oder Stile); jedes im Format JPG/PNG/WEBP, maximal 50MB, Seitenverhältnis 1:4 bis 4:1 und öffentlich zugänglich; im Prompt als Image1, Image2 usw. referenziert.

Array [ string ]

callbackobjectOptional

Konfiguration der Endzustands-Benachrichtigung. Ohne Angabe wird kein Callback gesendet — selbst abfragen.

Callbacks (Webhook)

Beim Erstellen callback.url angeben, dann POSTet HiAPI im Endzustand an Ihren Service — kein Polling nötig. Der Callback-Body entspricht der Aufgaben-Detailstruktur; Signaturprüfung, Wiederholungen und Idempotenz sind in der Übersicht der Unified Async API beschrieben.

urlstringPflicht

Pflicht, wenn callback angegeben ist. Nach dem Endzustand wird an diese URL gepostet; muss eine gültige http(s)-URL sein.

whenstringOptionalStandard: "final"

Derzeit wird nur final unterstützt — Benachrichtigung bei success und fail.

Optionen:final

storagestringOptionalStandard: "temp"

Speicherstufe für Artefakte: temp (Standard, ca. 7 Tage) oder persistent (langfristig, nach Größe abgerechnet). Bei unzureichendem Guthaben oder Überschreitung des Speicherlimits erfolgt ein stiller Downgrade auf temp; die wirksame Stufe steht in der Aufgaben-Detailantwort.

Optionen:temppersistent

Anfragebeispiele

# Asynchrone Aufgabe senden; gibt sofort eine taskId zurück (wartet nicht auf die Generierung)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "vidu-q3-ad/reference-to-video",
  "input": {
    "size": "1280*720",
    "audio": false,
    "prompt": "…",
    "duration": 5,
    "watermark": false,
    "reference_image_urls": "…"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "vidu-q3-ad/reference-to-video",
    input: {
      "size": "1280*720",
      "audio": false,
      "prompt": "…",
      "duration": 5,
      "watermark": false,
      "reference_image_urls": "…"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "vidu-q3-ad/reference-to-video",
        "input": {
          "size": "1280*720",
          "audio": False,
          "prompt": "…",
          "duration": 5,
          "watermark": False,
          "reference_image_urls": "…"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

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

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Aufgabendetails abrufen

GET https://api.hiapi.ai/v1/tasks/:id

Antwortfelder

taskIdstringPflicht

Aufgaben-ID, stets mit Präfix tk-hiapi-.

modelstringPflicht

Aufgelöster vollständiger Modellname. Mit route-Parameter eingereichte Aufgaben geben base@route zurück (z. B. gpt-image-2/text-to-image@ext); sonst identisch mit dem übermittelten Namen.

routestringOptional

Erscheint nur bei explizitem route-Parameter; gibt den übermittelten Wert zurück.

statusstringPflicht

Aufgabenstatus.

Statuswerte

queued Eingereiht, noch nicht gestartet. handling In Verarbeitung. archiving Verarbeitung abgeschlossen, Artefakte werden vorbereitet. success Endzustand: abgeschlossen, Artefakte verfügbar (output wird zurückgegeben). fail Endzustand: fehlgeschlagen (error wird zurückgegeben). Nach dem Senden den status prüfen: success und fail sind Endzustände, alles andere nicht. Alle 1–3 Sekunden bis zum Endzustand pollen. Nach Erfolg Artefakte aus output[].url laden und vor expireAt übertragen; für Langzeitaufbewahrung storage: "persistent" beim Erstellen angeben.

creatednumberPflicht

Zeitpunkt der Aufgabenerstellung (Unix-Sekunden).

completednumberPflicht

Unix-Sekunden des Endzustands; vor Abschluss stets 0.

outputarrayOptional

Nur bei status == success. Artefaktliste — immer ein Array; eine Aufgabe kann mehrere Typen gleichzeitig liefern (z. B. video + first_frame).

Array [ object ]

Array-Elemente

urlstringPflicht

Artefakt-URL, direkt herunterladbar.

typestringPflicht

Aktuell mögliche Werte: video, image, audio, first_frame, last_frame, thumbnail; später können weitere folgen.

expireAtnumberPflicht

Unix-Sekunden, bis wann das Artefakt verfügbar ist; vorher herunterladen oder übertragen.

errorobjectOptional

Nur bei status == fail.

codestringPflicht

Business-Fehlercode.

messagestringPflicht

Fehlerbeschreibung.

Antwortbeispiele

Erfolg

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

In Bearbeitung (nicht final)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Fehlgeschlagen

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}