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 金鑰，其餘一律不動。

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