API 接入

基础地址

https://freedomz.cn/v1

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

常用接口

协议	接口
模型列表	GET /v1/models
OpenAI Chat Completions	POST /v1/chat/completions
OpenAI Responses	POST /v1/responses
Anthropic Messages	POST /v1/messages
Grok 图片	POST /v1/images/generations、POST /v1/images/edits
Grok 视频提交	POST /v1/videos/generations、POST /v1/videos/edits、POST /v1/videos/extensions
Grok 视频结果	GET /v1/videos/{request_id}、GET /v1/videos/{request_id}/content

接口存在不代表每把 Key 都能调用全部模型。最终可用范围由 Key 分组和实时模型 列表决定。

Base URL 是否带 /v1

配置类型	填写
OpenAI SDK、OpenAI Compatible 客户端	https://freedomz.cn/v1
客户端明确说明会自动追加 /v1	https://freedomz.cn
Claude Code 的 ANTHROPIC_BASE_URL	https://freedomz.cn

路径重复成 /v1/v1/... 时，通常就是客户端自动拼接而配置中又填写了 /v1。

认证

所有受保护接口使用 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：默认不自动切换密钥或无限重试。
• 每次重试必须保留同一个业务幂等标识，避免重复计费或重复执行工具。

对于 401 和 403，客户端应立即停止当前任务，不能自动轮换多个密钥或账号 继续提交同一内容。

请求标识

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

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

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

Grok 的 Responses API、推理等级、结构化输出、图片和视频异步任务接入请参阅 Grok 开发者接入。视频任务的新客户端应按 xAI 官方状态 pending、done、failed、expired 判断任务结果。