Status van een actieaanvraag ophalen

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

​

Authenticatie en machtigingen

​

Parameters

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

​

Voorbeeldaanvragen

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)

​

Antwoord

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

​

Voltooide aanvraag met een opgeslagen resultaat

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

​

Voltooid verzoek voor segmentbewerking

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

​

Voltooide aanvraag zonder bewaard resultaat

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

​

Mislukte opgeslagen aanvraag

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

​

Onderbroken opgeslagen aanvraag

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

​

Opmerkingen bij de bewerking

• Roep dit aan als POST /v1/actions/action_request_get met een API-sleutel, of roep de MCP-tool action_request_get aan. Er is geen GET /v1/requests-endpoint.
• Beide invoervelden zijn vereist. requestId moet een UUID v4 zijn; operation is de exacte oorspronkelijke actienaam van 1–100 tekens die overeenkomt met ^[a-z][a-z0-9_]+$. Extra velden worden geweigerd.
• De inloggegevens moeten op dit moment alle primaire en aanvullende machtigingen hebben die de oorspronkelijke actie vereist. De initiërende uitvoerende gebruiker en de huidige eigendomscontext van het persoonlijke account of team moeten overeenkomen met de opgeslagen aanvraag.
• Alleen muterende acties hebben een opgeslagen aanvraagstatus. Namen van alleen-lezenacties retourneren ACTION_REQUEST_NOT_FOUND; een onbekende bewerking retourneert UNKNOWN_ACTION.
• REST retourneert HTTP 202 zolang data.status running is en HTTP 200 voor de aanvraagstatussen completed, failed of interrupted. Een opgeslagen failed-status wordt als data met de bijbehorende error geretourneerd en wordt niet opnieuw als fout opgeworpen door deze peilactie.
• De statuswaarden zijn running, completed, failed en interrupted. Een aanvraag met status running wordt gemeld als interrupted wanneer de uitvoeringslease is verlopen; deze wordt niet automatisch opnieuw gestart.
• Voltooide uitvoer wordt alleen bewaard als er geen resultaatvelden aanwezig zijn die op geheimen lijken en het geserialiseerde resultaat maximaal 256 KiB groot is. resultStored: false betekent niet dat de actie is mislukt; gebruik de bijbehorende history-, get- of download-actie.
• Pollen verbruikt geen maandelijkse integratieaanroep en blijft beschikbaar nadat de maandlimiet is bereikt. Authenticatie, vereisten voor een betaald abonnement en gedeelde snelheidslimieten blijven van toepassing.
• Voeg geen nieuwe idempotentiesleutel toe voor polling; requestId identificeert de oorspronkelijke mutatie. Een alleen-lezen-aanroep retourneert geen afzonderlijke buitenste requestId.
• Een voltooide actie kan een mediaverwerkingstaak retourneren in plaats van voltooide media. Ga verder met de relevante status- of geschiedenisactie van het domein als het geretourneerde resultaat aangeeft dat er nog verwerking plaatsvindt.
• webhooks_create_secret is alleen via REST beschikbaar en wordt niet via MCP ontdekt. Aanroepen of het resultaat opvragen via MCP geeft de toolfout ACTION_NOT_AVAILABLE_IN_MCP. Ondertekeningsgeheimen worden niet naar assistenten verstuurd.
• Opgeslagen resultaten en herhalingen gebruiken dezelfde openbare antwoordvelden als een nieuw actieresultaat. Fouten van mislukte verzoeken bevatten code, message, status en optioneel requestId, met vaste VoiceCheap-berichten. Niet-geclassificeerde opgeslagen fouten gebruiken INTERNAL_ERROR bij status 500 of hoger en anders ACTION_FAILED.

​

Verbruik

​

Fouten

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