Consulter le statut d’une requête d’action

POST https://api.voicecheap.ai/v1/actions/action_request_get

​

Authentification et autorisations

​

Paramètres

{
  "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
}

​

Exemples de requêtes

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"}'

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);

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)

​

Réponse

{
  "data": {
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
    "operation": "images_generate",
    "status": "running",
    "createdAt": 1792152000000,
    "updatedAt": 1792152005000,
    "pollAfterSeconds": 5
  }
}

​

Requête terminée avec un résultat enregistré

{
  "data": {
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
    "operation": "images_generate",
    "createdAt": 1792152000000,
    "updatedAt": 1792152005000,
    "status": "completed",
    "resultStored": true,
    "result": {
      "generationId": "example-generation",
      "status": "completed"
    }
  }
}

​

Requête de modification de segment terminée

{
  "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
          }
        ]
      }
    }
  }
}

​

Requête terminée sans résultat conservé

{
  "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."
  }
}

​

Requête enregistrée en échec

{
  "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"
    }
  }
}

​

Requête enregistrée interrompue

{
  "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."
  }
}

​

Notes de l’opération

• Appelez cette action avec POST /v1/actions/action_request_get et une clé API, ou utilisez l’outil MCP action_request_get. Il n’existe aucun point de terminaison GET /v1/requests.
• Les deux champs d’entrée sont obligatoires. requestId doit être un UUID v4 ; operation est le nom exact de l’action d’origine, de 1–100 caractères, correspondant à ^[a-z][a-z0-9_]+$. Les champs supplémentaires sont rejetés.
• Les identifiants doivent actuellement disposer de toutes les autorisations principales et supplémentaires exigées par l’action d’origine. L’appelant d’origine et le contexte actuel de propriété personnelle ou d’équipe doivent correspondre à la requête enregistrée.
• Seules les actions de mutation disposent d’un état de requête enregistré. Les noms d’actions en lecture seule renvoient ACTION_REQUEST_NOT_FOUND ; une opération inconnue renvoie UNKNOWN_ACTION.
• REST renvoie HTTP 202 lorsque data.status vaut running, et HTTP 200 pour les états de requête completed, failed ou interrupted. Un état failed enregistré est renvoyé comme données avec son erreur ; cette action d’interrogation ne lève pas de nouveau cette erreur.
• Les valeurs de statut sont running, completed, failed et interrupted. Une requête running est signalée comme interrupted lorsque son bail d’exécution a expiré ; elle ne redémarre pas automatiquement.
• Les résultats finalisés ne sont conservés que si aucune clé de résultat ne semble contenir de secret et si le résultat sérialisé ne dépasse pas 256 KiB. resultStored: false ne signifie pas que l’action a échoué ; utilisez son action history, get ou download.
• L’interrogation de l’état ne consomme aucun appel d’intégration mensuel et reste disponible après épuisement du quota mensuel. L’authentification, les exigences de forfait payant et les limites de fréquence partagées restent applicables.
• N’ajoutez pas de nouvelle clé d’idempotence pour le suivi ; requestId identifie la mutation d’origine. Un appel en lecture seule ne renvoie pas de requestId externe distinct.
• Une action terminée peut renvoyer une tâche de traitement média plutôt qu’un média finalisé. Poursuivez avec l’action de statut ou d’historique du domaine concerné lorsque le résultat renvoyé indique un travail en cours.
• webhooks_create_secret est réservé à REST et exclu de la découverte MCP. Son appel ou la consultation de son résultat via MCP renvoie l’erreur d’outil ACTION_NOT_AVAILABLE_IN_MCP. Les secrets de signature ne sont pas transmis aux assistants.
• Les résultats enregistrés et les rejeux utilisent les mêmes champs publics qu’un nouveau résultat d’action. Les erreurs des requêtes échouées contiennent code, message, status et, facultativement, requestId, avec des messages VoiceCheap fixes. Les échecs enregistrés non classés utilisent INTERNAL_ERROR pour un status de 500 ou plus, et ACTION_FAILED sinon.

​

Utilisation

​

Erreurs

{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This credential does not permit the requested action.",
  "status": 403,
  "details": {
    "requiredScopes": []
  }
}