通过 API 集成 AI:实用指南

你有一个应用。你想让它和 AI 对话。也许你想要聊天补全,也许是图像生成,也许两者。好消息:如果你用过 OpenAI API,你已经知道怎么用我们的。更好的消息:通过一个端点你可以访问 61 个提供商的 367 个模型。

不需要学新 SDK。没有专有协议。只需换 base URL 和你的 API 密钥。

步骤 1:拿到你的 API 密钥

在 zubnet.com 注册并导航到你的工作区设置。你的 API 密钥在那里。它以可识别的前缀开头:

zub_live_a1b2c3d4e5f6...

保密它。像对待密码一样。一旦泄露,立即在工作区设置中轮换 — 一旦你生成新密钥,旧密钥立刻失效。

步骤 2:设置你的 base URL

每个请求都发到:

https://api.zubnet.ai/v1

就这样。/v1 前缀匹配 OpenAI 的约定,所以任何支持 OpenAI 的库、工具或框架只需换 URL 就能工作。

步骤 3:发起你的第一个请求

使用 curl

最简单的测试 — 一条消息的聊天补全:

curl https://api.zubnet.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zub_live_YOUR_KEY" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "messages": [
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'

你会得到一个 JSON 响应,模型的回复在 choices[0].message.content。与 OpenAI 响应的结构完全相同。

使用 OpenAI SDK 的 Python

如果还没装,先安装 SDK:

pip install openai

然后用我们的 base URL 使用它:

from openai import OpenAI

client = OpenAI(
    api_key="zub_live_YOUR_KEY",
    base_url="https://api.zubnet.ai/v1"
)

response = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain quantum computing in three sentences."}
    ],
    max_tokens=500,
    temperature=0.7
)

print(response.choices[0].message.content)

这是一个完整、可用的示例。复制、粘贴、替换 API 密钥,运行。

模型参数

model 字段是变有意思的地方。你不被锁在一个提供商,而是从 61 个提供商的 367 个模型中选择。一些示例:

完整列表在我们的模型页面,可按类型(LLM、图像、视频、音频、3D、代码)和提供商过滤。你在那里看到的模型 ID 正是要放入 model 字段的内容。

图像生成

图像模型使用同样的端点模式。这是通过 Python 的 FLUX:

response = client.images.generate(
    model="flux-1.1-pro",
    prompt="A serene Japanese garden at dawn, soft morning light",
    n=1,
    size="1024x1024"
)

image_url = response.data[0].url
print(image_url)

响应包含托管在我们 CDN 上的生成图像 URL。下载、显示、嵌入 — URL 24 小时内有效。

流式响应

对聊天模型,流式随着 token 生成而发送,而不是等待完整响应。这对任何面向用户的聊天界面都是必要的 — 没人想盯着空白屏幕看 10 秒。

stream = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[
        {"role": "user", "content": "Write a short poem about code."}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

底层使用 Server-Sent Events(SSE)。每个 chunk 作为 HTTP 响应中的一行 data: 到达。OpenAI SDK 会为你处理解析,但如果你用原始 HTTP,你会看到这样的行:

data: {"choices":[{"delta":{"content":"Once"},"index":0}]}
data: {"choices":[{"delta":{"content":" upon"},"index":0}]}
data: {"choices":[{"delta":{"content":" a"},"index":0}]}
...
data: [DONE]

流以 data: [DONE] 结束。解析每行,提取 delta.content,追加到输出缓冲。这就是整个协议。

错误处理

API 使用标准 HTTP 状态码。这些是你真正会遇到的:

400 Bad Request — 你的请求体格式错误。检查 JSON 结构,确保 messages 是数组,确保 model 是有效的模型 ID。

401 Unauthorized — 你的 API 密钥缺失、无效或过期。检查 Authorization: Bearer 请求头。

403 Forbidden — 你的账户无权访问此模型或功能。检查工作区订阅级别。

429 Too Many Requests — 你触发了速率限制。响应包含 Retry-After 头告诉你要等多少秒。实施指数回退:

import time
from openai import RateLimitError

max_retries = 3
for attempt in range(max_retries):
    try:
        response = client.chat.completions.create(
            model="claude-sonnet-4-20250514",
            messages=[{"role": "user", "content": "Hello"}]
        )
        break
    except RateLimitError:
        wait = 2 ** attempt
        print(f"Rate limited. Waiting {wait}s...")
        time.sleep(wait)

500 / 502 / 503 — 服务端问题。少见但会发生。带回退重试。如持续,查看我们的 Pulse 状态页。

认证细节

每个请求都需要 Authorization 头:

Authorization: Bearer zub_live_YOUR_KEY

密钥作用于你的工作区。同一工作区的所有团队成员共享同一密钥和使用池。如果你需要按成员单独跟踪,就创建单独工作区。

速率限制

速率限制取决于你的计划级别。默认对大多数用例足够宽松:

• 每分钟请求数:按计划变化(60-600 RPM)
• 每分钟 token:按模型和计划变化
• 并发请求:没有硬上限,但如果你非常激进地突发,会触发 429

速率限制头包含在每个响应中:

x-ratelimit-limit-requests: 120
x-ratelimit-remaining-requests: 119
x-ratelimit-reset-requests: 0.5s

读这些头。让你的客户端尊重它们。当请求不随机失败时,用户会感谢你。

把一切组合起来

这是一个可投入生产的 Python 函数,处理错误、重试和流式:

import os
from openai import OpenAI, APIError, RateLimitError
import time

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

def ask(prompt, model="claude-sonnet-4-20250514", stream=False):
    for attempt in range(3):
        try:
            response = client.chat.completions.create(
                model=model,
                messages=[{"role": "user", "content": prompt}],
                stream=stream
            )
            if stream:
                return response  # iterate over chunks
            return response.choices[0].message.content
        except RateLimitError:
            time.sleep(2 ** attempt)
        except APIError as e:
            if attempt == 2:
                raise
            time.sleep(1)

# Usage
print(ask("Summarize the latest in quantum computing"))
print(ask("Same question, different model", model="gpt-4.1"))

通过改一个字符串切换模型。不需重构代码、不需新依赖、响应格式不变。这就是 OpenAI 兼容性的核心意义。

---

本指南所有代码示例截至 2026 年 3 月经过测试并可用。复制、运行、在其上构建。它们就是为此而存在。

准备开始?到 zubnet.com 拿你的 API 密钥