SDK 与客户端库

把 OpenAI、Anthropic 或 Google SDK 指向 Atlas Cloud，另附可直接复制的 Python 与 Node.js 客户端，用于图像、视频与音频生成。

Atlas Cloud 没有自己的 SDK；对语言模型来说，你也不需要——API 接受的正是现有 SDK 已经在用的格式。至于媒体生成，本页提供了一个可以直接复制进项目的小客户端。

你要调用的	怎么做
语言模型	把 OpenAI、Anthropic 或 Google SDK 指向 Atlas Cloud
图像、视频、音频、3D	用普通 HTTP 调用异步端点——客户端见下文
在终端或 CI 里	用 CLI
在 AI 辅助的 IDE 里	用 MCP Server

语言模型

改掉 Base URL 和 API Key，其余一律不动。

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ATLASCLOUD_API_KEY"],
    base_url="https://api.atlascloud.ai/v1",
)

response = client.chat.completions.create(
    model="deepseek-ai/deepseek-v3.2",
    messages=[{"role": "user", "content": "Explain HTTP vs HTTPS"}],
)
print(response.choices[0].message.content)

不同模型接受的协议并不相同——有的只支持 Messages，有的只支持 Responses。别默认 Chat Completions 一定能用，先查模型的 API 参考。参见 LLM API 协议。

媒体生成客户端

图像、视频、音频和 3D 生成都是异步的：先提交，再轮询。下面是一个功能完整的最小客户端。

import os
import time
import requests

API_KEY = os.environ["ATLASCLOUD_API_KEY"]
BASE = "https://api.atlascloud.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 端点由输出类型决定：3D 走 image，语音/音乐/转写都走 audio
ENDPOINTS = {
    "image": f"{BASE}/model/generateImage",
    "video": f"{BASE}/model/generateVideo",
    "audio": f"{BASE}/model/generateAudio",
}
TERMINAL = {"completed", "succeeded", "failed", "timeout"}


def submit(kind: str, model: str, **params) -> str:
    """提交生成任务，返回 prediction ID。参数平铺在顶层，不要包在 input 里。"""
    response = requests.post(
        ENDPOINTS[kind],
        headers=HEADERS,
        json={"model": model, **params},
        timeout=60,
    )
    response.raise_for_status()
    return response.json()["data"]["id"]


def wait(prediction_id: str, timeout: int = 600) -> dict:
    """轮询直到任务进入终态。间隔逐步放大，避免高频空转。"""
    deadline = time.time() + timeout
    delay = 2.0

    while time.time() < deadline:
        response = requests.get(
            f"{BASE}/model/prediction/{prediction_id}",
            headers=HEADERS,
            timeout=30,
        )
        response.raise_for_status()
        data = response.json()["data"]

        if data.get("status") in TERMINAL:
            if data["status"] in ("failed", "timeout"):
                raise RuntimeError(f"生成失败: {data.get('error') or data['status']}")
            return data

        time.sleep(delay)
        delay = min(delay * 1.5, 10.0)

    raise TimeoutError(f"任务 {prediction_id} 在 {timeout} 秒内未完成")


def upload(path: str) -> str:
    """上传本地文件，换成可用于生成请求的 URL。"""
    with open(path, "rb") as f:
        response = requests.post(
            f"{BASE}/model/uploadMedia", headers=HEADERS, files={"file": f}, timeout=600
        )
    response.raise_for_status()
    data = response.json()["data"]
    return data.get("download_url") or data.get("url")


if __name__ == "__main__":
    pid = submit("image", "MODEL_ID", prompt="a ceramic mug on a linen backdrop")
    result = wait(pid)
    print(result["outputs"][0])

这个客户端做对了两件最容易做错的事：

参数写在顶层，和 model 平级——不要包进 input 对象里。
对转写和歌词类模型，outputs[0] 是文本，不是 URL。 不要闭着眼睛去下载它。参见音频模型。

上生产前的注意事项

视频优先用 Webhook 而不是轮询，视频生成可能要好几分钟。参见 Webhook。
只对 429、500、503、504 重试，并采用指数退避。400、401、402、403 不要重试。参见错误与限流。
重试提交请务必谨慎。 提交请求超时不代表服务端没受理，盲目重试会多跑出一个要计费的任务。请改用异步提交加轮询。
记录每个响应里的 X-Request-ID——支持团队追踪一次调用靠的就是它。

社区库

社区维护的封装库汇总在 awesome-atlas-cloud-integrations。它们由社区独立维护——上生产前请先确认封装库到底做了什么。

语言模型

媒体生成客户端

上生产前的注意事项

社区库

相关内容

LLM API 协议

预测任务

错误与限流

集成

On this page