API 概览

外部 API 的认证方式、模型列表、聊天补全、图片生成与积分说明。

Base URL

请使用你自己站点的域名作为 API 基地址：

https://your-domain.com/api/v1

认证方式

先在 设置 -> API 密钥 中创建密钥，然后以 Bearer Token 方式传入：

Authorization: Bearer sk_live_...

API Key 创建后只会完整展示一次。平台仅保存哈希值和前缀，不保存完整明文。

可用模型列表

查询当前平台开放的公共模型：

curl https://your-domain.com/api/v1/models \
  -H "Authorization: Bearer $YOUR_API_KEY"

响应示例：

{
  "object": "list",
  "data": [
    {
      "id": "openai/gpt-5",
      "object": "model",
      "owned_by": "openrouter",
      "display_name": "GPT-5",
      "category": "chat",
      "capabilities": ["chat", "reasoning"],
      "credit_cost": 3
    }
  ]
}

聊天补全

接口：

POST /api/v1/chat/completions

请求示例：

curl https://your-domain.com/api/v1/chat/completions \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5",
    "messages": [
      { "role": "user", "content": "写一首关于 API 的俳句。" }
    ]
  }'

Node.js 示例：

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.YOUR_API_KEY,
  baseURL: 'https://your-domain.com/api/v1',
});

const completion = await client.chat.completions.create({
  model: 'openai/gpt-5',
  messages: [{ role: 'user', content: '写一首关于 API 的俳句。' }],
});

console.log(completion.choices[0]?.message?.content);

聊天接口会先经过平台模型白名单校验，再转发到上游提供商。

图片生成

接口：

POST /api/v1/images/generations

请求示例：

curl https://your-domain.com/api/v1/images/generations \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/nano-banana-pro",
    "prompt": "一个机器人在阅读 API 文档的电影感照片",
    "size": "1024x1024"
  }'

响应示例：

{
  "created": 1710000000,
  "data": [],
  "task_id": "local-task-id",
  "provider_task_id": "provider-task-id",
  "status": "pending",
  "model": "google/nano-banana-pro"
}

第一版会立即返回任务元数据，图片生成继续沿用平台现有任务流水线。

积分与限制

聊天和图片生成都消耗平台积分。
每个模型的积分消耗在平台模型注册表中配置。
当用户积分不足时，请求会在调用上游前被拒绝。
API Key 已预留每分钟速率限制字段，便于后续做正式限流。

错误格式

所有 /api/v1/* 接口统一返回：

{
  "error": {
    "message": "Model is not available",
    "type": "model_not_available",
    "code": "model_not_available"
  }
}

常见错误码：

invalid_api_key
api_disabled
model_required
model_not_available
messages_required
prompt_required
insufficient_credits
provider_not_configured
provider_error

说明

只有平台模型注册表中启用并公开的模型才可调用。
API 请求日志会记录 request ID、API Key、模型、状态码、耗时和积分消耗。
视频和音乐暂不开放到外部 API。

API 概览

On this page