Mit der V4V API erstellen.
Generiere Bilder, Videos und Audio aus deinen eigenen Anwendungen. Ein API-Schlüssel. Deine vorhandenen V4V-Credits.
https://v4v.ai/api/v1curl https://v4v.ai/api/v1/models \
-H "Authorization: Bearer $V4V_API_KEY"Authentifizierung
Erstelle unter Profile → API Keys einen benannten Schlüssel. Speichere das API-Secret und das Webhook-Signing-Secret, wenn sie angezeigt werden; sie werden nur einmal angezeigt. Mehrere Schlüssel können unabhängig voneinander erstellt und widerrufen werden. Schlüssel-Secrets werden als SHA-256-Hashes gespeichert.
Sende Authorization: Bearer v4v_live_… bei jeder API-Anfrage. Bewahre diesen Schlüssel auf deinem Server auf, außerhalb von Browseranwendungen und Quellcodeverwaltung. Ein Widerruf blockiert zukünftige Anfragen; bereits akzeptierte Generierungen laufen weiter.
Basis-URL: https://v4v.ai/api/v1.
Labor-Modelle entdecken
GET /models listet aktuelle Labor-Modell-IDs, Aktivierungsstatus, Eingaben, Parameter, Standardwerte, Bedingungen und Limits auf. GET /models/{model} beschreibt ein Modell. IDs und Schemas stammen aus demselben Katalog und denselben Standardwerten wie Labor. Die Studio-Konfiguration ist separat.
Modellnamen in den folgenden Beispielen sind echte Katalog-IDs. Verwende Discovery, um die aktuell für dein Konto aktivierten Modelle zu finden. Feldnamen sind modellspezifisch: Behalte die von Discovery zurückgegebenen Namen bei, einschließlich camelCase-Namen wie aspectRatio oder referenceImageUrls. Select-Werte sind Strings; numerische Werte für numerisch aussehende Select-Optionen werden ebenfalls akzeptiert. Felder können in input oder parameters übergeben werden, aber niemals in beiden. Unbekannte Felder werden abgelehnt. Modelle mit auswählbaren Versionen stellen parameters.variant bereit; verwende die von Discovery zurückgegebenen Werte und Standardwerte.
curl https://v4v.ai/api/v1/models \
-H "Authorization: Bearer $V4V_API_KEY"Zeitgesteuerte Sprachuntertitel
Ermittle ai.speech_to_text mit Typ subtitle. Übermittle eine dir gehörende Medien-Datei-ID oder eine unterstützte URL in input.audioUrl oder input.videoUrl an POST /lab; optionale Parameter sind unter anderem language_code (zum Beispiel uk, en oder auto) und diarize. Die Schätzung verwendet die ursprüngliche Quelldauer. Für die Transkription werden normale Konto-Credits verbraucht.
Eine abgeschlossene Aufgabe gibt results[].type: "subtitle", das Transkript text, srt und bearbeitbare cues mit start, end in Sekunden und text zurück. Bei erfolgreicher stiller Eingabe kann die Cue-Liste leer sein. Für Montagen verwende die MCP-Tools des Video Editors, um diese Cues auf Trim, Geschwindigkeit und Timeline-Position eines Quellclips abzustimmen.
Neueste Generierungsmodelle
Omni Flash 1.2 (video.gemini_omni_flash-1-2) ist das bevorzugte Modell für Videoanfragen ohne explizites Modell. Im Labor steht es an erster Stelle; Omni Flash 1.1 bleibt unter Mehr und über seine bestehende ID verfügbar. Ermittle aktuelle Parameter mit GET /models/{model}. Version 1.2 unterstützt Generierung und Bearbeitung von 3–15 Sekunden; die Interpolation von erstem/letztem Frame ist auf 10 Sekunden begrenzt. Gemeinsame 4/6/8/10-Sekunden-Tarife entsprechen den konfigurierten 1.1-Preisen. Verwende aktuelle Discovery- und Schätzdaten für Preise, statt diese Beziehung als dauerhafte Regel zu speichern.
Wähle GPT Image 2.6 über parameters.variant in image.text_to_image oder ai.image_edit. Verwende parameters.outputFormat mit diesen exakten Variantenfähigkeiten:
| Variante | Ausgabeformate |
|---|---|
gpt-image-2.6-flare-text | png, jpeg, webp, gif, svg |
gpt-image-2.6-sunburst-text | png, jpeg, webp, gif, svg |
gpt-image-2.6-flare-img | png, jpeg, webp |
gpt-image-2.6-sunburst-img | png, jpeg, webp |
gpt-image-2.6-economy-text | png, gif |
gpt-image-2.6-economy-img | png |
parameters_schema.outputFormat.allowed_by_variant ist maßgeblich. Flare/Sunburst werden anhand der tatsächlichen Ein-/Ausgabenutzung abgerechnet; die SVG-Konvertierungsnutzung ist im Endbetrag enthalten. Economy ist nur in 1K mit Preis pro Bild verfügbar. Downloads behalten GIF-Frames und SVG-Vektor-Bytes bei; SVG-Downloads verwenden attachment-Auslieferung.
Nano Banana 2.1 verwendet parameters.variant: "nano-banana-v2.1" in denselben Bildmodulen, mit bis zu 10 Referenzen und 1K/2K/4K-Ausgabe. Sein aktueller Abrechnungsmodus wird in veröffentlicht. Google/Vertex-Generierung wird anhand verifizierter Eingabe, gecachter Eingabe, Bildausgabe, Textausgabe und Thinking-Tokens abgerechnet, mit angewendetem Aufschlag und einmaligem Aufrunden der Gesamtsumme. Die Bildausgabe-Komponente beträgt vor Eingabe und Thinking ungefähr 11/16/36 V4V-Credits für 1K/2K/4K. Labor und Schätzungen zeigen einen ungefähren Bereich; die anfängliche Reservierung ist vom Endpreis getrennt. Andere Weiterleitung verwendet den konfigurierten Preis-pro-Bild-Tarif. Das Routing bleibt von V4V verwaltet; gib keinen Routing-Parameter an.
Kling 4.0 Videomodelle
Vier separate Knoten teilen sich dieselbe Generierung und Ergebnisbehandlung in Labor, Workflows, API und MCP:
| Katalog-ID | Modell | Dauer | Auflösung |
|---|---|---|---|
video.kling_v40_ref | Kling 4.0 Reference | 3–30 Sekunden | 720p / 1080p |
video.kling_v40_key | Kling 4.0 Keyframe | 3–30 Sekunden | 720p / 1080p |
video.kling_v40_flash_ref | Kling 4.0 Flash Reference | 3–20 Sekunden | 720p |
video.kling_v40_flash_key | Kling 4.0 Flash Keyframe | 3–20 Sekunden | 720p |
Alle akzeptieren ein erforderliches prompt (bis zu 8000 Zeichen), ganzzahliges duration, resolution und aspectRatio (auto, 16:9, 9:16, 1:1, 21:9; Flash Keyframe schließt auto aus). Alle können allein aus Text generieren. Referenzeingaben sind optional.
Referenzmodelle akzeptieren referenceImageUrls (bis zu 10), referenceVideoUrls (bis zu 5), elements (bis zu 7, bei Video höchstens 3) und keepOriginalSound. Ein benanntes Element hat name, entweder imageUrls (2–4 Bilder) oder videoUrl (ein 3–8 s langer Charakter-Clip), optional tag, description (100 Zeichen) und das Charakter-voiceUrl. Flash akzeptiert zusätzlich Element-type (image oder video). Standard Reference akzeptiert zusätzlich voices: bis zu 3 Objekte mit name und audioUrl. Flash bindet Stimmen stattdessen an Charakterelemente.
Es gibt höchstens 15 kombinierte Bilder, Videoreferenzen, Elemente und eigenständige Stimmen; Referenzvideos plus Videoelemente dürfen 5 nicht überschreiten. Jedes Referenzvideo muss 2–30 s lang sein (2–20 s für Flash), und ihre Gesamtdauer einschließlich Videoelementen beträgt höchstens 30 s (20 s für Flash). Namen müssen eindeutig sein, ohne Beachtung der Groß-/Kleinschreibung, und 1–20 chinesische Zeichen, Buchstaben, Ziffern oder Unterstriche enthalten; integrierte Referenznamen sind reserviert. Erwähne bereitgestellte Referenzen als , oder ihren deklarierten . Nicht deklarierte Erwähnungen werden abgelehnt.
GPT-6 Astra-Chat
Ermittle chat.gpt_6_astra mit GET /models/chat.gpt_6_astra (Slug: gpt-6-astra). Es hat den Typ chat und gibt Text zurück. Discovery enthält Token-Raten und die Rundungsregel.
{
"model": "chat.gpt_6_astra",
"input": {
"prompt": "Explain what is in this image.",
"imageUrls": [
"https://example.com/image.png"
]
},
"parameters": {
"reasoningEffort": "high",
"webSearch": true,
"stream": false
}
}Send this body to POST /lab. Images are optional; up to 12 URLs or owned file IDs are accepted. Text-only requests use string input upstream; image requests use an array of message content. Reasoning effort: low, medium, high, xhigh (default low). Web search and streaming default to false. Streamed responses are returned as a completed task after generation finishes.
Um eine Funktion anzubieten, übergib input.functionTools als JSON-String mit 1–10 Definitionen mit type: "function", name, description und parameters (ein Objekt-JSON-Schema). Setze parameters.webSearch auf false. Die Upstream-Anfrage verwendet tool_choice: "auto"; Funktionsanfragen werden in results[].function_calls zurückgegeben, damit deine Anwendung sie verarbeitet. Der Modell-Knoten führt keine Funktionen aus und setzt die Konversation nicht mit einem Funktionsergebnis fort.
Chat reserviert 1 Credit, bevor es in die Warteschlange eintritt. Dies ist eine Mindestreservierung, kein Festpreis oder Ausgabenlimit. Preise pro 1M Token: Eingabe 560, gecachte Eingabe 56, Cache-Schreibvorgänge 700, Ausgabe 2,800 Credits. Die kombinierten Token-Kosten werden einmalig auf einen ganzen Credit aufgerundet, mit einer Mindestgebühr von 1. Nach der Antwort wird jede zusätzliche Gebühr atomisch vom verfügbaren Guthaben abgezogen. Ist das Guthaben nicht ausreichend, schlägt die Aufgabe fehl und die nicht genutzte Reservierung wird freigegeben.
Für nutzungsbasierte Preise bei Chat und Bildern gibt der Schätzendpunkt außerdem credits_range mit min, max, assumptions, includes_markup: true, is_estimate: true und is_spending_cap: false zurück. Zeige dies als ungefähren Bereich in V4V-Credits an. Er enthält den aktuellen Aufschlag und Preisanpassungen. Dies sind illustrative Nutzungsszenarien; die tatsächlichen Kosten können außerhalb des Bereichs liegen. und beschreiben die anfängliche Reservierung separat. Der Bereich verändert weder die Abrechnung nach tatsächlicher Nutzung noch ermöglicht er eine Zulassung mit festem Budget.
LAB mit einem externen Bild
Medieneingaben akzeptieren im selben Feld eine externe URL oder eine V4V-Datei-ID. Arrays können beides mischen. URLs müssen echte Mediendateien ohne Browser-Cookies oder interaktiven Login zurückgeben. HTTPS und ausreichend langlebige signierte URLs werden empfohlen. V4V validiert und kopiert externe Medien vor der Generierung; URLs aus internen Netzwerken und unsichere Weiterleitungen werden abgelehnt.
curl https://v4v.ai/api/v1/lab \
-H "Authorization: Bearer $V4V_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: product-edit-001' \
-d '{"model":"ai.image_edit","input":{"prompt":"Place this product on a marble counter","referenceImageUrls":["https://example.com/product.jpg"]},"parameters":{"variant":"nano-banana-2","aspectRatio":"9:16","resolution":"2K"}}'Private Medien hochladen
POST /files akzeptiert ein Feld file mit multipart/form-data. Bilder, Video und Audio werden unterstützt, vorbehaltlich der Modellgrenzen. Das Standard-Upload-Limit beträgt 100 MiB und wird zusätzlich durch das Storage-Upload-Limit und das Proxy-Limit der Bereitstellung eingeschränkt. Dateien müssen dekodierbare Medien enthalten; die Prüfung von Audio/Video erfordert ffprobe auf dem Server.
curl https://v4v.ai/api/v1/files \
-H "Authorization: Bearer $V4V_API_KEY" \
-F 'file=@product.png'{
"id": "6aa962444bd1dd7ab65bc6b6",
"type": "image",
"content_type": "image/png",
"size": 123456
}Verwende die zurückgegebene ID direkt, ohne Präfix file_. GET /files/{id} ruft die Metadaten deiner Datei ab, ohne Credits zu berechnen.
{
"model": "ai.image_edit",
"input": {
"prompt": "Create a studio product photograph",
"referenceImageUrls": [
"6aa962444bd1dd7ab65bc6b6",
"https://example.com/side.jpg"
]
},
"parameters": {
"variant": "nano-banana-2"
}
}Studio mit externen oder privaten Medien
POST /studio verwendet denselben ausgewählten Studio-Workflow, dieselbe Vorbereitung, dieselbe Modellausführung, denselben Preis-Multiplikator und denselben Abonnementrabatt wie die Studio-Benutzeroberfläche.
{
"input": {
"product_name": "Example Product",
"product_description": "Lightweight everyday backpack",
"product_images": [
"https://example.com/front.jpg",
"6aa962444bd1dd7ab65bc6b6"
],
"prompt": "Show the product in everyday use"
},
"parameters": {
"duration": 10,
"aspect_ratio": "9:16",
"style": "UGC",
"language": "en",
"avatar": null
},
"callback_url": "https://partner.example/webhooks/v4v"
}Für einen vollständig privaten Medienfluss lade zuerst jedes Produktbild mit POST /files hoch und setze dann die zurückgegebenen IDs in input.product_images ein. Lade Avatar-, Audio- und Videoreferenzen auf dieselbe Weise hoch.
Studio akzeptiert product_id (ein eigenes gespeichertes Produkt), avatar_id (einen eigenen oder aktiven öffentlichen Bibliotheks-Avatar, mit unterstütztem Präfix public:), product_name, product_description, prompt, product_images, reference_images, avatar_media, audio und video. Jedes Medienfeld akzeptiert Referenzen; Arrays unterstützen mehrere Dateien. parameters.avatar akzeptiert eine Bibliotheks-Avatar-ID, eine einzelne Bild-URL oder Datei-ID oder null. Wähle entweder input.avatar_id oder parameters.avatar. Explizite Produktfelder überschreiben Bibliotheks-Standardwerte. Aktive Stilnamen/-IDs wenden die gespeicherten Stil-Anweisungen an. Unbekannte, inaktive und leere Stilwerte geben 422 INVALID_PARAMETER, field: "parameters.style" und error.allowed_values mit den aktiven IDs/Namen zurück. Lasse style weg, um den aktuellen Standard zu verwenden (UGC, wenn aktiv, sonst das erste aktive Preset). Zu den Parametern gehören außerdem style, language, voice, placement, duration, aspect_ratio und quality.
Migration für Clients, die zuvor Freitext in parameters.style übergeben haben: Verschiebe diese kreative Vorgabe nach und wähle einen aktiven Stil aus MCP (oder lasse style für den aktuellen Standard weg). Ein falsch geschriebener Stil wird nicht mehr zu einem benutzerdefinierten Stil.
Aufgaben und Credits
Die Generierung gibt nach der Eingabevalidierung und, wenn Kapazität verfügbar ist, nach der Credit-Reservierung HTTP 202 zurück, ohne auf die Generierung zu warten:
{
"task_id": "task_6aa962444bd1dd7ab65bc6b6",
"status": "queued",
"credits_reserved": 20,
"created_at": "2026-09-15T18:00:00Z"
}Optionaler Projektname
Sowohl POST /lab als auch POST /studio akzeptieren project_name auf der obersten Ebene, zusammen mit input, parameters und callback_url:
{
"project_name": "Summer campaign — product photo",
"model": "image-upscale-topaz",
"input": {
"image_url": "https://example.com/product.png"
},
"parameters": {
"upscale_factor": "2"
}
}Der getrimmte Name (1–200 Zeichen, nicht leer) wird zum Titel in Projekte und bei LAB für frühere Ausführungen. Wenn er weggelassen wird, wird der bestehende Standardtitel verwendet. Die Aufgabenantwort enthält project_name und project_id. Das Ändern des Namens mit demselben Idempotency-Schlüssel ist ein Konflikt, genau wie das Ändern der Generierungseingaben.
Aufgabenstatus
Der Server aktualisiert den Generierungsstatus im Hintergrund. Polling gibt den zuletzt gespeicherten status zurück: queued, processing, completed, failed oder cancelled. Solange die Aufgabe queued oder processing ist, zeige einen Ladeindikator. Wenn status gleich completed ist, lies Chat-Text aus results[].text oder lade Mediendateien von results herunter. Für failed prüfe error (einschließlich des fehlgeschlagenen stage, brief_completed, retryable und des vorgeschlagenen retry_after_seconds, soweit bekannt) und credits_used. Eine erfolgreiche kurze Generierung kann ihre Belastung behalten, wenn das Rendering fehlschlägt; ein vorübergehender Retry-Hinweis startet oder autorisiert keinen neuen kostenpflichtigen Versuch. cancelled ist ebenfalls terminal.
Webhooks sind optional. Ohne callback_url wiederhole die folgende Anfrage alle 3–5 Sekunden, bis status gleich completed, oder ist:
Projekte umbenennen und organisieren
Die Projektorganisation verwendet dieselben Ordner wie der Workspace Projects. Dabei werden keine Medien generiert, keine Credits reserviert und weder Generierungseingaben, Ergebnisse noch Idempotenz-Hashes geändert. Für alle Vorgänge ist dein API-Schlüssel erforderlich, und es wird nur auf die Projekte und Ordner deines Kontos zugegriffen.
| Methode und Pfad | Zweck |
|---|---|
GET /projects | Studio-, Workflow- und Labor-Projekte finden, einschließlich API-Aufgaben in der Warteschlange |
PATCH /projects/{project_id} | Ein Projekt umbenennen und/oder in einen Ordner verschieben |
GET /project-folders | Workspace-Ordner auflisten |
POST /project-folders | Einen Ordner mit {"name":"Summer campaign"} erstellen |
PATCH /project-folders/{folder_id} | Einen Ordner mit {"name":"Autumn campaign"} umbenennen |
Beide Listen-Endpunkte akzeptieren offset (Standard 0) und limit (1–100, Standard 50) und geben total sowie next_offset zurück (null auf der letzten Seite). Projekte werden zuerst nach dem neuesten Eintrag sortiert, mit einer stabilen ID als Tie-Breaker; Ordner werden nach Namen sortiert. Projektfilter sind source=all|studio|workflow|lab, q (wörtliche, nicht zwischen Groß- und Kleinschreibung unterscheidende Titelsuche, bis zu 200 Zeichen) und folder_id (eine eigene Ordner-ID oder unfiled für keinen Ordner). Lass folder_id weg, um alle Ordner einzubeziehen.
GET /projects gibt projects mit project_id, project_name, source, folder_id (String oder null), status, created_at und updated_at zurück. Der Status spiegelt das ursprüngliche Projekt oder den Labor-Verlauf wider; verwende GET /tasks/{task_id} für den Generierungsstatus. Verwende für Aktualisierungen das zurückgegebene ; ältere Labor-Einträge ohne zugrunde liegendes Projekt verwenden ihre Labor-Run-ID. gibt mit , , , und zurück.
Idempotenz
Sende Idempotency-Key (1–200 Zeichen), wenn du Labor- oder Studio-Anfragen absendest. Dasselbe Konto, derselbe Schlüsselwert, Endpunkt und JSON-Inhalt geben die ursprüngliche Aufgabe zurück, auch über verschiedene API-Schlüssel dieses Kontos hinweg. Die Reihenfolge von Objekteigenschaften wird ignoriert. Wenn ein Schlüssel für unterschiedlichen Inhalt wiederverwendet wird, wird HTTP 409 IDEMPOTENCY_CONFLICT zurückgegeben. Wenn die ursprüngliche Anfrage noch validiert wird, fordert HTTP 409 REQUEST_IN_PROGRESS dich auf, es mit demselben Schlüssel erneut zu versuchen. Eine abgelehnte Übermittlung bleibt ihrem Schlüssel zugeordnet; korrigiere sie mit einem neuen Schlüssel.
Persistente eindeutige Indizes verhindern, dass gleichzeitige Wiederholungen eine weitere Generierung oder Reservierung erzeugen. Idempotenzdatensätze bleiben im Aufgabenverlauf erhalten.
Signierte Callbacks
Gib optional ein öffentliches callback_url an. V4V sendet task.completed oder task.failed mit den Aufgabenfeldern, der Ergebnisliste und dem stabilen event_id. Callbacks enthalten die Header X-V4V-Timestamp und X-V4V-Signature: v1=<hex>. Verifiziere sie mit dem Webhook-Signaturschlüssel, der beim Erstellen des API-Schlüssels angezeigt wurde.
Die Signatur ist HMAC-SHA256 über den Zeitstempel, einen wörtlichen Punkt und den exakten unverarbeiteten Request-Body. Weise veraltete Zeitstempel zurück (zum Beispiel älter als fünf Minuten) und vergleiche Signaturen in konstanter Zeit.
import crypto from 'node:crypto';
const expected = crypto.createHmac('sha256', webhookSecret)
.update(`${timestamp}.${rawBody}`).digest('hex');
const valid = /^v1=[a-f0-9]{64}$/.test(signature)
&& Math.abs(Date.now() / 1000 - Number(timestamp)) < 300
&& crypto.timingSafeEqual(Buffer.from(signature.slice(3), 'hex'), Buffer.from(expected, 'hex'));Gib zügig eine 2xx-Antwort zurück. Die Zustellung erfolgt mindestens einmal: dedupliziere nach event_id. Netzwerkfehler, Timeouts, HTTP 408/429 und 5xx-Antworten werden mit exponentiellem Backoff wiederholt, beginnend bei 30 Sekunden und begrenzt auf eine Stunde, standardmäßig bis zu 12 Versuche lang. Andere Antworten ohne Erfolg, einschließlich Weiterleitungen, beenden die Zustellung. Wiederholungen erzeugen niemals Generierungen und belasten keine Credits. Frage den Aufgabenstatus ab, wenn die Callback-Zustellung ausgeschöpft ist.
Studio-Batch-Callbacks
POST /studio/batches akzeptiert außerdem ein optionales callback_url. Es gilt dieselbe Prüfung signierter Callbacks. Ereignisse sind batch.updated, batch.completed, batch.paused und batch.cancelled, mit einem stabilen event_id, batch_id, batch_revision, observed_at, state_token, Anzahlen und Credit-Summen. Lies GET /studio/batches/{batch_id} für die aktuellen paginierten Ergebnisse. Ereignisse enthalten kompakte Snapshots statt ablaufender Download-URLs; zwischen Worker-Ticks können Zwischenänderungen zusammengefasst werden.
Die Zustellung ist dauerhaft und wird unabhängig von der Generierung erneut versucht. Dedupliziere nach event_id und toleriere Ereignisse außerhalb der Reihenfolge; bei wiederholter Zustellung bleibt derselbe Body erhalten. Langsame oder ausfallende Empfänger erzeugen keine neuen Generierungen und blockieren die Generierungswarteschlange nicht. Eine Stornierung kann ein weiteres Update auslösen, wenn bereits zugelassene Arbeit abgeschlossen wird. Ein später angeforderter Neustart oder eine Überarbeitung reaktiviert die Überwachung. Ein Webhook ist eine HTTP-Integration und weckt für sich genommen keinen beendeten Browser-Chat wieder auf.
Fehler und Limits
Fehler verwenden ein einheitliches Format:
{
"error": {
"code": "INVALID_PARAMETER",
"message": "Allowed values: 5, 10.",
"field": "parameters.duration"
}
}HTTP 400/422 weist auf ungültige Eingaben oder Parameter hin; 401 auf einen ungültigen/zurückgezogenen Schlüssel; 402 auf unzureichende Credits; 403 auf deaktivierte Modelle oder verweigerten Zugriff; 404 auf nicht verfügbare Modelle/Dateien/Aufgaben; 409 auf einen Idempotenzkonflikt oder laufende Validierung; 429 auf ein Raten-/Gleichzeitigkeitslimit; 500 auf einen internen Fehler; und 503 auf eine vorübergehende Nichtverfügbarkeit des Dienstes. Fehlercodes umfassen INVALID_API_KEY, INSUFFICIENT_CREDITS, MODEL_NOT_FOUND, MODEL_DISABLED, INVALID_INPUT, INVALID_PARAMETER, INVALID_MEDIA_URL, MEDIA_NOT_ACCESSIBLE, UNSUPPORTED_MEDIA_TYPE, MEDIA_TOO_LARGE, FILE_NOT_FOUND, FILE_ACCESS_DENIED, RATE_LIMIT_EXCEEDED, GENERATION_FAILED, GENERATION_SERVICE_ERROR und SERVICE_UNAVAILABLE. GENERATION_SERVICE_ERROR kennzeichnet einen gemeldeten internen Fehler des Modell-Dienstes; daraus lässt sich nicht ableiten, dass die Eingabegröße oder die Parameter ungültig waren. Fehlende und unzugängliche Datei-IDs teilen sich dieselbe 404-Antwort, damit keine Dateien anderer Konten offengelegt werden.
Default limits are 120 requests per minute per key, 10 generation submissions per minute per account, and 3 concurrent accepted generations per account. Every HTTP 429 includes error.retryable and a positive integer error.retry_after_seconds; the HTTP Retry-After header uses the same value. Request-window errors also return reason: "request_rate_limit", the configured limit, and a public scope (key, generation, bulk, mcp-upload-link or mcp-upload), without internal account/key IDs. The retry delay is the rounded-up time remaining in the minute window, not always 60 seconds. MCP tool errors preserve these fields in their JSON even when HTTP headers are unavailable. Account contention uses its own reason: "account_busy" and one-second delay. Generation capacity is handled separately by the durable queue; wait for the accepted task rather than resubmitting it.
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "API rate limit exceeded. Retry after 18 seconds.",
"reason": "request_rate_limit",
"scope": "key",
"limit": 120,
"retryable": true,
"retry_after_seconds": 18
}
}Bei Ablehnungen im Anfragefenster (vor der Aufgabenerstellung) warte die angegebene Verzögerung ab und verwende denselben Idempotenzschlüssel und dieselben Argumente erneut. Eine Antwort, die auf eine bereits fehlgeschlagene Aufgabe verweist, ist für diese Aufgabe endgültig. Dies autorisiert keinen weiteren kostenpflichtigen Versuch nach einem endgültigen Generierungsfehler.
Studio-Massengenerierung (API und MCP)
Massengenerierung ist über die API und MCP verfügbar. In der Studio-Oberfläche gibt es noch keinen Workspace für Massengenerierung. Reiche bis zu 300 Produkte in einer JSON-Anfrage ein. Jedes Element erstellt einen Studio-Workflow mit eigener Aufgabe, gespeichertem Workflow/Einstellungen, Ergebnissen und Credit-Abrechnung. Produktimport und Referenz-Downloads erfolgen im Hintergrund; ein ungültiges Element schlägt unabhängig fehl, während die übrigen Elemente fortfahren.
Studio, LAB, REST, MCP, Shopify und Avatar-Generierung teilen sich eine persistente Serverwarteschlange mit einer absoluten Obergrenze von 10 aktiven Generierungsanfragen für dieses Deployment. Das Warten auf ein Generierungsergebnis belegt einen Slot. Eine abgeschlossene Generierung gibt diesen Slot frei, auch wenn ihre Datei noch gespeichert wird. Normale Anfragen haben Vorrang vor Bulk-Anfragen; Bulk nutzt die verfügbare Kapazität, vorbehaltlich globaler Bulk-Limits und Pro-Konto-Limits eines Administrators. Die Standardwerte sind 2 gleichzeitige Bulk-Workflows und 1 pro Konto. Mehrere Batches eines Kontos teilen sich dieses Limit. Die Verarbeitung läuft ohne offenen Browser oder Client-Polling weiter.
Einen Batch erstellen
POST /api/v1/studio/batches — gibt HTTP 202 zurück. Gib einen erforderlichen Idempotency-Key-Header mit 1–200 Zeichen an. Verwende nach einer Netzwerkunterbrechung denselben Schlüssel und identisches JSON erneut. Ein geänderter Body mit demselben Schlüssel gibt HTTP 409 zurück; die Annahme erstellt bei einer Wiederholung niemals einen zweiten Batch.
curl "$V4V_BASE_URL/api/v1/studio/batches" \
-H "Authorization: Bearer $V4V_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: autumn-catalogue-001' \
--data '{
"name": "Autumn catalogue",
"max_credits": 600,
"input": { "prompt": "Show three benefits of this product in a calm reveal" },
"parameters": { "duration": 8, "aspect_ratio": "9:16", "quality": "720p" },
"items": [
{ "sku": "MUG-01", "product_id": "0123456789abcdef01234567" },
{ "sku": "BAG-02", "product_url": "https://shop.example/products/bag?variant=blue" },
{
"sku": "LAMP-03",
"input": {
"product_name": "Desk lamp",
"product_description": "Adjustable warm light",
"product_images": ["https://shop.example/lamp.jpg"]
},
"parameters": { "style": "TV Spot" }
}
]
}'Verwende die Dauer, das Format und die Qualität, die vom aktuellen Studio-Workflow deines Deployments unterstützt werden, wie bei POST /api/v1/studio. Das Beispiel kalkuliert 600 Credits für drei 8-sekündige 720p-Omni-Clips: 3 × 180 = 540 Credits, mit 60 Credits Puffer. Drei 10-sekündige Clips in 720p verwenden 675 Credits; in 1080p 990 und in 4K 1.980, jeweils vor Preisen für Referenzvideos, zusätzlichen Schritten oder Wiederholungen. Hole immer aktuelle Schätzungen für die genauen Eingaben ein, bevor du ein Batch-Budget festlegst.