# 统一任务 API

七个空间使用同一套提交、轮询、下载流程。调用程序只需替换 Space 地址、任务密钥和请求 JSON。

## 鉴权

- 提交和轮询：`X-API-Key: <JOB_API_KEY>`。
- `HF_TOKEN` **可选**。不设置时可作为游客调用；需要使用 HF 账号身份时才发送 `Authorization: Bearer <HF_TOKEN>`。
- 下载：直接请求成功响应中的 `result_url`，只使用 URL 自带的 `token`；无需 `X-API-Key` 或 `HF_TOKEN`。
- 不要自行构造 `x-ip-token`。ZeroGPU 身份由 HF 代理在 `.hf.space` 请求上注入，游客同样由代理提供身份。GPU 配额和繁忙状态仍受 HF 限制。
- 结果链接携带下载权限，请只交给需要访问结果的人。客户端状态文件不保存账户/任务密钥，但完成后会保存结果链接。

## 三步调用

1. `POST /api/jobs`，JSON 请求体，使用 `X-API-Key`。建议设置 `Idempotency-Key`，但它不是必填项。
2. `GET status_url`，使用同一 `X-API-Key`。按 `Retry-After` 或 `poll_after_seconds` 轮询。
3. 成功后 `GET result_url`，保存响应内容。JSON、PNG、WebP、MP4 都走这一方法；按响应 `Content-Type` 识别内容。

提交成功：HTTP **202**。

```json
{"job_id":"...","status_url":"https://SPACE.hf.space/api/jobs/...","poll_after_seconds":2}
```

运行中：HTTP **202**。

```json
{"job_id":"...","status":"running"}
```

成功：HTTP **200**。

```json
{"job_id":"...","status":"succeeded","result_url":"https://SPACE.hf.space/api/jobs/.../result?token=..."}
```

失败：HTTP **500**，`status: failed` 是任务终态，不能当作临时服务器故障无限重试。

```json
{"job_id":"...","status":"failed","error":{"code":"GENERATION_FAILED"}}
```

响应可包含附加信息。旧 `image_url`、`video_url`、MOSS `result` 以及 Image Inversion 的标签字段继续保留；旧 `/image`、`/video` 下载地址继续可用。新调用统一读取 `result_url`。

## 下载与重试

`GET/HEAD /api/jobs/{job_id}/result?token=...` 支持：

- 完整下载 `200`、字节范围 `206`、越界范围 `416`。
- `Range: bytes=0-1023`、`bytes=1024-`、`bytes=-1024` 和多个范围。
- 稳定的 `ETag`、`Last-Modified`、`Accept-Ranges: bytes`、`Content-Length`。
- `If-Range`：ETag 或 Last-Modified 匹配才返回范围；不匹配返回完整结果，防止续传拼接不同版本。
- `HEAD` 返回元数据，没有响应体。

相同幂等键加相同请求会返回同一任务；相同键换参数返回 `409`。省略幂等键时，每次 POST 都是新任务。
提交断线后应复用原键；轮询和下载可直接重试。`429/503` 按 `Retry-After` 退避。
任务不存在或已过期返回 `404`；文件已丢失可返回 `410`。默认结果保留 30 分钟，容器重建也可能丢失结果；请及时保存。

## 同一个客户端

安装 `httpx` 即可，无需安装或登录 `huggingface_hub`：

```powershell
python -m pip install httpx
$env:JOB_API_KEY = "该空间的任务密钥"
# HF_TOKEN 可以不设置。
python api_client.py --url https://idlecloudx-moss-image-base.hf.space --request request.json --state job.json --output result.png
```

命令中断后原样再执行即可恢复。每个新任务使用新的 `--state` 文件。
客户端仅在明确设置 `HF_TOKEN` 时附带 HF 身份，不读取本机缓存登录。下载不会转发任务密钥或 HF 凭据。

## 空间和请求示例

下表中 `https://YOUR-ALLOWED-HOST/input.png` 应替换为符合该空间既有源图域名设置的 HTTPS 图片链接。

| 空间 | 服务地址 | 请求 JSON 示例 | 结果 |
| --- | --- | --- | --- |
| MOSS Base / SFT | `https://idlecloudx-moss-image-base.hf.space` | `{"model":"base","prompt":"A mountain at sunrise","seed":42}`，`model` 可改为 `sft` | PNG |
| Muse | `https://idlecloudx-01-krea-muse-v2-5-diffusers.hf.space` | `{"prompt":"A mountain at sunrise","width":1024,"height":1024,"seed":42}` | WebP |
| Krea Edit | `https://idlecloudx-01-krea2-edit.hf.space` | `{"source_image_url":"https://YOUR-ALLOWED-HOST/input.png","instruction":"Change the background to a garden","seed":42,"randomize_seed":false}` | WebP |
| AuraSR | `https://idlecloudx-aurasr-image-upscaling.hf.space` | `{"input_image_url":"https://YOUR-ALLOWED-HOST/input.png","scale_factor":4}` | PNG |
| Image Inversion | `https://idlecloudx-image-inversion.hf.space` | `{"input_image_url":"https://YOUR-ALLOWED-HOST/input.png"}` | JSON |
| Wan 1 | `https://idlecloudx-wan-i2v-1.hf.space` | `{"input_image_url":"https://YOUR-ALLOWED-HOST/input.png","prompt":"The camera slowly moves forward","seed":42,"randomize_seed":false}` | MP4 |
| Wan 2 | `https://idlecloudx-wan-i2v-2.hf.space` | 与 Wan 1 相同 | MP4 |

其它模型参数沿用各空间 README。接口统一不改变现有生成参数、尺寸约束和源图抓取规则。