API 接口参考

RootFlowAI 提供 OpenAI 兼容接口及部分模型家族的原生协议入口。接入时，需要同时核对模型、分组、接口与参数；替换 Base URL 并不代表所有模型都支持同一套功能。

先在模型价格页选择模型与分组，再按下表找到对应教程。尚未创建令牌时，先查看获取 API Key。

按用途选择接口

这是一张入口选择表，不是全部模型的能力承诺。工具调用、图片输入、结构化输出、长上下文与联网搜索等能力需要逐项匹配模型和分组。

Base URL 与完整请求地址

SDK 会在 Base URL 后追加接口路径。不要把完整的 /v1/chat/completions 当作 SDK Base URL，也不要重复拼出 /v1/v1。直接使用 curl 时则填写完整请求地址。

认证

本文 curl 与 OpenAI SDK 示例使用 RootFlowAI 令牌的 Bearer 认证：

Authorization: Bearer <ROOTFLOWAI_API_KEY>

在服务器或本机环境中设置密钥，不要把真实 Key 写进网页前端、Git 仓库或公开日志。下面 Bash 示例中的值是占位符：

export ROOTFLOWAI_API_KEY="sk-你的RootFlowAI令牌"
export ROOTFLOWAI_MODEL="填写支持目标接口的完整模型ID"

ROOTFLOWAI_MODEL 必须替换成实际模型 ID，不要直接把占位文字提交给接口。

免费检查：Models 模型列表

curl --fail-with-body --silent --show-error \
  https://api.rootflowai.com/v1/models \
  -H "Authorization: Bearer $ROOTFLOWAI_API_KEY"

此请求不发起模型推理。列表可以帮助确认地址、认证与模型可见性，但不能证明余额充足、目标分组可调用，或某个模型支持全部参数与工具。

下面的生成请求与 SDK 示例会产生实际调用费用，请先核对计费说明。

Chat Completions：消息对话

完整地址为 POST https://api.rootflowai.com/v1/chat/completions。下面是请求体示例，使用前将 MODEL_ID 替换为支持该接口的实际模型：

{
  "model": "MODEL_ID",
  "messages": [
    { "role": "user", "content": "用一句话介绍你能协助的任务。" }
  ],
  "stream": false
}

非流式文本响应通常从 choices[0].message.content 读取；消息可能包含工具调用或其他内容，不要假设所有响应都是纯文本。

Responses：input 工作流

完整地址为 POST https://api.rootflowai.com/v1/responses。请求格式与 Chat Completions 不同：

{
  "model": "MODEL_ID",
  "input": "用一句话介绍你能协助的任务。"
}

原始响应中的 output 是类型化内容数组。OpenAI SDK 提供 output_text 便捷属性用于获取文本；不要把它当作所有原始 HTTP 响应都必带的顶层字段。

需要联网搜索时，选择支持相应工具的模型，并按联网搜索能力说明显式传入工具、核对返回的工具事件。仅在提示词里写“请联网搜索”不会自动提供搜索工具。

Claude 与 Gemini 原生协议

Claude Messages 使用 /v1/messages，请求包含 model、max_tokens 和 messages。Claude Code 已负责组织这些请求，通常只需按安装配置教程配置地址、凭据与模型。自行集成时，还需按 Messages 协议设置版本头，例如 anthropic-version: 2023-06-01。

Gemini 原生 generateContent 将模型 ID 放在路径中，使用 contents 等字段；它与 Chat Completions 的 messages、Responses 的 input 不能互换。联网工具与图像输入请使用对应教程中的协议示例。

不同协议的流式事件、错误结构和 usage 字段也不同。切换接口时需要同步调整解析代码。

OpenAI SDK 示例

Python：Chat Completions

安装 SDK：

python -m pip install openai

代码从环境变量读取令牌和模型。运行前选择支持 Chat Completions 的模型：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROOTFLOWAI_API_KEY"],
    base_url="https://api.rootflowai.com/v1",
)

response = client.chat.completions.create(
    model=os.environ["ROOTFLOWAI_MODEL"],
    messages=[{"role": "user", "content": "用一句话介绍你能协助的任务。"}],
)
print(response.choices[0].message.content)

JavaScript：Responses

安装 SDK，并将示例保存为 example.mjs：

npm install openai

运行前将 ROOTFLOWAI_MODEL 设置为支持 Responses 的模型：

import OpenAI from "openai";

if (!process.env.ROOTFLOWAI_API_KEY || !process.env.ROOTFLOWAI_MODEL) {
  throw new Error("请先设置 ROOTFLOWAI_API_KEY 和 ROOTFLOWAI_MODEL");
}

const client = new OpenAI({
  apiKey: process.env.ROOTFLOWAI_API_KEY,
  baseURL: "https://api.rootflowai.com/v1",
});

const response = await client.responses.create({
  model: process.env.ROOTFLOWAI_MODEL,
  input: "用一句话介绍你能协助的任务。",
});
console.log(response.output_text);

执行 node example.mjs 会发起生成调用。SDK 可能自带重试机制；生产集成应按成本与任务语义设置超时和重试策略。

常见错误与核对顺序

向支持反馈时提供时间、路径、模型和脱敏错误信息，不要附带完整 API Key。调用扣费可在消费日志核对。

相关资料

• OpenAI 官方 SDK 快速开始
• OpenAI Chat Completions 参考
• Claude Code 网关配置
• 模型价格与计费说明
• 图像生成与联网搜索