research（規劃 → 多源網絡搜索 → 綜合）和 video（模型生成）以後台任務的形式運行：你先將其入隊，立即獲得一個 job_id，然後輪詢直到任務完成。
生命週期
- 入隊 —
POST /api/v1/research或/api/v1/video會返回202，並帶有{ id, job_id, status: "queued", poll_url }。 - 輪詢 —
GET /api/v1/jobs/{job_id}返回當前status：queued→active→completed（或failed）。 - 讀取結果 — 當
status === "completed"時，result中保存着類型化的負載數據。
SDK 用法
waitForJob() 會為你執行輪詢循環，並支持可選的 onProgress 回調和 AbortSignal。
theo.video() + waitForJob<VideoJobResult>()。
輪詢間隔與限制
- 默認輪詢間隔為 2 秒；
waitForJob默認在 5 分鐘後放棄（maxWaitMs），並拋出TheoTimeoutError。對於較長的視頻渲染，可以調高maxWaitMs。 - 不要以快於約 1 秒的頻率輪詢——這隻會消耗速率限制額度，並不會讓任務更快完成。
取消
傳入一個AbortSignal。當它觸發時，waitForJob 會停止輪詢，並以 TheoCancelledError 拒絕（它不會取消服務器端的任務——只是讓你的客戶端停止等待）。
結果模式
result 通過 job<T>() / waitForJob<T>() 上的泛型進行類型化。這些結構與 REST 負載一致（參見獲取任務狀態）：
ResearchJobResult—{ report, sources: { title, url }[], queries, sourceCount }VideoJobResult—{ videoUrl, model, engine, durationMs }ImageJobResult—{ imageUrl, model, engine }DocumentJobResult—{ title, format, downloadUrl, sizeBytes }任何model/engine字段都會以 Theo 品牌呈現——原始的上游標識符永遠不會出現。
成本與用量
任務結果目前尚不攜帶按任務計算的cost_cents 字段。要歸因 research/video 任務的支出，請查看聚合的用量報告（theo.usage()），其中包含覆蓋 research 和 video 的 by_mode 明細。
失敗
當status === "failed" 時，result 為 null，error 中保存着失敗原因字符串。入隊調用本身也可能在任務隊列暫時不可用時返回 503 queue_unavailable——請稍後重試。