Zur Dokumentation springen
v4v.EntwicklerdokumentationVORSCHAUDeine API-Schlüssel ↗
IN DIESEM LEITFADEN
AuthentifizierungLabor-Modelle entdeckenZeitgesteuerte SprachuntertitelNeueste GenerierungsmodelleKling 4.0 VideomodelleGPT-6 Astra-ChatLAB mit einem externen BildPrivate Medien hochladenStudio mit externen oder privaten MedienAufgaben und CreditsProjekte umbenennen und organisierenIdempotenzSignierte CallbacksFehler und LimitsStudio-Massengenerierung (API und MCP)
Zum Testen verfügbar
Vorschau mit Direktzugriff
API reference · v1

Mit der V4V API erstellen.

Generiere Bilder, Videos und Audio aus deinen eigenen Anwendungen. Ein API-Schlüssel. Deine vorhandenen V4V-Credits.

Loslegen →OpenAPI herunterladen ↓
ENDPUNKThttps://v4v.ai/api/v1
cURL
curl https://v4v.ai/api/v1/models \
  -H "Authorization: Bearer $V4V_API_KEY"
01

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.

02

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.

bash
curl https://v4v.ai/api/v1/models \
  -H "Authorization: Bearer $V4V_API_KEY"
03

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.

04

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:

VarianteAusgabeformate
gpt-image-2.6-flare-textpng, jpeg, webp, gif, svg
gpt-image-2.6-sunburst-textpng, jpeg, webp, gif, svg
gpt-image-2.6-flare-imgpng, jpeg, webp
gpt-image-2.6-sunburst-imgpng, jpeg, webp
gpt-image-2.6-economy-textpng, gif
gpt-image-2.6-economy-imgpng

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.

05

Kling 4.0 Videomodelle#

Vier separate Knoten teilen sich dieselbe Generierung und Ergebnisbehandlung in Labor, Workflows, API und MCP:

Katalog-IDModellDauerAuflösung
video.kling_v40_refKling 4.0 Reference3–30 Sekunden720p / 1080p
video.kling_v40_keyKling 4.0 Keyframe3–30 Sekunden720p / 1080p
video.kling_v40_flash_refKling 4.0 Flash Reference3–20 Sekunden720p
video.kling_v40_flash_keyKling 4.0 Flash Keyframe3–20 Sekunden720p

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.

06

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.

