Atlas Cloud 连接器使用指南
Atlas Cloud 连接器通过一个统一接口提供三百多个生成模型（图像、视频、语音、音乐、转写）。 用户通过账号授权连接，生成费用记在用户自己的 Atlas 账户上。
工具一览
| 工具 | 用途 | 是否计费 |
|---|---|---|
atlas_list_models | 按类型列出模型 | 否 |
atlas_search_docs | 按关键词搜模型和文档 | 否 |
atlas_get_model_info | 查单个模型的参数 schema、枚举值、默认值、定价 | 否 |
atlas_get_model_costs | 生成前估算这一次的费用 | 否 |
atlas_get_upload_url | 换上传票据，把本地文件变成公网 URL | 否 |
atlas_generate_image / atlas_generate_video / atlas_generate_audio | 提交生成任务 | 是 |
atlas_transcribe_audio | 音频转文字 | 是 |
atlas_quick_generate | 一步出结果，适合简单单张图 | 是 |
atlas_get_prediction | 查询异步任务状态和结果 | 否 |
atlas_list_predictions | 列最近的任务，找回丢失的任务 ID | 否 |
atlas_get_balance / atlas_get_model_usage | 查余额和用量 | 否 |
所有操作都走这些工具。不要用 curl 直接调 Atlas 的 REST API：这里是账号授权连接， 环境里没有 API Key，直接调只会 401。唯一的例外是上传（见下文）。
1. 模型和参数一律现查
模型目录经常变。每次生成前：
- 用
atlas_search_docs或atlas_list_models找候选模型 - 用
atlas_get_model_info取该模型的参数 schema、枚举值、默认值和定价 - 严格按 schema 构造参数
不要凭记忆写模型 ID 或参数名。常见错误：模型要 ratio 却传了 aspect_ratio，
要 image 却传了 image_url。schema 里没有的参数就是不存在。
2. 提交前报价
提交计费任务前，用 atlas_get_model_costs 估算费用并告诉用户。
能力相当的模型价差可能很大（视频每秒单价能差三倍以上），先比价再推荐。
3. 幂等键与服务端确认
五个计费工具都要求 idempotency_key（一个 UUID）：
- 每次新的生成都换一个新的 key；只有重试完全相同的请求才复用旧 key。
调用后可能拿到的不是任务 ID，而是一份报价和一个 confirmation_token。
这表示服务端没有提交、没有扣费，在等用户确认。这不是失败：
- 把报价原样告诉用户，停下等回复。
- 用户明确同意后，用同一个
idempotency_key、一字未改的参数、加上confirmation_token再调一次。 - 换了 key 或改了参数，令牌就失效，会再被拦一次。不要反复换 key 重试。
视频任务按秒计费，服务端算不出精确价时一律转确认，金额再小也一样。
4. 轮询与结果
提交成功后拿到 prediction ID，用 atlas_get_prediction 轮询。
- 返回成功状态之前，不要说任务完成，也不要给出任何产物链接。
failed是终点，再轮询也不会变。把error原文告诉用户，建议换一个能力相当的模型或原样重提。No available upstream channel/Upstream access denied是上游路由问题，换模型能绕开。- 提交时的金额是预估；失败的任务不计费。确认成功之前说"预计 $X"，不要说"已扣费"。
- 找不到之前的任务 ID 时，用
atlas_list_predictions找回。
5. 上传本地文件
远程服务读不到用户本机的文件，本地路径直接填进生成参数一定失败。
-
调
atlas_get_upload_url，拿到upload_url、expires_at、max_bytes和curl_example。 -
按
curl_example把文件 POST 上去，文件名（带扩展名）放在X-Atlas-Filename头里：bashcurl -sS -X POST "<upload_url>" \ -H "Content-Type: application/octet-stream" \ -H "X-Atlas-Filename: product.jpg" \ --data-binary @"/path/to/product.jpg" -
响应里的
url就是公网地址，填进image_url或音频参数。
- 票据已带身份，这条 curl 不需要任何 key。
- 一个
upload_url在有效期内（约 10 分钟）可传多个文件。上传不计费。 - 超过
max_bytes（默认 32MB）会被拒，请用户提供公网链接。 - curl 失败或响应里没有
url，如实说没传上去，不要写成"已上传"。
6. 交付
- 远端 URL 原样复制，不要编造、拼接或改写。
- 图片用
，视频音频用带说明的链接，让界面有机会渲染预览。 - 同时注明完整模型 ID（如
bytedance/seedream-v5.0-lite）和费用。 - 需要把产物存到本地时，下载失败（502、超时、空文件）要如实说，并给出远端链接。 产出文件存在海外对象存储，国内网络直连有时不通，换网络或代理通常能解决。
7. 授权与失败
- 看不到
atlas_*工具，只说明它们还没载入，不说明授权有问题。只有真正调用失败才能判定不可用。 - 调用失败时如实转述错误原文，不要模拟结果，不要换别的通道顶替。
- 不要替用户生成涉及真实人物肖像、他人版权角色或违规内容的素材。
