Aller à la documentation
v4v.Documentation développeurAPERÇUVos clés API ↗
DANS CE GUIDE
AuthentificationDécouvrir les modèles LabSous-titres horodatés de la paroleDerniers modèles de génération disponiblesModèles vidéo Kling 4.0Chat GPT-6 AstraLaboratoire avec une image externeTéléverser des médias privésStudio avec des médias externes ou privésTâches et créditsRenommer et organiser les projetsIdempotenceCallbacks signésErreurs et limitesGénération en masse Studio (API et MCP)
Disponible en test
Aperçu en accès direct
API reference · v1

Créez avec l’API V4V.

Générez des images, des vidéos et de l’audio depuis vos propres applications. Une clé API. Vos crédits V4V existants.

Commencer →Télécharger OpenAPI ↓
ENDPOINThttps://v4v.ai/api/v1
cURL
curl https://v4v.ai/api/v1/models \
  -H "Authorization: Bearer $V4V_API_KEY"
01

Authentification#

Créez une clé nommée dans Profil → Clés API. Enregistrez le secret API et le secret de signature webhook lorsqu’ils s’affichent ; ils ne sont affichés qu’une seule fois. Plusieurs clés peuvent être créées et révoquées indépendamment. Les secrets de clé sont stockés sous forme de hachages SHA-256.

Envoyez Authorization: Bearer v4v_live_… sur chaque requête API. Conservez cette clé sur votre serveur, hors des applications navigateur et du contrôle de source. La révocation bloque les futures requêtes ; les générations déjà acceptées se poursuivent.

URL de base : https://v4v.ai/api/v1.

02

Découvrir les modèles Lab#

GET /models liste les ID actuels des modèles Lab, leur état d’activation, les entrées, paramètres, valeurs par défaut, conditions et limites. GET /models/{model} décrit un modèle. Les ID et schémas proviennent du même catalogue et des mêmes valeurs par défaut que ceux utilisés par Lab. La configuration Studio est distincte.

Les noms de modèle dans les exemples ci-dessous sont de véritables ID de catalogue. Utilisez discovery pour trouver les modèles actuellement activés sur votre compte. Les noms de champ sont spécifiques au modèle : conservez les noms renvoyés par discovery, y compris les noms en camelCase tels que aspectRatio ou referenceImageUrls. Les valeurs de sélection sont des chaînes ; les valeurs numériques pour des options de sélection d’apparence numérique sont également acceptées. Les champs peuvent être fournis dans input ou parameters, mais jamais dans les deux. Les champs inconnus sont rejetés. Les modèles avec versions sélectionnables exposent parameters.variant ; utilisez les valeurs et les valeurs par défaut renvoyées par discovery.

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

Sous-titres horodatés de la parole#

Découvrez ai.speech_to_text avec le type subtitle. Envoyez un ID de fichier média détenu ou une URL prise en charge dans input.audioUrl ou input.videoUrl à POST /lab ; les paramètres facultatifs incluent language_code (par exemple uk, en ou auto) et diarize. L’estimation utilise la durée de la source d’origine. La transcription consomme les crédits habituels du compte.

Une tâche terminée renvoie results[].type: "subtitle", la transcription text, srt et des cues modifiables avec start, end en secondes et text. Une entrée silencieuse réussie peut avoir une liste de repères vide. Pour le montage, utilisez les outils MCP de Video Editor pour aligner ces repères sur le trim, la vitesse et la position dans la timeline d’un clip source.

04

Derniers modèles de génération disponibles#

Omni Flash 1.2 (video.gemini_omni_flash-1-2) est le modèle préféré pour les requêtes vidéo sans modèle explicite. Le Laboratoire l’affiche en premier ; Omni Flash 1.1 reste disponible sous Plus et via son ID existant. Découvrez les paramètres actuels avec GET /models/{model}. La version 1.2 prend en charge la génération et l’édition de 3 à 15 secondes ; l’interpolation première/dernière image est limitée à 10 secondes. Les tarifs partagés 4/6/8/10 secondes correspondent aux prix 1.1 configurés. Utilisez discovery et les estimations actuelles pour les tarifs au lieu de stocker cette relation comme règle permanente.

Choisissez GPT Image 2.6 via parameters.variant dans image.text_to_image ou ai.image_edit. Utilisez parameters.outputFormat avec ces capacités de variante exactes :

VarianteFormats de sortie
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 fait autorité. Flare/Sunburst sont ajustés en fonction de l’utilisation réelle en entrée/sortie ; l’utilisation de conversion SVG est incluse dans le total final. Economy est disponible en 1K uniquement avec une tarification par image. Les téléchargements conservent les images de GIF et les octets vectoriels SVG ; les téléchargements SVG utilisent une livraison en pièce jointe.

Nano Banana 2.1 utilise parameters.variant: "nano-banana-v2.1" dans les mêmes modules d’image, avec jusqu’à 10 références et une sortie 1K/2K/4K. Son mode de facturation actuel est publié dans . La génération Google/Vertex est ajustée à partir des entrées vérifiées, des entrées mises en cache, de la sortie image, de la sortie texte et des tokens de réflexion, avec une majoration appliquée et le total combiné arrondi une seule fois à l’unité supérieure. Le composant de sortie image est d’environ 11/16/36 crédits V4V pour 1K/2K/4K avant l’entrée et la réflexion. Le Laboratoire et les estimations affichent une plage approximative ; la réservation initiale est distincte du coût final. Les autres routages utilisent le tarif par image configuré. Le routage reste géré par V4V ; ne fournissez pas de paramètre de routage.

05

Modèles vidéo Kling 4.0#

Quatre nœuds distincts partagent la même gestion de génération et de résultat dans le Laboratoire, les Flux de travail, l'API et MCP :

