如何用ArtCraft Omni API批量生成？batch与all_job_tokens的实战技巧
【免费下载链接】artcraftArtCraft is an intentional crafting engine for artists, designers, and filmmakers项目地址: https://gitcode.com/GitHub_Trending/ar/artcraft
ArtCraft Omni API 是 ArtCraft 面向开发者的生成接口，只需一个 API Key 就能调用与网页端 "Omni Gen" 相同的能力：图片、视频、音频一站式生成。它的杀手锏是批量生成（batch）——一次请求产出多张图或多段视频，再用响应里的all_job_tokens数组追踪每一个子任务，直到全部完成。这篇实战指南带你用最少的代码掌握这两个核心机制。
📄 完整接口文档见仓库内：_docs/artcraft_omni_api.md
1. 为什么需要批量生成？
在 ArtCraft 的模型信息里，每个模型都声明了自己的批量能力：batch_size_options（可选数量列表）、batch_size_default（默认值）、batch_size_min/batch_size_max（上下限），定义见 OmniGenApi.ts。
典型使用场景：
- 🎨同一提示词出多版：让模型一次生成 4 张不同构图的图，挑最好的一张
- 🎬多片段视频：一次生成多个镜头，后期再拼接
- 🎵多段音频：Suno 类模型一个请求会拆成多个片段任务
好消息是：你不需要在应用里手写 N 次请求，一次调用就够了。
2. 三步开启批量生成
第 1 步：配置认证与地址
- Base URL：开发环境
http://localhost:12345，生产环境https://api.storyteller.ai - 认证方式：
Authorization: Bearer artcraft_api_…（Key 以artcraft_api_开头，只在Authorization头里传，不要带 cookie）
第 2 步：带上批量参数发请求
- 图片：在请求体中设置
image_batch_count，例如4就一次生成 4 张 - 视频：设置
video_batch_count
这两个字段的后端定义见 omni_gen_image_cost_and_generate_request.rs 与 omni_gen_video_cost_and_generate_request.rs。请求前记得用成本预估接口（/cost/…）确认总消耗——批量 = 单价 × 数量，余额不足会直接返回402 Payment required。
第 3 步：记住 idempotency_token 铁律
每次请求必须携带全新的idempotency_token（UUID）。重复使用旧值会被判为重复请求直接拒绝，这是防"手滑重复扣费"的关键设计。
3. 核心技巧：读懂 all_job_tokens
批量请求的响应长这样（简化）：
{ "success": true, "inference_job_token": "jinf_abc…", "all_job_tokens": ["jinf_abc…", "jinf_def…", "jinf_ghi…"] }all_job_tokens的官方注释写得很清楚——见 omni_gen_video_generate_response.rs：
- 单任务请求：数组里只有 1 个元素，与
inference_job_token相同 - 批量请求：包含本次请求创建的所有任务，一个都不能少
⚠️ 新手最常见的坑：只轮询了inference_job_token，剩下的 3 个任务"消失"了。正确的做法是把整个all_job_tokens数组存下来，每个 token 各自轮询。ArtCraft 桌面端就是这么做的：它遍历全部 token 逐一落库并监听完成事件，代码在 dispatch.rs。前端音频模块同样把all_job_tokens视为"每个都是独立的待完成生成"，见 omni-gen-audio.ts。
4. 轮询进度：单个查 vs 批量查
任务状态接口有两个，都要求同样的Authorization头：
| 接口 | 用途 |
|---|---|
GET /v1/omni_api/job_status/job/{token} | 查单个任务 |
GET /v1/omni_api/job_status/batch?tokens=…&tokens=… | 一次查多个任务 |
批量接口的响应是{ "success": true, "job_states": […] }，每个条目结构与单任务相同，定义见 omni_api_batch_get_job_status.rs。批量任务请务必用 batch 接口，一次网络往返拿回所有进度，比 N 次单独查询高效得多。
轮询时关注两个字段：
state.status.status—— 任务状态。pending/started/attempt_failed表示仍在进行；complete_success、complete_failure、dead、cancelled_by_user、cancelled_by_system是终态，见到即可停止轮询state.status.progress_percentage—— 0~100 的进度，可以直接做成进度条
当状态为complete_success时，成品地址在state.maybe_result.media_links.cdn_url（视频是.mp4，图片是图片文件）；视频任务还附带海报帧和 GIF 预览（maybe_video_previews）。
5. 实战检查清单 ✅
- 每批请求生成新的 UUID作为
idempotency_token - 保存完整
all_job_tokens数组，而不仅是主 token - 用
batch状态接口一次性轮询所有子任务 - 先查模型的
batch_size_max上限，再设image_batch_count/video_batch_count - 批量前先调
/cost/…预估总费用，避免 402 - 对失败终态（
complete_failure等）做告警或重试提示
写在最后
掌握batch参数 +all_job_tokens+ batch 状态查询这三个点，你就解锁了 ArtCraft Omni API 的完整批量工作流：一次请求、多个结果、统一追踪。更多字段细节（如 URL 输入与 media token 输入的互斥规则）可直接查阅 _docs/artcraft_omni_api.md，配合前端 OmniGenApi.ts 中的类型定义，照着抄就不会错。
【免费下载链接】artcraftArtCraft is an intentional crafting engine for artists, designers, and filmmakers项目地址: https://gitcode.com/GitHub_Trending/ar/artcraft
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
