Vai alla documentazione
v4v.Documentazione per sviluppatoriANTEPRIMALe tue chiavi API ↗
IN QUESTA GUIDA
AutenticazioneScopri i modelli LABSottotitoli vocali temporizzatiModelli di generazione più recentiModelli video Kling 4.0Chat GPT-6 AstraLAB con un'immagine esternaCarica media privatiStudio con media esterni o privatiTask e creditiRinominare e organizzare i progettiIdempotenzaCallback firmatiErrori e limitiGenerazione in blocco Studio (API e MCP)
Disponibile per i test
Anteprima ad accesso diretto
API reference · v1

Crea con l'API V4V.

Genera immagini, video e audio dalle tue applicazioni. Una chiave API. I tuoi crediti V4V esistenti.

Inizia →Scarica OpenAPI ↓
ENDPOINThttps://v4v.ai/api/v1
cURL
curl https://v4v.ai/api/v1/models \
  -H "Authorization: Bearer $V4V_API_KEY"
01

Autenticazione#

Crea una chiave con nome in Profilo → Chiavi API. Salva il segreto API e il segreto di firma del webhook quando compaiono; vengono mostrati una sola volta. È possibile creare e revocare più chiavi in modo indipendente. I segreti delle chiavi sono memorizzati come hash SHA-256.

Invia Authorization: Bearer v4v_live_… in ogni richiesta API. Conserva questa chiave sul tuo server, fuori dalle applicazioni browser e dal controllo versione. La revoca blocca le richieste future; le generazioni già accettate continuano.

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

02

Scopri i modelli LAB#

GET /models elenca gli ID correnti dei modelli LAB, stato abilitato, input, parametri, valori predefiniti, condizioni e limiti. GET /models/{model} descrive un modello. ID e schemi provengono dallo stesso catalogo e dagli stessi valori predefiniti usati da LAB. La configurazione di Studio è separata.

I nomi dei modelli negli esempi qui sotto sono ID di catalogo reali. Usa discovery per trovare i modelli attualmente abilitati sul tuo account. I nomi dei campi sono specifici del modello: mantieni i nomi restituiti da discovery, inclusi i nomi in camelCase come aspectRatio o referenceImageUrls. I valori select sono stringhe; sono accettati anche valori numerici per opzioni select dall'aspetto numerico. I campi possono essere forniti in input o parameters, ma mai in entrambi. I campi sconosciuti vengono rifiutati. I modelli con versioni selezionabili espongono parameters.variant; usa i valori e i predefiniti restituiti da discovery.

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

Sottotitoli vocali temporizzati#

Trova ai.speech_to_text con tipo subtitle. Invia un ID di file multimediale posseduto o un URL supportato in input.audioUrl o input.videoUrl a POST /lab; i parametri facoltativi includono language_code (per esempio uk, en o auto) e diarize. La stima usa la durata originale della sorgente. La trascrizione consuma i normali crediti dell'account.

Un task completato restituisce results[].type: "subtitle", la trascrizione text, srt e cues modificabile con start, end in secondi e text. Un input silenzioso riuscito può avere un elenco di cue vuoto. Per il montaggio, usa gli strumenti MCP di Video Editor per allineare questi cue al trim, alla velocità e alla posizione nella timeline di una clip sorgente.

04

Modelli di generazione più recenti#

Omni Flash 1.2 (video.gemini_omni_flash-1-2) è il modello preferito per le richieste video senza un modello esplicito. Il Laboratorio lo elenca per primo; Omni Flash 1.1 resta disponibile in Altro e tramite il suo ID esistente. Scopri i parametri attuali con GET /models/{model}. La versione 1.2 supporta generazione e modifica da 3 a 15 secondi; l'interpolazione first/last-frame è limitata a 10 secondi. Le tariffe condivise da 4/6/8/10 secondi corrispondono ai prezzi 1.1 configurati. Usa discovery ed estimates attuali per i prezzi invece di memorizzare questa relazione come regola permanente.

Scegli GPT Image 2.6 tramite parameters.variant in image.text_to_image o ai.image_edit. Usa parameters.outputFormat con queste capacità esatte delle varianti:

VarianteFormati di output
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 è autorevole. Flare/Sunburst vengono regolati in base all'uso effettivo di input/output; l'uso della conversione SVG è incluso nel totale finale. Economy è solo 1K con prezzo per immagine. I download mantengono i frame GIF e i byte vettoriali SVG; i download SVG usano la consegna come allegato.

Nano Banana 2.1 usa parameters.variant: "nano-banana-v2.1" negli stessi moduli immagine, con fino a 10 riferimenti e output 1K/2K/4K. La modalità di fatturazione attuale è pubblicata in . La generazione Google/Vertex viene regolata in base a input verificato, input in cache, output immagine, output testo e token di thinking, con markup applicato e totale combinato arrotondato una sola volta per eccesso. La componente di output immagine è circa 11/16/36 crediti V4V per 1K/2K/4K prima di input e thinking. Il Laboratorio e le estimates mostrano un intervallo approssimativo; la prenotazione iniziale è separata dal costo finale. Gli altri instradamenti usano la tariffa per immagine configurata. L'instradamento resta gestito da V4V; non fornire un parametro di routing.

05

Modelli video Kling 4.0#

Quattro nodi separati condividono la stessa gestione di generazione e risultati in Laboratorio, Flussi di lavoro, API e MCP:

