openapi: 3.1.0
info:
  title: JunboTop Image & Video API
  version: 1.0.0
  description: |
    JunboTop 图片和视频生成 API。视频任务采用异步模式：提交任务后，
    使用返回的 task_id 查询，直至任务 completed 或 failed。
servers:
  - url: https://junbotop.cn
    description: 生产环境
security:
  - bearerAuth: []
tags:
  - name: Video
    description: 视频生成与任务查询
  - name: Image
    description: 图片生成
  - name: Models
    description: 可用模型
paths:
  /v1/models:
    get:
      tags: [Models]
      summary: 获取当前令牌可用模型
      responses:
        '200':
          description: 模型列表
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/videos:
    post:
      tags: [Video]
      summary: 创建视频生成任务
      description: 返回任务 ID。任务提交成功后仍需查询最终状态。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoRequest'
            examples:
              textToVideo:
                summary: 文生视频
                value:
                  model: doubao-seedance-2.0-720p
                  prompt: 电影感镜头，一辆汽车在雨夜城市街道上行驶
                  duration: 5
                  aspect_ratio: '16:9'
              imageToVideo:
                summary: 图生视频
                value:
                  model: kling-3.0-turbo-720p
                  prompt: 人物缓慢转身看向镜头，保持主体一致
                  image_url: https://example.com/input.jpg
                  duration: 5
                  aspect_ratio: '16:9'
      responses:
        '200':
          description: 任务已提交
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlexibleTask'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: 额度不足
        '429':
          description: 频率或并发超限
  /v1/videos/{task_id}:
    get:
      tags: [Video]
      summary: 查询视频任务
      parameters:
        - name: task_id
          in: path
          required: true
          description: 创建任务接口返回的 id 或 task_id
          schema:
            type: string
      responses:
        '200':
          description: 当前任务状态和生成结果
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlexibleTask'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: 任务不存在或 URL 错误
  /v1/images/generations:
    post:
      tags: [Image]
      summary: 生成图片
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageRequest'
            example:
              model: nano-banana2-2k
              prompt: 极简风格的智能手表产品海报，白色背景，棚拍光线
              n: 1
      responses:
        '200':
          description: 图片生成成功
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: 额度不足
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
  schemas:
    VideoRequest:
      type: object
      required: [model, prompt]
      additionalProperties: true
      properties:
        model:
          type: string
          description: 带清晰度后缀的完整模型名
          examples: [doubao-seedance-2.0-720p]
        prompt:
          type: string
          minLength: 1
          description: 视频内容、动作、镜头和风格描述
        duration:
          type: integer
          minimum: 1
          description: 视频时长，具体支持范围取决于模型
        aspect_ratio:
          type: string
          examples: ['16:9', '9:16', '1:1']
        image_url:
          type: string
          format: uri
          description: 图生视频输入图片，必须可由服务端通过 HTTPS 访问
        video_url:
          type: string
          format: uri
          description: Motion Control 模型使用的参考视频
    ImageRequest:
      type: object
      required: [model, prompt]
      additionalProperties: true
      properties:
        model:
          type: string
          examples: [nano-banana2-2k]
        prompt:
          type: string
          minLength: 1
        n:
          type: integer
          default: 1
          minimum: 1
          maximum: 1
        response_format:
          type: string
          enum: [url, b64_json]
          description: 是否支持由具体模型和上游决定
    FlexibleTask:
      type: object
      description: 不同上游模型的字段可能略有差异，客户端应兼容 id/task_id、status/state、url/video_url。
      additionalProperties: true
      properties:
        id:
          type: string
        task_id:
          type: string
        status:
          type: string
          examples: [queued, processing, completed, failed]
        state:
          type: string
        video_url:
          type: string
          format: uri
        url:
          type: string
          format: uri
        error:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
  responses:
    BadRequest:
      description: 请求参数错误
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    Unauthorized:
      description: 令牌缺失、错误或已失效
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
