Atlas 云媒体

atlas-cloud-media
分类编程
作者Agentic Awesome Skills 社区
许可MIT
评分4.40/5
使用3.6K

Atlas Cloud Media

概述

使用 Atlas Cloud 的异步媒体 API 来生成图像或视频。此纯源码技能描述了模型发现、Schema 验证、任务提交、有界轮询和安全的输出检索；它不包含 SDK、可执行文件或托管运行时。

何时使用此技能

  • 当用户明确要求使用 Atlas Cloud 生成图像或视频时。
  • 当现有工作流需要发送 Atlas Cloud 图像或视频生成请求且能够发起 HTTPS 调用时。
  • 当在提交前必须发现特定模型的参数时。
  • 不要将此技能用于 OpenAI 兼容的文本聊天；该 API 具有不同的基础 URL 和契约。

前置条件

1. 确认用户已授权将提示词及任何参考媒体发送至第三方服务。
2. 说明生成服务是付费的，并在提交计费请求前获得批准。
3. 要求环境中必须存在 ATLASCLOUD_API_KEY。切勿要求用户将其粘贴到聊天、源文件、命令历史或日志中。
4. 确认输出目录以及用户需要图像生成、视频生成还是两者都需要。

API 契约

| 操作 | 方法与端点 |
| --- | --- |
| 列出模型 | GET https://api.atlascloud.ai/api/v1/models |
| 生成图像 | POST https://api.atlascloud.ai/api/v1/model/generateImage |
| 生成视频 | POST https://api.atlascloud.ai/api/v1/model/generateVideo |
| 轮询任务 | GET https://api.atlascloud.ai/api/v1/model/prediction/{id} |

生成和轮询请求使用以下请求头：

text
Authorization: Bearer $ATLASCLOUD_API_KEY
Content-Type: application/json

模型目录是公开的。每个目录条目包含一个 schema URL；在发送付费请求前，请获取该 Schema 并据此验证参数。不要猜测其他模型的参数，因为 size、ratio、aspect_ratio、image 和 image_url 等名称因模型而异。

工作流

1. 发现并验证模型

获取目录，按 type（Image 或 Video）过滤，并匹配用户请求的功能。读取所选条目的 schema，验证所有必填字段是否存在，并在提交前向用户展示模型和计费操作。

发现请求示例：

bash
curl --fail --silent --show-error \
  "https://api.atlascloud.ai/api/v1/models" \
  --output /tmp/atlas-models.json

jq -r '.data[] | select(.type == "Image") | [.model, .displayName, .schema] | @tsv' \
  /tmp/atlas-models.json

2. 提交单个生成任务

将 JSON 正文构建在文件中，以确保引号确定性，并能在不暴露 API 密钥的情况下审查请求详情。

使用目录确认模型的图像生成示例：

bash
jq -n \
  --arg model "qwen-image-3.0/text-to-image" \
  --arg prompt "A paper-cut city map in blue and white, clean editorial style" \
  '{model: $model, prompt: $prompt, size: "1024*1024", n: 1}' \
  > /tmp/atlas-image-request.json

curl --fail --silent --show-error \
  --request POST \
  "https://api.atlas
cloud.ai/api/v1/model/generateImage" \
  --header "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data @/tmp/atlas-image-request.json \
  --output /tmp/atlas-submit.json

使用目录已确认模型的视频示例：

bash
jq -n \
  --arg model "bytedance/seedance-2.0-fast/text-to-video" \
  --arg prompt "A small paper boat crossing a calm pond, locked camera" \
  '{
    model: $model,
    prompt: $prompt,
    duration: 4,
    resolution: "480p",
    ratio: "16:9",
    generate_audio: false,
    watermark: false
  }' > /tmp/atlas-video-request.json

curl --fail --silent --show-error \
  --request POST \
  "https://api.atlascloud.ai/api/v1/model/generateVideo" \
  --header "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data @/tmp/atlas-video-request.json \
  --output /tmp/atlas-submit.json

在轮询之前，请检查 .data.id 是否为非空字符串。将非 2xx 响应或缺失 ID 视为提交失败；不要自动重试计费请求，因为原始任务可能已被接收。

3. 设置截止时间的轮询

每三秒轮询一次。将 completed 或 succeeded 视为成功，在遇到 failed 或 timeout 时停止，并在十分钟后停止。保留预测 ID 用于诊断，但切勿记录请求头或 API 密钥。

bash
prediction_id=$(jq -er '.data.id | select(type == "string" and length > 0)' \
  /tmp/atlas-submit.json)

