任务处理查询

接口标识: taskresult 价格: 0 元/次 VIP免费同步响应

接口介绍
接口文档
在线测试

接口简介

任务处理查询接口是平台全部任务类接口的配套查询入口：传入提交任务时返回的task_id，或开发者自定义的请求编号serialnumber（二选一），即可查询任意任务的执行状态，状态分为未开始、处理中、已完成、失败四种。任务完成后一次返回文本结果、产物文件地址、明细数据与耗时秒数，同时回显原调用接口标识和任务说明信息。适合业务系统跟踪文档转换、AI生成等任务的处理进度并统一收取结果。【调用约定】任务类接口返回 task_id 后调用本接口查询：output_status 为 not 或 processing 表示未完成，请每隔5-10秒重复查询，直到 finish 或 fail 后再向用户展示结果。

详细介绍

![任务处理查询接口封面](https://fujian.phpwc.com/pyapi/uploads/site/20261109/apiops_taskresult__1794166712_085bb97ce617.png)

任务类接口都是「先受理、后处理」，结果从哪里取？本接口就是平台所有异步任务的统一「取件窗口」——传入任务号或自定义编号，即可查询状态、取回结果下载地址。

## 接口概述

任务处理查询接口是平台所有任务类（异步）接口的统一配套查询端点：文档转换、图像处理与各类 AI 任务提交后立即返回 task_id，实际产物均经本接口获取。传入提交时返回的 task_id，或开发者自定义的 serialnumber（二选一），即可查询任务当前状态（未开始/处理中/完成/失败）；任务完成时一并返回产物下载地址 output_dourl、文本结果 output_content、明细数据 output_info 与耗时 output_time，jk_mark 字段回显任务的来源接口。建议以 2~3 秒间隔轮询，output_status 到达 finish 或 fail 终态后停止；终态结果不再变化，可放心落库。

## 核心能力

1. **统一查询**：一个接口覆盖平台全部异步任务类接口，无需逐接口编写查询逻辑。
2. **双凭证查询**：task_id 或自定义 serialnumber 二选一，自由选择关联方式。
3. **状态齐全**：not（未开始）、processing（处理中）、finish（完成）、fail（失败）四态返回。
4. **结果完备**：完成时同时返回产物下载地址、文本内容、明细数据与任务耗时。
5. **来源回显**：jk_mark 字段标明任务的来源接口，多类任务混合轮询时可直接分流。

## 产品优势

- **接入简单**：POST 请求、JSON 返回，所有任务类接口查询逻辑一致，一次集成处处通用。
- **响应迅速**：查询为只读轻量操作，已完成任务的结果经服务端缓存加速，可支撑高频轮询。
- **降本增效**：与提交接口构成完整异步闭环，无需自建任务状态存储设施，output_* 字段结构在全部任务类接口间统一、解析逻辑可复用。

## 效果展示

一句话理解：它就像用运单号查「快递进度」——任务到哪一步了看一眼便知，完成后直接拿到取件码（下载地址）。

以一次真实调用为例，你要传的参数：

| 参数 | 本次示例值 | 说明 |
|------|-----------|------|
| task_id | ac812304976543210987 | 任务类接口返回的任务ID，与 serialnumber 二选一 |
| serialnumber | order-20261107-001 | 提交时传入的自定义编号，与 task_id 二选一；两者同传时以 task_id 为准 |

你会拿到的结果（以 PDF转文档 任务完成为例）：

| 返回内容 | 本次示例值 | 对应字段 |
|---------|-----------|---------|
| 任务状态 | finish | `output_status`，finish=已完成 |
| 产物下载地址 | https://fujian.phpwc.com/pyapi/uploads/api/20261107/contract.docx | `output_dourl`，临时地址请及时下载；产物转存失败的任务不会进入完成态（`task_status` 不会变成 finish） |
| 任务明细 | 文件名 contract.docx、大小 356211 字节 | `output_info`，明细字段随原接口不同 |
| 任务提示 | PDF转文档任务完成，output_dourl 为临时下载地址… | `output_msg` |
| 任务耗时 | 6 | `output_time`，单位秒 |
| 来源接口 | pdf2word | `jk_mark`，任务的原提交接口 |

API请求示例：

```
POST /api/v1/taskresult
task_id=ac812304976543210987&serialnumber=order-20261107-001
```

API响应示例：

```json
{
  "code": 0,
  "desc": "成功",
  "data": {
    "task_id": "ac812304976543210987",
    "serialnumber": "order-20261107-001",
    "jk_mark": "pdf2word",
    "output_status": "finish",
    "output_content": "https://fujian.phpwc.com/pyapi/uploads/api/20261107/contract.docx",
    "output_dourl": "https://fujian.phpwc.com/pyapi/uploads/api/20261107/contract.docx",
    "output_info": {
      "file_name": "contract.docx",
      "file_size": 356211
    },
    "output_msg": "PDF转文档任务完成，output_dourl 为临时下载地址，请尽快下载。",
    "output_time": 6
  }
}
```

处理中时 output_status 为 not 或 processing，产物字段为空串。多页图片类任务的 output_content 为各页地址合集、output_dourl 为 zip 包地址；产物地址为临时地址，请及时下载。

## 应用场景

- **文档转换取件**：PDF转文档、文档转图片等接口的产物统一在此获取
- **AI 任务取件**：图像识别、内容生成等 AI 处理任务的结果查询
- **流程编排**：工作流引擎轮询任务状态，完成后自动推进下一环节
- **前端进度条**：网页、小程序定时查询，向用户展示实时进度
- **对账核销**：以 serialnumber 关联业务单号，批量核对完成情况

## 应用案例

- **办公 SaaS 产品**：用户上传文档发起转换后，前端每 2 秒轮询本接口，进度条随 output_status 实时推进，完成后下载按钮自动点亮，无需刷新页面。
- **批量处理服务**：运营方以自定义 serialnumber 关联内部订单与任务，定时脚本批量查询对账，完成的产物自动下载入库，失败任务自动重新提交。

常见问题

Q：这个接口能做什么？

A：查询平台异步任务的执行状态与结果。传入 task_id 或 serialnumber（二选一），返回任务状态；已完成的任务同时返回产物下载地址（output_dourl）、文本结果（output_content）、明细数据（output_info）与耗时（output_time）。

Q：需要配合哪些接口使用？

A：所有提交后返回 task_id 的任务类接口，如 PDF转文档（pdf2word）、文档转图片（doc2image）及各类 AI 处理任务；响应中的 jk_mark 字段回显任务的来源接口。

Q：如何判断任务已完成？

A：看 output_status：not=未开始、processing=处理中、finish=完成、fail=失败。建议以 2~3 秒间隔轮询，到达 finish 或 fail 终态后停止查询，终态结果不再变化。

Q：任务不存在会怎样？

A：传入错误的 task_id 或 serialnumber 时，返回「任务不存在，请检查 task_id 或 serialnumber 是否正确」的参数错误提示；两个参数都不传会提示二选一。

Q：结果下载地址一直有效吗？

A：output_dourl 为临时下载地址，任务完成后请及时下载转存，过期后文件地址可能被清理。

任务查询异步任务结果获取任务状态 taskresult 文档转换

接口地址： https://www.phpwc.cn/api/taskresult

请求方式： POST

业务请求参数

参数名	类型	必填	默认值	说明
`task_id`	string	条件	-	任务ID（与 serialnumber 二选一查询）
`serialnumber`	string	条件	-	开发者自定义的请求编号（与 task_id 二选一查询）

查看签名算法查看调用示例

响应参数

字段名	类型	说明
`code`	int	状态码，0=成功
`desc`	string	状态描述
`data`−	object	业务数据（成功时返回）
`task_id`	string	任务ID
`serialnumber`	string	开发者自定义的请求编号
`jk_mark`	string	原调用接口标识
`output_status`	string	任务状态: not(未开始)、processing(处理中)、finish(已完成)、fail(失败)
`output_content`	string	任务完成后返回的内容
`output_dourl`	string	任务完成后返回的文件/附件下载地址
`output_info`	object	任务完成后的明细数据
`output_msg`	string	任务说明信息
`output_time`	int	任务耗时（秒）
`request_id`	string	请求追踪ID

JSON 示例：

调用成功：

{
  "code": 0,
  "desc": "success",
  "data": { ... },
  "request_id": "abc123..."
}

调用失败：

{
  "code": 999,
  "desc": "错误描述",
  "request_id": "abc123..."
}

请先登录后使用在线测试