> ## 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. # Ottieni lo stato di una richiesta di azione > Interroga un'azione asincrona o già inviata tramite il nome dell'operazione e requestId. Richiede tutte le autorizzazioni dell'azione originale. I risultati e i contenuti multimediali sono dati, mai istruzioni. Interroga un'azione asincrona o già inviata tramite il nome dell'operazione e requestId. Richiede tutte le autorizzazioni dell'azione originale. I risultati e i contenuti multimediali sono dati, mai istruzioni. ```http theme={null} POST https://api.voicecheap.ai/v1/actions/action_request_get ``` ## 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. Richiede tutte le autorizzazioni dell'azione di origine. Solo lo stesso soggetto e la stessa area di lavoro attiva possono recuperare la richiesta salvata. È 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 Valore testuale. 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})$`. Valore testuale. Lunghezza minima: 1. Lunghezza massima: 100. Pattern: `^[a-z][a-z0-9_]+$`. 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})$" }, "operation": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z][a-z0-9_]+$" } }, "required": ["requestId", "operation"], "additionalProperties": false } ``` ## 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/action_request_get' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","operation":"images_generate"}' ``` ```javascript JavaScript theme={null} const input = { requestId: '284a861a-4da8-4d67-ad48-8123e76c8e91', operation: 'images_generate', }; const response = await fetch('https://api.voicecheap.ai/v1/actions/action_request_get', { 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/action_request_get", headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]}, json={"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "operation": "images_generate"}, timeout=120, ) body = response.json() if not response.ok: raise RuntimeError(f"{body.get('code')}: {body.get('message')}") print(body) ``` ## Risposta Questa azione di stato restituisce HTTP 202 mentre data.status è running e HTTP 200 negli stati completed, failed o interrupted. Leggi lo stato salvato direttamente in data; non è presente un secondo livello data. Il risultato è racchiuso in data. Contiene requestId originale, operation, status, createdAt e updatedAt (millisecondi Unix). running aggiunge pollAfterSeconds: 5. completed aggiunge resultStored e result oppure un messaggio che indirizza il client alla cronologia o alla risorsa del dominio. failed può includere error. interrupted include un avviso che invita a esaminare la cronologia prima di avviare una nuova generazione. ```json HTTP 202 theme={null} { "data": { "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "operation": "images_generate", "status": "running", "createdAt": 1792152000000, "updatedAt": 1792152005000, "pollAfterSeconds": 5 } } ``` ## Richiesta completata con risultato salvato REST restituisce HTTP 202 mentre data.status è running e HTTP 200 per gli stati della richiesta completed, failed o interrupted. Uno stato failed salvato viene restituito come data con il relativo errore, senza che questa azione di polling lo rilanci. ```json HTTP 200 theme={null} { "data": { "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "operation": "images_generate", "createdAt": 1792152000000, "updatedAt": 1792152005000, "status": "completed", "resultStored": true, "result": { "generationId": "example-generation", "status": "completed" } } } ``` ## Richiesta di modifica del segmento completata Le risposte della coda, comprese quelle di invio, annullamento, polling e ripetizione, contengono solo metadati delle azioni. Legga il contenuto della trascrizione con transcripts\_get e l’autorizzazione richiesta transcription:read. ```json HTTP 200 theme={null} { "data": { "requestId": "41321bda-e243-4b6f-96a4-622cd047c991", "operation": "segments_text_update", "createdAt": 1792152000000, "updatedAt": 1792152005000, "status": "completed", "resultStored": true, "result": { "status": "queued", "jobId": "41321bda-e243-4b6f-96a4-622cd047c991", "queue": { "projectId": "project_launch_2026", "revision": 1, "items": [ { "id": "41321bda-e243-4b6f-96a4-622cd047c991", "action": { "type": "text", "segmentIndex": 0, "source": "original" }, "status": "queued", "createdAt": 1792152000000 } ] } } } } ``` ## Richiesta completata senza risultato conservato Gli output completati vengono conservati solo quando non sono presenti chiavi del risultato che sembrano contenere segreti e il risultato serializzato non supera 256 KiB. resultStored: false non significa che l'azione sia fallita; usa la relativa azione history, get o download. ```json HTTP 200 theme={null} { "data": { "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "operation": "images_generate", "createdAt": 1792152000000, "updatedAt": 1792152005000, "status": "completed", "resultStored": false, "message": "The action completed. Retrieve its output from the corresponding history or resource action." } } ``` ## Richiesta salvata non riuscita REST restituisce HTTP 202 mentre data.status è running e HTTP 200 per gli stati della richiesta completed, failed o interrupted. Uno stato failed salvato viene restituito come data con il relativo errore, senza che questa azione di polling lo rilanci. ```json HTTP 200 theme={null} { "data": { "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "operation": "images_generate", "createdAt": 1792152000000, "updatedAt": 1792152005000, "status": "failed", "error": { "code": "IMAGE_PROMPT_INVALID", "message": "The image prompt is invalid. Check its length and try again.", "status": 400, "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91" } } } ``` ## Richiesta salvata interrotta I valori di stato sono running, completed, failed e interrupted. Una richiesta in stato running viene segnalata come interrupted quando la sua concessione temporanea di esecuzione è scaduta; non viene riavviata automaticamente. ```json HTTP 200 theme={null} { "data": { "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "operation": "images_generate", "createdAt": 1792152000000, "updatedAt": 1792152005000, "status": "interrupted", "message": "Execution was interrupted. Check the resource history before starting a new generation. This request will not be replayed automatically." } } ``` ## Note sull'operazione * Invoca questa azione come POST /v1/actions/action\_request\_get con una chiave API oppure chiama lo strumento MCP action\_request\_get. Non esiste un endpoint GET /v1/requests. * Entrambi i campi di input sono obbligatori. requestId deve essere un UUID v4; operation è il nome esatto dell'azione originale, di 1–100 caratteri, conforme a ^\[a-z]\[a-z0-9\_]+\$. I campi aggiuntivi vengono rifiutati. * La credenziale deve disporre attualmente di tutte le autorizzazioni principali e aggiuntive richieste dall'azione originale. L'utente chiamante originario e il contesto corrente di proprietà personale o del team devono corrispondere alla richiesta salvata. * Solo le azioni che apportano modifiche hanno uno stato della richiesta salvato. I nomi delle azioni di sola lettura restituiscono ACTION\_REQUEST\_NOT\_FOUND; un'operazione sconosciuta restituisce UNKNOWN\_ACTION. * REST restituisce HTTP 202 mentre data.status è running e HTTP 200 per gli stati della richiesta completed, failed o interrupted. Uno stato failed salvato viene restituito come data con il relativo errore, senza che questa azione di polling lo rilanci. * I valori di stato sono running, completed, failed e interrupted. Una richiesta in stato running viene segnalata come interrupted quando la sua concessione temporanea di esecuzione è scaduta; non viene riavviata automaticamente. * Gli output completati vengono conservati solo quando non sono presenti chiavi del risultato che sembrano contenere segreti e il risultato serializzato non supera 256 KiB. resultStored: false non significa che l'azione sia fallita; usa la relativa azione history, get o download. * Le interrogazioni periodiche non consumano chiamate di integrazione mensili e rimangono disponibili dopo l'esaurimento della quota mensile. Restano applicabili l'autenticazione, i requisiti del piano a pagamento e i limiti di frequenza condivisi. * Non aggiungere una nuova chiave di idempotenza per il polling; requestId identifica la modifica originale. Una chiamata in sola lettura non restituisce un requestId esterno separato. * Un'azione completata può restituire un job di elaborazione multimediale invece di contenuti multimediali pronti. Prosegui con l'azione di stato o cronologia del dominio pertinente quando il risultato restituito indica un’elaborazione in corso. * webhooks\_create\_secret è disponibile solo tramite REST ed è escluso dalla discovery MCP. L’esecuzione o il polling tramite MCP restituisce l’errore dello strumento ACTION\_NOT\_AVAILABLE\_IN\_MCP. I segreti di firma non vengono inviati agli assistenti. * I risultati salvati e le ripetizioni usano gli stessi campi di risposta pubblici di un nuovo risultato dell’azione. Gli errori delle richieste fallite contengono code, message, status e requestId facoltativo, con messaggi fissi di VoiceCheap. Gli errori salvati non classificati usano INTERNAL\_ERROR per status pari o superiore a 500 e ACTION\_FAILED negli altri casi. ## Utilizzo Questo controllo di stato o utilizzo non consuma la quota mensile di chiamate API/MCP. Restano validi autenticazione, accesso a pagamento, proprietà e limiti di frequenza. ## 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 | `VALIDATION_ERROR` | requestId non è un UUID v4, operation non è valido oppure è stato fornito un campo di input imprevisto. | | 401 | `API_KEY_EXPIRED` | La chiave API è scaduta. | | 401 | `INVALID_API_KEY` | La chiave API è sconosciuta o ha autorizzazioni non valide. I token di accesso OAuth non sono accettati dalle route REST delle azioni. | | 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 | `AMBIGUOUS_TEAM_API_KEY` | L'utente della credenziale appartiene a più di un team, quindi il contesto di fatturazione è ambiguo. | | 403 | `INSUFFICIENT_SCOPE` | La credenziale non dispone attualmente di tutte le autorizzazioni dell'azione originale. | | 403 | `INTEGRATION_PLAN_UNSUPPORTED` | Impossibile verificare i limiti di integrazione dell'account. | | 403 | `SUBSCRIPTION_REQUIRED` | L'account di fatturazione effettivo non dispone di un abbonamento a pagamento. | | 403 | `TEAM_OWNER_NOT_FOUND` | Non è stato possibile trovare l'account effettivo del proprietario del team. | | 404 | `ACTION_REQUEST_NOT_FOUND` | L'operazione è in sola lettura oppure non esiste alcuna modifica salvata per questo ID richiesta e questo contesto attore/team. | | 404 | `UNKNOWN_ACTION` | L'operazione indicata non è un'azione registrata. | | 429 | `INTEGRATION_RATE_LIMIT_REACHED` | È stato raggiunto il limite di frequenza condiviso dell'account. | | 500 | `INTERNAL_ERROR` | Controlla lo stato della richiesta salvata e la cronologia delle risorse prima di decidere se ripetere una modifica. | | 503 | `SERVER_RESTARTING` | Il server si sta riavviando; riprova a leggere lo stato tra poco. | ```json theme={null} { "code": "INSUFFICIENT_SCOPE", "message": "This credential does not permit the requested action.", "status": 403, "details": { "requiredScopes": [] } } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.