ID du catalogueModèleDuréeRésolution
video.kling_v40_refKling 4.0 Reference3–30 secondes720p / 1080p
video.kling_v40_keyKling 4.0 Keyframe3–30 secondes720p / 1080p
video.kling_v40_flash_refKling 4.0 Flash Reference3–20 secondes720p
video.kling_v40_flash_keyKling 4.0 Flash Keyframe3–20 secondes720p

Tous acceptent un prompt obligatoire (jusqu'à 8000 caractères), un duration entier, resolution et aspectRatio (auto, 16:9, 9:16, 1:1, 21:9 ; Flash Keyframe exclut auto). Tous peuvent générer à partir du texte seul. Les entrées de référence sont facultatives.

Les modèles Reference acceptent referenceImageUrls (jusqu'à 10), referenceVideoUrls (jusqu'à 5), elements (jusqu'à 7, au plus 3 avec vidéo) et keepOriginalSound. Un élément nommé possède name, soit imageUrls (2 à 4 images), soit videoUrl (un clip de personnage de 3 à 8 s), tag facultatif, description (100 caractères) et voiceUrl de personnage. Flash accepte aussi type d'élément (image ou video). Standard Reference accepte en plus voices : jusqu'à 3 objets avec name et audioUrl. Flash associe plutôt les voix aux éléments de personnage.

Il peut y avoir au maximum 15 images, vidéos de référence, éléments et voix autonomes combinés ; les vidéos de référence plus les éléments vidéo ne peuvent pas dépasser 5. Chaque vidéo de référence doit durer 2 à 30 s (2 à 20 s pour Flash), et leur durée cumulée, éléments vidéo inclus, est d'au maximum 30 s (20 s pour Flash). Les noms doivent être uniques sans tenir compte de la casse, composés de 1 à 20 caractères chinois, lettres, chiffres ou underscores ; les noms de référence intégrés sont réservés. Mentionnez les références fournies comme , ou leur déclaré. Les mentions non déclarées sont rejetées.

06

Chat GPT-6 Astra#

Découvrez chat.gpt_6_astra avec GET /models/chat.gpt_6_astra (slug : gpt-6-astra). Il a le type chat et renvoie du texte. Discovery inclut les tarifs par token et la règle d’arrondi.

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.

Pour proposer une fonction, transmettez input.functionTools sous forme de chaîne JSON contenant 1 à 10 définitions avec type: "function", name, description et parameters (un objet JSON Schema). Définissez parameters.webSearch sur false. La requête amont utilise tool_choice: "auto" ; les demandes de fonction sont renvoyées dans results[].function_calls pour être traitées par votre application. Le nœud de modèle n’exécute pas les fonctions et ne poursuit pas la conversation avec un résultat de fonction.

Le chat réserve 1 crédit avant d’entrer dans la file d’attente. Il s’agit d’une réservation minimale, et non d’un prix fixe ni d’un plafond de dépense. Tarifs par 1M tokens : entrée 560, entrée mise en cache 56, écritures de cache 700, sortie 2 800 crédits. Le coût total des tokens est arrondi à l’unité supérieure une seule fois à un crédit entier, avec un minimum facturé de 1. Après la réponse, tout frais supplémentaire est déduit de façon atomique du solde disponible. Si le solde est insuffisant, la tâche échoue et la réservation inutilisée est libérée.

Pour le chat et les images tarifés à l’usage, le point de terminaison d’estimation renvoie aussi credits_range avec min, max, assumptions, includes_markup: true, is_estimate: true et is_spending_cap: false. Affichez cela comme une plage approximative en crédits V4V. Cela inclut la majoration actuelle et les ajustements de prix. Il s’agit de scénarios d’utilisation illustratifs ; le coût réel peut se situer hors de cette plage. et décrivent séparément la réservation initiale. La plage ne modifie pas l’ajustement selon l’usage réel et n’active pas l’admission avec budget strict.

07

Laboratoire avec une image externe#

Les entrées média acceptent une URL externe ou un ID de fichier V4V dans le même champ. Les tableaux peuvent mélanger les deux. Les URL doivent renvoyer de vrais fichiers média sans cookies de navigateur ni connexion interactive. HTTPS et des URL signées valides suffisamment longtemps sont recommandées. V4V valide et copie les médias externes avant la génération ; les URL de réseau interne et les redirections non sûres sont rejetées.

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

Téléverser des médias privés#

POST /files accepte un champ file utilisant multipart/form-data. Les images, les vidéos et les fichiers audio sont pris en charge, sous réserve des limites du modèle. La limite de téléversement par défaut est de 100 Mio, encore contrainte par la limite de téléversement de stockage du déploiement et la limite du proxy. Les fichiers doivent contenir des médias décodables ; l’inspection audio/vidéo requiert ffprobe sur le serveur.

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
}

Utilisez directement l’ID renvoyé, sans préfixe file_. GET /files/{id} consulte les métadonnées de votre fichier sans consommer de crédits.

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 avec des médias externes ou privés#

POST /studio utilise le même flux de travail Studio sélectionné, la même préparation, la même exécution du modèle, le même multiplicateur de prix et la même remise d’abonnement que l’interface Studio.

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"
}

Pour un flux entièrement en médias privés, téléversez d’abord chaque image produit avec POST /files, puis placez les ID renvoyés dans input.product_images. Téléversez les références d’avatar, audio et vidéo de la même manière.

