API.md

统一任务 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。

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

运行中：HTTP 202。

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

成功：HTTP 200。

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

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

{"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：

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。接口统一不改变现有生成参数、尺寸约束和源图抓取规则。