API文档

了解如何集成和使用API服务

简介

风屿汐 提供了一个统一、高效的接口来访问多种先进的AI模型。我们的API支持文本生成、图像创建、语音处理等多种功能。

所有API请求都通过HTTPS进行，使用JSON格式传输数据。

快速上手步骤

1. 注册账号并登录控制台

2. 在令牌管理中创建一个API密钥，选择需要绑定的模型

3. 使用该API密钥调用对应的API接口

4. 在控制台查看使用日志和消耗统计

认证

您需要在请求头中包含API密钥来进行身份验证。获取您的API密钥后，将其添加到请求的Authorization头中：

Authorization: Bearer YOUR_API_KEY

API密钥可在控制台 → 令牌管理中创建和管理。创建密钥时必须选择一个绑定模型。

快速开始

以下示例演示如何使用API密钥调用聊天完成接口：

Node.js 示例

const response = await fetch('https://fengyuxi.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Hello!' }]
  })
});

const data = await response.json();
console.log(data.choices[0].message.content);

cURL 示例

curl https://fengyuxi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Python 示例

import requests

response = requests.post(
    'https://fengyuxi.com/v1/chat/completions',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'gpt-4',
        'messages': [{'role': 'user', 'content': 'Hello!'}]
    }
)
print(response.json()['choices'][0]['message']['content'])

聊天完成 API

POST /v1/chat/completions
参数 类型 描述
model string 要使用的模型ID
messages array 对话消息数组
temperature number 采样温度 (0-2)
max_tokens integer 最大生成token数

模型列表

获取所有可用模型的列表：

GET /v1/models

模型列表会持续更新，您也可以在 模型广场 中浏览所有可用模型及其详细信息。

第三方工具集成

风屿汐 完全兼容 OpenAI API 格式，您可以在任何支持 OpenAI API 的工具或平台中配置使用。只需将 Base URL 设置为 https://fengyuxi.com，并填入您的 API 密钥即可。

在 Cursor 中配置

Cursor 是一款 AI 驱动的代码编辑器，支持自定义 OpenAI 兼容 API：

# 1. 打开 Cursor Settings (Ctrl+Shift+P → Preferences: Open Settings)
# 2. 导航到 Models 部分
# 3. 在 OpenAI Base URL 中输入：
https://fengyuxi.com

# 4. 在 OpenAI Key 中输入你的 API 密钥
# 5. 点击 "Verify" 验证连接
# 6. 在 Model 列表中添加可用的模型名称

在 Trae 中配置

Trae IDE 支持自定义模型提供商，配置步骤如下：

# 1. 打开 Trae 设置 (设置 → 模型)
# 2. 找到"自定义 OpenAI"或"兼容 API"选项
# 3. 添加自定义端点：
API地址: https://fengyuxi.com/v1/chat/completions
API密钥: 你的API密钥
模型名称: 你的令牌绑定的模型名称

# 4. 保存配置并测试连接

在 OpenClaw / OpenCalw 中配置

OpenClaw 和 OpenCalw 等工具同样支持 OpenAI 兼容接口：

# 1. 打开工具设置面板
# 2. 找到 API 或 Provider 配置
# 3. 选择"OpenAI 兼容模式"
# 4. 填入以下信息：
Base URL: https://fengyuxi.com
API Key: 你的API密钥
默认模型: 你的令牌绑定的模型名称

使用 OpenAI SDK

您也可以直接在代码中使用 OpenAI 官方 SDK，只需修改 base URL 即可：

Python (openai 库)

from openai import OpenAI

client = OpenAI(
    base_url='https://fengyuxi.com',
    api_key='YOUR_API_KEY'
)

response = client.chat.completions.create(
    model='gpt-4',
    messages=[{'role': 'user', 'content': '你是什么模型？'}]
)
print(response.choices[0].message.content)

Node.js (openai 库)

const { OpenAI } = require('openai');

const client = new OpenAI({
    baseURL: 'https://fengyuxi.com',
    apiKey: 'YOUR_API_KEY'
});

const response = await client.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: '你是什么模型？' }]
});
console.log(response.choices[0].message.content);

嵌入向量 API

将文本转换为向量表示，适用于语义搜索、文本分类、聚类等场景。

POST /v1/embeddings
参数 类型 描述
model string 嵌入模型ID
input string/array 要编码的文本，可以是字符串或字符串数组

Python 示例

from openai import OpenAI

client = OpenAI(
    base_url='https://fengyuxi.com',
    api_key='YOUR_API_KEY'
)

response = client.embeddings.create(
    model='text-embedding-3-small',
    input='需要编码的文本内容'
)
print(response.data[0].embedding)

图片生成 API

通过文本描述生成图片，支持 DALL-E 等模型。

POST /v1/images/generations
参数 类型 描述
prompt string 图片描述文本
n integer 生成数量 (1-10)
size string 图片尺寸，如 1024x1024