Studio accepte product_id (un produit enregistré détenu), avatar_id (un avatar de bibliothèque publique détenu ou public actif, avec préfixe public: pris en charge), product_name, product_description, prompt, product_images, reference_images, avatar_media, audio et video. Chaque champ média accepte des références ; les tableaux prennent en charge plusieurs fichiers. parameters.avatar accepte un ID d’avatar de bibliothèque, une URL d’image unique ou un ID de fichier, ou null. Choisissez soit input.avatar_id soit parameters.avatar. Les champs produit explicites remplacent les valeurs par défaut de la bibliothèque. Les noms/ID de style actifs appliquent les instructions de style enregistrées. Les valeurs de style inconnues, inactives et vides renvoient 422 INVALID_PARAMETER, field: "parameters.style" et error.allowed_values contenant les ID/noms actifs. Omettez le style pour utiliser la valeur par défaut actuelle (UGC si actif, sinon le premier préréglage actif). Les paramètres incluent aussi style, language, voice, placement, duration, aspect_ratio et quality.

Migration pour les clients qui transmettaient auparavant du texte libre dans : déplacez cette direction créative dans et choisissez un style actif depuis MCP (ou omettez le style pour la valeur par défaut actuelle). Un style mal orthographié ne devient plus un style personnalisé.

10

Tâches et crédits#

La génération renvoie HTTP 202 après validation des entrées et, lorsque la capacité est disponible, réservation des crédits, sans attendre la génération :

json
{
  "task_id": "task_6aa962444bd1dd7ab65bc6b6",
  "status": "queued",
  "credits_reserved": 20,
  "created_at": "2026-09-15T18:00:00Z"
}

Nom de projet facultatif

POST /lab et POST /studio acceptent tous deux project_name au niveau supérieur, aux côtés de input, parameters et 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"
  }
}

Le nom après suppression des espaces superflus (1 à 200 caractères, non vide) devient le titre dans Projets et, pour LAB, Anciennes exécutions. S’il est omis, le titre par défaut existant est utilisé. La réponse de la tâche inclut project_name et project_id. Changer le nom avec la même clé d’idempotence est un conflit, tout comme changer les entrées de génération.

Statut de la tâche

Le serveur actualise le statut de génération en arrière-plan. L’interrogation renvoie le dernier status enregistré : queued, processing, completed, failed ou cancelled. Tant que la tâche est queued ou processing, affichez un indicateur de chargement. Lorsque status vaut completed, lisez le texte du chat depuis results[].text ou téléchargez les fichiers média depuis results. Pour failed, examinez error (y compris le stage, brief_completed, retryable en échec et le retry_after_seconds suggéré lorsqu’ils sont connus) et credits_used. Une génération de brief réussie peut conserver sa facturation si le rendu échoue ; une indication de nouvelle tentative transitoire ne lance ni n’autorise une nouvelle tentative payante. cancelled est également terminal.

Les webhooks sont facultatifs. Sans callback_url, répétez la requête suivante toutes les 3 à 5 secondes jusqu’à ce que status soit completed, ou :

11

Renommer et organiser les projets#

L’organisation des projets utilise les mêmes dossiers que l’espace de travail Projects. Elle ne génère pas de médias, ne réserve pas de crédits et ne modifie pas les entrées de génération, les résultats ni les hachages d’idempotence. Toutes les opérations nécessitent votre clé API et n’accèdent qu’aux projets et dossiers de votre compte.

Méthode et cheminObjet
GET /projectsRechercher les projets Studio, flux de travail et Lab, y compris les tâches API en file d’attente
PATCH /projects/{project_id}Renommer un projet et/ou le déplacer vers un dossier
GET /project-foldersLister les dossiers de l’espace de travail
POST /project-foldersCréer un dossier avec {"name":"Summer campaign"}
PATCH /project-folders/{folder_id}Renommer un dossier avec {"name":"Autumn campaign"}

Les deux points de terminaison de liste acceptent offset (0 par défaut) et limit (1–100, 50 par défaut), et renvoient total et next_offset (null sur la dernière page). Les projets sont triés du plus récent au plus ancien avec un départage stable par ID ; les dossiers sont triés par nom. Les filtres de projet sont source=all|studio|workflow|lab, q (recherche littérale du titre, insensible à la casse, jusqu’à 200 caractères) et folder_id (un ID de dossier appartenant au compte, ou unfiled pour aucun dossier). Omettez folder_id pour inclure tous les dossiers.

GET /projects renvoie projects avec project_id, project_name, source, folder_id (chaîne ou null), status, created_at et updated_at. Le statut reflète le projet d’origine ou l’historique Lab ; utilisez GET /tasks/{task_id} pour le statut de génération. Utilisez le renvoyé pour les mises à jour ; les entrées Lab héritées sans projet associé utilisent leur ID d’exécution Lab. renvoie avec , , , et .

12

Idempotence#

Envoyez Idempotency-Key (1 à 200 caractères) lors de l’envoi de requêtes Lab ou Studio. Le même compte, la même valeur de clé, le même point de terminaison et le même contenu JSON renvoient la tâche d’origine, y compris via différentes clés API de ce compte. L’ordre des propriétés de l’objet est ignoré. La réutilisation d’une clé pour un contenu différent renvoie HTTP 409 IDEMPOTENCY_CONFLICT. Si la requête d’origine est encore en cours de validation, HTTP 409 REQUEST_IN_PROGRESS vous demande de réessayer avec la même clé. Un envoi rejeté reste associé à sa clé ; corrigez-le avec une nouvelle clé.

Des index uniques persistants empêchent que des nouvelles tentatives concurrentes créent une autre génération ou réservation. Les enregistrements d’idempotence restent associés à l’historique des tâches.

13

Callbacks signés#

Fournissez un callback_url public facultatif. V4V envoie task.completed ou task.failed avec les champs de la tâche, la liste des résultats et le event_id stable. Les callbacks comportent les en-têtes X-V4V-Timestamp et X-V4V-Signature: v1=<hex>. Vérifiez-les à l’aide du secret de signature webhook affiché lors de la création de la clé API.

