Tasks

Cancel task

Request cooperative cancellation of an owned generation and query its actual final status.

Endpoint

POST/api/v1/developer/generations/{generation_id}/cancel

Authentication & scope

Authorization: Bearer <credential>; formal account API Key / OAuth only.

Scope: generations:write

Cancellation is cooperative. A queued, undispatched task may cancel immediately; a running task can still return running. This does not promise immediate termination or a full refund. Continue querying the task's final status and charged_credits.

No request body or Idempotency-Key is required. The response has the same GenerationResponse shape as task queries; the example represents a task cancelled before dispatch.

Request parameters

Field	Type	Required	Description
`generation_id`	UUID (path)	Yes	Owned task identifier.

curl --request POST \
  --url 'https://api.perchanceai.art/api/v1/developer/generations/{generation_id}/cancel' \
  --header 'X-App-Id: perchanceai' \
  --header 'X-Request-Id: docs-example' \
  --header 'Authorization: Bearer <formal_account_credential>'

Response HTTP 200

Illustrative response shape, not a live API response. Example numbers and USD do not imply fixed pricing or a cash balance. Null fields are omitted.

REST success responses contain success, code, message, request_id and data; the table describes data.

Field	Type	Required	Description
`generation_id`	UUID	Yes	Durable task identifier owned by the credential's account and App.
`status`	string	Yes	Poll until succeeded, failed or cancelled; an accepted request is not completion.
`model_key / modality / operation`	string	Yes	Selected model, image/video modality and public operation.
`created_at / updated_at`	ISO UTC string	Yes	UTC timestamps.
`completed_at`	ISO UTC string	No	Completion time when present.
`poll_after_ms`	integer	No	Suggested delay for nonterminal tasks (currently 2000); omitted for terminal tasks.
`estimated_credits / reserved_credits / charged_credits`	integer	Yes	Estimated, reserved and actually charged account credits.
`outputs`	object[]	Yes	media_id, media_type, url, and optional width, height, duration_ms.
`error`	object	No	Task failure: code, message, retryable. Omitted when absent.
`client_trace_id`	string	No	Echoed client correlation identifier when provided.

{
  "success": true,
  "code": "OK",
  "message": "OK",
  "request_id": "docs-example",
  "data": {
    "generation_id": "11111111-1111-4111-8111-111111111111",
    "status": "cancelled",
    "model_key": "<model_key_from_catalog>",
    "modality": "image",
    "operation": "image_generation",
    "created_at": "2026-10-14T00:00:00.000Z",
    "updated_at": "2026-10-14T00:00:01.000Z",
    "estimated_credits": 10,
    "reserved_credits": 10,
    "charged_credits": 0,
    "outputs": [],
    "completed_at": "2026-10-14T00:00:01.000Z"
  }
}

Errors

401 — DEVELOPER_TOKEN_REQUIRED
401 — DEVELOPER_TOKEN_INVALID / DEVELOPER_TOKEN_EXPIRED / DEVELOPER_TOKEN_REVOKED
403 — DEVELOPER_SCOPE_INSUFFICIENT
404 — TASK_NOT_FOUND

Missing bearer returns REQUIRED; invalid credentials, including historical anonymous tokens, return INVALID. Expired or revoked credentials use their corresponding codes.

{
  "success": false,
  "code": "DEVELOPER_TOKEN_REQUIRED",
  "message": "A developer bearer token is required.",
  "request_id": "docs-example"
}