任务与结果文件

语音识别、语音合成和图片生成使用异步任务（Job）。提交后返回一个任务记录（Operation），你可以通过它的 ID 查询进度，完成后下载结果文件（Artifact）。各模型页已提供完整示例，本页用于查阅共同规则。

1. 提交任务

POST https://api.wildflow.cn/v1/jobs
Authorization: Bearer WILDFLOW_API_KEY
Idempotency-Key: 每次业务请求稳定且唯一的值
Content-Type: application/json

请求正文的公共结构是：

{
  "model": "公开模型名",
  "input_artifact_ids": ["需要预先上传输入的模型才使用"],
  "parameters": {
    "模型参数": "值"
  }
}

parameters 不能省略；input_artifact_ids 只用于需要预先上传输入的模型。具体字段由模型页面定义：双引擎语音识别、VoxCPM2、 IndexTTS-2.5 或 FLUX.2。首次接收成功返回 HTTP 202，响应头 Location 指向 /v1/jobs/{operation_id}。

2. 幂等与恢复

每个真实业务动作生成一个稳定且唯一的 Idempotency-Key：

相同 API Key、幂等键和请求正文会恢复原 Operation，不会创建第二个任务；
同一幂等键配合不同请求会返回 409 idempotency_conflict；
网络中断或轮询超时后，继续使用原请求和原幂等键；
不要通过更换幂等键盲目补发同一付费任务。

3. 查询状态

读取创建响应中的 Location，继续使用创建任务时的 API Key：

curl --fail-with-body \
  -H "Authorization: Bearer $WILDFLOW_API_KEY" \
  https://api.wildflow.cn/v1/jobs/{operation_id}

排队或执行期间按响应中的 Retry-After 等待后再查询。state 变为 succeeded 后，响应中的 artifacts[] 会提供 Artifact ID、媒体类型、文件大小、SHA-256 和下载路径。

4. 下载产物

curl --fail-with-body \
  -H "Authorization: Bearer $WILDFLOW_API_KEY" \
  https://api.wildflow.cn/v1/artifacts/{artifact_id}/content \
  --output result.bin

文件扩展名应根据响应中的 media_type 决定，例如 VoxCPM2 当前为 audio/mpeg，IndexTTS-2.5 当前为 audio/wav，FLUX.2 当前为 image/png。下载后可核对 size_bytes 和 sha256；不要把提交响应当作最终结果文件；ASR 的最终结果为 JSON，音频和图片使用各自的媒体格式。

5. 错误与重试

状态或错误	处理方式
`400 invalid_request`	检查模型名、`parameters` 层级和模型参数
`401` / `403`	检查 API Key、额度和允许的模型范围
`409 idempotency_conflict`	使用原请求恢复，或为真正的新业务动作创建新键
`429` / `503`	错误允许重试时按 `Retry-After` 等待；创建任务仍保留原请求和幂等键
`recovery_required`	停止自动补发，保留 Operation ID 并联系平台恢复

6. 当前限制与反馈

queued 和 running 都是正常中间状态；同一模型与不同模型的任务都可能同时排队或执行；
只有 succeeded 后才下载 Artifact；提交响应不是媒体文件；
当前可调用的首方 Job 模型包括 wildflow/dual-asr-v1、VoxCPM2、IndexTTS-2.5 和 FLUX.2 [klein] 4B； IndexTTS-2.5 当前为团队内部使用，只有在鉴权目录 /v1/models 中可见时才提交；
ASR 使用普通 API Key 并正常计费；模型广场为 callable=false 时不要提交；
recovery_required 表示副作用需要平台处理，调用方不得自动换幂等键重试。

任何情况下都不要在日志、前端代码、反馈消息或截图中记录完整 API Key。需要人工协助时，通过管理员微信 zxdwhda_01 提供请求时间、模型名、Operation ID、HTTP 状态码和脱敏后的错误信息。