{ "openapi": "3.1.0", "info": { "title": "HypersHub API", "version": "1.0", "description": "HypersHub 统一 AI 模型接入网关，同时兼容 OpenAI Chat Completions、 Anthropic Messages 和 Gemini generateContent / streamGenerateContent 等协议格式。 使用同一个平台 API Key 即可访问所有支持的模型。\n", "contact": { "url": "https://apiclaw.cc" } }, "servers": [ { "url": "https://apiclaw.cc", "description": "Production" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "使用平台 API Key，格式为 Bearer $HY_API_KEY" }, "XApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Anthropic 原生鉴权头，值为平台 API Key" }, "XGoogApiKey": { "type": "apiKey", "in": "header", "name": "x-goog-api-key", "description": "Gemini 原生鉴权头，值为平台 API Key" } }, "schemas": { "ChatMessage": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant", "tool" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ] }, "tool_calls": { "type": "array", "items": { "type": "object" } }, "tool_call_id": { "type": "string" } } }, "ChatCompletionsRequest": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "example": "claude-sonnet-4-6" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } }, "stream": { "type": "boolean", "default": false }, "tools": { "type": "array", "items": { "type": "object", "required": [ "type", "function" ], "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object" } } } } } }, "reasoning_effort": { "type": "string", "enum": [ "low", "medium", "high" ] }, "temperature": { "type": "number", "default": 1 }, "top_p": { "type": "number", "default": 1 }, "presence_penalty": { "type": "number", "default": 0 }, "frequency_penalty": { "type": "number", "default": 0 }, "max_completion_tokens": { "type": "integer", "example": 512 }, "response_format": { "type": "object" }, "stop": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } }, "ChatCompletionsResponse": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } } }, "finish_reason": { "type": "string" } } } }, "usage": { "$ref": "#/components/schemas/OpenAIUsage" } } }, "OpenAIUsage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } }, "AnthropicMessage": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ] } } }, "ThinkingConfig": { "type": "object", "required": [ "type", "budget_tokens" ], "properties": { "type": { "type": "string", "enum": [ "enabled", "disabled" ] }, "budget_tokens": { "type": "integer", "description": "允许模型用于内部思考的最大 token 数，需小于 max_tokens" } } }, "MessagesRequest": { "type": "object", "required": [ "model", "messages", "max_tokens" ], "properties": { "model": { "type": "string", "example": "claude-opus-4-7" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/AnthropicMessage" } }, "max_tokens": { "type": "integer", "example": 1024 }, "system": { "type": "string" }, "stream": { "type": "boolean", "default": false }, "thinking": { "$ref": "#/components/schemas/ThinkingConfig" }, "tools": { "type": "array", "items": { "type": "object", "required": [ "name", "input_schema" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "input_schema": { "type": "object" } } } }, "tool_choice": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auto", "any", "tool" ] }, "name": { "type": "string" } } }, "temperature": { "type": "number" }, "top_p": { "type": "number" }, "top_k": { "type": "integer" }, "stop_sequences": { "type": "array", "items": { "type": "string" } } } }, "MessagesResponse": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "model": { "type": "string" }, "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "text": { "type": "string" } } } }, "stop_reason": { "type": "string" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" } } } } }, "GeminiPart": { "type": "object", "properties": { "text": { "type": "string" } } }, "GeminiContent": { "type": "object", "required": [ "parts" ], "properties": { "role": { "type": "string", "enum": [ "user", "model" ], "description": "缺省时网关自动补 \"user\"" }, "parts": { "type": "array", "items": { "$ref": "#/components/schemas/GeminiPart" } } } }, "GenerationConfig": { "type": "object", "properties": { "temperature": { "type": "number" }, "topP": { "type": "number" }, "topK": { "type": "integer" }, "maxOutputTokens": { "type": "integer" }, "stopSequences": { "type": "array", "items": { "type": "string" } }, "thinkingConfig": { "type": "object", "properties": { "thinkingBudget": { "type": "integer" } } } } }, "GenerateContentRequest": { "type": "object", "required": [ "contents" ], "properties": { "contents": { "type": "array", "items": { "$ref": "#/components/schemas/GeminiContent" } }, "generationConfig": { "$ref": "#/components/schemas/GenerationConfig" }, "systemInstruction": { "type": "object", "properties": { "parts": { "type": "array", "items": { "$ref": "#/components/schemas/GeminiPart" } } } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "functionDeclarations": { "type": "array", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object" } } } } } } } } }, "GenerateContentResponse": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/GeminiContent" }, "finishReason": { "type": "string" }, "index": { "type": "integer" } } } }, "usageMetadata": { "type": "object", "properties": { "promptTokenCount": { "type": "integer" }, "candidatesTokenCount": { "type": "integer" }, "totalTokenCount": { "type": "integer" } } } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } } } } }, "ResponsesRequest": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "example": "gpt-5.4" }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ], "example": "Write a one-sentence product description." }, "instructions": { "type": "string", "description": "系统提示词，等价于 Chat Completions 中的 system message。" }, "stream": { "type": "boolean", "default": false }, "max_output_tokens": { "type": "integer", "example": 256 }, "reasoning_effort": { "type": "string", "enum": [ "low", "medium", "high" ] }, "temperature": { "type": "number", "default": 1 }, "tools": { "type": "array", "items": { "type": "object" } }, "text": { "type": "object" }, "previous_response_id": { "type": "string" } } }, "ResponsesResponse": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "integer" }, "status": { "type": "string" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "type": "object" } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } } } }, "Model": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "model" ] }, "created": { "type": "integer" }, "owned_by": { "type": "string" } } }, "ModelList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } } } }, "paths": { "/v1/chat/completions": { "post": { "operationId": "createChatCompletion", "summary": "Create chat completion", "description": "OpenAI Chat Completions 兼容端点，支持流式和非流式两种模式。 支持全系列 Claude、Gemini、GPT 模型。\n", "tags": [ "Chat" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionsRequest" }, "example": { "model": "claude-sonnet-4-6", "messages": [ { "role": "system", "content": "你是一个专业的产品助手。" }, { "role": "user", "content": "写一个三行产品介绍" } ], "max_completion_tokens": 256 } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/responses": { "post": { "operationId": "createResponse", "summary": "Create a response", "description": "OpenAI Responses API 原生格式端点，支持流式和非流式两种模式。", "tags": [ "Responses" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesRequest" }, "example": { "model": "gpt-5.4", "instructions": "You are a helpful assistant.", "input": "Write a one-sentence product description.", "max_output_tokens": 256 } } } }, "responses": { "200": { "description": "成功；stream=true 时返回 text/event-stream。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesResponse" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/ResponsesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/messages": { "post": { "operationId": "createMessage", "summary": "Create message", "description": "Anthropic Messages 原生格式端点，支持多轮对话、Tool Use 和 Extended Thinking。兼容 x-api-key 和 Bearer 两种鉴权方式。\n", "tags": [ "Anthropic Messages" ], "security": [ { "BearerAuth": [] }, { "XApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesRequest" }, "example": { "model": "claude-opus-4-7", "max_tokens": 1024, "system": "你是一个专业的产品助手。", "messages": [ { "role": "user", "content": "解释一下边际成本" } ] } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1beta/models/{model}:generateContent": { "post": { "operationId": "generateContent", "summary": "Generate content", "description": "Gemini generateContent 原生格式端点，支持多模态输入、多轮对话、 Function Calling 和 thinkingConfig。 兼容 x-goog-api-key 和 Bearer 两种鉴权方式。\n", "tags": [ "Gemini" ], "security": [ { "BearerAuth": [] }, { "XGoogApiKey": [] } ], "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "example": "gemini-3.1-pro-preview" }, "description": "Gemini 模型 ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateContentRequest" }, "example": { "system_instruction": { "parts": [ { "text": "你是一个专业的产品助手。" } ] }, "contents": [ { "role": "user", "parts": [ { "text": "用一句话解释 API 网关" } ] } ], "generationConfig": { "maxOutputTokens": 256 } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateContentResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1beta/models/{model}:streamGenerateContent": { "post": { "operationId": "streamGenerateContent", "summary": "Stream generate content", "description": "Gemini streamGenerateContent 原生格式端点，以 SSE 流式返回内容， 支持多模态输入、多轮对话、Function Calling 和 thinkingConfig。 兼容 x-goog-api-key 和 Bearer 两种鉴权方式。\n", "tags": [ "Gemini" ], "security": [ { "BearerAuth": [] }, { "XGoogApiKey": [] } ], "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "example": "gemini-3.1-pro-preview" }, "description": "Gemini 模型 ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateContentRequest" }, "example": { "contents": [ { "role": "user", "parts": [ { "text": "Count from 1 to 3" } ] } ] } } } }, "responses": { "200": { "description": "成功，返回 SSE 事件流；每个事件的 data 为 GenerateContentResponse 形状的 JSON。", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/GenerateContentResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/models": { "get": { "operationId": "listModels", "summary": "List models", "description": "返回当前 API Key 有权限访问的模型列表，格式兼容 OpenAI Models API。", "tags": [ "Models" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/models/{model}": { "get": { "operationId": "retrieveModel", "summary": "Retrieve model", "description": "查询单个模型的详情。若该模型不在当前 API Key 的可访问范围内，返回 404。", "tags": [ "Models" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "example": "claude-sonnet-4-6" }, "description": "模型 ID，例如 claude-sonnet-4-6 或 gpt-5.4。" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } } }