> ## 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.

# Genera una miniatura YouTube

> Genera una miniatura 1280×720 per l'account connesso, usando la quota multimediale dell'app web. Riutilizza requestId quando ripeti la stessa richiesta; usa thumbnails_download per recuperare il risultato.

Genera una miniatura 1280×720 per l'account connesso, usando la quota multimediale dell'app web. Riutilizza requestId quando ripeti la stessa richiesta; usa thumbnails\_download per recuperare il risultato.

```http theme={null}
POST https://api.voicecheap.ai/v1/actions/thumbnails_generate
```

## Autenticazione e autorizzazioni

**x-api-key** `string` *required*

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

**requestId** `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}$`.

**prompt** `string` *required*

Valore testuale.

Lunghezza minima: 10. Lunghezza massima: 1200.

**referenceImageKeys** `array`

Elenco di valori. Consulta lo schema di input completo per la struttura degli elementi.

Numero massimo di elementi: 3. Valore predefinito: \[].

> [accordion] Schema di input completo
>
> 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": {
>       "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}$",
>       "description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries."
>     },
>     "prompt": {
>       "type": "string",
>       "minLength": 10,
>       "maxLength": 1200
>     },
>     "referenceImageKeys": {
>       "default": [],
>       "maxItems": 3,
>       "type": "array",
>       "items": {
>         "type": "string",
>         "minLength": 1,
>         "maxLength": 512,
>         "description": "An uploaded JPG, PNG or WebP object key under uploads/{yourUserId}/. Remote URLs are not accepted."
>       }
>     }
>   },
>   "required": ["prompt"],
>   "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/thumbnails_generate' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"2fcb6b7f-4e5d-421a-b35b-b68548dfd83e","prompt":"A clean YouTube thumbnail showing a mountain sunrise, with the text “A new adventure”.","referenceImageKeys":["uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png"]}'
```

```javascript JavaScript theme={null}
const input = {
  requestId: '2fcb6b7f-4e5d-421a-b35b-b68548dfd83e',
  prompt: 'A clean YouTube thumbnail showing a mountain sunrise, with the text “A new adventure”.',
  referenceImageKeys: ['uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png'],
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/thumbnails_generate', {
  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/thumbnails_generate",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"requestId": "2fcb6b7f-4e5d-421a-b35b-b68548dfd83e", "prompt": "A clean YouTube thumbnail showing a mountain sunrise, with the text “A new adventure”.", "referenceImageKeys": ["uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png"]},
    timeout=120,
)
body = response.json()
if not response.ok:
    raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
```

## 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 miniatura restituiti al termine della generazione. L'output è di 1280 × 720 pixel; i byte dell'immagine, previewDataUrl e i token di passaggio non sono inclusi.

```json HTTP 202 theme={null}
{
  "data": {
    "requestId": "2fcb6b7f-4e5d-421a-b35b-b68548dfd83e",
    "status": "running",
    "pollAction": "action_request_get",
    "pollAfterSeconds": 5
  },
  "requestId": "2fcb6b7f-4e5d-421a-b35b-b68548dfd83e"
}
```

```json HTTP 200 theme={null}
{
  "data": {
    "generationId": "109c61cb35dbdc01a94aabb3b1a128519ed1f8823800a7a327b9d8d8c2c0e10b",
    "status": "completed",
    "width": 1280,
    "height": 720,
    "referenceImageCount": 1,
    "createdAt": 1792144800000,
    "updatedAt": 1792144800000,
    "expiresAt": 1792749600000
  },
  "requestId": "2fcb6b7f-4e5d-421a-b35b-b68548dfd83e"
}
```

```json HTTP 202 replay_running theme={null}
{
  "data": {
    "requestId": "2fcb6b7f-4e5d-421a-b35b-b68548dfd83e",
    "operation": "thumbnails_generate",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "status": "running",
    "pollAfterSeconds": 5
  },
  "requestId": "2fcb6b7f-4e5d-421a-b35b-b68548dfd83e"
}
```

```json HTTP 200 replay_completed_without_result theme={null}
{
  "data": {
    "requestId": "2fcb6b7f-4e5d-421a-b35b-b68548dfd83e",
    "operation": "thumbnails_generate",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "status": "completed",
    "resultStored": false,
    "message": "The action completed. Retrieve its output from the corresponding history or resource action."
  },
  "requestId": "2fcb6b7f-4e5d-421a-b35b-b68548dfd83e"
}
```

## Campi del risultato

| Campo | Descrizione |
| - | - |
| `data.generationId` | Identificatore da passare invariato a thumbnails\_get o thumbnails\_download. |
| `data.status` | completed, expired o deleted. Un record deleted rimane deleted anche dopo la sua scadenza. |
| `data.width` | Larghezza dell'output in pixel: 1280. |
| `data.height` | Altezza dell'output in pixel: 720. |
| `data.referenceImageCount` | Numero di immagini di riferimento utilizzate: da 0 a 3. |
| `data.createdAt` | Ora di creazione in millisecondi Unix. |
| `data.updatedAt` | Ora dell'ultimo aggiornamento in millisecondi Unix. |
| `data.expiresAt` | Ora in millisecondi Unix dopo la quale la miniatura generata non può essere scaricata. |

## 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":"2fcb6b7f-4e5d-421a-b35b-b68548dfd83e","operation":"thumbnails_generate"}'
```

```json HTTP 200 theme={null}
{
  "data": {
    "requestId": "2fcb6b7f-4e5d-421a-b35b-b68548dfd83e",
    "operation": "thumbnails_generate",
    "status": "completed",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "resultStored": true,
    "result": {
      "generationId": "109c61cb35dbdc01a94aabb3b1a128519ed1f8823800a7a327b9d8d8c2c0e10b",
      "status": "completed",
      "width": 1280,
      "height": 720,
      "referenceImageCount": 1,
      "createdAt": 1792144800000,
      "updatedAt": 1792144800000,
      "expiresAt": 1792749600000
    }
  }
}
```

## Note sull'operazione

* Richiede thumbnails: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 referenceImageKeys è \[] e sono accettate al massimo tre chiavi.
* Questa azione richiede un'esecuzione prolungata. La risposta API/MCP iniziale riporta normalmente running; interroga periodicamente action\_request\_get con operation thumbnails\_generate e lo stesso requestId per ottenere il risultato finale mostrato qui.
* Usa la normale quota giornaliera di generazione di miniature dell'account. Le nuove miniature 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.
* Una richiesta completata può restituire la miniatura esistente. Una richiesta di integrazione precedentemente non riuscita o interrotta non viene rieseguita automaticamente. Controlla lo stato della richiesta e thumbnails\_list prima di avviare una nuova richiesta.
* Usa thumbnails\_get o thumbnails\_list per i metadati e thumbnails\_download per i byte WebP. L'identificatore della generazione è una stringa opaca, non 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

| 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` | Una chiave di riferimento o i suoi byte non superano i controlli di proprietà, tipo, dimensione del file, dimensioni dell'immagine o decodifica. |
| 400 | `THUMBNAIL_PROMPT_INVALID` | Il prompt normalizzato non rientra nell'intervallo di 10–1200 caratteri. |
| 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. |
| 409 | `THUMBNAIL_GENERATION_IN_PROGRESS` | La richiesta della miniatura è già in elaborazione. |
| 409 | `THUMBNAIL_REQUEST_FAILED` | Questo tentativo di generazione della miniatura è già fallito. Controlla il suo stato prima di decidere se avviare una nuova richiesta. |
| 409 | `THUMBNAIL_REQUEST_ID_REUSED` | L'identificatore della richiesta di miniatura è già associato a un input diverso. |
| 410 | `THUMBNAIL_NOT_FOUND` | Il risultato precedentemente completato per questa richiesta è scaduto oppure non è più disponibile. |
| 422 | `THUMBNAIL_REQUEST_REJECTED` | Impossibile generare la miniatura da questo prompt o riferimento. Modifica il contenuto per una nuova richiesta. |
| 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. |
| 429 | `THUMBNAIL_DAILY_LIMIT_REACHED` | La quota giornaliera dell'account per la generazione di miniature è esaurita. |
| 500 | `INTERNAL_ERROR` | Controlla lo stato della richiesta salvata e la cronologia delle risorse prima di decidere se ripetere una modifica. |
| 502 | `INTERNAL_ERROR` | La generazione o la preparazione della miniatura non è riuscita. Controlla lo stato della richiesta prima di decidere di avviare un'altra generazione. |
| 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` | La generazione della miniatura o il suo risultato memorizzato sono temporaneamente non disponibili. Controlla lo stato della richiesta prima di riprovare. |
| 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": ["thumbnails:write"]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.