openapi: 3.1.0
info:
  title: HypersHub API
  version: '1.0'
  description: 'HypersHub 统一 AI 模型接入网关，同时兼容 OpenAI Chat Completions、 Anthropic Messages 和 Gemini generateContent / streamGenerateContent 等协议格式。 使用同一个平台 API Key 即可访问所有支持的模型。

    '
  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 模型。

        '
      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 两种鉴权方式。

        '
      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 两种鉴权方式。

        '
      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 两种鉴权方式。

        '
      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'