ID catalogoModelloDurataRisoluzione
video.kling_v40_refKling 4.0 Reference3–30 secondi720p / 1080p
video.kling_v40_keyKling 4.0 Keyframe3–30 secondi720p / 1080p
video.kling_v40_flash_refKling 4.0 Flash Reference3–20 secondi720p
video.kling_v40_flash_keyKling 4.0 Flash Keyframe3–20 secondi720p

Tutti accettano un prompt obbligatorio (fino a 8000 caratteri), duration intero, resolution e aspectRatio (auto, 16:9, 9:16, 1:1, 21:9; Flash Keyframe esclude auto). Tutti possono generare dal solo testo. Gli input di riferimento sono facoltativi.

I modelli Reference accettano referenceImageUrls (fino a 10), referenceVideoUrls (fino a 5), elements (fino a 7, al massimo 3 con video) e keepOriginalSound. Un elemento denominato ha name, oppure imageUrls (2–4 immagini) oppure videoUrl (una clip personaggio di 3–8 s), tag facoltativo, description (100 caratteri) e voiceUrl del personaggio. Flash accetta anche l'elemento type (image o video). Standard Reference accetta inoltre voices: fino a 3 oggetti con name e audioUrl. Flash invece associa le voci agli elementi personaggio.

Ci sono al massimo 15 tra immagini, riferimenti video, elementi e voci standalone combinati; i video di riferimento più gli elementi video non possono superare 5. Ogni video di riferimento deve durare 2–30 s (2–20 s per Flash), e la loro durata combinata inclusi gli elementi video è al massimo di 30 s (20 s per Flash). I nomi devono essere univoci ignorando maiuscole e minuscole, 1–20 caratteri cinesi, lettere, cifre o underscore; i nomi di riferimento incorporati sono riservati. Cita i riferimenti forniti come , o con il loro dichiarato. Le menzioni non dichiarate vengono rifiutate.

06

Chat GPT-6 Astra#

Trova chat.gpt_6_astra con GET /models/chat.gpt_6_astra (slug: gpt-6-astra). Ha tipo chat e restituisce testo. Discovery include le tariffe dei token e la regola di arrotondamento.

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.

Per offrire una funzione, passa input.functionTools come stringa JSON contenente 1–10 definizioni con type: "function", name, description e parameters (un oggetto JSON Schema). Imposta parameters.webSearch su false. La richiesta upstream usa tool_choice: "auto"; le richieste di funzione vengono restituite in results[].function_calls perché la tua applicazione le gestisca. Il nodo del modello non esegue funzioni né continua la conversazione con il risultato di una funzione.

La chat riserva 1 credito prima di entrare in coda. Questa è una prenotazione minima, non un prezzo fisso né un tetto di spesa. Tariffe per 1M token: input 560, input in cache 56, scritture in cache 700, output 2.800 crediti. Il costo combinato dei token viene arrotondato per eccesso una sola volta a un credito intero, con un addebito minimo di 1. Dopo la risposta, ogni addebito aggiuntivo viene detratto atomicamente dal saldo disponibile. Se il saldo è insufficiente, il task fallisce e la prenotazione non usata viene rilasciata.

Per chat e immagini con prezzo basato sull'uso, l'endpoint estimate restituisce anche credits_range con min, max, assumptions, includes_markup: true, is_estimate: true e is_spending_cap: false. Mostralo come intervallo approssimativo in crediti V4V. Include il markup attuale e gli adeguamenti di prezzo. Questi sono scenari d'uso illustrativi; il costo reale può essere fuori intervallo. e descrivono separatamente la prenotazione iniziale. L'intervallo non modifica la regolazione in base all'uso effettivo né abilita l'ammissione con budget rigido.

07

LAB con un'immagine esterna#

Gli input multimediali accettano un URL esterno o un ID file V4V nello stesso campo. Gli array possono mescolare entrambi. Gli URL devono restituire file multimediali reali senza cookie del browser né login interattivo. Sono consigliati HTTPS e URL firmati con durata sufficientemente lunga. V4V valida e copia i media esterni prima della generazione; gli URL di rete interna e i reindirizzamenti non sicuri vengono rifiutati.

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

Carica media privati#

POST /files accetta un campo file usando multipart/form-data. Sono supportati immagini, video e audio, nel rispetto dei limiti del modello. Il limite di upload predefinito è 100 MiB, ulteriormente vincolato dal limite di upload dello storage del deployment e dal limite del proxy. I file devono contenere media decodificabili; l'ispezione audio/video richiede ffprobe sul 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
}

Usa direttamente l'ID restituito, senza prefisso file_. GET /files/{id} recupera i metadati del tuo file senza consumare crediti.

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 con media esterni o privati#

POST /studio usa lo stesso flusso di lavoro Studio selezionato, la stessa preparazione, esecuzione del modello, moltiplicatore di prezzo e sconto dell'abbonamento dell'interfaccia 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"
}

Per un flusso completamente con media privati, carica prima ogni immagine prodotto usando POST /files, poi inserisci gli ID restituiti in input.product_images. Carica allo stesso modo avatar, audio e riferimenti video.

Studio accetta product_id (un prodotto salvato posseduto), avatar_id (un avatar della libreria pubblica posseduto o attivo, con prefisso public: supportato), product_name, product_description, prompt, product_images, reference_images, avatar_media, audio e video. Ogni campo multimediale accetta riferimenti; gli array supportano più file. parameters.avatar accetta un ID avatar della libreria, un singolo URL immagine o ID file, oppure null. Scegli tra input.avatar_id o parameters.avatar. I campi prodotto espliciti sostituiscono i valori predefiniti della libreria. I nomi/ID di stile attivi applicano le istruzioni di stile salvate. Valori di stile sconosciuti, inattivi o vuoti restituiscono 422 INVALID_PARAMETER, field: "parameters.style" e error.allowed_values contenenti gli ID/nomi attivi. Ometti lo stile per usare il predefinito attuale (UGC se attivo, altrimenti il primo preset attivo). I parametri includono anche style, language, voice, placement, duration, aspect_ratio e quality.

