Obtener el estado de una solicitud de acción

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

​

Autenticación y permisos

​

Parámetros

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

​

Ejemplos de solicitud

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)

​

Respuesta

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

​

Solicitud completada con un resultado guardado

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

​

Solicitud de edición de segmento completada

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

​

Solicitud completada sin un resultado conservado

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

​

Solicitud guardada fallida

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

​

Solicitud guardada interrumpida

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

​

Notas de la operación

• Invoca esta acción como POST /v1/actions/action_request_get con una clave de API, o llama a la herramienta MCP action_request_get. No existe ningún endpoint GET /v1/requests.
• Ambos campos de entrada son obligatorios. requestId debe ser un UUID v4; operation es el nombre exacto de la acción original, de 1–100 caracteres, que coincide con ^[a-z][a-z0-9_]+$. Se rechazan los campos adicionales.
• La credencial debe tener actualmente todos los permisos principales y adicionales requeridos por la acción original. El actor de origen y el contexto actual de propiedad personal o de equipo deben coincidir con la solicitud guardada.
• Solo las acciones que modifican datos tienen un estado de solicitud guardado. Los nombres de acciones de solo lectura devuelven ACTION_REQUEST_NOT_FOUND; una operación desconocida devuelve UNKNOWN_ACTION.
• REST devuelve HTTP 202 mientras data.status es running y HTTP 200 para los estados de solicitud completed, failed o interrupted. Un estado failed guardado se devuelve como datos con su error; esta acción de consulta periódica no vuelve a lanzar el error.
• Los valores de estado son running, completed, failed e interrupted. Una solicitud running se indica como interrupted cuando su arrendamiento de ejecución ha caducado; no se reinicia automáticamente.
• Los resultados completados solo se conservan cuando no hay claves de resultado que parezcan secretos y el resultado serializado es de un máximo de 256 KiB. resultStored: false no significa que la acción haya fallado; usa su acción de historial, get o descarga.
• La consulta periódica no consume ninguna llamada mensual de integración y sigue disponible después de agotar el límite mensual. Se siguen aplicando la autenticación, los requisitos de plan de pago y los límites de solicitudes compartidos.
• No añadas una nueva clave de idempotencia para consultar el estado; requestId identifica la modificación original. Una llamada de solo lectura no devuelve un requestId externo independiente.
• Una acción completada puede devolver una tarea de procesamiento multimedia en lugar del contenido multimedia terminado. Continúa con la acción de estado o historial del dominio correspondiente cuando el resultado devuelto indique trabajo en curso.
• webhooks_create_secret solo está disponible por REST y no aparece en el descubrimiento MCP. Ejecutarla o consultar su resultado mediante MCP devuelve el error de herramienta ACTION_NOT_AVAILABLE_IN_MCP. Los secretos de firma no se envían a los asistentes.
• Los resultados guardados y las repeticiones usan los mismos campos de respuesta públicos que un resultado nuevo. Los errores de solicitudes fallidas contienen code, message, status y requestId opcional, con mensajes fijos de VoiceCheap. Los fallos guardados sin clasificar usan INTERNAL_ERROR para status de 500 o superior, y ACTION_FAILED en los demás casos.

​

Uso

​

Errores

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