# 任务查询与结算

> 提交响应、任务状态、结果地址与人民币结算字段。

Base URL：`https://platform.sgt.site`

| 方法 | 路径 |
| --- | --- |
| GET | `/apimart/v1/tasks/{task_id}` |

<a id="apimart-tasks-section-1"></a>

## 提交响应

图片和视频的提交成功都返回 HTTP 200：

```json
{
  "code": 200,
  "task_id": "task_example",
  "data": [
    {
      "status": "submitted",
      "task_id": "task_example"
    }
  ]
}
```

`data[0].task_id` 是 APIMart 提交契约；顶层 task_id 是同值的平台兼容扩展。此时尚不能读取生成产物的 URL，也不能认定已经生成成功。

查询：

```http
GET /apimart/v1/tasks/task_example HTTP/1.1
Authorization: Bearer YOUR_VIRTUAL_KEY
```

排队中示例：

```json
{
  "code": 200,
  "data": {
    "id": "task_example",
    "status": "pending",
    "progress": 0,
    "created": 1790553600,
    "cost": null,
    "credits_cost": null,
    "currency": "CNY",
    "credit_unit_cny": 0.01
  }
}
```

图片成功、结算处理中示例：

```json
{
  "code": 200,
  "data": {
    "id": "task_example",
    "status": "completed",
    "progress": 100,
    "created": 1790553600,
    "completed": 1790553630,
    "actual_time": 30,
    "result": {
      "images": [
        {
          "url": [
            "https://platform.sgt.site/apimart/v1/tasks/task_example/artifacts/0?expires=1790640030&sig=example"
          ]
        }
      ]
    },
    "billing_status": "pending",
    "cost": null,
    "credits_cost": null,
    "currency": "CNY",
    "credit_unit_cny": 0.01
  }
}
```

视频成功时的 result：

```json
{
  "videos": [
    {
      "url": [
        "https://media.example.com/generated-video.mp4?Expires=1790640000&Signature=example"
      ]
    }
  ]
}
```

上面最后一段仅是 result 对象，不是整个查询响应。多个输出会有多个条目，按上游产物顺序排列；URL 本身仍是数组。请直接使用返回的 URL，不要根据图片或视频列表的位置重新拼装地址。

图片和视频的 url 使用同一规则，有效期内均可直接读取，不需要 `Authorization`、Cookie、平台虚拟密钥或 Provider 凭据。可直接下载、放入 img/video 元素，或作为支持该格式模型的参考素材 URL。客户端统一按“提交 → 查询 → 使用返回的 URL”处理，不区分图片和视频，也不需要额外的换链接口。url 有两种：

- **上游产物链接**：上游签发、可公网读取的原始地址，原样保留签名参数。
- **签名下载地址**：`/apimart/v1/tasks/{task_id}/artifacts/{index}?expires=…&sig=…`，由平台签发并读取产物。以下情况返回这种地址：上游只返回内联字节；产物需要 Provider 凭据才能读取；链接不是 HTTPS；链接位于渠道 API 主机；链接带用户信息或 `key` 查询参数。签名限定到该任务的该产物，修改任何参数都会失效，下载说明见 [结果下载](apimart-content.md)。

读取任一种 url 时都不要附带 `Authorization` 或平台虚拟密钥。

上游产物链接的有效期、下载次数和可访问性由上游决定。平台不返回 `expires_at`，也不自动刷新过期链接。Seedance 链接 24 小时内有效，Seedance 2.5 最多下载 100 次；MiniMax H3 为限时链接；可灵产物 30 天后清理。签名下载地址默认 24 小时内有效，到期时间见 URL 的 `expires`（Unix 秒）；每次查询都会重新签发，两次查询得到的 URL 虽然不同，但都指向同一产物。签名下载地址同样不会延长上游产物的可用期，请在任务完成后尽快转存。

两种 url 发出后，撤销虚拟密钥、模型或渠道权限都无法收回已发出的地址，只会阻止再次查询和签发；任务查询本身仍按当前权限校验。任务被删除或退款后，签名下载地址不再可读。

任务已成功但平台找不到任何可读取的产物证据时，查询返回 HTTP 502 `task output unavailable`，不返回空地址或输入素材地址。不要因此重新提交生成，请向平台管理员提供 task_id 排查处理。

<a id="apimart-tasks-section-2"></a>

## 5.1 状态与字段

| 字段 | 类型 | 含义 |
| --- | --- | --- |
| `data.id` | string | 平台任务 ID |
| `data.status` | string | pending / processing / completed / failed / cancelled |
| `data.progress` | integer | 0–100；不是剩余时间预测 |
| `data.created` | integer | Unix 秒 |
| `data.completed` | integer | 成功时的完成时间，Unix 秒 |
| `data.actual_time` | integer | 成功时从提交到结束的秒数，不是视频媒体时长 |
| `data.result` | object | 成功时出现，含 images/videos；每个 url 为上游产物链接或签名下载地址，均无需额外鉴权即可读取 |
| `data.error` | object | failed 时出现 |
| `data.reconciliation_required` | boolean | 为 true 表示提交结果待平台确认，不要自动重新生成 |
| `data.billing_status` | string | 有结算状态时为 pending 或 settled；非终态可能省略 |
| `data.cost` | number / null | 最终人民币金额；未确认时为 null |
| `data.credits_cost` | number / null | 平台换算积分，cost×100 |
| `data.currency` | string | 固定 CNY |
| `data.credit_unit_cny` | number | 固定 0.01 |

任务失败时查询请求仍可能返回 HTTP 200，必须检查 data.status。典型任务错误：

```json
{
  "code": 502,
  "type": "generation_failed",
  "message": "Invalid image aspect ratio",
  "provider_code": "task_failed"
}
```

此处展示 `data.error` 的结构，与 HTTP 请求失败时的顶层 error 不同。`message` 是平台受控的失败提示，不转发模型服务原文：宽高比、尺寸或分辨率、内容审核、时长、媒体格式、输入参数各有固定英文提示，无法识别时统一为 `Task failed`。`provider_code` 只公开允许的错误码，如 `invalid_parameter`、`content_policy_violation` 或模型服务的数字错误码，其余统一为 `task_failed`。需要定位原始原因时，可向平台管理员提供 task_id。

<a id="apimart-tasks-section-3"></a>

## 5.2 结算规则

- 生成提交和最终结算分开。预算预留不是最终消费。
- processing 或未结算时 cost/credits_cost 为 null；0 才表示已经确认的零费用。
- completed 且 billing_status=pending 时可读取结果，最终费用仍需等待 settled。
- 已确认失败并完成释放时，最终费用为 0。
- 部分出图按实际确认的输出数量结算，不以请求的 n 代替实际出图数。
- 重复发起 GET 查询或下载不会触发重新生成，不产生新的模型生成费用；接口限流仍然生效。上游产物链接由调用方直接从上游读取，不经过平台，但计入上游的下载次数限制。签名下载地址每次读取都由平台向上游取回产物，同样计入上游的下载次数限制。
- 生成成功、下载可用与归档完成是不同事实。
- 原生取消完成后可能显示 cancelled；原生删除完成后查询返回 404。本协议本身没有取消或删除路由。
- cost 为 mote 的人民币权威费用，不是 APIMart 官方美元价格或官方账户积分。