> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Inizializza il caricamento di un'immagine di riferimento > Prepara il caricamento di un riferimento JPG, PNG o WebP fino a 8 MiB. Usa images_upload_sign_parts per ottenere gli URL PUT, carica i byte, quindi chiama images_upload_complete e usa il relativo fileKey durante la generazione. Prepara il caricamento di un riferimento JPG, PNG o WebP fino a 8 MiB. Usa images\_upload\_sign\_parts per ottenere gli URL PUT, carica i byte, quindi chiama images\_upload\_complete e usa il relativo fileKey durante la generazione. ```http theme={null} POST https://api.voicecheap.ai/v1/actions/images_upload_initialize ``` ## Autenticazione e autorizzazioni Invia una chiave API VoiceCheap in questa intestazione. È supportato anche Authorization: Bearer con la stessa chiave API. I token di accesso OAuth sono accettati solo da MCP, non da questo endpoint REST. Autorizzazioni richieste: `images:write`. È necessario un abbonamento a pagamento attivo. Le autorizzazioni non modificano i ruoli del team, la proprietà delle risorse, i crediti multimediali o i limiti del piano. ## Parametri Facoltativo al livello di trasporto: se omesso, il server inserisce un identificatore prima della validazione. Fornisci un tuo UUID v4 stabile per recuperare in sicurezza una risposta persa. Formato: "uuid". Pattern: `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$`. Il nome del file immagine, con un'estensione corrispondente a contentType. Lunghezza minima: 1. Lunghezza massima: 250. Pattern: `\.(?:jpe?g|png|webp)$`. Valore testuale. Valori consentiti: "image/jpeg", "image/png", "image/webp". Dimensioni esatte del file in byte, fino a 8 MiB. Minimo: 1. Massimo: 8388608. Il JSON Schema seguente conserva i nomi esatti dei campi, i tipi annidati, i valori predefiniti, i limiti e i valori accettati esposti dalla discovery. Le ulteriori regole tra campi sono elencate nelle note sull'operazione. ```json theme={null} { "type": "object", "properties": { "requestId": { "description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries.", "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" }, "filename": { "type": "string", "minLength": 1, "maxLength": 250, "pattern": "\\.(?:jpe?g|png|webp)$", "description": "The image filename, with an extension matching contentType." }, "contentType": { "type": "string", "enum": ["image/jpeg", "image/png", "image/webp"] }, "fileSize": { "type": "integer", "minimum": 1, "maximum": 8388608, "description": "Exact file size in bytes, up to 8 MiB." } }, "required": ["filename", "contentType", "fileSize"], "additionalProperties": false } ``` ## Idempotenza Usa un UUID v4 in requestId o nell'intestazione HTTP Idempotency-Key per ogni modifica. Riutilizza lo stesso identificatore e argomenti identici dopo un errore di rete. Se vengono forniti entrambi, devono coincidere. Ripetere una richiesta salvata non ripete l'operazione e non consuma un'altra chiamata mensile. Le richieste non riuscite o interrotte non vengono riavviate automaticamente. Ogni modifica può restituire HTTP 202 quando un nuovo tentativo trova la stessa richiesta ancora in esecuzione, anche se la prima esecuzione è normalmente sincrona. Se l'esecuzione è completata ma resultStored è false, un nuovo tentativo restituisce HTTP 200 con lo stato della richiesta salvata anziché il risultato originale. Recupera l'output tramite l'azione di cronologia, risultato o download del relativo dominio. ## Esempi di richiesta Sostituisci gli identificatori delle risorse e le chiavi multimediali di esempio con i valori restituiti per il tuo account. Mantieni stabile l'identificatore della richiesta quando ripeti la stessa modifica. ```bash cURL theme={null} curl --request POST 'https://api.voicecheap.ai/v1/actions/images_upload_initialize' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"requestId":"85d80887-5e1c-4a86-bbad-bb105487f7e4","filename":"reference.png","contentType":"image/png","fileSize":7340032}' ``` ```javascript JavaScript theme={null} const input = { requestId: '85d80887-5e1c-4a86-bbad-bb105487f7e4', filename: 'reference.png', contentType: 'image/png', fileSize: 7340032, }; const response = await fetch('https://api.voicecheap.ai/v1/actions/images_upload_initialize', { method: 'POST', headers: { 'x-api-key': process.env.VOICECHEAP_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify(input), }); const body = await response.json(); if (!response.ok) throw new Error(body.code + ': ' + body.message); console.log(body); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.voicecheap.ai/v1/actions/images_upload_initialize", headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]}, json={"requestId": "85d80887-5e1c-4a86-bbad-bb105487f7e4", "filename": "reference.png", "contentType": "image/png", "fileSize": 7340032}, timeout=120, ) body = response.json() if not response.ok: raise RuntimeError(f"{body.get('code')}: {body.get('message')}") print(body) ``` ## Risposta Una prima esecuzione riuscita restituisce HTTP 200 con il risultato dell'operazione in data. Una ripetizione può invece restituire lo stato della richiesta salvata. L'esempio mostra una risposta supportata, non tutti i campi facoltativi. Una nuova sessione di caricamento in più parti di un'immagine di riferimento, la futura chiave dell'oggetto, la dimensione delle parti in byte e il numero massimo di caricamenti paralleli. Questo non carica alcun byte dell'immagine né rende key pronto per la generazione. ```json HTTP 200 theme={null} { "data": { "uploadId": "c547fb7f-f334-46a8-a8bb-80b5b343889a", "key": "uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png", "partSize": 5242880, "maxConcurrency": 4 }, "requestId": "85d80887-5e1c-4a86-bbad-bb105487f7e4" } ``` ```json HTTP 202 replay_running theme={null} { "data": { "requestId": "85d80887-5e1c-4a86-bbad-bb105487f7e4", "operation": "images_upload_initialize", "createdAt": 1792144800000, "updatedAt": 1792144820000, "status": "running", "pollAfterSeconds": 5 }, "requestId": "85d80887-5e1c-4a86-bbad-bb105487f7e4" } ``` ```json HTTP 200 replay_completed_without_result theme={null} { "data": { "requestId": "85d80887-5e1c-4a86-bbad-bb105487f7e4", "operation": "images_upload_initialize", "createdAt": 1792144800000, "updatedAt": 1792144820000, "status": "completed", "resultStored": false, "message": "The action completed. Retrieve its output from the corresponding history or resource action." }, "requestId": "85d80887-5e1c-4a86-bbad-bb105487f7e4" } ``` ## Campi del risultato | Campo | Descrizione | | - | - | | `data.uploadId` | UUID che identifica la sessione di caricamento attiva. Passalo alle restanti azioni di caricamento. | | `data.key` | Chiave del futuro oggetto di proprietà dell'utente. Usa fileKey da un completamento riuscito come riferimento per la generazione. | | `data.partSize` | Dimensione richiesta delle parti in byte, tranne l'ultima parte che contiene i byte rimanenti. | | `data.maxConcurrency` | Numero massimo consigliato di caricamenti di parti in parallelo: 4. | ## Recupera e monitora questa richiesta Usa lo stesso identificatore anche dopo una connessione persa. Se resultStored è false, recupera l'output tramite la corrispondente azione di cronologia, risultato o download. Non avviare mai una seconda generazione solo per verificarne l'avanzamento. ```bash theme={null} curl --request POST 'https://api.voicecheap.ai/v1/actions/action_request_get' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"requestId":"85d80887-5e1c-4a86-bbad-bb105487f7e4","operation":"images_upload_initialize"}' ``` ```json HTTP 200 theme={null} { "data": { "requestId": "85d80887-5e1c-4a86-bbad-bb105487f7e4", "operation": "images_upload_initialize", "status": "completed", "createdAt": 1792144800000, "updatedAt": 1792144820000, "resultStored": true, "result": { "uploadId": "c547fb7f-f334-46a8-a8bb-80b5b343889a", "key": "uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png", "partSize": 5242880, "maxConcurrency": 4 } } } ``` ## Note sull'operazione * Richiede images:write; non è necessario alcuno scope aggiuntivo per il caricamento. * Gli spazi iniziali e finali vengono rimossi da filename, che deve contenere 1–250 caratteri e terminare con .jpg, .jpeg, .png o .webp. L'estensione deve corrispondere a contentType: image/jpeg, image/png o image/webp. fileSize è il numero intero esatto di byte, da 1 a 8,388,608. * L'implementazione di caricamento condivisa restituisce partSize 5 MiB (5,242,880 byte) per questi riferimenti. Un file di dimensione massima di 5 MiB usa una parte; un file più grande fino a 8 MiB ne usa due. Richiedi gli URL PUT con images\_upload\_sign\_parts, carica i byte, quindi chiama images\_upload\_complete. * Usa il fileKey restituito dal completamento come referenceImageKey in images\_generate. Il risultato di initialize usa key, non fileKey. Non passare key alla generazione prima del completamento. * La sessione di caricamento in produzione scade dopo 24 ore. Gli URL firmati delle parti scadono dopo un'ora. Il completamento e l'interruzione rimuovono la sessione attiva; sign-parts e complete restituiscono quindi Upload not found. Nessuna delle due risposte include un campo expiresAt. * Questa azione usa le creazioni e i caricamenti di proprietà dell'utente connesso, anche quando la credenziale è connessa nel contesto di un team. * Usa un requestId UUID v4 oppure l'header HTTP Idempotency-Key e riutilizzalo con input identici nei nuovi tentativi. Il livello di integrazione registra ogni modifica e ne restituisce lo stato o il risultato registrato senza eseguirla nuovamente. Una richiesta fallita o interrotta non viene ritentata automaticamente. * Il nome del file nella chiave dell'oggetto viene sanitizzato e può essere abbreviato. Conserva esattamente la chiave e l'uploadId restituiti; non costruirli autonomamente. I byte dell'immagine vengono convalidati durante la generazione, oltre alla dimensione e al tipo dichiarati durante il caricamento. ## Utilizzo Ogni invocazione riuscita consuma una chiamata API/MCP mensile. Si applicano anche i crediti multimediali e le quote di generazione proprie dell'operazione. ## Errori | Stato HTTP | Codice | Significato o risoluzione | | - | - | - | | 400 | `CREDENTIAL_IN_QUERY` | Le credenziali sono state fornite in un parametro di query access\_token o api\_key. Invia le credenziali negli header. | | 400 | `IDEMPOTENCY_CONFLICT` | L'intestazione Idempotency-Key e il campo requestId del corpo devono coincidere. | | 400 | `INVALID_REQUEST_ID` | requestId o Idempotency-Key non è un UUID v4. | | 400 | `REFERENCE_IMAGE_INVALID` | L'estensione del nome del file non corrisponde al contentType dell'immagine dichiarato. | | 400 | `VALIDATION_ERROR` | Un argomento è mancante, ha un valore non supportato, supera il proprio limite oppure non fa parte dello schema di input rigoroso. | | 401 | `API_KEY_EXPIRED` | La chiave API è scaduta. | | 401 | `INVALID_API_KEY` | Fornisci una chiave API valida e non scaduta. | | 401 | `INVALID_CREDENTIAL` | L'header Authorization non è valido oppure è in conflitto con x-api-key. | | 401 | `MISSING_CREDENTIAL` | Non è stata fornita alcuna credenziale utilizzabile negli header, oppure la credenziale superava 4096 caratteri. | | 401 | `USER_NOT_FOUND` | L'account associato alla credenziale non esiste più. | | 403 | `ACCOUNT_UNAVAILABLE` | L'account che esegue l'azione o quello di fatturazione non è disponibile o è in fase di eliminazione. | | 403 | `AMBIGUOUS_TEAM_API_KEY` | L'utente della credenziale appartiene a più di un team, quindi il contesto di fatturazione è ambiguo. | | 403 | `INSUFFICIENT_SCOPE` | Concedi tutte le autorizzazioni richieste o scegli un'altra credenziale. | | 403 | `INTEGRATION_PLAN_UNSUPPORTED` | Impossibile verificare i limiti di integrazione dell'account. | | 403 | `SUBSCRIPTION_REQUIRED` | Usa un abbonamento a pagamento attivo. | | 403 | `TEAM_OWNER_NOT_FOUND` | Non è stato possibile trovare l'account effettivo del proprietario del team. | | 409 | `CONCURRENT_ACTION_LIMIT_REACHED` | Questo account ha già 10 azioni di integrazione in esecuzione. Interroga una richiesta esistente prima di avviarne un'altra. | | 409 | `IDEMPOTENCY_CONFLICT` | L'identificatore della richiesta è già stato utilizzato con argomenti diversi; una mancata corrispondenza tra l'identificatore nell'header e quello nel corpo restituisce HTTP 400 con lo stesso codice. | | 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Attendi il ripristino mensile o cambia piano. | | 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Rispetta Retry-After quando presente e applica attese crescenti tra i tentativi. | | 500 | `INTERNAL_ERROR` | Controlla lo stato della richiesta salvata e la cronologia delle risorse prima di decidere se ripetere una modifica. | | 503 | `ACTION_RESULT_UNAVAILABLE` | L'azione è stata eseguita ma non è stato possibile salvarne il risultato. Esamina lo stato della richiesta salvata e la cronologia delle risorse prima di avviare una nuova generazione. | | 503 | `INTERNAL_ERROR` | Non è stato possibile creare o salvare la sessione di caricamento. Riprova con lo stesso identificatore di modifica e controlla il suo stato registrato. | | 503 | `SERVER_RESTARTING` | Il server si sta riavviando. Riprova tra poco e mantieni lo stesso identificatore della richiesta per una modifica. | ```json theme={null} { "code": "INSUFFICIENT_SCOPE", "message": "This credential does not permit the requested action.", "status": 403, "details": { "requiredScopes": ["images:write"] } } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.