返回首页

Fuderation API 文档

通过 API 调用角色聊天功能，使用您账户的点数进行计费。

认证方式

所有 API 请求需要在 Header 中携带 API Key 进行认证： 

Authorization: Bearer fud_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

您可以在 设置 → API Key 管理 中创建和管理您的 API Key。每个用户只能创建一个 Key。

角色聊天

POST /api/v1/chat/completions

请求参数

参数 类型 必填 说明
character_id integer * 角色 ID（显示 ID，如 10123，对应界面上的角色编号）
line_id integer * 故事线编号（从 1 开始，对应界面上的 #1, #2...）
messages array * 消息历史，格式同 OpenAI
model string - 模型名称，默认 gemini-2.5-pro
stream boolean - 是否流式输出，默认 false
user_name string - 用户名称，用于 变量替换
max_tokens integer - 最大输出 token 数，默认 4096
关于 line_id：故事线编号对应角色页面中显示的 #1, #2, #3... 编号。 编号仅计算已发布的故事线，未发布的故事线不参与编号。 即使中间的故事线被删除或取消发布，其他故事线的编号也会重新排列，始终保持连续。

请求示例

{
    "character_id": 10123,
    "line_id": 1,
    "messages": [
        {"role": "user", "content": "你好，今天过得怎么样？"}
    ],
    "model": "gemini-2.5-pro",
    "stream": false,
    "user_name": "小明",
    "max_tokens": 2048
}

响应示例（非流式）

{
    "success": true,
    "message": {
        "role": "assistant",
        "content": "你好呀！今天心情不错~"
    },
    "usage": {
        "prompt_tokens": 150,
        "completion_tokens": 30,
        "total_tokens": 180,
        "cost": 50
    }
}

流式响应格式

当 stream: true 时，响应为 SSE (Server-Sent Events) 格式： 

data: {"choices": [{"delta": {"content": "你好"}}]}
data: {"choices": [{"delta": {"content": "呀！"}}]}
data: {"choices": [{"delta": {"content": "今天"}}]}
...
data: [DONE]

获取用户信息

GET /api/v1/user/info

响应示例

{
    "success": true,
    "user": {
        "id": 1,
        "username": "example_user",
        "points": 10000,
        "balance_paid": 5000,
        "balance_free": 5000,
        "user_group": "default"
    }
}

错误码说明

HTTP 状态码 说明
401 API Key 缺失或无效
402 点数不足
403 用户被封禁 / 角色不可访问 / 模型无权限
404 角色或故事线不存在
500 服务器内部错误 / AI 调用失败

代码示例

Python

import requests

API_KEY = "fud_your_api_key_here"
BASE_URL = "https://your-domain.com"

response = requests.post(
    f"{BASE_URL}/api/v1/chat/completions",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "character_id": 10123,  # 角色显示 ID
        "line_id": 1,           # 故事线编号 #1
        "messages": [
            {"role": "user", "content": "你好！"}
        ],
        "model": "gemini-2.5-pro"
    }
)

data = response.json()
print(data["message"]["content"])

JavaScript (fetch)

const API_KEY = "fud_your_api_key_here";

const response = await fetch("/api/v1/chat/completions", {
    method: "POST",
    headers: {
        "Authorization": `Bearer ${API_KEY}`,
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        character_id: 10123,  // 角色显示 ID
        line_id: 1,           // 故事线编号 #1
        messages: [
            { role: "user", content: "你好！" }
        ],
        model: "gemini-2.5-pro"
    })
});

const data = await response.json();
console.log(data.message.content);

cURL

curl -X POST "https://your-domain.com/api/v1/chat/completions" \
  -H "Authorization: Bearer fud_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "character_id": 10123,
    "line_id": 1,
    "messages": [{"role": "user", "content": "你好！"}],
    "model": "gemini-2.5-pro"
  }'

注意事项