企业官网建设流程全解析

ArtCraft Omni API常见错误信息5条速查表：从bad URL到互斥输入一网打尽

【免费下载链接】artcraftArtCraft is an intentional crafting engine for artists, designers, and filmmakers项目地址: https://gitcode.com/GitHub_Trending/ar/artcraft

ArtCraft是一款面向艺术家、设计师和电影创作者的 AI 创作引擎，其Omni API让你用 API Key 直接调用 AI 视频/图像生成能力。本文是一份ArtCraft Omni API 常见错误信息速查表，精选了 5 条最高频的报错（bad URL、互斥输入、格式不匹配、401、402），帮助你快速定位问题、少走弯路。

一、先认识 ArtCraft Omni API 的调用方式

Omni API 是 ArtCraft 面向程序化调用的接口：你在Authorization头里带上 API Key（而不是 Cookie），向视频生成端点提交model、prompt、以及参考媒体 URL（图片 / 视频 / 音频），服务器会自动下载这些 URL 并启动生成任务。

完整官方文档见 _docs/artcraft_omni_api.md，接口路由实现位于 crates/api_clients/artcraft/artcraft_router/，返回的 token 数据结构定义在 crates/schema/public/tokens/。

二、5条常见错误信息速查表

三、逐条精讲：如何最快定位问题

1️⃣ bad URL：URL 必须以 http(s) 开头

所有 URL 输入（如reference_image_urls、start_frame_image_url）都必须是http://或https://开头的完整直链，否则会收到：

URL must start with http:// or https://, bad URL: <url>

两个细节容易踩坑：

• CDN/跳转链接没问题：服务器会自动跟随重定向（最多 10 次），所以带签名参数的图片直链可以放心用；
• 真正判定看"下载到的字节"：文件类型是从下载内容里嗅探出来的，不是看后缀名。

2️⃣ 互斥输入：urls 与 media_tokens 只能二选一

每个 URL 字段都有对应的 media-token 字段（如reference_image_urls↔reference_image_media_tokens），两者互斥：

• 手里只有在线链接 → 只传_urls；
• 素材已上传过、手里有m_…媒体 token → 只传_media_tokens；
• 两边都传 → 直接报 "must be set, not both"。

记住一个原则：同一类素材，只走一条输入通道。

3️⃣ 格式不匹配：400 "不允许的类型"

服务器下载文件后按真实字节判定类型，常见要求如下：

典型翻车姿势：把.webm视频当参考视频传进去，就会收到 400 并说明该类型不被允许。测试仓库里就有各种合法素材可以参考：test_data/image/juno.jpg、test_data/video/mp4/。

4️⃣ 401 Unauthorized：身份没通过

三种可能，按概率排查：

1. 没带 Key 或格式错——推荐写法Authorization: Bearer artcraft_api_xxx…（Key 共 53 位，前缀artcraft_api_）；
2. Key 打错/复制不完整——密钥只在创建时显示一次，丢了只能重建；
3. 账号被封禁——需要联系 ArtCraft 团队处理。

⚠️ 顺带提醒：Omni API 只认 API Key，发 Cookie 也没用，会被直接忽略。

5️⃣ 402 Payment required：积分不足

这不是 bug，而是账单信号：账户积分/余额不够扣本次生成的费用。去账户后台充值后即可重试。排查其他问题前，先确认余额，能省掉一轮无效调试。

四、附赠：2 个高频"隐形坑" 🕳️

• idempotency_token必须每次都是全新 UUID：复用旧 token 会被当作重复请求拒绝。批量生成时尤其注意，每个请求都要现场生成一个新 UUID；
• 生产地址别记错：线上 API 域名是api.storyteller.ai，开发环境才是http://localhost:12345，地址写错会收到奇怪的连接错误。

五、小结

把这 5 条速查表贴在你的调试脚本旁边，ArtCraft Omni API 的报错基本就不再神秘了。祝生成顺利！🎬

【免费下载链接】artcraftArtCraft is an intentional crafting engine for artists, designers, and filmmakers项目地址: https://gitcode.com/GitHub_Trending/ar/artcraft