openapi: 3.0.0
info:
  title: Flux-2 API
  description: Apikley Flux-2 API 文档 - 文生图
  version: 1.0.0
  contact:
    name: 技术支持
    email: [email protected]
servers:
  - url: https://api.apikley.ru
    description: API 服务器
security:
  - BearerAuth: []
paths:
  /api/v1/jobs/createTask:
    post:
      summary: 使用 flux-2/flex-text-to-image 生成图像
      operationId: flux-2-flex-text-to-image
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
              properties:
                model:
                  type: string
                  enum:
                    - flux-2/flex-text-to-image
                  default: flux-2/flex-text-to-image
                  description: |-
                    用于生成任务的模型名称。必填字段。

                    - 该端点必须使用 `flux-2/flex-text-to-image` 模型
                  example: flux-2/flex-text-to-image
                callBackUrl:
                  type: string
                  format: uri
                  description: |-
                    接收生成任务完成通知的回调 URL。可选配置，建议在生产环境中使用。

                    - 任务生成完成后，系统会向该 URL POST 任务状态与结果
                    - 回调内容包含生成的资源 URL 与任务相关信息
                    - 您的回调端点需要支持接收带 JSON 负载的 POST 请求
                    - 也可以选择调用任务详情端点，主动轮询任务状态
                  example: https://your-domain.com/api/callback
                input:
                  type: object
                  description: 生成任务的输入参数
                  properties:
                    prompt:
                      description: 生成提示词，长度必须在 3-5000 字符之间。（最大长度：5000 字符）
                      type: string
                      maxLength: 5000
                      example: >-
                        A humanoid figure with a vintage television set for a
                        head, featuring a green-tinted screen displaying a
                        `Hello FLUX.2` writing in ASCII font. The figure is
                        wearing a yellow raincoat, and there are various wires
                        and components attached to the television. The
                        background is cloudy and indistinct, suggesting an
                        outdoor setting
                    aspect_ratio:
                      description: 生成图像的宽高比。选择 `auto` 时会匹配首张输入图像的比例（需传入输入图像）。
                      type: string
                      enum:
                        - '1:1'
                        - '4:3'
                        - '3:4'
                        - '16:9'
                        - '9:16'
                        - '3:2'
                        - '2:3'
                        - auto
                      default: '1:1'
                      example: '1:1'
                    resolution:
                      description: 输出图像的分辨率。
                      type: string
                      enum:
                        - 1K
                        - 2K
                      default: 1K
                      example: 1K
                  required:
                    - prompt
                    - aspect_ratio
                    - resolution
            example:
              model: flux-2/flex-text-to-image
              callBackUrl: https://your-domain.com/api/callback
              input:
                prompt: >-
                  A humanoid figure with a vintage television set for a head,
                  featuring a green-tinted screen displaying a `Hello FLUX.2`
                  writing in ASCII font. The figure is wearing a yellow
                  raincoat, and there are various wires and components attached
                  to the television. The background is cloudy and indistinct,
                  suggesting an outdoor setting
                aspect_ratio: '1:1'
                resolution: 1K
      responses:
        '200':
          description: 请求成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          taskId:
                            type: string
                            description: 任务 ID，可用于调用任务详情端点查询任务状态
                            example: task_flux-2_1765175490366
              example:
                code: 200
                msg: success
                data:
                  taskId: task_flux-2_1765175490366
        '500':
          $ref: '#/components/responses/Error'
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          enum:
            - 200
            - 401
            - 402
            - 404
            - 422
            - 429
            - 455
            - 500
            - 501
            - 505
          description: |-
            响应状态码

            - **200**: 成功 - 请求已处理完成
            - **401**: 未授权 - 身份验证凭据缺失或无效
            - **402**: 积分不足 - 账户积分不足以执行该操作
            - **404**: 未找到 - 请求的资源或端点不存在
            - **422**: 验证错误 - 请求参数未通过校验
            - **429**: 速率限制 - 已超出该资源的请求频次限制
            - **455**: 服务不可用 - 系统正在维护中
            - **500**: 服务器错误 - 处理请求时发生意外故障
            - **501**: 生成失败 - 内容生成任务执行失败
            - **505**: 功能禁用 - 当前请求的功能暂未开放
        msg:
          type: string
          description: 响应消息，请求失败时为错误描述
          example: success
  responses:
    Error:
      description: 服务器错误
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: |-
        所有 API 都需要通过 Bearer Token 进行身份验证。

        获取 API Key：
        1. 访问 [API Key 管理页面](https://app.apikley.ru/keys) 获取您的 API Key

        使用方法：
        在请求头中添加：
        Authorization: Bearer APIKLEY_API_KEY

        注意事项：
        - 请妥善保管您的 API Key，切勿泄露给他人
        - 若怀疑 API Key 泄露，请立即在管理页面重置