La signature est un HMAC-SHA256 calculé sur l’horodatage, un point littéral et le corps brut exact de la requête. Rejetez les horodatages trop anciens (par exemple, de plus de cinq minutes) et comparez les signatures en temps constant.

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'));

Renvoyez rapidement une réponse 2xx. La livraison a lieu au moins une fois : dédupliquez par event_id. Les échecs réseau, délais d’expiration, réponses HTTP 408/429 et réponses 5xx sont réessayés avec un backoff exponentiel, à partir de 30 secondes et plafonné à une heure, jusqu’à 12 tentatives par défaut. Les autres réponses non réussies, y compris les redirections, arrêtent la livraison. Les nouvelles tentatives ne créent jamais de générations et ne facturent jamais de crédits. Interrogez le statut de la tâche si la livraison du callback est épuisée.

Callbacks de lot Studio

POST /studio/batches accepte aussi un callback_url facultatif. La même vérification de callback signé s’applique. Les événements sont batch.updated, batch.completed, batch.paused et batch.cancelled, avec un event_id stable, batch_id, batch_revision, observed_at, state_token, des totaux et des crédits. Lisez GET /studio/batches/{batch_id} pour obtenir les résultats paginés actuels. Les événements contiennent des instantanés compacts plutôt que des URL de téléchargement expirantes ; les changements intermédiaires peuvent être regroupés entre les cycles du worker.

La livraison est durable et réessayée indépendamment de la génération. Dédupliquez par event_id et tolérez les événements hors ordre ; une livraison répétée conserve le même corps. Des récepteurs lents ou défaillants ne créent pas de nouvelles générations et ne bloquent pas la file de génération. L’annulation peut émettre une mise à jour supplémentaire lorsque le travail déjà admis se termine. Une demande ultérieure de redémarrage ou de reprise du travail réactive la supervision. Un webhook est une intégration HTTP et ne réveille pas à lui seul un chat de navigateur terminé.

14

Erreurs et limites#

Les erreurs utilisent un format unique :

json
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Allowed values: 5, 10.",
    "field": "parameters.duration"
  }
}

HTTP 400/422 indique une entrée ou des paramètres invalides ; 401 une clé invalide/révoquée ; 402 des crédits insuffisants ; 403 des modèles désactivés ou un accès refusé ; 404 des modèles/fichiers/tâches indisponibles ; 409 un conflit d’idempotence ou une validation en cours ; 429 une limite de débit/concurrence ; 500 une erreur interne ; et 503 une indisponibilité temporaire du service. Les codes d’erreur incluent 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 et SERVICE_UNAVAILABLE. GENERATION_SERVICE_ERROR identifie une erreur interne du service de modèle signalée ; cela n’établit pas que la taille de l’entrée ou les paramètres étaient invalides. Les ID de fichier manquants et inaccessibles partagent une réponse 404 afin d’éviter de révéler les fichiers d’autres comptes.

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
  }
}

Pour les rejets dans la fenêtre de requête (avant la création de la tâche), attendez le délai indiqué et réutilisez la même clé d’idempotence et les mêmes arguments. Une réponse identifiant une tâche déjà en échec est définitive pour cette tâche. Cela n’autorise pas une autre tentative payante après un échec terminal de génération.

15

Génération en masse Studio (API et MCP)#

La génération en masse est disponible via l’API et MCP. Il n’existe pas encore d’espace de travail de génération en masse dans l’interface Studio. Envoyez jusqu’à 300 produits dans une seule requête JSON. Chaque élément crée un flux de travail Studio avec sa propre tâche, ses paramètres/flux de travail enregistrés, ses résultats et sa comptabilisation des crédits. L’import des produits et le téléchargement des références s’effectuent en arrière-plan ; un élément invalide échoue indépendamment tandis que les autres continuent.

Studio, LAB, REST, MCP, Shopify et la génération d’avatar partagent une file serveur persistante avec un plafond absolu de 10 requêtes de génération actives pour ce déploiement. L’attente d’un résultat de génération occupe un emplacement. Une génération terminée libère cet emplacement même pendant l’enregistrement de son fichier. Les requêtes ordinaires sont prioritaires sur les requêtes en masse ; le mode en masse utilise la capacité disponible, sous réserve des limites globales de masse et par compte définies par un administrateur. Les valeurs par défaut sont de 2 flux de travail en masse simultanés et 1 par compte. Plusieurs lots appartenant à un même compte partagent cette limite. Le traitement se poursuit sans navigateur ouvert ni interrogation du client.

Créer un lot

POST /api/v1/studio/batches — renvoie HTTP 202. Fournissez un en-tête Idempotency-Key obligatoire de 1 à 200 caractères. Réutilisez la même clé et un JSON identique après une interruption réseau. Un corps modifié avec la même clé renvoie HTTP 409 ; l’acceptation ne crée jamais un second lot lors d’une nouvelle tentative.

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" }
      }
    ]
  }'

Utilisez la durée, le format et la qualité pris en charge par le flux de travail Studio actuel de votre déploiement, comme pour . L’exemple prévoit 600 crédits pour trois clips Omni de 8 secondes en 720p : 3 × 180 = 540 crédits, laissant 60 crédits de marge. Trois clips de 10 secondes en 720p utilisent 675 crédits ; en 1080p, 990 ; et en 4K, 1 980, avant la tarification des vidéos de référence, les étapes supplémentaires ou les nouvelles tentatives. Obtenez toujours les estimations actuelles pour les entrées exactes avant de choisir un budget de lot.

V4V / API reference · v1Créez quelque chose qui mérite d’être regardé.
pricing_by_variant

