Cancel a video task

POST/v1/video/tasks/{task_id}/cancel

Requires service.use permission and Idempotency-Key.

Put your API key after Authorization: Bearer; send no request body.
Send an Idempotency-Key; the same key replays the original response.
Before generation starts, cancellation takes effect at once: the task becomes cancelled and the whole reservation is released.
After generation starts, the answer is not_effective; the task continues and is settled as usual.

Headers

#AuthorizationstringRequired

Bearer, a space and your API key. A missing or invalid key returns 401 authentication_failed.

#X-Request-IDstring

Your own request identifier. An invalid or repeated value is replaced; the value used comes back in the X-Request-ID response header.

#Idempotency-KeystringRequired

Generate a new value for every new request and save it; it starts with a letter or digit. When the outcome is unknown, retry with the same key and the original body to get the original response; the same key with a different body returns 409 idempotency_conflict. Keys belong to your team, not to one API key.

Length8–128CharactersA–Z a–z 0–9 . _ : -

Path parameters

#task_idstringRequired

ID of the video task to retrieve

Request

IDEMPOTENCY_KEY=${IDEMPOTENCY_KEY:-$(uuidgen)}
printf '%s\n' "Save IDEMPOTENCY_KEY for retries: ${IDEMPOTENCY_KEY}" >&2
curl --request POST "${CHENVOYA_BASE_URL}/v1/video/tasks/${TASK_ID}/cancel" \
  --header "Authorization: Bearer ${CHENVOYA_API_KEY}" \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}"

import urllib.request
import urllib.parse
import json
import os
import sys
import re
import uuid

key = os.environ["CHENVOYA_API_KEY"].strip()
if not key or re.search(r"[\x00-\x1f\x7f-\x9f]", key):
    sys.exit("Set CHENVOYA_API_KEY to a non-empty value without control characters")
base = os.environ["CHENVOYA_BASE_URL"].rstrip("/")
headers = {"Authorization": "Bearer " + key}
idempotency = os.environ.get("IDEMPOTENCY_KEY") or str(uuid.uuid4())
print("Save IDEMPOTENCY_KEY for retries: " + idempotency, file=sys.stderr)
headers["Idempotency-Key"] = idempotency
TASK_ID = os.environ["TASK_ID"]
path = "/v1/video/tasks/{task_id}/cancel".replace("{task_id}", urllib.parse.quote(TASK_ID, safe=""))
request = urllib.request.Request(base + path, data=None, headers=headers, method="POST")
try:
    with urllib.request.urlopen(request) as response:
        print(response.read().decode("utf-8"))
except urllib.request.HTTPError as error:
    print(error.read().decode("utf-8"))
    sys.exit(1)

// Needs Node.js 20 or later; save it as a .mjs file and run it.
const key = process.env.CHENVOYA_API_KEY?.trim();
if (!key || /[\x00-\x1f\x7f-\x9f]/.test(key)) {
  console.error("Set CHENVOYA_API_KEY to a non-empty value without control characters");
  process.exit(1);
}
const base = process.env.CHENVOYA_BASE_URL;
if (!base) throw new Error("Set CHENVOYA_BASE_URL");
const headers = {Authorization: `Bearer ${key}`};
const idempotency = process.env.IDEMPOTENCY_KEY || crypto.randomUUID();
console.error("Save IDEMPOTENCY_KEY for retries: " + idempotency);
headers["Idempotency-Key"] = idempotency;
const TASK_ID = process.env.TASK_ID;
if (!TASK_ID) throw new Error("Set TASK_ID");
const path = "/v1/video/tasks/{task_id}/cancel".replace("{task_id}", encodeURIComponent(TASK_ID));
const response = await fetch(base.replace(/\/$/, "") + path, {method: "POST", headers, body: undefined});
console.log(await response.text());
if (!response.ok) process.exitCode = 1;

package main

import (
	"crypto/rand"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
	"regexp"
	"strings"
)

