openapi: 3.1.0
info:
  title: Boooooom Creator API
  version: 1.0.0
  description: 炸弹人学院创作者资源包与火豹概念图接口。
servers:
  - url: https://boooooom.shop/api/v1
security:
  - creatorToken: []
paths:
  /game/runtime-packs/{runtimeKey}:
    get:
      security: []
      summary: 获取已审核、可由游戏加载的运行资源包
      parameters:
        - in: path
          name: runtimeKey
          required: true
          schema: {type: string}
      responses:
        "200": {description: 受控运行包的 Manifest、版本和预览素材地址}
        "404": {description: 未登记的运行包}
        "409": {description: 已登记资源包尚未发布有效 runtime 版本}
  /creator/profile:
    get:
      summary: 查询创作者、Token、资源包和生成记录
      responses:
        "200": {description: 创作者资料}
        "401": {description: Token 无效}
  /creator/packs/upload:
    post:
      summary: 上传经过校验的 ZIP 资源包
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file: {type: string, format: binary}
      responses:
        "200": {description: 上传成功或内容相同的幂等重传}
        "400": {description: ZIP、Manifest 或校验文件无效}
        "409": {description: 资源 ID 已被占用或已发布版本内容不同}
  /creator/generate:
    post:
      summary: 提交火豹概念图生成任务
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [category, name, prompt]
              properties:
                category: {enum: [small_monster, boss_monster]}
                name: {type: string, maxLength: 128}
                prompt: {type: string, minLength: 20, maxLength: 4000}
                archetype: {enum: [ground, flying, aquatic, mechanical, spectral]}
                referenceImages: {type: array, maxItems: 3, items: {type: string, format: uri}}
                requestId: {type: string, minLength: 8, maxLength: 64}
      responses:
        "202": {description: 已排队}
        "409": {description: 当前账号已有任务进行中}
        "429": {description: 达到每日生成额度}
  /creator/generations/{generationId}:
    get:
      summary: 查询持久化生成任务状态
      parameters:
        - in: path
          name: generationId
          required: true
          schema: {type: string}
      responses:
        "200": {description: ready 或 failed}
        "202": {description: queued 或 running}
  /assets/packs:
    get:
      summary: 查询会员可见资源包
      responses:
        "200": {description: 资源包列表}
  /assets/packs/{packRef}/download:
    get:
      summary: 下载资源包
      parameters:
        - in: path
          name: packRef
          required: true
          schema: {type: string}
        - in: query
          name: version
          schema: {type: string}
      responses:
        "302": {description: 跳转到短期 OSS 签名地址}
components:
  securitySchemes:
    creatorToken:
      type: http
      scheme: bearer
      bearerFormat: bb_creator_...
  schemas:
    AssetPackV2:
      $ref: https://boooooom.shop/school/docs/asset-pack-v2.schema.json
