資源
獲取任務狀態
輪詢異步任務（視頻、研究等）的狀態。
GET
/
api
/
v1
/
jobs
/
{id}
獲取任務狀態
curl --request GET \
--url https://api.example.com/api/v1/jobs/{id}import requests
url = "https://api.example.com/api/v1/jobs/{id}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/api/v1/jobs/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/jobs/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/jobs/{id}"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/jobs/{id}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/jobs/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"id": "<string>",
"type": "<string>",
"status": "<string>",
"progress": 123,
"result": {},
"error": {},
"created_at": {},
"completed_at": {}
}獲取一個異步任務的當前狀態。用於從 Video 和 Research 端點輪詢結果。
認證
需要 Bearer 令牌。參見認證。路徑參數
string
必填
異步端點返回的任務 ID（例如
job_xyz789）。請求示例
curl https://www.hitheo.ai/api/v1/jobs/job_xyz789 \
-H "Authorization: Bearer $THEO_API_KEY"
// 單次輪詢
const status = await theo.job("job_xyz789");
console.log(status.status, status.progress);
// 自動輪詢直到完成（推薦）
const result = await theo.waitForJob("job_xyz789");
console.log(result.result);
響應
string
任務 ID。
string
任務類型（例如
"video"、"research"）。string
當前狀態：
"queued"、"active"、"completed" 或 "failed"。number
進度百分比（0–100）。
object | null
任務結果。在狀態變為
"completed" 之前為 null。其具體結構取決於任務的 type —— 參見下方的各類型的結果模式。任何提供方/模型標識始終以 Theo 品牌呈現（engine / model），絕不暴露原始上游名稱。string | null
當狀態為
"failed" 時的錯誤信息。string | null
任務創建的時間。
string | null
任務完成（或失敗）的時間。
響應示例（已完成）
result 是一個對象，而非單純的 URL。以視頻任務為例：
{
"id": "job_xyz789",
"type": "video",
"status": "completed",
"progress": 100,
"result": {
"videoUrl": "https://artifacts.hitheo.ai/video/xyz789.mp4",
"model": "Theo Motion",
"engine": "theo-motion",
"durationMs": 90000
},
"error": null,
"created_at": "2026-04-10T12:00:00Z",
"completed_at": "2026-04-10T12:01:30Z"
}
響應示例（進行中）
{
"id": "job_xyz789",
"type": "research",
"status": "active",
"progress": 45,
"result": null,
"error": null,
"created_at": "2026-04-10T12:00:00Z",
"completed_at": null
}
SDK 的
theo.waitForJob(jobId, { intervalMs, maxWaitMs, signal, onProgress }) 會以可配置的間隔（默認 2 秒）自動輪詢，支持整體超時（默認 5 分鐘）、可選的 AbortSignal，以及 onProgress 回調。舊版的位置參數形式 waitForJob(id, intervalMs, maxWaitMs) 依然可用。參見異步任務指南。各類型的結果模式
result 對象因任務 type 而異。這些結構與 SDK 中的類型化結果接口（ResearchJobResult、VideoJobResult、ImageJobResult、DocumentJobResult）一一對應 —— 使用 theo.waitForJob<VideoJobResult>(...) 輪詢即可獲得對應類型。
research
{
"report": "# Markdown report with inline citations...",
"sources": [{ "title": "Source title", "url": "https://..." }],
"queries": ["generated search query"],
"sourceCount": 8
}
video
{ "videoUrl": "https://...", "model": "Theo Motion", "engine": "theo-motion", "durationMs": 90000 }
image
{ "imageUrl": "https://...", "model": "Theo Studio", "engine": "theo-studio" }
document
{ "title": "Report", "format": "pdf", "downloadUrl": "https://...", "sizeBytes": 248000 }
端點
GET /api/v1/jobs/{id}
需要通過 Bearer 令牌進行認證。參見認證。這個頁面有幫助嗎?
獲取任務狀態
curl --request GET \
--url https://api.example.com/api/v1/jobs/{id}import requests
url = "https://api.example.com/api/v1/jobs/{id}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/api/v1/jobs/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/jobs/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/jobs/{id}"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/jobs/{id}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/jobs/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"id": "<string>",
"type": "<string>",
"status": "<string>",
"progress": 123,
"result": {},
"error": {},
"created_at": {},
"completed_at": {}
}