Consultar o status de uma requisição de ação

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

​

Autenticação e permissões

​

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
}

​

Exemplos de requisição

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)

​

Resposta

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

​

Requisição concluída com resultado salvo

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

​

Solicitação de edição de segmento concluída

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

​

Requisição concluída sem resultado retido

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

​

Requisição salva com falha

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

​

Requisição salva interrompida

{
  "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 da operação

• Invoque como POST /v1/actions/action_request_get com uma chave de API ou chame a ferramenta MCP action_request_get. Não existe endpoint GET /v1/requests.
• Ambos os campos de entrada são obrigatórios. requestId deve ser um UUID v4; operation é o nome exato da ação original, com 1–100 caracteres, correspondente a ^[a-z][a-z0-9_]+$. Campos extras são rejeitados.
• A credencial deve ter atualmente todas as permissões principais e adicionais exigidas pela ação original. O autor da ação original e o contexto atual de propriedade pessoal/da equipe devem corresponder à requisição salva.
• Somente ações de mutação têm um estado de requisição salvo. Nomes de ações somente de leitura retornam ACTION_REQUEST_NOT_FOUND; uma operação desconhecida retorna UNKNOWN_ACTION.
• REST retorna HTTP 202 enquanto data.status é running e HTTP 200 para os estados de requisição completed, failed ou interrupted. Um estado failed salvo é retornado como data com seu erro, sem ser relançado por esta ação de consulta periódica.
• Os valores de status são running, completed, failed e interrupted. Uma requisição running é informada como interrupted quando sua concessão temporária de execução expira; ela não é reiniciada automaticamente.
• Saídas concluídas são retidas apenas quando não há chaves de resultado que pareçam conter segredos e o resultado serializado tem no máximo 256 KiB. resultStored: false não significa que a ação falhou; use sua ação de histórico, get ou download.
• A consulta periódica não consome chamadas mensais de integração e permanece disponível após o esgotamento do limite mensal. A autenticação, os requisitos de plano pago e os limites de taxa compartilhados continuam se aplicando.
• Não adicione uma nova chave de idempotência para consultar o status; requestId identifica a mutação original. Uma chamada somente de leitura não retorna um requestId externo separado.
• Uma ação concluída pode retornar um trabalho de processamento de mídia em vez da mídia finalizada. Continue com a ação de status ou histórico do domínio correspondente quando o resultado retornado indicar um trabalho em andamento.
• webhooks_create_secret está disponível apenas por REST e não aparece na descoberta MCP. Executar ou consultar essa ação pelo MCP retorna o erro de ferramenta ACTION_NOT_AVAILABLE_IN_MCP. Os segredos de assinatura não são enviados aos assistentes.
• Os resultados salvos e as repetições usam os mesmos campos públicos de resposta de um novo resultado da ação. Erros de solicitações com falha contêm code, message, status e requestId opcional, com mensagens fixas da VoiceCheap. Falhas salvas não classificadas usam INTERNAL_ERROR para status de 500 ou superior, e ACTION_FAILED nos demais casos.

​

Uso

​

Erros

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