for attempt in $(seq 1 200); do
  sleep 3
  curl --fail --silent --show-error \
    "https://api.atlascloud.ai/api/v1/model/prediction/$prediction_id" \
    --header "Authorization: Bearer $ATLASCLOUD_API_KEY" \
    --output /tmp/atlas-prediction.json


status=$(jq -r '.data.status // "unknown"' /tmp/atlas-prediction.json)
  case "$status" in
    completed|succeeded) break ;;
    failed|timeout)
      jq -r '.data.error // "Atlas Cloud generation failed"' \
        /tmp/atlas-prediction.json >&2
      exit 1
      ;;
  esac
done


test "$status" = "completed" || test "$status" = "succeeded"

4. 下载并验证输出

从 .data.outputs 中读取第一个 HTTPS URL。Atlas 的输出 URL 是临时的，请及时下载。不要将 Authorization 或任何其他 Atlas 请求头发送到输出主机。拒绝非 HTTPS URL，并在将其视为有效交付物之前检查下载文件的内容类型和大小。

bash
output_url=$(jq -er '.data.outputs[0] | select(startswith("https://"))' \
  /tmp/atlas-prediction.json)

curl --fail --silent --show-error --location \
  "$output_url" \
  --output ./atlas-output.bin


test -s ./atlas-output.bin
file ./atlas-output.bin

仅在检测到文件类型后才重命名文件。报告本地路径、模型 ID、尺寸或时长，以及输出是否通过了基础播放或解码验证。

错误处理

  • 401 或 403：停止并要求用户验证访问权限。不要自动打印或轮换密钥。
  • 400 或 422：获取模型的当前 Schema 并修正 Payload。不要盲目重新提交。
  • 429：停止并报告频率限制；遵循任何 Retry-After 值。
  • 5xx 或网络超时：首先轮询已知的预测 ID。除非用户同意可能的重复计费，否则不要创建第二个付费任务。
  • failed 或 timeout：报告脱敏后的服务错误和预测 ID；不要声称已生成输出。
  • 媒体缺失或无效：ke
保留原始响应以用于诊断，不要覆盖现有目标，且不要将任务标记为完成。

最佳实践

  • 在生成前立即使用公共目录和各模型的 schema。
  • 除非用户明确批准批量操作及其成本，否则每次仅提交一个任务。
  • 在审批步骤中保持提示词、参考媒体权限和供应商内容策略可见。
  • 仅在任务处于活跃状态时使用短轮询间隔；务必强制执行截止时间。
  • 及时下载即将过期的输出结果并在本地进行验证。
  • 切勿将 Atlas 承载令牌（bearer token）转发至 CDN 或用户提供的 URL。

局限性

  • 此纯源码技能仅提供操作指令，不包含已安装的 Atlas Cloud 客户端、捆绑脚本、队列工作进程或重试服务。
  • 可用模型、schema、价格和输出保留时间可能会发生变化；请以实时目录为准。
  • 模型的可用性并不保证提示词或参考资产一定被允许。
  • 生成过程是异步的，可能需要几分钟时间。
  • 基础文件检查不能替代人工对媒体质量、事实准确性、权限或安全性的审核。

安全与防护注意事项

  • 将提示词和上传的媒体视为发送给第三方的资料；请先获得用户同意，并避免包含不必要的个人或机密信息。
  • 将凭据保存在环境变量或经批准的密钥管理器中。
  • 从日志和错误报告中脱敏授权请求头（authorization headers）和签名输出 URL。
  • 切勿将下载的媒体作为代码执行，且切勿将此工作流用于大规模托管或无关的文件传输。
  • 遵守相关法律、供应商政策和知识产权。

常见陷阱

  • 问题： 从另一个模型复制的 payload 返回验证错误。
解决方案： 获取所选目录条目的当前 schema，并根据该 schema 重新构建请求。
  • 问题： 网络超时导致重复的付费请求。
解决方案： 在考虑重新提交之前，请保留并轮询原始的预测 ID（prediction ID）。
  • 问题： 下载的文件是 HTML 或 JSON 而非媒体文件。
解决方案： 在重命名或发布之前，检查 HTTP 状态、内容类型、文件签名和大小。
  • 问题： 输出下载导致 API 密钥泄露给另一个主机。
解决方案： 使用不带 Atlas 授权请求头的全新下载请求。

相关技能

  • @video-router - 在提交计费任务前，决定请求是否应使用生成的视频。
  • @image-studio - 围绕生成的资产规划并审核图像制作工作。