cURL 示例

curl https://fengyuxi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只可爱的猫",
    "n": 1,
    "size": "1024x1024"
  }'

API 密钥管理

在控制台中创建和管理 API 密钥。每个密钥可以绑定不同的模型、设置权限级别和用量限制。

密钥属性

  • 绑定模型 — 指定密钥可以调用的模型
  • 权限级别 — 只读或读写权限
  • 月额度限制 — 每月最大使用量
  • 速率限制 — RPM（每分钟请求数）和 TPD（每日 token 数）
  • 允许模型列表 — 限制可用模型范围
POST /api/api-keys

请求体：{ name, model, permission, monthly_limit, allow_models }

速率限制

系统为每个 API 密钥设置了两层速率限制，确保资源公平分配：

RPM（每分钟请求数）

每分钟最多允许的 API 请求次数。超过限制将返回 429 状态码。

TPD（每日 Token 数）

每天最多消耗的 token 总数。超过限制后将无法继续调用。

PUT /api/api-keys/:id/rate-limit

请求体：{ rpm: 60, tpd: 100000 }

用量预警配置

设置用量阈值，当用量超过设定值时系统会自动触发告警通知。

告警类型

  • balance_low — 余额低于阈值时告警
  • daily_spent — 日消耗超过阈值时告警
  • monthly_calls_pct — 月调用量超过阈值百分比时告警
POST /api/alert-configs

请求体：{ type: "balance_low", threshold: 10, method: "webhook" }

数据导出

支持将使用数据导出为 CSV 格式，方便在 Excel 或其他数据分析工具中查看。

GET /api/export/request-logs

导出请求日志，支持按时间范围和模型筛选

GET /api/export/usage-summary

导出按模型汇总的使用统计

自动续期

JWT Token 默认有效期为 24 小时。为了避免频繁重新登录，系统支持 Refresh Token 自动续期机制。

工作原理

  1. 登录时同时返回 token 和 refreshToken
  2. JWT 过期后，使用 refreshToken 调用 POST /api/refresh 获取新 Token
  3. Refresh Token 有效期为 30 天（记住我）或 24 小时（默认）
  4. 系统每 1 小时自动清理过期的 Refresh Token
POST /api/refresh

请求体：{ refreshToken: "your_refresh_token" }

前端实现建议

async function refreshAuthToken() {
    const refreshToken = localStorage.getItem('refreshToken');
    if (!refreshToken) return false;

    try {
        const res = await fetch('/api/refresh', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ refreshToken })
        });
        const data = await res.json();
        if (data.success) {
            localStorage.setItem('token', data.token);
            return true;
        }
    } catch (e) {}
    return false;
}

视频生成 API

通过文本描述生成视频，支持 Sora、Kling、Runway Gen 等主流视频模型。

POST /v1/video/generations
参数 类型 描述
model string 视频模型ID，如 Sora-3、Kling-3
prompt string 视频内容描述
duration integer 视频时长（秒），不同模型支持范围不同

语音与音频 API

支持语音识别（ASR）、语音合成（TTS）和音乐生成等音频处理能力。

语音识别

POST /v1/audio/transcriptions

支持 Whisper 系列模型，将音频文件转写为文字。支持 MP3、WAV、M4A 等多种格式。

语音合成

POST /v1/audio/speech

使用 ElevenLabs、CosyVoice 等模型将文字转换为自然语音，支持多语言多情感。

错误处理

API 错误将以标准 HTTP 状态码返回，响应体中包含详细错误信息。

状态码 错误类型 说明
400 Bad Request 请求参数错误，请检查请求体格式
401 Unauthorized API 密钥无效或已过期，请检查 Authorization 头
402 Insufficient Balance 余额不足，请充值后再试
429 Rate Limit Exceeded 请求频率超限，请稍后重试
500 Internal Error 服务器内部错误，请联系支持 
// 错误响应示例
{
  "error": {
    "message": "Insufficient balance",
    "type": "insufficient_balance",
    "code": "402"
  }
}

最佳实践

1. 合理的密钥管理

为不同应用创建独立的 API 密钥，方便追踪和控制用量。设置合理的月度额度限制和速率限制。

2. 错误重试策略

实现指数退避重试机制，对 429 和 5xx 错误进行自动重试。建议初始等待 1 秒，每次翻倍，最大重试 3 次。

3. Token 用量优化

合理设置 max_tokens 限制，避免不必要的 token 消耗。使用流式响应（stream: true）可降低延迟感知。

4. Token 自动续期

实现 Refresh Token 自动续期机制，避免因 Token 过期导致的服务中断。建议在 API 调用前检查 Token 有效期。

5. 用量监控告警

设置用量预警，当余额或调用量接近阈值时及时通知。定期导出使用日志进行成本分析。