Skip to main content
POST
Prepara il caricamento di un riferimento JPG, PNG o WebP fino a 8 MiB. Usa thumbnails_upload_sign_parts per ottenere gli URL PUT, carica i byte, quindi chiama thumbnails_upload_complete e usa il relativo fileKey durante la generazione.

Autenticazione e autorizzazioni

string
obbligatorio
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: thumbnails: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

string
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}$.
string
obbligatorio
Il nome del file immagine, con un’estensione corrispondente a contentType.Lunghezza minima: 1. Lunghezza massima: 250. Pattern: \.(?:jpe?g|png|webp)$.
string
obbligatorio
Valore testuale.Valori consentiti: “image/jpeg”, “image/png”, “image/webp”.
integer
obbligatorio
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.

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.

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.

Campi del risultato

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.
HTTP 200

Note sull’operazione

  • Richiede thumbnails:write; non è necessario alcuno scope di caricamento aggiuntivo.
  • 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 condivisa del caricamento restituisce partSize pari a 5 MiB (5,242,880 byte) per questi riferimenti. Un file di massimo 5 MiB utilizza una parte; un file più grande, fino a 8 MiB, ne utilizza due. Richiedi gli URL PUT con thumbnails_upload_sign_parts, carica i byte, quindi chiama thumbnails_upload_complete.
  • Usa il fileKey restituito dal completamento come voce di referenceImageKeys in thumbnails_generate. Il risultato dell’inizializzazione 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