Lấy trạng thái tác vụ video

Sau khi gửi tác vụ qua Tạo tác vụ video, hãy thăm dò GET /v1/video/generations/{task_id} cho đến khi tác vụ đạt trạng thái kết thúc, rồi tải video từ GET /v1/videos/{task_id}/content. Việc thăm dò đọc bản ghi mà RouteAPI làm mới ở chế độ nền, nên khoảng 10–15 giây là đủ.

Lấy bản ghi tác vụ

GET /v1/video/generations/{task_id}

Tác vụ được giới hạn theo người dùng của API Key: task_id thuộc tài khoản khác được báo là task_not_exist.

curl https://api.routeapi.ai/v1/video/generations/task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

{
  "code": "success",
  "message": "",
  "data": {
    "id": 4512,
    "created_at": 1792048450,
    "updated_at": 1792048569,
    "task_id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
    "platform": "54",
    "user_id": 1024,
    "group": "default",
    "channel_id": 18,
    "quota": 123456,
    "action": "generate",
    "status": "SUCCESS",
    "progress": "100%",
    "fail_reason": "",
    "result_url": "https://...mp4",
    "submit_time": 1792048458,
    "start_time": 1792048461,
    "finish_time": 1792048569,
    "properties": {
      "input": "",
      "origin_model_name": "seedance-2.0-fast"
    },
    "data": { "id": "cgt-xxxxxxxx", "status": "succeeded" }
  }
}

Các trường của bản ghi tác vụ

Trường	Mô tả
`code`	`"success"` khi đọc được tác vụ; khi lỗi dùng cấu trúc lỗi tác vụ mô tả bên dưới
`data.id`	ID dòng nội bộ; không dùng trong bất kỳ yêu cầu nào
`data.task_id`	ID tác vụ RouteAPI — giá trị dùng để thăm dò và tải về
`data.status`	`NOT_START`, `SUBMITTED`, `QUEUED`, `IN_PROGRESS`, `SUCCESS` hoặc `FAILURE`
`data.progress`	Chuỗi tiến độ như `"30%"` hoặc `"100%"`
`data.result_url`	URL video sau khi tác vụ thành công. Có thể trỏ tới endpoint tải của RouteAPI hoặc trực tiếp tới URL upstream có thời hạn
`data.fail_reason`	Lý do thất bại; các trường hợp khác để trống
`data.submit_time` / `start_time` / `finish_time`	Giây Unix. `start_time` và `finish_time` bằng `0` cho tới khi tác vụ bắt đầu và kết thúc
`data.created_at` / `updated_at`	Giây Unix, thời điểm tạo và cập nhật cuối của dòng
`data.quota`	Hạn mức bị trừ cho tác vụ
`data.platform`	Số loại kênh upstream đã chạy tác vụ
`data.group` / `data.channel_id` / `data.user_id`	Nhóm tính phí, kênh và tài khoản sở hữu. Hữu ích khi hỏi hỗ trợ về một tác vụ
`data.action`	Loại tác vụ: `generate`, `textGenerate`, `firstTailGenerate`, `referenceGenerate` hoặc `remixGenerate`
`data.properties`	Thuộc tính đã lưu: `origin_model_name`, `upstream_model_name`, và bản chụp yêu cầu upstream trong `input` khi adapter có ghi. Dành cho gỡ lỗi
`data.data`	Payload tác vụ mới nhất của nhà cung cấp upstream, lưu để gỡ lỗi. Cấu trúc tùy nhà cung cấp

Trạng thái

Trạng thái	Ý nghĩa	Việc cần làm
`NOT_START`	Dòng đã tồn tại nhưng chưa thăm dò upstream	Tiếp tục thăm dò
`SUBMITTED` / `QUEUED`	Đã nhận, đang chờ trong hàng đợi của nhà cung cấp	Tiếp tục thăm dò
`IN_PROGRESS`	Đang tạo	Tiếp tục thăm dò
`SUCCESS`	Kết thúc thành công	Tải video
`FAILURE`	Kết thúc thất bại	Đọc `fail_reason`; khoản giữ trước đã được hoàn

Chỉ SUCCESS là kết thúc thành công; FAILURE là kết thúc thất bại và khoản giữ trước đã được hoàn khi bạn thấy nó. Mọi trạng thái khác đều có nghĩa là tiếp tục thăm dò.

Ví dụ thăm dò

import os
import time
import requests

BASE = "https://api.routeapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['ROUTEAPI_KEY']}"}

