API 文档

快速开始

所有接口均为 HTTPS JSON 协议，基础地址：

https://www.huodouai.com/v1

兼容 OpenAI SDK，已有项目只需把 base_url 指向本地址即可。

认证方式

在请求头携带 API Key：

Authorization: Bearer zk_你的key

Key 由管理员开通，格式为 zk_ 前缀。Key 泄露后可联系管理员吊销并重新生成。

列出可用模型

GET /v1/models

curl https://www.huodouai.com/v1/models \
  -H "Authorization: Bearer zk_你的key"

响应返回当前账号可访问的模型列表，每个模型含 id、owned_by 等字段，结构与 OpenAI 一致。

对话补全

POST /v1/chat/completions

curl https://www.huodouai.com/v1/chat/completions \
  -H "Authorization: Bearer zk_你的key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao",
    "messages": [
      {"role": "system", "content": "你是一个助手"},
      {"role": "user", "content": "你好"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

请求参数

参数	类型	说明
model	string	模型 ID，从 /v1/models 获取
messages	array	对话消息数组，含 role/content
temperature	float	0-2，越高越随机，默认 1.0
max_tokens	int	最大生成 token 数
stream	bool	是否流式输出，默认 false

流式输出

设置 "stream": true，响应为 Server-Sent Events (SSE)，逐段返回：

import openai
client = openai.OpenAI(
    api_key="zk_你的key",
    base_url="https://www.huodouai.com/v1"
)
stream = client.chat.completions.create(
    model="doubao",
    messages=[{"role":"user","content":"写一首短诗"}],
    stream=True
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

错误码

HTTP	含义	处理建议
401	未认证 / Key 无效	检查 Authorization 头
403	无权限 / 额度用尽	确认套餐额度或联系管理员
404	模型不存在	用 /v1/models 查可用模型
429	限流	降低频率，指数退避重试
500	服务内部错误	稍后重试，持续异常联系支持

限流与配额

• 每个 Key 按套餐有每分钟请求数与每日总额度上限
• 超限返回 429，建议客户端做指数退避（1s → 2s → 4s）
• S4 及以上支持多 Key 分组，按组隔离配额
• 用量与计费在控制台可查

SDK 与迁移

Python（openai 官方 SDK）

pip install openai
import openai
client = openai.OpenAI(
    api_key="zk_你的key",
    base_url="https://www.huodouai.com/v1"
)

Node.js

import OpenAI from "openai";
const client = new OpenAI({
  apiKey: "zk_你的key",
  baseURL: "https://www.huodouai.com/v1"
});

LangChain / LlamaIndex

把 base_url 指向本服务，模型名填对应模型 ID 即可，无需改动业务代码。

商业化服务 API（网关 :9099）

火斗云智 AIOS 商业化能力网关，提供决策引擎、记忆网关代理、产品矩阵查询等能力。网关已上线云端，支持 HTTPS 调用。

Base URL

https://www.huodouai.com:9099/api/v1

1. 健康检查

GET /api/v1/health

curl https://www.huodouai.com:9099/api/v1/health
{"status":"healthy","service":"huodouai-commercial-gateway","version":"V1.0-sim"}

2. 三维稳态决策引擎

POST /api/v1/decision

三维稳态决策：利益 40% / 风险 35% / 成本 25%。风险、成本为负向指标（越低越好），自动换算正向分。

curl -X POST https://www.huodouai.com:9099/api/v1/decision \
  -H "Content-Type: application/json" \
  -d '{"options":[{"name":"方案A","benefit":60,"risk":20,"cost":30},{"name":"方案B","benefit":75,"risk":35,"cost":50}]}'

{"decision":[{"name":"方案A","benefit":60,"risk":20,"cost":30,"score":69.5},...],"recommended":"方案A"}

3. 记忆网关真值查询（代理 9120）

GET /api/v1/memory/truth/{key}

curl https://www.huodouai.com:9099/api/v1/memory/truth/strategy.product.matrix

4. 记忆网关真值写入（代理 9120）

POST /api/v1/memory/upsert

curl -X POST https://www.huodouai.com:9099/api/v1/memory/upsert \
  -H "Content-Type: application/json" \
  -d '{"key":"demo.truth","truth_value":{"note":"示例真值"}}'

5. 商业化产品矩阵查询

GET /api/v1/products

curl https://www.huodouai.com:9099/api/v1/products
{"matrix":{"matrix_name":"火斗云智AIOS数字资产产品矩阵","version":"V1.1",...}}

商业化 API 错误码

HTTP	含义	处理建议
400	请求参数缺失 / 格式错误	检查 options / key 字段
404	端点不存在	对照文档检查路径
502	记忆网关代理失败	检查 9120 网关状态