Skip to main content
POST
Genera un’immagine per l’account connesso. Si applicano la stessa quota multimediale e le stesse protezioni dell’app web. Salva il generationId restituito e usa images_download per recuperare l’immagine. Riutilizza requestId quando ripeti la stessa richiesta.

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

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
Valore testuale.Lunghezza minima: 10. Lunghezza massima: 1200.
string
Valore testuale.Valori consentiti: “square”, “landscape”, “portrait”. Valore predefinito: “square”.
string
Chiave di un oggetto JPG, PNG o WebP caricato sotto uploads/{yourUserId}/. Gli URL remoti non sono accettati.Lunghezza minima: 1. Lunghezza massima: 512.
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

Questa operazione restituisce HTTP 202 mentre è in esecuzione. Salva requestId e interroga action_request_get con questo identificatore e il nome dell’operazione originale. Gli stati del polling sono running, completed, failed e interrupted. Un risultato completato può rimandare a un processo multimediale separato; prosegui con l’azione di stato o di output specifica dell’operazione. Metadati finali della generazione restituiti dal gestore al termine della generazione dell’immagine. Non sono inclusi byte dell’immagine, previewDataUrl o URL di download.

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 images:write. Gli spazi iniziali e finali del prompt vengono rimossi e il prompt deve contenere 10–1200 caratteri; viene inoltre normalizzato prima della generazione. Il valore predefinito di aspectRatio è square e sono accettati anche landscape o portrait. È accettato al massimo un referenceImageKey.
  • Questa è un’azione di lunga durata. La risposta API/MCP iniziale riporta normalmente running; interroga periodicamente action_request_get con operation images_generate e lo stesso requestId per ottenere il risultato finale mostrato qui.
  • Usa la normale quota giornaliera di generazione di immagini dell’account. Le immagini generate dell’account scadono sette giorni dopo la creazione; scarica il risultato prima di expiresAt.
  • Questa azione usa le creazioni e i caricamenti di proprietà dell’utente connesso, anche quando la credenziale è connessa nel contesto di un team.
  • Le chiavi di riferimento devono puntare a caricamenti completati sotto uploads/{yourUserId}/ e terminare con .jpg, .jpeg, .png o .webp. Sono rifiutati URL remoti, chiavi di altri utenti, segmenti di attraversamento delle directory, barre rovesciate, sequenze di escape percentuali, stringhe di query, frammenti e caratteri di controllo.
  • Ogni riferimento deve essere non vuoto, avere una dimensione massima di 8 MiB (8,388,608 byte), essere decodificabile come il tipo di immagine identificato dalla sua estensione e misurare 128–4096 pixel su ogni lato. Anche il numero di pixel decodificati è limitato. Un riferimento caricato rimane riutilizzabile; queste azioni di generazione non consumano né eliminano il suo file caricato.
  • 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.
  • È possibile generare una sola immagine alla volta per questo utente. Usa images_list e images_get per controllare lo stato di creazione e images_download per ottenere i byte PNG. L’identificatore di generazione è una stringa opaca; non sostituirlo con requestId.

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