Gemini 4 Argon (chat.gemini_4_argon) est également disponible via le Laboratoire, les Flux de travail et l’API/MCP. Son utilisation en entrée, entrée mise en cache, sortie et réflexion est ajustée après la réponse. Consultez les tarifs actuels, les dates de lancement et les ajustements de taux via la découverte du modèle.

@image_1
@video_1
@name

Les modèles Keyframe utilisent firstFrameUrl. Standard Keyframe accepte aussi des keyframeUrls ordonnés (jusqu'à 8 images intermédiaires) et lastFrameUrl ; ceux-ci nécessitent une première image. Le nombre total d'images ne peut pas dépasser min(duration + 1, 10). Flash Keyframe ne prend en charge que la première image. Mentionnez les images comme @first_frame, @keyframe_1, @last_frame. La sortie basée sur les images suit le format d'image de la première image.

Tous les champs média, y compris les éléments et voix imbriqués, acceptent des URL ou des ID de fichier V4V possédés dans l'API/MCP. Les ports image/vidéo des Flux de travail utilisent reference_image_urls / reference_video_urls, ou first_frame_url / keyframe_urls / last_frame_url ; les prompts utilisent script-in. Standard Reference accepte aussi l'audio sur voice_audio_urls, déclaré comme @voice_1, @voice_2, etc. Les deux sorties des Flux de travail sont des video / clips standard, adaptés au moteur de rendu et à l'éditeur existants. L'API/MCP renvoie la tâche asynchrone habituelle et des fichiers de résultat téléchargeables ; interrogez la tâche ou utilisez les webhooks de fin.

Taux de base approuvés en crédits V4V par seconde, avant les remplacements administrateur ou les ajustements existants de flux de travail. Ces taux sont utilisés directement, sans conversion USD ni majoration retail :

Modèle720p, sans vidéo720p, avec vidéo1080p, sans vidéo1080p, avec vidéo
Standard Reference28.51742.525.5
Standard Keyframe28.5indisponible42.5indisponible
Flash Reference1711.3indisponibleindisponible
Flash Keyframe17indisponibleindisponibleindisponible

Exemples pour une sortie de 5 secondes :

Modèle5 s sans vidéo source5 s avec jusqu'à 5 s de vidéo source
Standard Reference, 720p142.5 crédits170 crédits
Standard Reference, 1080p212.5 crédits255 crédits
Standard Keyframe, 720p / 1080p142.5 / 212.5 créditsindisponible
Flash Reference, 720p85 crédits113 crédits
Flash Keyframe, 720p85 créditsindisponible

Sans entrée vidéo, les secondes facturables sont égales aux secondes de sortie. Avec une vidéo de référence ou un élément vidéo, les secondes facturables sont égales à max(total input video seconds, output seconds) + output seconds, au tarif correspondant avec entrée vidéo. Par exemple, une sortie Standard Reference 1080p de 10 s avec 15 s d'entrée représente 25 secondes facturées, soit 637.5 crédits avant ajustements. Les fractions de crédit sont conservées ; la facturation complète est arrondie une seule fois à deux décimales. Si la durée d'entrée est inconnue, la durée d'entrée maximale autorisée par le modèle est utilisée pour une estimation prudente ; le serveur vérifie les durées sources réelles avant facturation. Demandez un devis actuel en utilisant les mêmes entrées que pour la génération. L'administration expose des tarifs distincts résolution/entrée vidéo pour chaque nœud. Les anciens nœuds Kling conservent leurs tarifs et réglages existants.

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"
  }
}

Utilisez ce corps avec generate_lab dans MCP ou POST /api/v1/lab en HTTP. Pour un devis, ajoutez "source": "lab" et utilisez estimate_generation dans MCP ou POST /api/v1/generation/quote en HTTP. Découvrez toujours d'abord le modèle sélectionné avec get_model ou GET /api/v1/models/{id}. L'autorisation de génération standard, les vérifications de solde, les clés d'idempotence, les callbacks et les remboursements en cas d'échec s'appliquent.

credits_estimated
initial_reservation_estimated

GET /tasks/{task_id} et les callbacks de fin renvoient du texte en ligne sans nécessiter de fichier média :

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 reflète la réservation étendue après ajustement. incomplete: true signifie que la limite de sortie a été atteinte ; les tokens consommés sont quand même facturés. Des interrogations répétées ou la répétition de la même clé d’idempotence ne créent pas une autre facturation.

parameters.style
input.prompt
describe_studio

Le flux de travail sélectionné détermine les limites. ProVid prend en charge des durées entières de 4 à 15 secondes, 480p/720p/1080p, et les ratios 9:16, 16:9, 1:1, 4:5, 4:3, 3:4, 21:9, adaptatif. OmniVid prend en charge 4/6/8/10 secondes, 360p/720p/1080p/4k, et 9:16 ou 16:9. Les nouvelles requêtes OmniVid Studio utilisent par défaut 720p et 10 secondes sauf si des paramètres explicites sont fournis. Les options invalides renvoient une erreur de validation. Les limites de combinaison des médias s’appliquent également. OmniVid prend en charge les ID de référence audio dans le Laboratoire mais n’accepte pas les fichiers bruts de référence audio dans Studio ; les références non prises en charge renvoient une erreur de validation.

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

À la fin, lisez les résultats texte inline ; téléchargez les fichiers média depuis results[].url. Pendant l’enregistrement des fichiers générés, la tâche reste processing ; le seul succès de la génération ne constitue pas un achèvement. Répétez la requête de statut pour actualiser les URL de téléchargement expirées. L’interrogation ne lance pas une autre génération et ne facture pas de crédits.

