Pekerjaan asinkron

Mendapatkan Status Tugas

Mengambil status dan hasil dari tugas asinkron apa pun: gambar, video, musik, 3D, Worlds, dan transkripsi audio asinkron

GET
/v1/tasks/{id}

Gambaran Umum

Gunakan GET /v1/tasks/{id} untuk memeriksa tugas asinkron apa pun. Endpoint ini melayani tugas gambar, video, musik, 3D, Worlds, dan transkripsi audio asinkron. Masukkan id atau task_id dari respons pembuatan.

Bidang hasil World, seperti world_id dan world_marble_url, didokumentasikan pada Mendapatkan Status World. Untuk tugas World, X-Task-Type adalah 3d.

Untuk sebagian besar tugas, poll_url dalam respons pembuatan adalah jalur yang sama ini. Respons pembuatan Worlds mengembalikan poll_url di bawah /v1/worlds/generations/{id}; lakukan polling /v1/tasks/{id} dengan id tugas untuk Worlds juga.

Jalur status per-modalitas, seperti /v1/images/{id}, /v1/videos/generations/{id}, /v1/music/generations/{id}, dan /v1/3d/generations/{id}, adalah endpoint kompatibilitas. Endpoint ini tetap didukung untuk integrasi yang sudah ada.

Pembacaan status mengembalikan HTTP 200 untuk tugas yang gagal. Baca status, bukan kode HTTP, untuk melihat hasilnya. Bidang hasil bergantung pada jenis tugas; lihat Mendapatkan Status Gambar, Mendapatkan Status Video, Mendapatkan Status Musik, dan Mendapatkan Status 3D. Tautan hasil adalah URL hasil media TokenLab yang tetap valid selama 30 hari; lihat Retensi data.

Parameter Jalur

idstringpathwajib

id atau task_id yang dikembalikan oleh permintaan pembuatan.

Respons

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

idstring

Pengidentifikasi tugas asinkron kanonik.

task_idstring

Alias pengidentifikasi tugas asinkron.

poll_urlstring

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

billing_transaction_idstring

ID transaksi penagihan, jika tercatat untuk tugas tersebut. Header X-Billing-Transaction-ID membawa nilai yang sama. Ini adalah pengidentifikasi penagihan, bukan pengidentifikasi tugas.

statusstring

Status tugas: pending, processing, completed, failed, atau timeout. Hentikan polling pada status completed, failed, atau timeout. Tugas yang dibatalkan direpresentasikan sebagai failed dengan cancelled: true.

cancelledboolean

true ketika tugas asinkron dalam antrean dibatalkan sebelum eksekusi.

cancellation_statusstring

Penanda pembatalan. Muncul sebagai cancelled ketika pembatalan berhasil.

dataarray

Untuk tugas gambar yang selesai, hasil gambar yang dihasilkan dikembalikan di sini. Tugas gambar mengembalikan URL dalam data[].url.

progressnumber

Nilai progres opsional. Hanya dikembalikan ketika nilai progres nyata tersedia; gunakan status untuk menentukan penyelesaian.

video_urlstring

URL aset hasil ketika tugas selesai dan menghasilkan video.

videoobject

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

videosarray

Payload video ganda ketika lebih dari satu output tersedia.

errorstring | object

Alasan tugas gagal: berupa string, atau objek dengan message dan, jika diketahui, type, code, param, dan retryable.

error_detailsobject

Detail kegagalan ketika tugas gagal: status, message, type, code, retryable, dan param jika bidang permintaan yang bermasalah.

media_retentionobject

Status penyimpanan tautan hasil: days dan items[] dengan url, kind, status, dan expires_at. Bidang ini bisa saja tidak ada; tautan tetap berfungsi.

createdinteger

Stempel waktu pembuatan jika tersedia.

updatedinteger

Stempel waktu pembaruan terakhir jika tersedia.

modelstring

Model yang digunakan oleh tugas jika tersedia.

Header Respons

Respons status yang berhasil menyertakan header berikut:

HeaderDeskripsi
X-Task-IDID tugas publik
X-Task-TypeKeluarga tugas, seperti image, video, music, 3d, atau audio
Cache-Controlno-store. Jangan melakukan cache pada respons status
X-Billing-Transaction-IDID transaksi penagihan, jika tercatat
X-Task-CostBiaya tugas yang telah diselesaikan, jika tugas telah diselesaikan

Perilaku Kesalahan

HTTPKodeArti
400missing_task_id, invalid_task_idID tugas hilang atau bukan ID tugas yang valid
403task_not_ownedTugas tidak termasuk dalam ruang kerja API key ini. Hentikan polling tugas tersebut
404async_task_not_foundTugas telah kedaluwarsa atau tidak tersedia
503async_task_owner_unavailableTugas tidak dapat dibaca saat ini. Coba lagi
{
  "error": {
    "message": "Task not found or no longer available.",
    "type": "invalid_request_error",
    "code": "async_task_not_found"
  }
}

Contoh

Permintaan

curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"
{  "id": "string",  "status": "pending",  "progress": 0,  "created": 0,  "updated": 0,  "model": "string",  "video": {    "url": "string",    "duration": 0,    "width": 0,    "height": 0  },  "error": "string",  "error_details": {    "projection_version": 0,    "status": 400,    "message": "string",    "type": "string",    "code": "string",    "param": "string",    "retryable": true,    "upstream": {      "source": "string",      "code": "string",      "message": "string",      "param": "string"    }  },  "task_id": "string",  "poll_url": "string",  "cancelled": true,  "cancellation_status": "cancelled",  "billing_transaction_id": "string",  "video_url": "string",  "last_frame_url": "string",  "videos": [    {}  ],  "data": [    {}  ],  "audio_url": "string",  "title": "string",  "lyrics": "string",  "model_url": "string",  "glb_url": "string",  "fbx_url": "string",  "media_retention": {    "days": 0,    "items": [      {        "url": "http://example.com",        "kind": "image",        "content_type": "string",        "status": "saving",        "expires_at": "2019-08-24T14:15:22Z"      }    ]  }}

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