批量 AI 生成 API：安全提交、轮询与验收任务

批量生成客户端应是带记录的队列，而不是一次性发出所有提示词的循环。每个条目需要稳定的本地 ID、所选 model_id、校验后的 input 对象、提交状态、task_uuid、时间戳、终态、输出和错误详情。NamiFusion Marketplace REST API 通过 POST /api/v1/marketplace/run/{model_id} 提交单个模型任务，响应包含 task_uuid 和 status；客户端随后读取 GET /api/v1/marketplace/run/tasks/{task_uuid}，直到 completed、failed 或 cancelled。这种异步结构允许工作进程中断后恢复，也避免长时间生成占住同一个请求。

发现接口契约并准备输入

在 API Keys 页面创建密钥并放在源码管理之外。批处理前先调用 GET /api/v1/marketplace/models 查找活跃模型，再调用 GET /api/v1/marketplace/models/detail?model_id={model_id} 读取该模型当前参数，并据此构建请求。必填字段必须提供；可选字段仅在明确设置或模型提供适用默认值时加入。不要假定不同模型的 prompt、尺寸、seed 或媒体字段相同。媒体输入应采用实时参数声明的格式：通常是可访问 URL；只有参数明确支持自动上传 base64 时才可提交 base64。

花费积分前先规范化批次：拒绝重复本地 ID、空的必填提示词、不受支持的 URL，以及模型与校验 schema 不一致的行。保存规范化请求摘要，便于操作者识别意外重复。混合模型输入应拆为各模型独立队列，因为校验、预期时长、成本和并发策略可能不同。每个模型先运行一个金丝雀条目，检查输出契约后再放行余下队列。

正确提交并轮询单个任务

请求体把模型字段包在 input 中。请用实时模型详情里的值替换 MODEL_ID 和示例字段。成功提交会返回含 task_uuid 的 JSON，第一时间持久化它。轮询任务路由而不是模型路由，只有 completed、failed 或 cancelled 才停止。completed 时读取 output，但不要假定永远只有一个 URL，应按当前响应结构校验；failed 或 cancelled 时保存完整终态以供诊断。认证可使用 Authorization: Bearer YOUR_API_KEY 或 X-API-Key。真实密钥绝不能进入代码、日志、截图或客户端 JavaScript。

# 1) Submit — returns { "task_uuid": "...", "status": ... }
curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/MODEL_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"prompt":"A precise, model-compatible prompt"}}'

# 2) Poll until status is completed, failed, or cancelled
curl "https://www.namifusion.com/api/v1/marketplace/run/tasks/TASK_UUID" \
  -H "Authorization: Bearer YOUR_API_KEY"

把单任务扩展为有边界批处理

1. 先读取并校验全部行，不提交。
2. 发送一个金丝雀任务并验证终态输出。
3. 使用小型 worker 池，不要每行启动一个 worker。
4. 每个待处理行先持久化“submitting”，发送后保存 task_uuid 与“submitted”。发送后的网络失败具有歧义，应先查本地记录与任务列表再决定是否重提。
5. 以适中间隔和随机抖动轮询活跃 UUID。
6. 遇到 429 按服务端建议等待，临时 5xx 使用退避。
7. 终态任务停止轮询。
8. 验证输出，并把内容审核状态与 API 状态分开记录。
9. 导出清单，映射本地 ID、模型、请求摘要、task_uuid、状态、输出和审核结果。
10. 进程重启后只恢复未完成行。

验收输出并诊断失败

API 成功只表示服务商完成了任务，不代表媒体符合简报。先确认所有预期输出存在且可访问，再检查文件类型、尺寸或时长、损坏情况和任务专属规则。图片检查解剖、文字、身份与构图；视频检查开场保真、时间扭曲、音频与尾帧。只有分类原因后才重试：参数无效应修 schema 或输入；内容缺陷应改提示词、参考、模型或设置；临时服务故障可延迟重试。失败任务不能反复重提，技术完成但审核不通过的结果应作为一次有来源记录的新修订。

限流、成本与运行边界

Marketplace 任务会预先消耗积分。模型价格、参数计费、服务时长、超时与输出格式都不同，因此放行批次前应获取当前模型详情并向操作者显示批次预估总额。API key 请求使用账户级每分钟请求桶，还可能叠加显式配置的 rate_limit_per_minute。指南或客户端不应写死通用并发数；应允许配置，出现 429 时降低，并遵循服务端提示。调度器应设置最大尝试次数、自有的批次最高支出与停止开关。对账完成前保留原始任务记录。模型超时很长时，应保留 task_uuid 稍后继续，而不是把客户端截止时间当成失败证据。