Docs

任务与结果

最后更新: 2026-10-03阅读约 6 分钟

有些工具会立即（同步）返回；另一些会启动一个任务并在后台完成。本页介绍第二种情况：如何得知任务已完成以及如何获取结果。

创建响应

异步工具返回 202：

{ "jobId": "...", "status": "...", "state": "pending", "requestId": "req_..." }

state 字段对所有工具都一致，请以它为准：

值含义
pending已接收，尚未开始
running进行中
action_required等待您操作（报告审核：确认提取的数据）
completed已完成
partial部分完成：部分文件失败（内容包可能出现）
failed失败

status 是工具的原始状态（DONE、processing、need_confirm 等）。为兼容而保留；新的集成请基于 state。

任务 ID

所有工具的每个任务响应都包含 jobId 字段：创建时、状态中以及确认后。请用它轮询状态。

1.6.0 版本之前，各工具以不同名称返回 ID（id、_id、contentGenJobId）。这些字段仍为现有集成保留，但已弃用：请使用 jobId。

状态轮询

状态位于 GET /<工具路径>/jobs/{id}：

工具状态
完整估价报告GET /valuation/report/jobs/{id}
报告审核GET /valuation/review/jobs/{id}
内容包GET /content/generate/jobs/{id}
文案GET /text/generate/jobs/{id}
视频GET /video/create/jobs/{id}
数字人GET /avatar/video/jobs/{id}
照片GET /photo/enhance/jobs/{id}
户型图GET /floorplan/create/jobs/{id}
PDFGET /pdf/create/jobs/{id}
  • 轮询免费，不计为 API 调用，但计入请求频率限制。每 3 到 5 秒一次即可。
  • 只有创建任务的密钥所属账户能看到该任务。他人的或未知的 ID 返回相同的 404。
  • 机构中绑定经纪人的密钥只能看到自己启动的任务；整个机构的密钥能看到机构的所有任务。
  • 任务在创建后 7 天内可以查询。之后 GET .../jobs/{id} 返回 404，内容包、文案和视频文件也无法再通过 API 下载。
  • 状态响应包含同样的 status 和 state，结果就绪后还包含工具的结果。失败的内容包、文案或视频任务带有 error，照片任务带有 metadata.error：以通用文本说明原因。

户型图和报告审核会立即处理文件：202 响应已包含最终状态（completed、failed 或 action_required），因此轮询是可选的。

任务等待您操作时

读取文件后，报告审核（估价）停在 action_required，并在 extracted 中返回提取的数据。检查后确认：

curl -X POST https://developers.grem.capital/api/v1/valuation/review/jobs/JOB_ID/confirm \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{}'

空请求体表示「全部正确」。要修正某个值，只需在 extracted 中发送修改过的字段，名称与响应中相同（嵌套对象 subject 合并一层）。随后任务进入 running，结果照常到达。

用 webhooks 代替轮询

每个异步工具都会发送 <工具>.completed 或 <工具>.failed 事件（内容包还会发送 content.partial）。订阅和签名验证：Webhooks。

  • 事件通常在任务结束后一分钟内到达。
  • 只有在创建任务时已存在对应事件的订阅，任务才会被跟踪。请提前订阅，不要在启动任务之后才订阅。
  • 如果任务 30 分钟内未完成，会收到带 reason: "timeout" 的 .failed。任务本身仍可能完成：轮询会显示其真实状态。

现成文件

文件通过 GET /artifacts/{path} 用同一个密钥下载（权限范围 tools:artifacts）。免费，支持 Range。{path} 为以下之一：

内容路径
内容包、文案或视频文件v1/ai/assistant/announcement/jobs/{jobId}/artifacts/{artifactId}/download
数字人视频v1/ai/assistant/avatar/jobs/{jobId}/artifacts/{artifactId}/download
PDF 演示文稿v1/ai/pdf-generator/files/{id}/download
优化后的照片v1/ai/photo-enhancement/jobs/{jobId}/download/{variant}
完整估价报告 PDFv1/ai/appraisal/reports/{id}/pdf
租金估算 PDFv1/ai/appraisal/rent/{id}/pdf
审核报告v1/ai/appraisal/reviews/{id}/report.pdf 或 report.docx
户型图报告v1/ai/floor-plan/jobs/{id}/report.pdf
传单文件v1/ai/flyer/file/{name}
视频配乐（试听）v1/ai/video-generator/music/{trackId}
普通文件工具响应中的 /files/... 路径

内容包文件的 ID 在任务状态的 artifacts 字段中。内容包、文案和视频文件仅对同一账户通过 API 创建的任务可用，有效期 7 天。

curl -L -o video.mp4 \
  "https://developers.grem.capital/api/v1/artifacts/v1/ai/assistant/announcement/jobs/JOB_ID/artifacts/ARTIFACT_ID/download" \
  -H "Authorization: Bearer gsk_live_xxx"

PDF 演示文稿还有一个 link 字段：文件的直接地址。

相关文章

这篇文章对您有帮助吗？