ycapis + GPT 接入说明（网站/后端集成）

本文档描述如何通过 ycapis 调用 GPT 系列模型（例如 gpt-5.4-pro），采用 OpenAI Responses 风格接口，适用于网站后端、服务端应用以及 Agent 调用。

安全提醒：请务必只在服务器端使用 YCAPIS_API_KEY，不要在浏览器前端直接暴露。

1. 基本信息

Base URL: https://ycapis.com/v1
推荐模型示例：gpt-5.4-pro
协议风格：OpenAI Responses API 兼容

2. 鉴权

所有请求需要在 HTTP 头里带上：

Authorization: Bearer <YCAPIS_API_KEY>
Content-Type: application/json

<YCAPIS_API_KEY> 为你在 ycapis 后台生成的 API Key。
建议在服务器环境变量中配置，例如：
- Linux/Node.js: .env 文件里写 YCAPIS_API_KEY=xxxx，代码中通过 process.env.YCAPIS_API_KEY 读取。

3. 文本对话接口

3.1 端点

POST https://ycapis.com/v1/responses

3.2 最简请求体示例（单轮字符串）

{
  "model": "gpt-5.4-pro",
  "input": "用一句话介绍一下你自己。"
}

3.3 Chat 风格请求体示例（多轮对话）

{
  "model": "gpt-5.4-pro",
  "input": [
    {
      "role": "system",
      "content": "你是一个说中文、回答简洁的助手。"
    },
    {
      "role": "user",
      "content": "帮我用三句话介绍一下比特币。"
    }
  ]
}

3.4 带参数的请求体示例

{
  "model": "gpt-5.4-pro",
  "input": "写一段 100 字左右的自我介绍。",
  "max_output_tokens": 512,
  "temperature": 0.7,
  "top_p": 0.95
}

字段说明：

model: 模型 ID，例如 gpt-5.4-pro、gpt-5.4、gpt-5.3-codex 等。
input: 可以是字符串，或 [{role, content}] 数组。
max_output_tokens: 最大输出 token 数（可选）。
temperature / top_p: 控制随机性，语义同 OpenAI。

4. 返回格式

典型成功响应：

{
  "id": "resp_01J44zW6T7mi2wk83vv6r77R",
  "model": "gpt-5.4-pro",
  "output": [
    {
      "role": "assistant",
      "content": "你好，我是一个由 ycapis 代理的 GPT-5.4-Pro 模型，可以用中文帮你解决各种问题。"
    }
  ],
  "usage": {
    "input_tokens": 32,
    "output_tokens": 18,
    "total_tokens": 50
  }
}

关键字段：

output[0].content: 模型生成的文本回复。
usage: token 使用统计，可用于费用/配额监控。

错误响应示例：

{
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required field: input"
  }
}

5. Node.js / Next.js 后端调用示例

以下示例展示如何在 Node.js/Next.js 后端封装一个调用 ycapis 的函数：

import fetch from "node-fetch";

export async function callYcapis(prompt: string) {
  const res = await fetch("https://ycapis.com/v1/responses", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.YCAPIS_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "gpt-5.4-pro",
      input: prompt,
      max_output_tokens: 512
    })
  });

  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error(`ycapis error: ${res.status} ${JSON.stringify(err)}`);
  }

  const data = await res.json();
  const text = data.output?.[0]?.content ?? "";
  return text;
}

前端只需要请求你自己的 API，而不是直接请求 ycapis：

// pages/api/chat.ts
export default async function handler(req, res) {
  const { prompt } = req.body;
  const reply = await callYcapis(prompt);
  res.status(200).json({ reply });
}

浏览器调用示例：

const res = await fetch("/api/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ prompt: userInput })
});
const data = await res.json();
console.log(data.reply);

6. Python 后端调用示例

import os
import requests

YCAPIS_API_KEY = os.environ.get("YCAPIS_API_KEY")

def call_ycapis(prompt: str) -> str:
    url = "https://ycapis.com/v1/responses"
    headers = {
        "Authorization": f"Bearer {YCAPIS_API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "model": "gpt-5.4-pro",
        "input": prompt,
        "max_output_tokens": 512,
    }
    resp = requests.post(url, headers=headers, json=payload, timeout=30)
    resp.raise_for_status()
    data = resp.json()
    return (data.get("output") or [{}])[0].get("content", "")

7. 给 AI/Agent 的简化协议说明

Provider: ycapis
Base URL: https://ycapis.com/v1
Endpoint: POST /responses
Auth: Authorization: Bearer <YCAPIS_API_KEY>
Request schema:

{
  "model": "string",
  "input": "string | Array<{role: 'system'|'user'|'assistant', content: string}>",
  "max_output_tokens": "number (optional)",
  "temperature": "number (optional)",
  "top_p": "number (optional)"
}

Response schema（简化）：

{
  "id": "string",
  "model": "string",
  "output": [
    { "role": "assistant", "content": "string" }
  ],
  "usage": {
    "input_tokens": "number",
    "output_tokens": "number",
    "total_tokens": "number"
  },
  "error": {
    "type": "string",
    "message": "string"
  }
}

注意：请不要把真实的 YCAPIS_API_KEY 写进此文档，统一通过环境变量/配置文件注入，避免泄漏。

ycapis + GPT 接入说明（网站/后端集成）

On this page