Migrazione per i client che in precedenza passavano testo libero in parameters.style: sposta quella direzione creativa in input.prompt e scegli uno stile attivo da MCP (oppure ometti lo stile per il predefinito attuale). Uno stile scritto in modo errato non diventa più uno stile personalizzato.

10

Task e crediti#

La generazione restituisce HTTP 202 dopo la validazione dell'input e, quando la capacità è disponibile, la prenotazione dei crediti, senza attendere la generazione:

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

Nome progetto facoltativo

Sia POST /lab sia POST /studio accettano project_name al livello superiore, insieme a input, parameters e 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"
  }
}

Il nome ripulito (1–200 caratteri, non vuoto) diventa il titolo in Progetti e, per LAB, in Vecchie esecuzioni. Se omesso, viene usato il titolo predefinito esistente. La risposta del task include project_name e project_id. Cambiare il nome con la stessa chiave di idempotenza crea un conflitto, proprio come cambiare gli input di generazione.

Stato del task

Il server aggiorna lo stato della generazione in background. Il polling restituisce l'ultimo status salvato: queued, processing, completed, failed o cancelled. Mentre il task è queued o processing, mostra un indicatore di caricamento. Quando status è completed, leggi il testo della chat da results[].text o scarica i file multimediali da results. Per failed, controlla error (inclusi i valori non riusciti stage, brief_completed, retryable e il suggerimento retry_after_seconds dove noto) e credits_used. Una generazione breve riuscita può mantenere il suo addebito se il rendering fallisce; un suggerimento di nuovo tentativo transitorio non avvia né autorizza un nuovo tentativo a pagamento. Anche cancelled è terminale.

I webhook sono facoltativi. Senza callback_url, ripeti la seguente richiesta ogni 3–5 secondi finché status non è completed, failed o cancelled:

11

Rinominare e organizzare i progetti#

L'organizzazione dei progetti usa le stesse cartelle dell'area di lavoro Projects. Non genera contenuti multimediali, non riserva crediti e non modifica input di generazione, risultati o hash di idempotenza. Tutte le operazioni richiedono la tua chiave API e accedono solo ai progetti e alle cartelle del tuo account.

Metodo e percorsoScopo
GET /projectsTrova progetti Studio, flussi di lavoro e LAB, incluse le attività API in coda
PATCH /projects/{project_id}Rinomina un progetto e/o spostalo in una cartella
GET /project-foldersElenca le cartelle dell'area di lavoro
POST /project-foldersCrea una cartella con {"name":"Summer campaign"}
PATCH /project-folders/{folder_id}Rinomina una cartella con {"name":"Autumn campaign"}