Interrogez GET /tasks/{task_id}, ou fournissez une URL de callback. Le statut est queued, processing, completed, failed ou cancelled. L’interrogation nécessite une clé API détenue par le même compte que la tâche.

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"
    }
  ]
}

Chaque résultat média inclut des valeurs asset_id et file_id stables. Utilisez file_id dans les entrées média des générations suivantes. Les réponses incluent aussi project_id. La liste des résultats prend en charge plusieurs images, vidéos et fichiers audio. Les liens de résultat sont signés et utilisables sans cookies V4V ni authentification. Récupérez à nouveau le statut de la tâche pour renouveler les liens expirés. La garantie de réutilisation repose sur un ID de fichier stable plus une URL signée renouvelable, tant que le fichier stocké existe et que l’accès reste autorisé ; ce n’est pas une URL publique immuable. Pour réutiliser un résultat le lendemain, résolvez à nouveau le même ID de tâche/fichier puis téléchargez via la nouvelle URL. Toute personne détenant un lien de résultat peut l’utiliser jusqu’à son expiration.

Pour les requêtes LAB/Studio uniques, les crédits estimés sont retenus lorsque la capacité du compte est disponible. Si la limite configurée de tâches simultanées est atteinte (3 par défaut), la requête renvoie la même tâche durable en file d’attente avec credits_reserved, credits_estimated et queue à zéro, contenant limit, retry_after_seconds: 5 et estimated_start_at: null. Le worker admet les tâches en attente sans autre soumission. Il réserve les crédits de façon atomique lorsqu’un slot s’ouvre ; si le solde est alors insuffisant, la tâche échoue à stage: "admission" et planifie son webhook. Réutilisez la clé d’idempotence d’origine après des erreurs réseau ; ne créez pas une autre tâche pour contourner l’attente. Pour les lots bulk, l’estimation de chaque élément n’est retenue que lorsque cet élément est admis à démarrer. Les frais de génération consomment cette réservation. Les frais de génération en échec suivent le chemin de remboursement existant ; les crédits retenus inutilisés sont libérés à la fin ou en cas d’échec. Les étapes réussies dans un flux de travail Studio partiellement en échec conservent leurs frais normaux. Discovery, l’interrogation, la consultation de fichiers, les callbacks et les nouvelles tentatives de callback n’ont pas de frais de génération.

GET /balance renvoie les crédits actuellement disponibles. GET /usage renvoie les 100 dernières requêtes de génération du compte. Le profil affiche le nombre total de requêtes/générations sur toute la durée de vie et les crédits réglés pour chaque clé, ainsi que l’historique récent des tâches. Les téléversements restent dans la bibliothèque Lab de l’utilisateur et peuvent y être supprimés.

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

Une mise à jour de projet accepte project_name (après suppression des espaces superflus, 1 à 200 caractères), folder_id, ou les deux. Envoyez {"folder_id":null} pour retirer un projet de tout dossier. Les champs omis restent inchangés. La réponse contient project_id et les champs mis à jour. Les renommages et déplacements mettent aussi à jour la tâche API correspondante et l’historique Lab ; les tâches en file d’attente conservent l’organisation lors de la création de leurs projets.

Les noms de dossier sont nettoyés des espaces superflus, doivent contenir entre 1 et 80 caractères, et être uniques dans un compte. La création renvoie HTTP 201 ; le renommage renvoie 200, chacun avec les champs de dossier ci-dessus. Le renommage conserve l’ID du dossier et ses projets. Un nom en double renvoie 409 FOLDER_NAME_CONFLICT ; des champs invalides renvoient 422 INVALID_INPUT ; des projets ou dossiers inaccessibles renvoient 404 PROJECT_NOT_FOUND ou FOLDER_NOT_FOUND. Après une réponse incertaine à la création d’un dossier, listez les dossiers avant de réessayer.

Les réponses de lot incluent state_token, qui change en cas de progression ou de commandes significatives, et reste stable lorsque seules les URL signées sont renouvelées. MCP expose en plus wait_studio_batch pour une attente côté serveur bornée pendant une conversation active ; voir surveillance MCP.

POST /api/v1/studio
ChampSignification
nameNom de lot obligatoire, 1 à 200 caractères
max_creditsBudget de crédits positif obligatoire ; les crédits dépensés plus les réservations actives ne peuvent jamais le dépasser
input, parametersChamps Studio partagés facultatifs, utilisant les mêmes noms que pour une requête Studio unique
itemsTableau obligatoire de 1 à 300 objets produit
items[].skuRéférence client facultative, 200 caractères maximum
items[].product_idID facultatif de la bibliothèque Products appartenant à ce compte
items[].product_urlPage produit publique facultative à importer ; les paramètres de variante/requête sont conservés, sauf le suivi eBay, qui est canonicalisé
items[].input, items[].parametersRemplacements au niveau de l’élément ; la priorité est élément → lot → valeurs par défaut Studio
test_countValeur facultative 5 ; traite uniquement les cinq premiers éléments puis attend une reprise explicite

Utilisez un ID de bibliothèque produit, une URL de page produit, ou les détails/images du produit dans input. Lorsque l’ID produit et l’URL sont tous deux fournis, le produit de la bibliothèque est utilisé. Les champs d’entrée explicitement fournis par l’appelant remplacent les valeurs importées. Les médias de référence sont copiés dans un stockage détenu par le compte par le même service que celui utilisé pour les générations API uniques. Les imports API de pages produit utilisent des requêtes HTTP publiques bornées avec redirections validées. Les liens d’annonces eBay disposent aussi d’un mécanisme de secours protégé par navigateur. Une boutique peut néanmoins refuser un import ou exiger une connexion ; dans ce cas, fournissez un ID de produit détenu par le compte ou des données/images produit préparées. La limite du corps de requête est de 1 Mio. Envoyez des listes de produits en JSON ; le téléversement de fichier CSV ne fait pas partie de cette version de l’API.

