API 接入

基础地址

https://freedomz.cn/v1

该地址用于 API 请求。用户控制台位于 https://ai.freedomz.cn/，不要把控制台 域名当作 API 基础地址。

认证

所有受保护接口使用 Bearer Token：

Authorization: Bearer YOUR_API_KEY

建议通过环境变量读取：

export FREEDOMZ_API_KEY="YOUR_API_KEY"

$env:FREEDOMZ_API_KEY = "YOUR_API_KEY"

OpenAI SDK 配置

使用兼容 OpenAI API 基础地址的 SDK 时，将 base_url 或 baseURL 指向 FreedomZ AI。

Python 示例：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FREEDOMZ_API_KEY"],
    base_url="https://freedomz.cn/v1",
)

models = client.models.list()
for model in models.data:
    print(model.id)

Node.js 示例：

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.FREEDOMZ_API_KEY,
  baseURL: 'https://freedomz.cn/v1'
})

const models = await client.models.list()
console.log(models.data.map((model) => model.id))

流式响应

支持流式输出的接口可设置：

{
  "stream": true
}

客户端应持续读取 Server-Sent Events，不要由普通 HTTP 代理缓存完整响应。 长任务需要设置合理的客户端读取超时，并在连接中断时避免无上限立即重试。

超时与重试

推荐策略：

• 连接超时：10 至 20 秒。
• 普通请求读取超时：根据模型任务设置 2 至 10 分钟。
• 重试状态：仅对 429、部分 5xx 和明确的网络错误进行有限重试。
• 退避：采用指数退避并加入随机抖动。
• 401、403：默认不自动切换密钥或无限重试。
• 每次重试必须保留同一个业务幂等标识，避免重复计费或重复执行工具。

请求标识

发生异常时记录响应头或响应体中的请求 ID，并同时记录：

• 北京时间和时区；
• 接口路径；
• HTTP 状态码；
• 使用的模型名称；
• 是否流式；
• 客户端重试次数。

不要记录完整 API 密钥、密码或含敏感信息的完整请求正文。