json
{
  "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.

07

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.

bash
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"}}'
08

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.

bash
curl https://v4v.ai/api/v1/files \
  -H "Authorization: Bearer $V4V_API_KEY" \
  -F 'file=@product.png'
json
{
  "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.

json
{
  "model": "ai.image_edit",
  "input": {
    "prompt": "Create a studio product photograph",
    "referenceImageUrls": [
      "6aa962444bd1dd7ab65bc6b6",
      "https://example.com/side.jpg"
    ]
  },
  "parameters": {
    "variant": "nano-banana-2"
  }
}
09

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.

json
{
  "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.

10

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:

json
{
  "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:

json
{
  "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:

11

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 PfadZweck
GET /projectsStudio-, 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-foldersWorkspace-Ordner auflisten
POST /project-foldersEinen 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.

12

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.

13

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.

javascript
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.

14

Fehler und Limits#

Fehler verwenden ein einheitliches Format:

json
{
  "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.

json
{
  "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.

15

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.

bash
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.

V4V / API reference · v1Baue etwas, das es wert ist, gesehen zu werden.
pricing_by_variant

Gemini 4 Argon (chat.gemini_4_argon) ist ebenfalls über Labor, Workflows und API/MCP verfügbar. Seine Nutzung für Eingabe, gecachte Eingabe, Ausgabe und Thinking wird nach der Antwort abgerechnet. Lies aktuelle Preise, Startdaten und Ratenanpassungen aus der Modell-Discovery.

@image_1
@video_1
@name

Keyframe-Modelle verwenden firstFrameUrl. Standard Keyframe akzeptiert zusätzlich geordnete keyframeUrls (bis zu 8 Zwischenframes) und lastFrameUrl; dafür ist ein erstes Frame erforderlich. Die Gesamtzahl der Frames darf min(duration + 1, 10) nicht überschreiten. Flash Keyframe unterstützt nur das erste Frame. Erwähne Frames als @first_frame, @keyframe_1, @last_frame. Die Frame-basierte Ausgabe folgt dem Seitenverhältnis des ersten Bildes.

Alle Medienfelder, einschließlich verschachtelter Elemente und Stimmen, akzeptieren in API/MCP URLs oder eigene V4V-Datei-IDs. Workflow-Bild-/Video-Ports verwenden reference_image_urls / reference_video_urls oder first_frame_url / keyframe_urls / last_frame_url; Prompts verwenden script-in. Standard Reference akzeptiert zusätzlich Audio auf voice_audio_urls, deklariert als @voice_1, @voice_2 usw. Beide Workflow-Ausgaben sind standardmäßige video / clips, geeignet für den vorhandenen Renderer und Editor. API/MCP geben die üblichen asynchronen Aufgaben und herunterladbaren Ergebnisdateien zurück; frage die Aufgabe ab oder verwende Abschluss-Webhooks.

Genehmigte Basisraten in V4V-Credits pro Sekunde, vor Überschreibungen durch Administratoren oder bestehenden Workflow-Anpassungen. Diese Raten werden direkt verwendet, ohne USD-Umrechnung oder Einzelhandelsaufschlag:

Modell720p, ohne Video720p, mit Video1080p, ohne Video1080p, mit Video
Standard Reference28.51742.525.5
Standard Keyframe28.5nicht verfügbar42.5nicht verfügbar
Flash Reference1711.3nicht verfügbarnicht verfügbar
Flash Keyframe17nicht verfügbarnicht verfügbarnicht verfügbar

Beispiele für eine Ausgabe von 5 Sekunden:

Modell5 s ohne Quellvideo5 s mit bis zu 5 s Quellvideo
Standard Reference, 720p142.5 Credits170 Credits
Standard Reference, 1080p212.5 Credits255 Credits
Standard Keyframe, 720p / 1080p142.5 / 212.5 Creditsnicht verfügbar
Flash Reference, 720p85 Credits113 Credits
Flash Keyframe, 720p85 Creditsnicht verfügbar

Ohne Videoeingabe entsprechen abrechenbare Sekunden den Ausgabesekunden. Mit Referenzvideo oder einem Videoelement entsprechen die abrechenbaren Sekunden max(total input video seconds, output seconds) + output seconds, zum entsprechenden Tarif mit Videoeingabe. Zum Beispiel sind bei einer 10-s-1080p-Standard-Reference-Ausgabe mit 15 s Eingabe 25 abrechenbare Sekunden 637.5 Credits vor Anpassungen. Bruchteile von Credits bleiben erhalten; die vollständige Belastung wird nur einmal auf zwei Dezimalstellen gerundet. Bei unbekannter Eingabedauer wird für eine konservative Schätzung die maximal zulässige Eingabedauer des Modells verwendet; der Server prüft die tatsächlichen Quelldauern vor der Belastung. Fordere ein aktuelles Angebot mit denselben Eingaben wie für die Generierung an. Die Administration stellt für jeden Knoten separate Tarife für Auflösung/Videoeingabe bereit. Ältere Kling-Knoten behalten ihre bestehenden Preise und Einstellungen.

json
{
  "model": "video.kling_v40_key",
  "input": {
    "prompt": "Move from @first_frame to @keyframe_1 and finish at @last_frame",
    "firstFrameUrl": "https://example.com/start.png",
    "keyframeUrls": [
      "https://example.com/middle.png"
    ],
    "lastFrameUrl": "https://example.com/end.png"
  },
  "parameters": {
    "duration": 5,
    "resolution": "1080p",
    "aspectRatio": "16:9"
  }
}

Verwende diesen Body mit generate_lab in MCP oder POST /api/v1/lab in HTTP. Für ein Angebot füge "source": "lab" hinzu und verwende estimate_generation in MCP oder POST /api/v1/generation/quote in HTTP. Ermittle das ausgewählte Modell immer zuerst mit get_model oder GET /api/v1/models/{id}. Es gelten die üblichen Regeln für Generierungsautorisierung, Guthabenprüfungen, Idempotenzschlüssel, Callbacks und Rückerstattungen bei Fehlern.

credits_estimated
initial_reservation_estimated

GET /tasks/{task_id} und Completion-Callbacks geben Inline-Text zurück, ohne eine Medien-Datei zu erfordern:

json
{
  "status": "completed",
  "credits_reserved": 3,
  "credits_used": 3,
  "results": [
    {
      "type": "text",
      "text": "The image shows…",
      "incomplete": false,
      "function_calls": [],
      "usage": {
        "input_tokens": 4443,
        "uncached_input_tokens": 4443,
        "cached_input_tokens": 0,
        "cache_write_tokens": 0,
        "output_tokens": 47
      },
      "credits": 3
    }
  ]
}

credits_reserved spiegelt die erweiterte Reservierung nach der Abrechnung wider. incomplete: true bedeutet, dass das Ausgabelimit erreicht wurde; verbrauchte Tokens werden trotzdem berechnet. Wiederholtes Polling oder erneutes Senden desselben Idempotency-Schlüssels erzeugt keine weitere Belastung.

input.prompt
describe_studio

Der ausgewählte Workflow bestimmt die Limits. ProVid unterstützt 4–15 ganzzahlige Sekunden, 480p/720p/1080p und die Seitenverhältnisse 9:16, 16:9, 1:1, 4:5, 4:3, 3:4, 21:9, adaptiv. OmniVid unterstützt 4/6/8/10 Sekunden, 360p/720p/1080p/4k und 9:16 oder 16:9. Neue OmniVid-Studio-Anfragen verwenden standardmäßig 720p und 10 Sekunden, sofern keine expliziten Einstellungen angegeben werden. Ungültige Optionen geben einen Validierungsfehler zurück. Es gelten auch Limits für die Medienkombination. OmniVid unterstützt Audio-Referenz-IDs in LAB, akzeptiert aber keine rohen Audio-Referenzdateien in Studio; nicht unterstützte Referenzen geben einen Validierungsfehler zurück.

failed
cancelled
bash
curl "$V4V_BASE_URL/api/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $V4V_API_KEY"

Bei Abschluss lies Textergebnisse inline; lade Mediendateien von results[].url herunter. Während generierte Dateien gespeichert werden, bleibt die Aufgabe processing; allein der Generierungserfolg ist noch kein Abschluss. Wiederhole die Statusanfrage, um abgelaufene Download-URLs zu aktualisieren. Polling startet keine weitere Generierung und berechnet keine Credits.

Frage GET /tasks/{task_id} ab oder gib eine Callback-URL an. Der Status ist queued, processing, completed, failed oder cancelled. Für Polling ist ein API-Schlüssel erforderlich, der demselben Konto gehört wie die Aufgabe.

json
{
  "task_id": "task_6aa962444bd1dd7ab65bc6b6",
  "source": "lab",
  "status": "completed",
  "credits_used": 18,
  "results": [
    {
      "type": "video",
      "url": "https://v4v.ai/api/v1/results/…",
      "content_type": "video/mp4",
      "size": 18392832,
      "expires_at": "2026-09-16T00:00:00Z"
    }
  ]
}

Jedes Medienergebnis enthält stabile Werte für asset_id und file_id. Verwende file_id in nachfolgenden Medieneingaben für Generierungen. Antworten enthalten außerdem project_id. Die Ergebnisliste unterstützt mehrere Bilder, Videos und Audiodateien. Ergebnislinks sind signiert und ohne V4V-Cookies oder Authentifizierung nutzbar. Rufe den Aufgabenstatus erneut ab, um abgelaufene Links zu erneuern. Die Wiederverwendungszusage besteht aus einer stabilen Datei-ID plus einer erneuerbaren signierten URL, solange die gespeicherte Datei existiert und der Zugriff weiterhin erlaubt ist; es handelt sich nicht um eine unveränderliche öffentliche URL. Um ein Ergebnis am nächsten Tag wiederzuverwenden, löse dieselbe Aufgaben-/Datei-ID erneut auf und lade über die neue URL herunter. Jede Person, die einen Ergebnislink besitzt, kann ihn bis zum Ablauf verwenden.

Bei einzelnen LAB-/Studio-Anfragen werden geschätzte Credits reserviert, wenn Kontokapazität verfügbar ist. Wenn das konfigurierte Limit für gleichzeitige Aufgaben voll ist (Standard 3), gibt die Anfrage dieselbe dauerhafte Warteschlangenaufgabe mit null credits_reserved, credits_estimated und queue zurück, das limit, retry_after_seconds: 5 und estimated_start_at: null enthält. Der Worker lässt wartende Aufgaben ohne erneute Übermittlung zu. Er reserviert Credits atomar, wenn ein Slot frei wird; reicht das Guthaben zu diesem Zeitpunkt nicht aus, schlägt die Aufgabe bei stage: "admission" fehl und ihr Webhook wird eingeplant. Verwende nach Netzwerkfehlern den ursprünglichen Idempotency-Schlüssel erneut; erstelle keine weitere Aufgabe, um die Wartezeit zu umgehen. Bei Bulk-Batches wird die Schätzung jedes Elements erst dann reserviert, wenn dieses Element zum Start zugelassen wird. Generierungsgebühren verbrauchen diese Reservierung. Gebühren für fehlgeschlagene Generierungen folgen dem bestehenden Erstattungspfad; ungenutzte reservierte Credits werden bei Abschluss oder Fehlschlag freigegeben. Erfolgreiche Schritte in einem teilweise fehlgeschlagenen Studio-Workflow behalten ihre normalen Belastungen. Discovery, Polling, Dateiabfrage, Callbacks und Callback-Wiederholungen verursachen keine Generierungsgebühr.

GET /balance gibt die aktuell verfügbaren Credits zurück. GET /usage gibt die letzten 100 Generierungsanfragen für das Konto zurück. Das Profil zeigt die Gesamtzahlen der Anfragen/Generierungen und die abgerechneten Credits für jeden Schlüssel sowie den letzten Aufgabenverlauf. Uploads bleiben in der Labor-Bibliothek des Nutzers und können dort gelöscht werden.

project_id
GET /project-folders
folders
folder_id
name
color
created_at
updated_at
bash
# Discover projects and folders.
curl -H "Authorization: Bearer $V4V_API_KEY" \
  'https://v4v.ai/api/v1/projects?source=studio&limit=50'
curl -H "Authorization: Bearer $V4V_API_KEY" \
  'https://v4v.ai/api/v1/project-folders'

# Supply real IDs returned by the list endpoints.
curl -X PATCH "https://v4v.ai/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $V4V_API_KEY" -H 'Content-Type: application/json' \
  -d '{"project_name":"Summer campaign — approved","folder_id":"YOUR_FOLDER_ID"}'

Eine Projektaktualisierung akzeptiert project_name (getrimmt, 1–200 Zeichen), folder_id oder beides. Sende {"folder_id":null}, um ein Projekt aus einem Ordner zu entfernen. Weggelassene Felder bleiben unverändert. Die Antwort enthält project_id und die aktualisierten Felder. Umbenennungen und Verschiebungen aktualisieren auch die entsprechende API-Aufgabe und den Labor-Verlauf; Aufgaben in der Warteschlange behalten die Organisation bei, wenn ihre Projekte erstellt werden.

Ordnernamen werden getrimmt, müssen 1–80 Zeichen enthalten und sind innerhalb eines Kontos eindeutig. Das Erstellen gibt HTTP 201 zurück; das Umbenennen gibt 200 zurück, jeweils mit den oben genannten Ordnerfeldern. Beim Umbenennen bleiben die Ordner-ID und ihre Projekte erhalten. Ein doppelter Name gibt 409 FOLDER_NAME_CONFLICT zurück; ungültige Felder geben 422 INVALID_INPUT zurück; nicht zugängliche Projekte oder Ordner geben 404 PROJECT_NOT_FOUND oder FOLDER_NOT_FOUND zurück. Nach einer unsicheren Antwort auf eine Ordnererstellung solltest du vor einem erneuten Versuch zuerst die Ordner auflisten.

Batch-Antworten enthalten state_token, das sich bei relevantem Fortschritt oder Steueraktionen ändert und stabil bleibt, wenn nur signierte URLs erneuert werden. MCP stellt zusätzlich wait_studio_batch für begrenztes serverseitiges Warten während einer aktiven Unterhaltung bereit; siehe MCP monitoring.

FeldBedeutung
nameErforderlicher Batch-Name, 1–200 Zeichen
max_creditsErforderliches positives Credit-Budget; verbrauchte Credits plus aktive Reservierungen dürfen es niemals überschreiten
input, parametersOptionale gemeinsame Studio-Felder mit denselben Namen wie bei einer einzelnen Studio-Anfrage
itemsErforderliches Array mit 1–300 Produktobjekten
items[].skuOptionale Client-Referenz, höchstens 200 Zeichen
items[].product_idOptionale Products-Bibliotheks-ID, die diesem Konto gehört
items[].product_urlOptionale öffentliche Produktseite zum Importieren; Varianten-/Query-Parameter bleiben erhalten, außer eBay-Tracking, das kanonisiert wird
items[].input, items[].parametersElement-Overrides; Priorität ist Element → Batch → Studio-Standards
test_countOptionaler Wert 5; verarbeitet nur die ersten fünf Elemente und wartet dann auf eine ausdrückliche Fortsetzung

Verwende eine Produktbibliotheks-ID, eine Produktseiten-URL oder Produktdetails/-bilder in input. Wenn sowohl Produkt-ID als auch URL angegeben werden, wird das Bibliotheksprodukt verwendet. Eingabefelder, die der Aufrufer ausdrücklich angibt, überschreiben importierte Werte. Referenzmedien werden von demselben Dienst wie bei einzelnen API-Generierungen in eigenen Speicher kopiert. API-Importe von Produktseiten verwenden begrenzte öffentliche HTTP-Anfragen mit validierten Weiterleitungen. Für eBay-Angebotslinks gibt es zusätzlich einen geschützten Browser-Fallback. Ein Shop kann einen Import dennoch ablehnen oder eine Anmeldung verlangen; gib in diesem Fall eine eigene Produkt-ID oder vorbereitete Produktdaten/-bilder an. Das Limit für den Request-Body beträgt 1 MiB. Sende JSON-Produktlisten; das Hochladen von CSV-Dateien ist nicht Teil dieser API-Version.

Die Antwort enthält batch_id, status, total_items, max_credits, credits_used, credits_committed, Anzahlen und eine erste Seite von Elementen. Die anfängliche Annahme reserviert keine Credits für den gesamten Batch. Aufgaben können erst beim nächsten Worker-Tick erscheinen, daher kann ein akzeptiertes Element anfangs ein leeres attempts-Array haben.

Fortschritt und Ergebnisse

  • GET /api/v1/studio/batches?offset=0&limit=50 listet die Batches dieses Kontos auf.
  • GET /api/v1/studio/batches/{batch_id}?offset=0&limit=50 gibt den Elementfortschritt zurück. Die Paginierung erfolgt über den nullbasierten Elementindex, mit einer maximalen Seitengröße von 100.
  • Jedes Element enthält sein index, optionales sku, Status und attempts. Ein Versuch enthält ein normales task_id, version, credits_used und Status; abgeschlossene Versuche enthalten signierte Ergebnis-URLs.
  • GET /api/v1/tasks/{task_id} ruft einen einzelnen Versuch ab und erneuert dessen signierte Ergebnis-Links. Normale Regeln für Aufgabenbesitz gelten über Schlüssel desselben Kontos hinweg.

Ein Element mit IMPORT_FAILED ist fehlgeschlagen, bevor es zur kostenpflichtigen Generierung zugelassen wurde. Seine Fehlermeldung weist, wenn bekannt, auf eine blockierende eBay-/Sicherheitsseite hin und schlägt eine Wiederholung oder vorbereitete Produktdaten vor. PREPARATION_FAILED kennzeichnet einen unerwarteten Fehler bei der Generierungsvorbereitung nach dem Import; gib bei Kontakt mit dem Support das task_id an. Validierungs-/Medienfehler behalten ihre spezifischen Codes. Andere Elemente laufen weiter. Jeder fehlgeschlagene Versuch ist endgültig: resume versucht ihn nicht erneut. Nachdem du die Eingabe korrigiert oder einen Fix bereitgestellt hast, verwende retry_failed oder rework unten, um einen neuen Versuch im selben Batch zu erstellen. Die Wiederverwendung des ursprünglichen Erstellungsschlüssels gibt den ursprünglichen Batch zurück; er wird nicht erneut ausgeführt.

DIRECTOR_REQUEST_FAILED means the AI Director's text-model request was rejected before it could produce a video brief. REFERENCE_MEDIA_UNAVAILABLE identifies an unreadable, unsupported or oversized Director reference image. Report the task_id to support; do not treat either error as a video-generation failure or automatically spend credits on another attempt. Saved account images are sent directly from storage to the Director as binary image inputs, so this stage does not need anonymous CDN access.

Frage nicht öfter als einmal alle fünf Sekunden ab. Ein Batch meldet completed, wenn alle seine Elemente einen endgültigen Status erreicht haben; prüfe Anzahlen und einzelne Fehler, da der Abschluss fehlgeschlagene Elemente einschließen kann. Ein Element, das hinter einem Fünf-Elemente-Sample zurückgehalten wird, meldet waiting_for_sample. Das Sample pausiert mit TEST_REVIEW_REQUIRED, nachdem seine Versuche abgeschlossen sind.

Pausieren, fortsetzen, abbrechen und das Budget erhöhen

POST /api/v1/studio/batches/{batch_id}:

json
{
  "action": "pause"
}
json
{
  "action": "resume",
  "max_credits": 1000
}
json
{
  "action": "cancel"
}

Pausieren und Abbrechen verhindern zukünftige Starts. Bereits zum Start zugelassene Versuche behalten ihre Reservierungen und werden normal abgeschlossen. Fortsetzen setzt den Rest nach einem Sample, einer Guthabenaufladung oder einem erhöhten Budget fort. Budgets dürfen nur erhöht werden. Abbrechen stoppt die verbleibenden Elemente. Diese Steueraktionen sind idempotent, solange der angeforderte Batch-Status unverändert ist; ein abgebrochener Batch kann nicht resume, aber er kann endgültige Elemente ausdrücklich restart oder rework.

Fehler erneut versuchen, Elemente überarbeiten oder einen Batch neu starten

Verwende denselben POST /api/v1/studio/batches/{batch_id}-Endpunkt. Diese Aktionen erstellen neue, potenziell kostenpflichtige Versuche und erfordern für jeden beabsichtigten Vorgang einen neuen Idempotency-Key-Header (1–200 Zeichen). Verwende nach einer Netzwerkunterbrechung denselben Schlüssel und identisches JSON erneut. Ein geänderter Body gibt IDEMPOTENCY_CONFLICT zurück. Schlüssel für diese Vorgänge sind getrennt von der Batch-Erstellung auf das Konto und den Batch begrenzt. Der Request-Body ist auf 1 MiB begrenzt.

AktionWas ausgeführt wird
retry_failedNur Elemente, deren neuester Versuch fehlgeschlagen ist. Optionales item_indexes wählt eine Teilmenge aus; ohne Angabe gilt es für alle Fehlschläge.
reworkAusgewählte terminale Elemente, einschließlich erfolgreicher oder abgebrochener. Erforderliche items-Einträge identifizieren genau ein nullbasiertes index oder das aktuelle task_id sowie optional product_id, product_url, input oder parameters.
restartJedes Element, einschließlich erfolgreicher, mit einem neuen Versuch. Warte zuerst, bis zugelassene Arbeit abgeschlossen ist. Das Sample-Gate wird entfernt.
bash
curl "$V4V_BASE_URL/api/v1/studio/batches/$BATCH_ID" \
  -H "Authorization: Bearer $V4V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: catalogue-retry-1" \
  -d '{"action":"retry_failed","max_credits":800}'

So korrigierst du nur ein Produkt, ohne erfolgreiche Elemente neu zu erzeugen:

json
{
  "action": "rework",
  "items": [
    {
      "index": 1,
      "product_url": "https://www.ebay.de/itm/227541601859",
      "input": {
        "prompt": "A slow close-up of the bag and its details."
      },
      "parameters": {
        "duration": 8
      }
    }
  ]
}

Um Ergebnisse neu zu erstellen, mit denen du unzufrieden bist, kopiere ihr aktuelles items[].task_id aus der Batch-Antwort. Du kannst dieselben Eingaben beibehalten oder einen neuen Prompt angeben:

json
{
  "action": "rework",
  "items": [
    {
      "task_id": "task_0123456789abcdef01234567"
    },
    {
      "task_id": "task_abcdef0123456789abcdef01",
      "input": {
        "prompt": "Slower close-up, softer lighting"
      }
    }
  ]
}

Verwende die vorhandene Batch-URL und eine neue Operation Idempotency-Key. Die Batch kehrt zu running zurück, die ausgewählten Elemente werden zu queued, und ihre task_id/results/error auf oberster Ebene werden geleert, bis der neue Versuch materialisiert/abgeschlossen ist. Andere abgeschlossene Elemente bleiben unverändert. Frühere Ausgaben bleiben nur im Verlauf von attempts erhalten; Clients sollten items[].results für das aktuelle Ergebnis anzeigen. Pro Eintrag ist genau eines von index oder task_id zulässig. Eine fremde/nicht zugehörige Aufgabe gibt TASK_NOT_FOUND zurück; eine Aufgabe aus einer bereits ersetzten Version gibt BATCH_ITEM_VERSION_CHANGED (409) zurück, sodass veraltete Auswahlen nicht stillschweigend ein neueres Ergebnis erneut ausführen können. Das erneute Abspielen eines akzeptierten Schlüssels bleibt sicher, selbst nachdem seine ausgewählte Aufgabe historisch geworden ist.

Für einen vollständigen erneuten Durchlauf sende {"action":"restart"} mit einem neuen Schlüssel. Alle drei Aktionen akzeptieren optionale operationweite Änderungen an input und parameters sowie ein erhöhtes max_credits. Änderungen werden über die vorherige Anfrage dieses Elements gelegt; elementbezogene Änderungen haben Vorrang. Das Ändern von product_id oder product_url löscht die vorherige Alternative. Frühere Anfrage-Snapshots und Ergebnisse bleiben unverändert. Nachfolgende Wiederholungen übernehmen die zuletzt akzeptierten Korrekturen und bereiten einen frischen Workflow vor.

Ausgewählte Versuche müssen terminal sein. BATCH_ITEMS_ACTIVE (409) bedeutet, dass Arbeit noch in der Warteschlange/zugelassen/in Verarbeitung ist, ein ausgewähltes Wiederholungselement nicht fehlgeschlagen ist oder gerade eine andere Wiederholung akzeptiert wurde. Für einen vollständigen Neustart brich ausstehende Arbeit ab und warte, bis zugelassene Versuche abgeschlossen sind. GENERATION_UNRESOLVED (409) blockiert Wiederholungen, während eine frühere Generierungsanfrage in der Warteschlange steht, läuft, verteilt wird oder ungewiss ist; gleiche ihr Ergebnis zuerst ab. NO_FAILED_ITEMS (409) bedeutet, dass es nichts zum Wiederholen gibt. Wiederholen und Überarbeiten startet die Verarbeitung explizit, einschließlich anderer ausstehender Elemente in dieser Batch; ein vorhandenes Fünf-Elemente-Sample-Gate bleibt bestehen, sofern resume oder restart es nicht entfernt.

max_credits bleibt eine kumulative Grenze: frühere Belastungen plus aktuelle Reservierungen zählen weiterhin. Eine Wiederholung erstattet erfolgreiche frühere Schritte nicht und setzt das Budget nicht zurück. Es wird keine Reservierung für die gesamte Batch vorgenommen. Neue Versionen verwenden dieselben globalen und kontoabhängigen Bulk-Warteschlangen. API-/MCP-Credit-Logs behalten die Zuordnung zu Batch, Element und Version bei.

Antworten behalten jeden Versuch in items[].attempts bei, jeweils mit eigener Task/eigenem Projekt und steigendem version (Nummern können übersprungen werden). items[].version, Elementstatus und counts beschreiben die zuletzt beabsichtigte Version; eine neue Version meldet anfangs Warteschlange, noch bevor ihre Aufgabe materialisiert ist. credits_used enthält alle Versionen. Eine Batch ist erst abgeschlossen, wenn die neueste Version jedes Elements terminal ist. Erneut abgespielte Operationen starten niemals zusätzliche Versuche. Pro Batch werden bis zu 100 versionserzeugende Operationen und 8 MiB an kumulierten Änderungen gespeichert; BATCH_HISTORY_LIMIT (409) fordert bei Erreichen des Limits eine neue Batch an.

INSUFFICIENT_CREDITS oder BUDGET_EXCEEDED pausieren neue Starts. Das Hinzufügen von Account-Credits setzt eine Batch nicht automatisch fort: Rufe resume explizit auf. Budget-Zulassung und Account-Reservierung sind innerhalb ihrer jeweiligen MongoDB-Dokumente atomar, sodass gleichzeitige Worker weder das Batch-Budget überschreiten noch denselben Versuch doppelt belasten können. Es ist kein MongoDB-Replica-Set erforderlich.

Ein Timeout bei der Statusabfrage beweist nicht, dass eine Generierung fehlgeschlagen ist. Wenn eine Antwort auf das Senden einer Generierung verloren geht, bleibt ihr Slot zur Abstimmung belegt; das System sendet nicht automatisch eine Ersatzanfrage, die Kosten verursacht. Sobald die Generierung erfolgreich ist, verwenden Wiederholungen beim Dateispeicher das vorhandene Generierungsergebnis wieder. Explizit abgelehnte, rate-limitierte Übermittlungen können mit begrenztem Backoff wiederholt werden. Die Prüfung abgeschlossener Ergebnisse, Versionsfreigabe, ZIP-Export und eine Studio-Bulk-UI aus dem umfassenderen Plan #194 sind nicht Teil dieses API-Releases; einzelne signierte Downloads sind über normale Task-Ergebnisse verfügbar.

Credit-Logs

Administratoren können Credit-Logs nach API oder MCP filtern. Einträge enthalten den API-Schlüsselnamen/die API-Schlüssel-ID, Task-/Projekt-/Job-IDs, die Generierungsquelle und gegebenenfalls Marker für Bulk-Batch/Element/Version. Schlüsselgeheimnisse werden niemals protokolliert.

Reservierungen und Abrechnung sind Audit-Ereignisse mit einer Credit-Differenz von null; die Metadaten erfassen den reservierten Betrag. Belastungen und Erstattungen tragen die tatsächliche Credit-Differenz genau einmal. balanceAfter ist das verfügbare Kontoguthaben, das ausstehende Reservierungen ausschließt. Historische API-Belastungen werden aus gespeicherten Job-Belegen wiederhergestellt, ohne das Konto erneut zu belasten; wo das historische verfügbare Guthaben nicht rekonstruiert werden kann, weist die Admin-Oberfläche darauf hin.

Diagnose fehlgeschlagener Generierungen

Fehlgeschlagene REST-Aufgaben, MCP-get_task-Ergebnisse und signierte task.failed-Callbacks verwenden ein gemeinsames Fehlerobjekt. message ist die V4V-Zusammenfassung; provider_error bewahrt den Grund des Modelldienstes, wobei Anmeldedaten, privates Routing und Netzwerkstandorte geschwärzt werden. provider verwendet den öffentlichen Routing-Alias managed.

json
{
  "error": {
    "code": "GENERATION_FAILED",
    "message": "Generation failed. Unused credits and failed generation charges have been released.",
    "stage": "generation",
    "retryable": false,
    "provider": "managed",
    "provider_error": "The model is currently unable to process speech edits. If you think this was an error, send feedback.",
    "hint": "Remove speech from the reference video or use still images."
  }
}

Sicherheitsablehnungen, Sprachbearbeitungen und nicht unterstützte Dauern/Auflösungen erfordern eine Änderung der Anfrage. Ratenlimits und Timeouts enthalten retryable: true, retry_after_seconds: 60 und einen Wiederherstellungshinweis. Unbekannte Gründe bleiben verfügbar, ohne erfundene Diagnose oder Retry-Empfehlung. Diese Felder werden weggelassen, wenn keine Diagnose des Modelldienstes existiert. Ältere fehlgeschlagene Aufgaben werden angereichert, während ihr Workflow-Fehlereintrag verfügbar bleibt. Studio und Labor zeigen denselben bereinigten Grund an und senden ihn als GA4-generation_failed.reason (vorbehaltlich des bestehenden Analytics-Limits von 120 Zeichen).

Ein Retry-Hinweis startet niemals eine weitere Generierung. Ein neuer kostenpflichtiger Versuch erfordert eine ausdrückliche Benutzeranfrage und einen neuen Idempotency-Schlüssel. Bestehende Credit-Abrechnung, Erstattungen für fehlgeschlagene Schritte, Belastungen für abgeschlossene Schritte und Webhook-Signierung bleiben unverändert wirksam.