openapi: 3.0.3
info:
  title: DeepFlow API
  version: 0.1.0-draft
  description: |
    DeepFlow API 用户侧模型调用接口初稿。

    Base URL: https://deepflow.online/v1

    模型、分组、价格与具体参数能力以模型广场和实际接口返回为准。
    标有 x-deepflow-status: to-be-verified 的接口在公开发布前必须完成验证。
  contact:
    name: DeepFlow API Support (待补充)
    url: https://deepflow.online
servers:
  - url: https://deepflow.online
    description: DeepFlow API production
security:
  - BearerAuth: []
tags:
  - name: Models
    description: 可用模型
  - name: Chat
    description: OpenAI 兼容文本与多模态对话
  - name: Responses
    description: OpenAI Responses 兼容接口
  - name: Images
    description: 图像生成与编辑
paths:
  /v1/models:
    get:
      tags: [Models]
      summary: 获取当前密钥可用模型
      operationId: listModels
      x-deepflow-status: current
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelsResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /v1/chat/completions:
    post:
      tags: [Chat]
      summary: 创建聊天响应
      operationId: createChatCompletion
      x-deepflow-status: current
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChatCompletionRequest"
            example:
              model: gpt-5.6-luna
              messages:
                - role: user
                  content: 用一句话介绍 DeepFlow API。
              stream: false
      responses:
        "200":
          description: 成功；流式请求返回 text/event-stream
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatCompletionResponse"
            text/event-stream:
              schema:
                type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
  /v1/responses:
    post:
      tags: [Responses]
      summary: 创建模型响应
      operationId: createResponse
      x-deepflow-status: current-model-dependent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResponsesRequest"
            example:
              model: gpt-5.6-sol
              input: 用三点总结稳定 API 集成的关键。
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
  /v1/images/generations:
    post:
      tags: [Images]
      summary: 生成图像
      operationId: createImage
      x-deepflow-status: current
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImageGenerationRequest"
            example:
              model: gpt-image-1.5
              prompt: A clean isometric illustration of an AI API gateway
              n: 1
              size: 1024x1024
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
  /v1/images/edits:
    post:
      tags: [Images]
      summary: 编辑图像
      description: 此接口保留自 New API 兼容能力，DeepFlow 需按具体上游模型完成验证后再公开。
      operationId: editImage
      x-deepflow-status: to-be-verified
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [image, prompt]
              properties:
                model:
                  type: string
                  example: gpt-image-1
                image:
                  type: string
                  format: binary
                mask:
                  type: string
                  format: binary
                prompt:
                  type: string
                n:
                  type: integer
                  minimum: 1
                size:
                  type: string
                response_format:
                  type: string
                  enum: [url, b64_json]
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: "Authorization: Bearer sk-your-deepflow-key"
  responses:
    BadRequest:
      description: 请求参数错误
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Unauthorized:
      description: API 密钥无效或已禁用
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    RateLimited:
      description: 请求频率、并发或额度受限
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
  schemas:
    Model:
      type: object
      required: [id, object]
      properties:
        id:
          type: string
        object:
          type: string
          example: model
        created:
          type: integer
        owned_by:
          type: string
    ModelsResponse:
      type: object
      required: [object, data]
      properties:
        object:
          type: string
          example: list
        data:
          type: array
          items:
            $ref: "#/components/schemas/Model"
    Message:
      type: object
      required: [role, content]
      properties:
        role:
          type: string
          enum: [system, developer, user, assistant, tool]
        content:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                additionalProperties: true
        name:
          type: string
        tool_call_id:
          type: string
        tool_calls:
          type: array
          items:
            type: object
            additionalProperties: true
    ChatCompletionRequest:
      type: object
      required: [model, messages]
      properties:
        model:
          type: string
        messages:
          type: array
          items:
            $ref: "#/components/schemas/Message"
        stream:
          type: boolean
          default: false
        stream_options:
          type: object
          properties:
            include_usage:
              type: boolean
        temperature:
          type: number
          minimum: 0
          maximum: 2
        top_p:
          type: number
          minimum: 0
          maximum: 1
        max_tokens:
          type: integer
        max_completion_tokens:
          type: integer
        reasoning_effort:
          type: string
          enum: [low, medium, high]
        tools:
          type: array
          items:
            type: object
            additionalProperties: true
        tool_choice:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            additionalProperties: true
        usage:
          type: object
          additionalProperties: true
    ResponsesRequest:
      type: object
      required: [model, input]
      properties:
        model:
          type: string
        input:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                additionalProperties: true
        stream:
          type: boolean
        instructions:
          type: string
        tools:
          type: array
          items:
            type: object
            additionalProperties: true
        reasoning:
          type: object
          additionalProperties: true
    ImageGenerationRequest:
      type: object
      required: [prompt]
      properties:
        model:
          type: string
          example: gpt-image-1.5
        prompt:
          type: string
        n:
          type: integer
          minimum: 1
          maximum: 10
        size:
          type: string
          example: 1024x1024
        quality:
          type: string
        background:
          type: string
          enum: [transparent, opaque, auto]
        moderation:
          type: string
        style:
          type: string
        stream:
          type: boolean
        response_format:
          type: string
          enum: [url, b64_json]
        user:
          type: string
    ImageResponse:
      type: object
      properties:
        created:
          type: integer
        data:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
                format: uri
              b64_json:
                type: string
        usage:
          type: object
          additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            param:
              type: string
              nullable: true
            code:
              type: string
              nullable: true
