Read a video task

GET/v1/video/tasks/{task_id}

Check execution progress, delivery, usage and the billing summary.

Put your API key after Authorization: Bearer in the request header.
Returns the task status, delivery, usage and settlement summary; keep reading until status is final.
After success, download from output.assets[].url; the link is null when expired or unavailable.

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.

Path parameters

#task_idstringRequired

ID of the video task to retrieve

Request

curl --request GET "${CHENVOYA_BASE_URL}/v1/video/tasks/${TASK_ID}" \
  --header "Authorization: Bearer ${CHENVOYA_API_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}
TASK_ID = os.environ["TASK_ID"]
path = "/v1/video/tasks/{task_id}".replace("{task_id}", urllib.parse.quote(TASK_ID, safe=""))
request = urllib.request.Request(base + path, data=None, headers=headers, method="GET")
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 TASK_ID = process.env.TASK_ID;
if (!TASK_ID) throw new Error("Set TASK_ID");
const path = "/v1/video/tasks/{task_id}".replace("{task_id}", encodeURIComponent(TASK_ID));
const response = await fetch(base.replace(/\/$/, "") + path, {method: "GET", headers, body: undefined});
console.log(await response.text());
if (!response.ok) process.exitCode = 1;

package main

import (
	"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}", "{task_id}", url.PathEscape(taskID), 1)
	request, err := http.NewRequest("GET", base+path, nil)
	if err != nil {
		fail(err.Error())
	}
	request.Header.Set("Authorization", "Bearer "+key)
	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)
}

ReturnsHTTP 200

The current task, including delivery, usage and billing information.

Returns The video task object; its fields are described there.

Response headers

#X-Request-IDstringRequired

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

Response

{
  "id": "task_32ae2a5177b310d3bc1ec83a98f63889",
  "object": "video.task",
  "request_id": "req_6acd96894df9798feb0ddb21e5a52d70",
  "billing_correlation_id": "billcorr_2f6c57065a4404b27fb9b6b24ea9a0d0",
  "model": "dreamina-seedance-2-0-260128",
  "status": "succeeded",
  "phase": null,
  "delivery_status": "available",
  "settlement_status": "settled",
  "created_at": 1793167380,
  "started_at": 1793167381,
  "completed_at": 1793167382,
  "usage": {
    "meter_type": "seedance_video_generation",
    "video_tokens": 51652,
    "output_duration_seconds": 5,
    "input_video_duration_seconds": 0,
    "resolution": "720p",
    "fps": 24,
    "has_reference_video": false
  },
  "billing": {
    "currency": "USD",
    "final_actual_cost": "0.361564",
    "collected_liability_amount": "0.361564",
    "funding_debit_amount": "0.361564",
    "refunded_liability_amount": "0.000000",
    "funding_refund_amount": "0.000000",
    "outstanding_receivable": "0.000000",
    "billing_url": "/v1/video/tasks/task_32ae2a5177b310d3bc1ec83a98f63889/billing"
  },
  "output": {
    "assets": [
      {
        "asset_id": "asset_4d00c4c64086b1e29724c1f2349f3708",
        "media_type": "video",
        "role": "result",
        "url": "https://media.example.invalid/download/result-0001?signature=example",
        "materialized_at": 1793167385,
        "expires_at": 1793253785,
        "delivery_source": "platform",
        "materialization_status": "completed",
        "download_status": "available"
      }
    ]
  },
  "cancellation": null,
  "error": 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": "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
200	The current task, including delivery, usage and billing information.
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
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 Quickstart Receive callbacks