Entrambi gli endpoint di elenco accettano offset (predefinito 0) e limit (1–100, predefinito 50), restituendo total e next_offset (null nell'ultima pagina). I progetti sono ordinati dal più recente al meno recente con un criterio stabile di spareggio basato su ID; le cartelle sono ordinate per nome. I filtri dei progetti sono source=all|studio|workflow|lab, q (ricerca letterale del titolo, senza distinzione tra maiuscole e minuscole, fino a 200 caratteri) e folder_id (un ID cartella posseduto, oppure unfiled per nessuna cartella). Ometti folder_id per includere tutte le cartelle.

GET /projects restituisce projects con project_id, project_name, source, folder_id (stringa o null), status, created_at e updated_at. Lo stato riflette il progetto originale o la cronologia LAB; usa GET /tasks/{task_id} per lo stato della generazione. Usa il valore restituito per gli aggiornamenti; le voci LAB legacy senza un progetto sottostante usano il loro ID esecuzione LAB. restituisce con , , , e .

12

Idempotenza#

Invia Idempotency-Key (1–200 caratteri) quando invii richieste LAB o Studio. Lo stesso account, valore della chiave, endpoint e contenuto JSON restituiscono l'attività originale, anche tra chiavi API diverse dello stesso account. L'ordine delle proprietà dell'oggetto viene ignorato. Riutilizzare una chiave per contenuti diversi restituisce HTTP 409 IDEMPOTENCY_CONFLICT. Se la richiesta originale è ancora in fase di convalida, HTTP 409 REQUEST_IN_PROGRESS ti chiede di riprovare con la stessa chiave. Un invio rifiutato resta associato alla sua chiave; correggilo usando una nuova chiave.

Indici univoci persistenti impediscono che tentativi simultanei creino un'altra generazione o prenotazione. I record di idempotenza restano insieme alla cronologia delle attività.

13

Callback firmati#

Fornisci un callback_url pubblico facoltativo. V4V invia task.completed o task.failed con i campi dell'attività, l'elenco dei risultati e il valore stabile event_id. I callback hanno intestazioni X-V4V-Timestamp e X-V4V-Signature: v1=<hex>. Verifica usando il segreto di firma del webhook mostrato quando è stata creata la chiave API.

La firma è HMAC-SHA256 sul timestamp, un punto letterale e il corpo grezzo esatto della richiesta. Rifiuta timestamp non più validi (per esempio, più vecchi di cinque minuti) e confronta le firme in tempo costante.

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

Restituisci rapidamente una risposta 2xx. La consegna avviene almeno una volta: deduplica in base a event_id. Errori di rete, timeout, risposte HTTP 408/429 e 5xx vengono ritentati con backoff esponenziale, a partire da 30 secondi e con limite massimo di un'ora, per un massimo predefinito di 12 tentativi. Altre risposte non riuscite, inclusi i reindirizzamenti, interrompono la consegna. I tentativi non creano mai generazioni né addebitano crediti. Esegui il polling dello stato dell'attività se la consegna del callback esaurisce i tentativi.

Callback batch Studio

POST /studio/batches accetta anche un callback_url facoltativo. Si applica la stessa verifica dei callback firmati. Gli eventi sono batch.updated, batch.completed, batch.paused e batch.cancelled, con un valore stabile event_id, batch_id, batch_revision, observed_at, state_token, conteggi e totali dei crediti. Leggi GET /studio/batches/{batch_id} per i risultati correnti paginati. Gli eventi contengono snapshot compatti invece di URL di download in scadenza; le modifiche intermedie possono essere accorpate tra i tick del worker.

La consegna è durevole e viene ritentata indipendentemente dalla generazione. Deduplica in base a event_id e tollera eventi fuori ordine; le consegne ripetute mantengono lo stesso corpo. Ricevitori lenti o con errori non creano nuove generazioni né bloccano la coda di generazione. L'annullamento può emettere un ulteriore aggiornamento quando il lavoro già ammesso termina. Un successivo riavvio o rifacimento richiesto riattiva il monitoraggio. Un webhook è un'integrazione HTTP e non riattiva di per sé una chat del browser già terminata.

14

Errori e limiti#

Gli errori usano un unico formato:

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

HTTP 400/422 indica input o parametri non validi; 401 una chiave non valida/revocata; 402 crediti insufficienti; 403 modelli disabilitati o accesso negato; 404 modelli/file/attività non disponibili; 409 un conflitto di idempotenza o una convalida in corso; 429 un limite di frequenza/concorrenza; 500 un errore interno; e 503 indisponibilità temporanea del servizio. I codici di errore includono 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 e SERVICE_UNAVAILABLE. GENERATION_SERVICE_ERROR identifica un errore interno segnalato del servizio del modello; non dimostra che la dimensione dell'input o i parametri fossero non validi. Gli ID file mancanti e quelli non accessibili condividono una risposta 404 per evitare di rivelare i file di altri account.

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

Per i rifiuti nella finestra della richiesta (prima della creazione dell'attività), attendi il ritardo indicato e riutilizza la stessa chiave di idempotenza e gli stessi argomenti. Una risposta che identifica un'attività già non riuscita è definitiva per quell'attività. Questo non autorizza un altro tentativo a pagamento dopo un errore terminale di generazione.

15

Generazione in blocco Studio (API e MCP)#

La generazione in blocco è disponibile tramite API e MCP. Non esiste ancora un'area di lavoro in blocco nell'interfaccia Studio. Invia fino a 300 prodotti in una richiesta JSON. Ogni elemento crea un flusso di lavoro Studio con la propria attività, il flusso di lavoro/le impostazioni salvati, i risultati e il conteggio dei crediti. L'importazione del prodotto e i download dei riferimenti avvengono in background; un elemento non valido fallisce in modo indipendente mentre gli elementi rimanenti continuano.

Studio, LAB, REST, MCP, Shopify e la generazione di avatar condividono una coda server persistente con un limite massimo assoluto di 10 richieste di generazione attive per questa distribuzione. L'attesa del risultato di una generazione occupa uno slot. Una generazione completata libera quello slot anche mentre il suo file viene salvato. Le richieste ordinarie hanno priorità su quelle in blocco; l'elaborazione in blocco usa la capacità disponibile, soggetta ai limiti globali in blocco e per account dell'amministratore. I valori predefiniti sono 2 flussi di lavoro in blocco simultanei e 1 per account. Più batch appartenenti allo stesso account condividono questo limite. L'elaborazione continua senza un browser aperto o polling del client.

Crea un batch

POST /api/v1/studio/batches — restituisce HTTP 202. Fornisci un'intestazione Idempotency-Key obbligatoria di 1–200 caratteri. Riutilizza la stessa chiave e lo stesso JSON dopo un'interruzione di rete. Un corpo modificato con la stessa chiave restituisce HTTP 409; l'accettazione non crea mai un secondo batch per un tentativo ripetuto.

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

Usa durata, formato e qualità supportati dal flusso di lavoro Studio attuale della tua distribuzione, come per POST /api/v1/studio. L'esempio prevede un budget di 600 crediti per tre clip Omni da 8 secondi a 720p: 3 × 180 = 540 crediti, lasciando 60 crediti di margine. Tre clip da 10 secondi a 720p usano 675 crediti; a 1080p ne usano 990 e a 4K 1.980, prima del prezzo del video di riferimento, dei passaggi extra o dei tentativi ripetuti. Ottieni sempre stime aggiornate per gli input esatti prima di scegliere un budget batch.

V4V / API reference · v1Crea qualcosa che valga la pena guardare.
pricing_by_variant

Gemini 4 Argon (chat.gemini_4_argon) è disponibile anche tramite Laboratorio, flussi di lavoro e API/MCP. Il suo uso di input, input in cache, output e thinking viene regolato dopo la risposta. Leggi prezzi attuali, date di lancio e adeguamenti delle tariffe da model discovery.

@image_1
@video_1
@name

I modelli Keyframe usano firstFrameUrl. Standard Keyframe accetta anche keyframeUrls ordinati (fino a 8 fotogrammi intermedi) e lastFrameUrl; questi richiedono un primo fotogramma. Il totale dei fotogrammi non può superare min(duration + 1, 10). Flash Keyframe supporta solo il primo fotogramma. Cita i fotogrammi come @first_frame, @keyframe_1, @last_frame. L'output basato sui fotogrammi segue il rapporto d'aspetto della prima immagine.

Tutti i campi media, inclusi elementi e voci nidificati, accettano URL o ID file V4V di tua proprietà in API/MCP. Le porte immagine/video dei flussi di lavoro usano reference_image_urls / reference_video_urls, oppure first_frame_url / keyframe_urls / last_frame_url; i prompt usano script-in. Standard Reference accetta inoltre audio su voice_audio_urls, dichiarato come @voice_1, @voice_2, ecc. Entrambi gli output del flusso di lavoro sono standard video / clips, adatti al renderer e all'editor esistenti. API/MCP restituiscono la consueta attività asincrona e i file di risultato scaricabili; esegui il polling dell'attività o usa i webhook di completamento.

Tariffe base approvate in crediti V4V al secondo, prima delle sostituzioni dell'amministratore o delle regolazioni esistenti del flusso di lavoro. Queste tariffe vengono usate direttamente, senza conversione in USD né ricarico retail:

Modello720p, senza video720p, con video1080p, senza video1080p, con video
Standard Reference28.51742.525.5
Standard Keyframe28.5non disponibile42.5non disponibile
Flash Reference1711.3non disponibilenon disponibile
Flash Keyframe17non disponibilenon disponibilenon disponibile

Esempi per un output di 5 secondi:

Modello5 s senza video sorgente5 s con fino a 5 s di video sorgente
Standard Reference, 720p142.5 crediti170 crediti
Standard Reference, 1080p212.5 crediti255 crediti
Standard Keyframe, 720p / 1080p142.5 / 212.5 creditinon disponibile
Flash Reference, 720p85 crediti113 crediti
Flash Keyframe, 720p85 creditinon disponibile

Senza input video, i secondi fatturabili equivalgono ai secondi di output. Con video di riferimento o un elemento video, i secondi fatturabili equivalgono a max(total input video seconds, output seconds) + output seconds, alla corrispondente tariffa con input video. Per esempio, un output Standard Reference 1080p di 10 s con 15 s di input corrisponde a 25 secondi fatturati, 637.5 crediti prima delle regolazioni. I crediti frazionari vengono mantenuti; l'addebito completo viene arrotondato una sola volta a due decimali. Se la durata dell'input è sconosciuta, viene usata per una stima prudenziale la durata massima di input consentita dal modello; il server verifica le durate reali delle sorgenti prima dell'addebito. Richiedi un preventivo aggiornato usando gli stessi input della generazione. L'amministrazione espone tariffe separate per risoluzione/input video per ogni nodo. I nodi Kling meno recenti mantengono i loro prezzi e impostazioni esistenti.

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

Usa questo body con generate_lab in MCP o POST /api/v1/lab in HTTP. Per un preventivo, aggiungi "source": "lab" e usa estimate_generation in MCP o POST /api/v1/generation/quote in HTTP. Individua sempre prima il modello selezionato con get_model o GET /api/v1/models/{id}. Si applicano l'autorizzazione standard della generazione, i controlli del saldo, le chiavi di idempotenza, i callback e i rimborsi per errore.

credits_estimated
initial_reservation_estimated

GET /tasks/{task_id} e i callback di completamento restituiscono testo inline senza richiedere un file multimediale:

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 riflette la prenotazione ampliata dopo la regolazione. incomplete: true significa che è stato raggiunto il limite di output; i token consumati vengono comunque fatturati. Polling ripetuti o il nuovo tentativo della stessa chiave di idempotenza non creano un altro addebito.

describe_studio

Il flusso di lavoro selezionato determina i limiti. ProVid supporta da 4 a 15 secondi interi, 480p/720p/1080p e rapporti 9:16, 16:9, 1:1, 4:5, 4:3, 3:4, 21:9, adaptive. OmniVid supporta 4/6/8/10 secondi, 360p/720p/1080p/4k e 9:16 o 16:9. Le nuove richieste Studio OmniVid usano per impostazione predefinita 720p e 10 secondi, salvo impostazioni esplicite. Le opzioni non valide restituiscono un errore di validazione. Si applicano anche i limiti di combinazione dei media. OmniVid supporta ID di riferimento audio in LAB ma non accetta file di riferimento audio grezzi in Studio; i riferimenti non supportati restituiscono un errore di validazione.

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

Al completamento, leggi i risultati testuali inline; scarica i file multimediali da results[].url. Mentre i file generati vengono salvati, il task resta processing; il solo successo della generazione non equivale al completamento. Ripeti la richiesta di stato per aggiornare gli URL di download scaduti. Il polling non avvia un'altra generazione né addebita crediti.

Esegui il polling di GET /tasks/{task_id} oppure fornisci un URL di callback. Lo stato è queued, processing, completed, failed o cancelled. Il polling richiede una chiave API posseduta dallo stesso account del task.

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

Ogni risultato multimediale include valori asset_id e file_id stabili. Usa file_id negli input multimediali delle generazioni successive. Le risposte includono anche project_id. L'elenco dei risultati supporta più immagini, video e file audio. I link dei risultati sono firmati e utilizzabili senza cookie V4V né autenticazione. Recupera di nuovo lo stato del task per rinnovare i link scaduti. La garanzia di riutilizzo consiste in un ID file stabile più un URL firmato rinnovabile, finché il file memorizzato esiste e l'accesso resta consentito; non è un URL pubblico immutabile. Per riutilizzare un risultato il giorno successivo, risolvi di nuovo lo stesso ID task/file e scaricalo tramite il nuovo URL. Chiunque possieda un link al risultato può usarlo fino alla scadenza.

Per richieste singole LAB/Studio, i crediti stimati vengono trattenuti quando la capacità dell'account è disponibile. Se il limite configurato di task concorrenti è pieno (predefinito 3), la richiesta restituisce lo stesso task accodato durevole con credits_reserved pari a zero, credits_estimated e queue contenente limit, retry_after_seconds: 5 e estimated_start_at: null. Il worker ammette i task in attesa senza un altro invio. Prenota i crediti atomicamente quando si apre uno slot; un saldo insufficiente in quel momento fa fallire il task in stage: "admission" e pianifica il suo webhook. Riusa la chiave di idempotenza originale dopo errori di rete; non creare un altro task per aggirare l'attesa. Per i batch bulk, la stima di ogni elemento viene trattenuta solo quando quell'elemento viene ammesso all'avvio. Gli addebiti di generazione consumano quella prenotazione. Gli addebiti per generazioni non riuscite seguono il percorso di rimborso esistente; i crediti trattenuti e non usati vengono rilasciati al completamento o al fallimento. I passaggi riusciti in un flusso di lavoro Studio parzialmente non riuscito mantengono i loro normali addebiti. Discovery, polling, lookup dei file, callback e nuovi tentativi di callback non hanno alcun addebito di generazione.

GET /balance restituisce i crediti attualmente disponibili. GET /usage restituisce le ultime 100 richieste di generazione dell'account. Il profilo mostra i conteggi complessivi di richieste/generazioni e i crediti liquidati per ogni chiave, oltre alla cronologia recente delle attività. I caricamenti restano nella libreria LAB dell'utente e possono essere eliminati lì.

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

Un aggiornamento del progetto accetta project_name (ripulito dagli spazi, 1–200 caratteri), folder_id, oppure entrambi. Invia {"folder_id":null} per rimuovere un progetto da qualsiasi cartella. I campi omessi restano invariati. La risposta contiene project_id e i campi aggiornati. Rinomine e spostamenti aggiornano anche l'attività API corrispondente e la cronologia LAB; le attività in coda mantengono l'organizzazione quando i loro progetti vengono creati.

I nomi delle cartelle vengono ripuliti dagli spazi, devono contenere da 1 a 80 caratteri e sono univoci all'interno di un account. La creazione restituisce HTTP 201; la rinomina restituisce 200, in entrambi i casi con i campi della cartella indicati sopra. La rinomina mantiene l'ID della cartella e i relativi progetti. Un nome duplicato restituisce 409 FOLDER_NAME_CONFLICT; campi non validi restituiscono 422 INVALID_INPUT; progetti o cartelle non accessibili restituiscono 404 PROJECT_NOT_FOUND o FOLDER_NOT_FOUND. Dopo una risposta incerta alla creazione di una cartella, elenca le cartelle prima di riprovare.

Le risposte batch includono state_token, che cambia con progressi o controlli significativi e resta stabile quando si rinnovano solo gli URL firmati. MCP espone inoltre wait_studio_batch per un'attesa lato server limitata durante una conversazione attiva; vedi monitoraggio MCP.

CampoSignificato
nameNome batch obbligatorio, 1–200 caratteri
max_creditsBudget di crediti positivo obbligatorio; i crediti spesi più le prenotazioni attive non possono mai superarlo
input, parametersCampi Studio condivisi facoltativi, che usano gli stessi nomi di una singola richiesta Studio
itemsArray obbligatorio di 1–300 oggetti prodotto
items[].skuRiferimento client facoltativo, massimo 200 caratteri
items[].product_idID facoltativo della libreria Products posseduta da questo account
items[].product_urlPagina prodotto pubblica facoltativa da importare; i parametri di variante/query vengono mantenuti tranne il tracciamento eBay, che viene canonicalizzato
items[].input, items[].parametersOverride dell'elemento; la precedenza è elemento → batch → valori predefiniti Studio
test_countValore facoltativo 5; elabora solo i primi cinque elementi e poi attende una ripresa esplicita

Usa un ID della libreria prodotti, un URL di pagina prodotto oppure dettagli/immagini del prodotto in input. Quando vengono forniti sia l'ID prodotto sia l'URL, viene usato il prodotto della libreria. I campi di input forniti esplicitamente dal chiamante sostituiscono i valori importati. I contenuti multimediali di riferimento vengono copiati in uno spazio di archiviazione posseduto dallo stesso servizio usato per le singole generazioni API. Le importazioni API delle pagine prodotto usano richieste HTTP pubbliche limitate con reindirizzamenti convalidati. Anche i link alle inserzioni eBay hanno un fallback protetto nel browser. Un negozio può comunque rifiutare un'importazione o richiedere l'accesso; in tal caso fornisci un ID prodotto posseduto o dati/immagini del prodotto già preparati. Il limite del corpo della richiesta è 1 MiB. Invia elenchi di prodotti in JSON; il caricamento di file CSV non fa parte di questa versione API.

La risposta include batch_id, status, total_items, max_credits, credits_used, credits_committed, i conteggi e una prima pagina di elementi. L'accettazione iniziale non riserva alcun credito per l'intero batch. Le attività possono apparire al tick successivo del worker, quindi un elemento accettato può inizialmente avere un array attempts vuoto.

Avanzamento e risultati

  • GET /api/v1/studio/batches?offset=0&limit=50 elenca i batch di questo account.
  • GET /api/v1/studio/batches/{batch_id}?offset=0&limit=50 restituisce l'avanzamento degli elementi. La paginazione avviene per indice elemento a partire da zero, con una dimensione massima della pagina di 100.
  • Ogni elemento include il suo index, l'eventuale sku, lo stato e attempts. Un tentativo include un normale task_id, version, credits_used e stato; i tentativi completati includono URL dei risultati firmati.
  • GET /api/v1/tasks/{task_id} recupera un singolo tentativo e aggiorna i suoi link ai risultati firmati. Le normali regole di proprietà delle attività si applicano tra chiavi diverse possedute dallo stesso account.

Un elemento con IMPORT_FAILED non ha superato la fase precedente all'ammissione della generazione a pagamento. Il suo messaggio di errore identifica una pagina eBay/di sicurezza bloccante quando nota e suggerisce un nuovo tentativo o dati prodotto preparati. PREPARATION_FAILED identifica un errore imprevisto nella preparazione della generazione dopo l'importazione; includi task_id quando contatti l'assistenza. Gli errori di convalida/dei contenuti multimediali mantengono i loro codici specifici. Gli altri elementi continuano. Ogni tentativo non riuscito è terminale: resume non lo ritenta. Dopo aver corretto l'input o distribuito una correzione, usa retry_failed o rework sotto per creare un nuovo tentativo nello stesso batch. Riutilizzare la chiave di creazione originale restituisce il batch originale; non lo riesegue.

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.

Esegui il polling non più di una volta ogni cinque secondi. Un batch riporta completed quando tutti i suoi elementi hanno raggiunto uno stato terminale; controlla i conteggi e i singoli errori perché il completamento può includere elementi non riusciti. Un elemento trattenuto dietro un campione di cinque elementi riporta waiting_for_sample. Il campione si mette in pausa con TEST_REVIEW_REQUIRED dopo che i suoi tentativi si sono assestati.

Metti in pausa, riprendi, annulla e aumenta il budget

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

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

Mettere in pausa e annullare impediscono avvii futuri. I tentativi già ammessi all'avvio mantengono le loro prenotazioni e terminano normalmente. Riprendi continua il resto dopo un campione, una ricarica del saldo o un aumento del budget. I budget possono solo aumentare. L'annullamento interrompe gli elementi rimanenti. Questi controlli sono idempotenti finché lo stato batch richiesto resta invariato; un batch annullato non può resume, ma può esplicitamente restart o rework elementi terminali.

Ritenta gli errori, rielabora gli elementi o riavvia un batch

Usa lo stesso endpoint POST /api/v1/studio/batches/{batch_id}. Queste azioni creano nuovi tentativi, potenzialmente a pagamento, e richiedono una nuova intestazione Idempotency-Key (1–200 caratteri) per ogni operazione intenzionale. Riutilizza quella chiave e lo stesso JSON dopo un'interruzione di rete. Un corpo modificato restituisce IDEMPOTENCY_CONFLICT. Le chiavi per queste operazioni sono limitate all'account e al batch, separatamente dalla creazione del batch. Il corpo della richiesta è limitato a 1 MiB.

AzioneCosa viene eseguito
retry_failedSolo gli elementi il cui tentativo più recente non è riuscito. Facoltativo: item_indexes seleziona un sottoinsieme; omettilo per includere tutti gli errori.
reworkElementi terminali selezionati, inclusi quelli completati con successo o annullati. Le voci items richieste identificano esattamente un solo index con indice zero-based oppure il task_id corrente, più eventuali product_id, product_url, input o parameters.
restartOgni elemento, inclusi quelli completati con successo, con un nuovo tentativo. Attendi prima che il lavoro ammesso termini. Il gate del campione viene rimosso.
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}'

Per correggere un solo prodotto senza rigenerare gli elementi completati con successo:

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

Per rifare risultati che non ti piacciono, copia il loro items[].task_id corrente dalla risposta del batch. Puoi mantenere gli stessi input oppure fornire un nuovo prompt:

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

Usa l'URL del batch esistente e una nuova operazione Idempotency-Key. Il batch torna a running, gli elementi selezionati diventano queued e i loro task_id/results/error di primo livello vengono azzerati finché il nuovo tentativo non viene materializzato/completato. Gli altri elementi completati restano invariati. L'output precedente viene mantenuto solo nella cronologia attempts; i consumer devono mostrare items[].results per il risultato corrente. Per ogni voce è consentito esattamente uno tra index e task_id. Un task esterno/non correlato restituisce TASK_NOT_FOUND; un task di una versione già sostituita restituisce BATCH_ITEM_VERSION_CHANGED (409), così selezioni obsolete non possono rieseguire in silenzio un risultato più recente. Ripetere una chiave accettata resta sicuro anche dopo che il task selezionato è diventato storico.

Per una riesecuzione completa, invia {"action":"restart"} con una nuova chiave. Tutte e tre le azioni accettano modifiche facoltative a livello di operazione per input e parameters, oltre a un max_credits aumentato. Le modifiche vengono unite alla richiesta precedente di quell'elemento; prevalgono le modifiche per singolo elemento. Modificare product_id o product_url azzera l'alternativa precedente. Gli snapshot delle richieste precedenti e i risultati restano invariati. I tentativi successivi ereditano le ultime correzioni accettate e preparano un nuovo flusso di lavoro.

I tentativi selezionati devono essere terminali. BATCH_ITEMS_ACTIVE (409) significa che il lavoro è ancora in coda/ammesso/in elaborazione, che un elemento selezionato per il retry non era fallito, oppure che un altro retry è appena stato accettato. Per un riavvio completo, annulla il lavoro in sospeso e attendi che i tentativi ammessi terminino. GENERATION_UNRESOLVED (409) blocca i retry mentre una richiesta di generazione precedente è in coda, in esecuzione, in dispatch o con esito incerto; riconcilia prima il suo risultato. NO_FAILED_ITEMS (409) significa che non c'è nulla da ritentare. Riprovare e rilavorare avvia esplicitamente l'elaborazione, inclusi gli altri elementi in sospeso in quel batch; un gate campione esistente di cinque elementi viene mantenuto, a meno che resume o restart non lo rimuova.

max_credits resta un limite cumulativo: gli addebiti precedenti più le prenotazioni correnti continuano a contare. Un retry non rimborsa i passaggi precedenti completati con successo né reimposta il budget. Non viene effettuata alcuna prenotazione per l'intero batch. Le nuove versioni usano le stesse code bulk globali e per account. I Log dei crediti API/MCP mantengono l'attribuzione di batch, elemento e versione.

Le risposte mantengono ogni tentativo in items[].attempts, ciascuno con il proprio task/project e version crescente (i numeri possono avere salti). items[].version, lo stato dell'elemento e counts descrivono la versione prevista più recente; una nuova versione inizialmente viene segnalata come in coda ancora prima che il suo task venga materializzato. credits_used include tutte le versioni. Un batch si completa solo quando la versione più recente di ogni elemento è terminale. Le operazioni ripetute non avviano mai tentativi aggiuntivi. Per ogni batch vengono mantenute fino a 100 operazioni che creano versioni e 8 MiB di modifiche accumulate; BATCH_HISTORY_LIMIT (409) richiede un nuovo batch quando il limite è raggiunto.

INSUFFICIENT_CREDITS o BUDGET_EXCEEDED mette in pausa i nuovi avvii. Aggiungere crediti account non riprende automaticamente un batch: chiama esplicitamente resume. L'ammissione del budget e la prenotazione dell'account sono atomiche all'interno dei rispettivi documenti MongoDB, quindi i worker concorrenti non possono superare il budget del batch né addebitare due volte lo stesso tentativo. Non è richiesto alcun replica set MongoDB.

Un timeout nella verifica dello stato non dimostra che una generazione sia fallita. Se la risposta di invio di una generazione va persa, il relativo slot resta occupato per la riconciliazione; il sistema non invia automaticamente una richiesta a pagamento sostitutiva. Una volta che la generazione riesce, i retry dell'archiviazione file riutilizzano il risultato di generazione esistente. Gli invii esplicitamente rifiutati per rate limit possono essere ritentati con bounded backoff. La revisione dei risultati completati, l'approvazione delle versioni, l'esportazione ZIP e una UI bulk in Studio dal piano più ampio #194 non rientrano in questa release API; i download firmati individuali sono disponibili tramite i normali risultati dei task.

Log dei crediti

Gli amministratori possono filtrare i Log dei crediti per API o MCP. Le voci includono nome/ID della chiave API, ID di task/project/job, origine della generazione e marcatori di batch/elemento/versione bulk quando applicabili. I secret delle chiavi non vengono mai registrati.

Le prenotazioni e la regolazione sono eventi di audit con un delta crediti pari a zero; i metadati registrano l'importo prenotato. Addebiti e rimborsi riportano il delta crediti effettivo esattamente una volta. balanceAfter è il saldo disponibile dell'account, che esclude le prenotazioni in sospeso. Gli addebiti API storici vengono ripristinati dalle ricevute dei job memorizzate senza addebitare di nuovo l'account; dove il saldo disponibile storico non può essere ricostruito, l'interfaccia admin lo indica.

Diagnostica delle generazioni non riuscite

I task REST non riusciti, i risultati MCP get_task e i callback firmati task.failed condividono un oggetto error. message è il riepilogo V4V; provider_error conserva il motivo del servizio modello con credenziali, routing privato e posizioni di rete oscurati. provider usa l'alias di routing pubblico 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."
  }
}

I rifiuti di sicurezza, le modifiche vocali e le durate/risoluzioni non supportate richiedono la modifica della richiesta. Limiti di frequenza e timeout includono retryable: true, retry_after_seconds: 60 e un suggerimento di recupero. I motivi sconosciuti restano disponibili senza una diagnosi inventata o una raccomandazione di nuovo tentativo. Questi campi vengono omessi quando non esiste una diagnostica del servizio modello. I task non riusciti meno recenti vengono arricchiti mentre il relativo record di errore del flusso di lavoro resta disponibile. Studio e Laboratorio mostrano lo stesso motivo sanitizzato e lo inviano come GA4 generation_failed.reason (nel rispetto del limite analytics esistente di 120 caratteri).

Un suggerimento di nuovo tentativo non avvia mai un'altra generazione. Un nuovo tentativo a pagamento richiede una richiesta esplicita dell'utente e una nuova chiave di idempotenza. La regolazione dei crediti esistente, i rimborsi per passaggi non riusciti, gli addebiti per passaggi completati e la firma dei webhook restano in vigore.