Video & materi

Mendapatkan Status Video

Mendapatkan status dan hasil tugas video

GET
/v1/tasks/{id}

GET /v1/videos/generations/{id} adalah endpoint kompatibilitas. Endpoint ini tetap didukung untuk integrasi yang sudah ada dan mengembalikan hasil dalam format yang sama dengan GET /v1/tasks/{id}. Integrasi baru harus melakukan polling ke GET /v1/tasks/{id}; lihat Mendapatkan Status Tugas.

Parameter Path

idstringpathwajib

ID tugas yang dikembalikan oleh permintaan pembuatan video. id dan task_id mengidentifikasi tugas yang sama.

Pembacaan status mengembalikan HTTP 200 bahkan ketika tugas gagal; periksa status. Tugas yang kedaluwarsa atau tidak tersedia akan mengembalikan 404 async_task_not_found. Tugas yang bukan milik workspace Anda akan mengembalikan 403 task_not_owned. 503 async_task_owner_unavailable bersifat sementara: coba ulangi permintaan tersebut.

Respons

Bidang yang menjelaskan hasil, kesalahan, stempel waktu, dan model akan dikembalikan jika tersedia untuk tugas tersebut.

idstring

ID Tugas.

task_idstring

ID tugas yang sama dengan id.

poll_urlstring

URL status untuk tugas ini. Lakukan polling GET /v1/tasks/{id} dengan id.

billing_transaction_idstring

ID transaksi penagihan setelah penyelesaian. Ini terpisah dari ID tugas.

statusstring

Status tugas: pending, processing, completed, failed.

progressinteger

Progres opsional dari 0 hingga 100. Hanya dikembalikan jika nilai progres yang sebenarnya tersedia; gunakan status untuk menentukan penyelesaian.

video_urlstring

URL video yang dihasilkan (saat selesai). Ini adalah URL hasil media TokenLab yang tetap valid selama 30 hari; lihat Mengunduh hasil. Tugas yang gagal dan belum selesai tidak mengembalikan URL video.

last_frame_urlstring

URL frame terakhir yang dihasilkan, saat Anda memintanya dengan return_last_frame dan model mendukungnya.

videoobject

Hasil video tunggal dengan url, duration, width, dan height jika tersedia.

videosarray

Hasil video ganda saat tugas mengembalikan lebih dari satu output.

errorstring | object

Alasan tugas gagal (hanya saat status adalah failed): berupa string, atau objek dengan message dan, jika diketahui, type, code, param, dan retryable. Tugas yang gagal juga dapat membawa error_details; lihat Pekerjaan asinkron dan polling.

media_retentionobject

Status penyimpanan video: days dan items, masing-masing dengan url, kind, status, dan expires_at. Bidang ini bisa tidak ada jika status tidak diketahui tepat waktu; URL tetap berfungsi.

createdinteger

Stempel waktu pembuatan.

updatedinteger

Stempel waktu pembaruan terakhir.

modelstring

Model yang digunakan untuk tugas tersebut.

Permintaan

curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"

Respons

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "veo3.1",
  "created": 1706000000,
  "updated": 1706000000
}

Mengunduh Hasil

video_url terlihat seperti https://api.tokenlab.sh/v1/media-results/{id}.mp4?token=…. Token di dalam URL adalah kredensial, jadi header Authorization tidak diperlukan. Bagikan URL hanya kepada orang yang boleh melihat video tersebut. URL akan mengarahkan ke file, jadi ikuti pengalihan (redirect) saat Anda mengunduh (curl -L).

  • URL tetap valid selama 30 hari sejak hasil pertama kali direkam. Unduh file jika Anda membutuhkannya lebih lama; lihat Retensi data.
  • 404 media_not_found: token atau ekstensi file tidak cocok dengan hasil. Gunakan URL persis yang Anda terima.
  • 410 media_expired: periode 30 hari telah berakhir.
  • 502 atau 503 media_unavailable: hasil masih direkam, atau TokenLab sedang sibuk. Coba lagi setelah jeda Retry-After.
  • Tambahkan metadata=true ke URL untuk membaca status penyimpanan alih-alih filenya.

Beberapa hasil dikirimkan sebagai https://api.tokenlab.sh/v1/videos/generations/{id}/content. URL tersebut memerlukan header Authorization: Bearer yang sama dengan yang Anda gunakan untuk polling, dan hanya workspace pemilik tugas yang dapat membukanya.

Interval Pengecekan

  • Periksa setiap 5–10 detik.
  • Tingkatkan interval untuk tugas yang berjalan lama.
  • Tetapkan waktu tunggu maksimum untuk aplikasi Anda.
  • Berhenti saat statusnya failed dan tampilkan error yang dikembalikan.
import requests
import time

def wait_for_video(task_id, max_wait=600, interval=5):
    """Menunggu video dengan batas waktu."""
    start = time.time()

    while time.time() - start < max_wait:
        response = requests.get(
            f"https://api.tokenlab.sh/v1/tasks/{task_id}",
            headers={"Authorization": "Bearer sk-your-api-key"}
        )
        response.raise_for_status()
        data = response.json()

        if data["status"] == "completed":
            return data["video_url"]
        elif data["status"] == "failed":
            raise Exception(data.get("error", "Pembuatan video gagal"))

        time.sleep(interval)

    raise TimeoutError("Pembuatan video kehabisan waktu")

Otorisasi

BearerAuth
AuthorizationBearer <token>

Autentikasi API Key. Buat atau kelola API key di Dashboard > API > API Keys.

Lokasi: header

Parameter path

id*string

ID tugas asinkron yang dikembalikan oleh id / task_id, atau disematkan dalam poll_url

Respons

application/json

application/json

application/json

application/json

application/json

application/json

application/json