La réponse inclut batch_id, status, total_items, max_credits, credits_used, credits_committed, des totaux et une première page d’éléments. L’acceptation initiale ne réserve aucun crédit pour l’ensemble du lot. Les tâches peuvent apparaître au cycle suivant du worker ; un élément accepté peut donc initialement avoir un tableau attempts vide.

Progression et résultats

  • GET /api/v1/studio/batches?offset=0&limit=50 liste les lots de ce compte.
  • GET /api/v1/studio/batches/{batch_id}?offset=0&limit=50 renvoie la progression des éléments. La pagination s’effectue par index d’élément basé sur zéro, avec une taille de page maximale de 100.
  • Chaque élément inclut son index, son sku facultatif, son statut et son attempts. Une tentative inclut un task_id, version, credits_used et un statut normaux ; les tentatives terminées incluent des URL de résultat signées.
  • GET /api/v1/tasks/{task_id} récupère une tentative unique et actualise ses liens de résultat signés. Les règles normales de propriété des tâches s’appliquent entre les clés appartenant au même compte.

Un élément avec IMPORT_FAILED a échoué avant l’admission à une génération payante. Son message d’erreur identifie, lorsqu’elle est connue, une page eBay/de sécurité bloquante et suggère une nouvelle tentative ou des données produit préparées. PREPARATION_FAILED identifie un échec inattendu de préparation de génération après l’import ; incluez le task_id lors d’un contact avec le support. Les erreurs de validation/média conservent leurs codes spécifiques. Les autres éléments continuent. Chaque tentative en échec est terminale : resume ne la relance pas. Après correction de l’entrée ou déploiement d’un correctif, utilisez retry_failed ou rework ci-dessous pour créer une nouvelle tentative dans le même lot. La réutilisation de la clé de création d’origine renvoie le lot d’origine ; elle ne le relance pas.

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.

N’interrogez pas plus d’une fois toutes les cinq secondes. Un lot signale completed lorsque tous ses éléments ont atteint un statut terminal ; inspectez les totaux et les erreurs individuelles, car l’achèvement peut inclure des éléments en échec. Un élément retenu derrière un échantillon de cinq éléments signale waiting_for_sample. L’échantillon se met en pause avec TEST_REVIEW_REQUIRED après la stabilisation de ses tentatives.

Mettre en pause, reprendre, annuler et augmenter le budget

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

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

La mise en pause et l’annulation empêchent les démarrages futurs. Les tentatives déjà admises au démarrage conservent leurs réservations et se terminent normalement. La reprise poursuit le reste après un échantillon, une recharge de solde ou une augmentation du budget. Les budgets ne peuvent qu’augmenter. L’annulation arrête les éléments restants. Ces commandes sont idempotentes tant que l’état demandé du lot reste inchangé ; un lot annulé ne peut pas resume, mais il peut explicitement restart ou rework des éléments terminaux.

Réessayer les échecs, retravailler des éléments ou redémarrer un lot

Utilisez le même point de terminaison POST /api/v1/studio/batches/{batch_id}. Ces actions créent de nouvelles tentatives, potentiellement payantes, et nécessitent un nouvel en-tête Idempotency-Key (1 à 200 caractères) pour chaque opération intentionnelle. Réutilisez cette clé et un JSON identique après une interruption réseau. Un corps modifié renvoie IDEMPOTENCY_CONFLICT. Les clés de ces opérations sont délimitées au compte et au lot, séparément de la création du lot. Le corps de requête est limité à 1 Mio.

ActionCe qui s’exécute
retry_failedUniquement les éléments dont la tentative la plus récente a échoué. item_indexes facultatif permet de sélectionner un sous-ensemble ; omettez-le pour inclure tous les échecs.
reworkÉléments terminaux sélectionnés, y compris ceux réussis ou annulés. Les entrées items requises identifient exactement un index indexé à partir de zéro ou le task_id actuel, ainsi que, éventuellement, product_id, product_url, input ou parameters.
restartChaque élément, y compris les réussites, avec une nouvelle tentative. Attendez d’abord que le travail admis soit terminé. L’échantillon de contrôle est supprimé.
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}'

Pour corriger un seul produit sans régénérer les éléments réussis :

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
      }
    }
  ]
}

Pour refaire des résultats qui ne vous plaisent pas, copiez leur items[].task_id actuel depuis la réponse du lot. Vous pouvez conserver les mêmes entrées ou fournir un nouveau prompt :

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

Utilisez l’URL de lot existante et une nouvelle opération Idempotency-Key. Le lot repasse à running, les éléments sélectionnés deviennent queued, et leurs task_id/results/error de niveau supérieur sont effacés jusqu’à ce que la nouvelle tentative soit matérialisée/terminée. Les autres éléments terminés restent inchangés. La sortie antérieure n’est conservée que dans l’historique attempts ; les consommateurs doivent afficher items[].results pour le résultat actuel. Une seule de index ou task_id est autorisée par entrée. Une tâche étrangère/sans rapport renvoie TASK_NOT_FOUND ; une tâche issue d’une version déjà remplacée renvoie BATCH_ITEM_VERSION_CHANGED (409), afin que des sélections obsolètes ne puissent pas relancer silencieusement un résultat plus récent. Rejouer une clé acceptée reste sûr même après que sa tâche sélectionnée est devenue historique.