task_id = requests.post(
    f"{BASE}/v1/video/generations",
    headers=HEADERS,
    json={
        "model": "seedance-2.0-fast",
        "prompt": "An orange cat stretching on a windowsill at sunrise",
        "duration": 5,
        "resolution": "720p",
        "ratio": "16:9",
    },
    timeout=60,
).json()["task_id"]

while True:
    task = requests.get(f"{BASE}/v1/video/generations/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    print(task["status"], task["progress"])

    if task["status"] == "SUCCESS":
        video = requests.get(f"{BASE}/v1/videos/{task_id}/content", headers=HEADERS, timeout=300)
        video.raise_for_status()
        with open(f"{task_id}.mp4", "wb") as f:
            f.write(video.content)
        break
    if task["status"] == "FAILURE":
        raise SystemExit(f"task failed: {task['fail_reason']}")

    time.sleep(15)

Ví dụ shell đầy đủ

#!/usr/bin/env bash
set -euo pipefail
: "${ROUTEAPI_KEY:?set ROUTEAPI_KEY first}"
BASE="${ROUTEAPI_BASE:-https://api.routeapi.ai}"
AUTH="Authorization: Bearer $ROUTEAPI_KEY"

TASK_ID=$(curl -sS -X POST "$BASE/v1/video/generations" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.0-fast","prompt":"An orange cat stretching on a windowsill at sunrise","duration":4,"resolution":"480p","ratio":"16:9"}' \
  | jq -er .task_id)

echo "task: $TASK_ID"

for _ in $(seq 1 60); do
  RESP=$(curl -sS "$BASE/v1/video/generations/$TASK_ID" -H "$AUTH")
  STATUS=$(echo "$RESP" | jq -r .data.status)
  echo "status: $STATUS $(echo "$RESP" | jq -r .data.progress)"

  case "$STATUS" in
    SUCCESS)
      curl -sSL -o "$TASK_ID.mp4" "$BASE/v1/videos/$TASK_ID/content" -H "$AUTH"
      echo "saved $TASK_ID.mp4"
      exit 0
      ;;
    FAILURE)
      echo "failed: $(echo "$RESP" | jq -r .data.fail_reason)"
      exit 1
      ;;
  esac

  sleep 15
done

echo "timed out waiting for the task"
exit 1

Thăm dò GET /v1/video/generations/{task_id} thường chỉ đọc bản ghi cục bộ, nên giữ khoảng 10–15 giây thay vì gọi dồn dập endpoint.

Tải video

GET /v1/videos/{task_id}/content

Truyền byte của video qua RouteAPI, nên bên gọi không cần truy cập kho lưu trữ của nhà cung cấp. Phản hồi mang Cache-Control: public, max-age=86400 và Content-Type của upstream (mặc định video/mp4 cho kết quả Base64 nội tuyến).

curl -L -o out.mp4 \
  https://api.routeapi.ai/v1/videos/task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV/content \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

Đường dẫn này chấp nhận API Key hoặc phiên console, và chỉ trả dữ liệu của các tác vụ do bên gọi sở hữu. Lỗi của nó dùng cấu trúc đối tượng {"error": {"message": "...", "type": "..."}}:

Trạng thái	Ý nghĩa
400	Tác vụ chưa hoàn thành; thông báo chứa trạng thái hiện tại
404	Tác vụ không tồn tại, hoặc thuộc tài khoản khác
403	URL video phân giải được bị từ chối bởi quy tắc bảo vệ truy cập ra ngoài
500	Không đọc được dòng tác vụ hoặc kênh của nó, hoặc không phân tích được URL video
502	Không kết nối được nhà cung cấp, nhà cung cấp trả trạng thái khác 200, hoặc URL video rỗng

Lỗi

Trạng thái	Mã	Ý nghĩa
400	`task_not_exist`	`task_id` không tồn tại hoặc thuộc tài khoản khác
500	`get_task_failed`	RouteAPI không đọc được dòng tác vụ của chính nó
500	`marshal_response_failed`, `copy_response_body_failed`	RouteAPI không tuần tự hóa hoặc ghi được phản hồi

Yêu cầu bị từ chối trước khi định tuyến dùng body lỗi middleware chuẩn {"error": {"message": ..., "type": "error", "code": ...}}, không dùng cấu trúc tác vụ.

Tạo tác vụ video — gửi tác vụ và khung yêu cầu dùng chung.
Định dạng video OpenAI — phương ngữ /v1/videos của cùng tác vụ, với remix.
Asset — 404 từ API asset nghĩa là tài khoản chưa có không gian asset.
Lỗi thường gặp — mã trạng thái dùng chung cho mọi endpoint mô hình.