获取输出文件

GET /api/v1/forward/batches/{batch_id}/output 返回 output.jsonl 的 OSS 预签名下载链接。Batch 必须处于终态，否则返回 400 batch_not_ready。

请求头

Header	是否必填	说明
Authorization	是	`Bearer <PAT 或 SAT>`

路径参数

参数	类型	是否必填	说明
batch_id	string	是	Batch ID。

示例请求

curl -s -X GET 'https://api.qoder.com.cn/api/v1/forward/batches/batch_completed001/output' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

示例响应

HTTP 200 OK

{
  "url": "https://cloud-agents-storage.oss-cn-beijing.aliyuncs.com/files%2F<user_id>%2F<file_id>%2Fcontent?Expires=1783685162&OSSAccessKeyId=<ak>&Signature=<sig>&response-content-disposition=attachment%3B%20filename%3Dbatch-batch_completed001-output.jsonl",
  "expires_at": "2026-07-10T12:06:02Z"
}

响应字段

字段	类型	说明
url	string	OSS 预签名下载链接，含 `Expires` / `OSSAccessKeyId` / `Signature` 及 `response-content-disposition`，下载文件名为 `batch-<batch_id>-output.jsonl`。
expires_at	string	链接过期时间，RFC 3339，需在此之前完成下载。

output.jsonl 行格式

每个 Batch Task 对应一行：

{
  "custom_id": "task-001",
  "status": "completed",
  "session_id": "sess_abc",
  "template_id": "tmpl_abc",
  "identity_id": "idn_abc",
  "started_at": "2026-08-06T14:01:03Z",
  "completed_at": "2026-08-06T14:03:41Z",
  "response": {"body": {"text": "report generated"}},
  "error": null,
  "usage": {
    "total_credits": 2.75
  },
  "artifacts": [
    {
      "file_id": "file_abc",
      "name": "report.xlsx",
      "size": 20480,
      "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
    }
  ]
}

template_id、identity_id 始终输出；session_id 仅在 Session 已创建时输出。started_at 和 completed_at 为 RFC 3339 UTC 字符串，缺失时为 null；started_at 表示最终一次持久化执行尝试的开始时间。成功行输出 response 和 error: null；其他状态输出 response: null 和 {"code": string, "message": string}。合法 JSON 结果直接作为 response.body，普通文本包装为 {"text": ...}。 artifacts 仅在非空时出现在行顶层。每项使用 file_id、name、size，并在来源提供时增加 content_type；不提供 filename、size_bytes，也不在 response.body 中复制 artifacts。 usage 在任务已持久化合法 CAS Session 用量时出现在行顶层，当前包含 total_credits；显式零值保留，缺失或非法时省略。该值单位为 CAS Credit，不代表 token 数或货币金额。瞬时错误重试创建新 Session 时，只记录最终或当前 Session 的用量，不累加已被替换的历史 Session。

error.jsonl 行格式

失败行保留原始 body，并携带与 output 行一致的状态、Session/Template/Identity、时间、结构化错误及可选顶层 artifacts。当前 error.jsonl 不输出 usage：

{
  "custom_id": "task-002",
  "status": "failed",
  "session_id": "sess_def",
  "template_id": "tmpl_abc",
  "identity_id": "idn_abc",
  "started_at": "2026-08-06T14:01:03Z",
  "completed_at": "2026-08-06T14:01:20Z",
  "body": {"input": "generate report"},
  "response": null,
  "error": {"code": "session_error", "message": "sandbox terminated unexpectedly"}
}

字段增强只影响部署后新生成的文件，不回填历史 output/error 文件。文件资源在结构解析、后台预校验或 Session 最终校验时失败，也遵循相同格式。原始 body.resources 会被保留；如果失败发生在 Session 创建前，则省略 session_id：

{
  "custom_id": "task-file-missing",
  "status": "failed",
  "template_id": "tmpl_abc",
  "identity_id": "idn_abc",
  "started_at": null,
  "completed_at": "2026-08-29T09:20:11Z",
  "body": {
    "input": "分析报告",
    "resources": [
      {
        "type": "file",
        "file_id": "opaque-missing-id",
        "mount_path": "/data/input/report.pdf"
      }
    ]
  },
  "response": null,
  "error": {
    "code": "config_error",
    "message": "file resource is unavailable"
  }
}

资源错误 code 包括 invalid_line、config_error、permission_denied 和重试耗尽后的 transient_error。失败消息使用安全的分类描述，不返回文件所有者、上游内部状态或文件是否真实存在等元数据。

错误

HTTP	Type	Code	触发条件
400	`invalid_request_error`	`batch_not_ready`	Batch 未处于终态。
404	`not_found_error`	`batch_not_found`	Batch 不存在、跨用户访问、或 output 文件未生成。
410	`not_found_error`	`file_expired`	输出文件超过 30 天保留期已被清理。
401	`authentication_error`	`authentication_required`	PAT 或 SAT 无效或已过期。

备注

输出文件保留期为 30 天，超期后返回 410 file_expired。
下载文件名为 batch-<batch_id>-output.jsonl。
失败行结果同时出现在 output.jsonl 和 error.jsonl 中；后者通过 Batch 的 /error 端点下载。
Batch 结果文件不登记为 Forward 通用文件资源，不能通过 /api/v1/forward/files/{file_id} 或 /content 查询。

获取输出文件

请求头

路径参数

示例请求

示例响应

响应字段

output.jsonl 行格式

error.jsonl 行格式

错误

备注

相关

查询 Batch 详情

获取错误文件

​请求头

​路径参数

​示例请求

​示例响应

​响应字段

​output.jsonl 行格式

​error.jsonl 行格式

​错误

​备注

​相关

查询 Batch 详情

获取错误文件

请求头

路径参数

示例请求

示例响应

响应字段

output.jsonl 行格式

error.jsonl 行格式

错误

备注

相关