Pour une relance complète, envoyez {"action":"restart"} avec une nouvelle clé. Les trois actions acceptent des modifications facultatives à l’échelle de l’opération pour input et parameters, ainsi qu’un max_credits augmenté. Les modifications sont fusionnées avec la requête précédente de cet élément ; les modifications par élément priment. Changer product_id ou product_url efface l’alternative précédente. Les instantanés de requête et résultats antérieurs restent inchangés. Les nouvelles tentatives suivantes héritent des dernières corrections acceptées et préparent un nouveau flux de travail.

Les tentatives sélectionnées doivent être terminales. BATCH_ITEMS_ACTIVE (409) signifie que le travail est encore en file d’attente/admis/en cours de traitement, qu’un élément de nouvelle tentative sélectionné n’a pas échoué, ou qu’une autre nouvelle tentative vient d’être acceptée. Pour un redémarrage complet, annulez le travail en attente et attendez que les tentatives admises soient terminées. GENERATION_UNRESOLVED (409) bloque les nouvelles tentatives tant qu’une requête de génération antérieure est en file d’attente, en cours d’exécution, en cours d’envoi ou incertaine ; réconciliez d’abord son résultat. NO_FAILED_ITEMS (409) signifie qu’il n’y a rien à relancer. La relance et la reprise de travail démarrent explicitement le traitement, y compris pour les autres éléments en attente de ce lot ; un échantillon de contrôle existant de cinq éléments est conservé sauf si resume ou restart le supprime.

max_credits reste une limite cumulative : les frais antérieurs plus les réservations actuelles comptent toujours. Une nouvelle tentative ne rembourse pas les étapes antérieures réussies et ne réinitialise pas le budget. Aucune réservation de lot complet n’est effectuée. Les nouvelles versions utilisent les mêmes files globales et par compte pour le traitement en lot. Les journaux de crédits API/MCP conservent l’attribution par lot, élément et version.

Les réponses conservent chaque tentative dans items[].attempts, chacune avec sa propre tâche/projet et un version croissant (des numéros peuvent être sautés). items[].version, le statut de l’élément et counts décrivent la dernière version visée ; une nouvelle version signale initialement l’état en file d’attente même avant que sa tâche soit matérialisée. credits_used inclut toutes les versions. Un lot n’est terminé que lorsque la version la plus récente de chaque élément est terminale. Les opérations rejouées ne démarrent jamais de tentatives supplémentaires. Jusqu’à 100 opérations créant des versions et 8 MiB de modifications cumulées sont conservées par lot ; BATCH_HISTORY_LIMIT (409) demande un nouveau lot lorsque la limite est atteinte.

INSUFFICIENT_CREDITS ou BUDGET_EXCEEDED suspend les nouveaux démarrages. L’ajout de crédits au compte ne reprend pas automatiquement un lot : appelez explicitement resume. L’admission sur budget et la réservation de compte sont atomiques dans leurs documents MongoDB respectifs, de sorte que des workers concurrents ne peuvent ni dépasser le budget du lot ni débiter deux fois la même tentative. Aucun replica set MongoDB n’est requis.

Un délai d’expiration lors d’une recherche de statut ne prouve pas qu’une génération a échoué. Si une réponse de soumission de génération est perdue, son emplacement reste occupé pour rapprochement ; le système ne soumet pas automatiquement de requête payante de remplacement. Une fois la génération réussie, les nouvelles tentatives de stockage de fichiers réutilisent le résultat de génération existant. Les soumissions explicitement rejetées pour limitation de débit peuvent être relancées avec un backoff borné. La revue des résultats terminés, l’approbation de version, l’export ZIP et une interface de lot Studio du plan #194 plus large sont hors du périmètre de cette version de l’API ; des téléchargements signés individuels sont disponibles via les résultats de tâche normaux.

Journaux de crédits

Les administrateurs peuvent filtrer les journaux de crédits par API ou MCP. Les entrées incluent le nom/ID de la clé API, les ID de tâche/projet/job, la source de génération, ainsi que des marqueurs de lot/élément/version en cas d’utilisation. Les secrets de clés ne sont jamais journalisés.

Les réservations et l’ajustement sont des événements d’audit avec un delta de crédits nul ; les métadonnées enregistrent le montant réservé. Les frais et remboursements portent le delta de crédits réel exactement une seule fois. balanceAfter est le solde disponible du compte, qui exclut les réservations en cours. Les frais API historiques sont restaurés à partir des reçus de tâche stockés sans refacturer le compte ; lorsque le solde disponible historique ne peut pas être reconstitué, l’interface d’administration l’indique.

Diagnostics des échecs de génération

Les tâches REST en échec, les résultats MCP get_task et les callbacks signés task.failed partagent un objet d’erreur. message est le résumé V4V ; provider_error préserve la raison du service de modèle avec les identifiants, le routage privé et les emplacements réseau masqués. provider utilise l’alias de routage public 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."
  }
}

Les refus de sécurité, les modifications vocales et les durées/résolutions non prises en charge nécessitent de modifier la requête. Les limites de débit et les expirations incluent retryable: true, retry_after_seconds: 60 et une indication de récupération. Les raisons inconnues restent disponibles sans diagnostic inventé ni recommandation de nouvelle tentative. Ces champs sont omis lorsqu’aucun diagnostic du service de modèle n’existe. Les anciennes tâches en échec sont enrichies tandis que leur enregistrement d’échec de flux de travail reste disponible. Studio et le Laboratoire affichent la même raison assainie et l’envoient comme GA4 generation_failed.reason (sous réserve de la limite analytique existante de 120 caractères).

Une indication de nouvelle tentative ne lance jamais une autre génération. Une nouvelle tentative payante exige une demande explicite de l’utilisateur et une nouvelle clé d’idempotence. L’ajustement des crédits existant, les remboursements d’étapes en échec, les frais d’étapes terminées et la signature des webhooks restent en vigueur.