> For AI agents: the complete documentation index is available at https://docs.reelway.ai/llms.txt, the full documentation bundle is available at https://docs.reelway.ai/llms-full.txt.

# 项目状态 API

WebSocket 通道实时推送进度,但在无长连接的场景(函数计算、定时对账、进程重启后恢复)你需要用 REST 读取项目状态。本页的端点都以**账户凭证**鉴权,只返回凭证所有者的项目。

## 实时投影:`GET /v2/projects/{id}`


GEThttps://rcn.reelway.ai/v2/projects/{id}鉴权:凭证

所有者实时状态投影,处理中与完成后均可读


```bash
curl --fail-with-body https://rcn.reelway.ai/v2/projects/0b0f6c0e-7d4b-4d3c-9c6f-0c7a7e3f2a11 \
  -H "api-key: $REELWAY_API_KEY"
```

### 响应

```json
{
  "status": "success",
  "data": {
    "id": "0b0f6c0e-7d4b-4d3c-9c6f-0c7a7e3f2a11",
    "status": "processing",
    "finished": false,
    "workerJobs": [
      { "imgID": "6f1c…", "status": "jobStarted", "performedSteps": 2 }
    ],
    "completedWorkerJobs": [
      {
        "imgID": "a93d…",
        "status": "jobCompleted",
        "performedSteps": 4,
        "worker": { "name": "node-5090-01" },
        "seedUsed": 20251102,
        "NSFW": false
      }
    ],
    "jobCountCompletedByState": { "jobCompleted": 1, "jobError": 0 }
  }
}
```

| 字段                         | 说明                                                                |
| -------------------------- | ----------------------------------------------------------------- |
| `status` / `finished`      | 项目级状态与是否终态                                                        |
| `workerJobs[]`             | 在途作业:`imgID`、当前 `status`、已执行步数                                    |
| `completedWorkerJobs[]`    | 已终态作业:`status` 为 `jobCompleted` 或 `jobError`;含执行节点名、实际种子与 NSFW 标记 |
| `jobCountCompletedByState` | 按终态聚合计数                                                           |

产物下载 URL 不在投影中:凭 `imgID` 调用 `GET /v1/image/downloadUrl` 或 `GET /v1/media/downloadUrl`(见[媒体与图像 URL](https://docs.reelway.ai/api-reference/media.md))。

## 完成后读取:`GET /v1/projects/{id}`


GEThttps://rcn.reelway.ai/v1/projects/{id}鉴权:凭证

仅完成后可读;处理中返回 404


与 `/v2` 同形,但沿用 Sogni v1 口径:**项目处理中返回 `404`**,只有完成后才返回 `200`。SDK 用这一差异区分「尚未完成」与「不存在」。新集成请直接使用 `/v2`。

### 从 v1 迁移

把 `GET /v1/projects/{id}` 替换为 `GET /v2/projects/{id}`,并把「`404` 等于处理中」的逻辑改为读取 `data.finished`。

## 历史列表:`GET /v1/jobs/list`


GEThttps://rcn.reelway.ai/v1/jobs/list鉴权:凭证

近 7 天任务历史,分页


| 查询参数        | 说明             |
| ----------- | -------------- |
| `limit`     | 1–100,默认 50    |
| `since`     | 毫秒时间戳,只返回其后的任务 |
| `state`     | 按状态过滤          |
| `mediaOnly` | 仅返回有媒体产物的任务    |

响应 `data.jobs[]`、`data.offset`、`data.limit`。历史窗口为 **7 天**;更久的记录请在完成时自行归档。

## 恢复快照:`GET /api/v1/artist/projects/sync`


GEThttps://rcn.reelway.ai/api/v1/artist/projects/sync鉴权:凭证

进程重启后的恢复快照


返回 `activeProjects`(仍在途)与 `unclaimedCompletedProjects`(已完成但客户端尚未确认领取)。SDK 在重连后自动调用;自实现客户端在重启后调用一次,即可继续追踪在途项目并领取遗漏的结果。

## 轮询与 HTTP 错误

- 推荐轮询间隔 2–5 秒;终态(`finished: true`)后停止。
- `404`:`/v2` 下表示项目不存在或不属于该凭证;`/v1` 下还可能表示处理中。
- `401`(`101`):凭证无效。
- `429`:按 `Retry-After` 退避。

## 保留与兼容

- 投影在项目完成后持续可读;产物签名 URL 有效期 48 小时,需长期保存请转存。
- `/v1` 与 `/v2` 响应形状保持 Sogni 兼容,`@sogni-ai/sogni-client` 的既有解析逻辑可直接复用。