func main() {
	key := strings.TrimSpace(os.Getenv("CHENVOYA_API_KEY"))
	if key == "" || regexp.MustCompile(`[\x00-\x1f\x7f-\x9f]`).MatchString(key) {
		fail("Set CHENVOYA_API_KEY to a non-empty value without control characters")
	}
	base := strings.TrimRight(os.Getenv("CHENVOYA_BASE_URL"), "/")
	if base == "" {
		fail("Set CHENVOYA_BASE_URL")
	}
	taskID := os.Getenv("TASK_ID")
	if taskID == "" {
		fail("Set TASK_ID")
	}
	path := strings.Replace("/v1/video/tasks/{task_id}/cancel", "{task_id}", url.PathEscape(taskID), 1)
	request, err := http.NewRequest("POST", base+path, nil)
	if err != nil {
		fail(err.Error())
	}
	request.Header.Set("Authorization", "Bearer "+key)
	idempotency := os.Getenv("IDEMPOTENCY_KEY")
	if idempotency == "" {
		idempotency = newOperationKey()
	}
	fmt.Fprintln(os.Stderr, "Save IDEMPOTENCY_KEY for retries: "+idempotency)
	request.Header.Set("Idempotency-Key", idempotency)
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		fail(err.Error())
	}
	text, err := io.ReadAll(response.Body)
	response.Body.Close()
	if err != nil {
		fail(err.Error())
	}
	fmt.Println(string(text))
	if response.StatusCode < 200 || response.StatusCode > 299 {
		os.Exit(1)
	}
}

func fail(message string) {
	fmt.Fprintln(os.Stderr, message)
	os.Exit(1)
}

// newOperationKey returns a random UUID; save it to retry with the same value.
func newOperationKey() string {
	var b [16]byte
	if _, err := rand.Read(b[:]); err != nil {
		fail(err.Error())
	}
	b[6] = b[6]&0x0f | 0x40
	b[8] = b[8]&0x3f | 0x80
	return fmt.Sprintf("%x-%x-%x-%x-%x", b[0:4], b[4:6], b[6:8], b[8:10], b[10:16])
}

ReturnsHTTP 202

A permanent snapshot of the cancellation operation. effective means Cancelled; not_effective means Not cancelled. Continue checking the task and its billing.

#task_idstringRequired

Video Task ID belonging to your team.

Length4–128CharactersA–Z a–z 0–9 _ -

#cancel_operation_idstringRequired

Stable Cancellation ID. New idempotency keys for the same task refer to this same ID.

Length4–128CharactersA–Z a–z 0–9 _ -

#cancel_statusstringRequired

Cancellation status. Reports Cancelled or Not cancelled immediately.

requestedRequested

effectiveCancelled

not_effectiveNot cancelled

failedFailed

#task_status_at_responsestringRequired

Task status saved when this idempotency key first receives a response. Replays keep this saved status.

queuedQueued

processingProcessing

succeededSucceeded

failedFailed

cancelledCancelled

#reason_codestringRequiredNullable

Null when cancellation takes effect; generation_already_started when generation has already started and the task is not cancelled.

Length1–96Charactersa–z 0–9 _

Response headers

#X-Request-IDstringRequired

The identifier of this request: the valid value you sent, or its replacement.

#LocationstringRequired

Canonical relative lookup path for the accepted object.

Response

{
  "task_id": "task_32ae2a5177b310d3bc1ec83a98f63889",
  "cancel_operation_id": "cancelop_ab99971fbec36056096527b7494b2059",
  "cancel_status": "requested",
  "task_status_at_response": "processing",
  "reason_code": null
}

{
  "error": {
    "code": "invalid_request",
    "message": "request parameters are invalid"
  },
  "trace_id": "trace_error_example"
}

{
  "error": {
    "code": "task_not_found",
    "message": "task was not found"
  },
  "trace_id": "trace_error_example"
}

{
  "error": {
    "code": "task_not_cancellable",
    "message": "the terminal task has no cancellation operation"
  },
  "trace_id": "trace_error_example"
}

{
  "error": {
    "code": "rate_limited",
    "message": "request rate limit exceeded"
  },
  "trace_id": "trace_error_example"
}

Status codes

Each error.code and what to do about it is on Error codes.

Status	Meaning and error.code
202	A permanent snapshot of the cancellation operation. Response headers`Location`
400	The submitted request is not valid. invalid_request
401	The API key is missing or invalid. Response headers`WWW-Authenticate` authentication_failed
404	No task with this ID is visible to your team. task_not_found
409	The idempotency key belongs to a different request, or the finished task has no cancellation operation to refer to. idempotency_conflict idempotency_replay_expired task_not_cancellable
429	The request rate limit blocks this read operation. Response headers`Retry-After` rate_limited
500	Internal error. internal_error
503	The service is temporarily unavailable. dependency_unavailable

Task status and results Idempotency and retries How billing works