openapi: "3.1.0"
info:
  title: "Flux AI API"
  version: "1.0.0"
  summary: "Public API for Flux AI image generation, ecommerce product photos, ad creatives, and generation task automation."
  description: "Flux AI exposes authenticated REST endpoints for AI agents and backend integrations to create image generation tasks, poll task status, inspect available models, and wire callbacks into product photo and ecommerce visual workflows."
  contact:
    name: "Flux AI Support"
    email: "support@fluxaipro.art"
    url: "https://fluxaipro.art/contact"
servers:
  -
    url: "https://fluxaipro.art"
    description: "Flux AI production"
externalDocs:
  description: "Flux AI developer resources"
  url: "https://fluxaipro.art/developers"
tags:
  -
    name: "AI Generations"
    description: "Create and monitor image generation tasks for product photos, ad creatives, ecommerce images, and brand visuals."
  -
    name: "Models"
    description: "Discover supported Flux AI image models and pricing."
  -
    name: "Agent Integration"
    description: "Resources for AI agents, MCP clients, and automation tools."
components:
  securitySchemes:
    bearerAuth:
      type: "http"
      scheme: "bearer"
      bearerFormat: "API key"
      description: "Use a Flux AI API key from the API Keys page as a Bearer token."
  schemas:
    GenerationTaskCreateRequest:
      type: "object"
      required:
        - "modality"
        - "params"
      properties:
        provider:
          type: "string"
          description: "Optional provider identifier. Omit to let Flux AI resolve the provider from model configuration."
          example: "sub2api"
        model:
          type: "string"
          description: "Model identifier, commonly in provider:model format."
          example: "sub2api:gpt-image-2"
        displayName:
          type: "string"
          description: "Human readable model name, such as Flux Dev, Flux 2 Pro, GPT Image 2, Qwen Image, Seedream 4, or Nano Banana Pro."
          example: "Flux 2 Pro"
        modality:
          type: "string"
          enum:
            - "image"
            - "text"
            - "video"
            - "audio"
          example: "image"
        subType:
          type: "string"
          enum:
            - "text-to-image"
            - "image-to-image"
          description: "Generation workflow type for image tasks."
          example: "text-to-image"
        params:
          type: "object"
          additionalProperties: true
          description: "Model-specific generation parameters such as prompt, negative prompt, size, image references, seed, and style controls."
          example:
            prompt: "Studio product photo of a matte black water bottle on a marble surface, softbox lighting, ecommerce hero image"
            aspectRatio: "1:1"
            outputFormat: "png"
        dedupeKey:
          type: "string"
          description: "Optional idempotency key. Reusing it returns the existing task rather than creating a duplicate."
        priority:
          type: "number"
          minimum: 1
          maximum: 10
          default: 5
        invokeType:
          type: "string"
          enum:
            - "await"
            - "poll"
            - "callback"
          default: "await"
        callbackUrl:
          type: "string"
          format: "uri"
          nullable: true
          description: "HTTPS callback URL used when invokeType is callback."
    GenerationTaskCreateResponse:
      type: "object"
      properties:
        taskId:
          type: "string"
          example: "739209234324812800"
        status:
          type: "string"
          example: "queued"
        invokeType:
          type: "string"
          example: "poll"
        createdAt:
          type: "string"
          format: "date-time"
    GenerationTask:
      type: "object"
      additionalProperties: true
      properties:
        id:
          type: "string"
        status:
          type: "string"
        model:
          type: "string"
        modality:
          type: "string"
        subType:
          type: "string"
        result:
          type: "object"
          additionalProperties: true
        error:
          type: "string"
          nullable: true
        createdAt:
          type: "string"
          format: "date-time"
        updatedAt:
          type: "string"
          format: "date-time"
    ModelListResponse:
      type: "object"
      additionalProperties: true
      properties:
        models:
          type: "array"
          items:
            type: "object"
            additionalProperties: true
    ErrorResponse:
      type: "object"
      properties:
        code:
          type: "string"
        message:
          type: "string"
security:
  -
    bearerAuth:
[]
paths:
  "/api/v1/ai/generations":
    post:
      tags:
        - "AI Generations"
      summary: "Create an AI image generation task"
      description: "Create a Flux AI generation task for product photos, ecommerce images, ad creatives, brand visuals, text-to-image, or image-to-image workflows."
      operationId: "createGenerationTask"
      security:
        -
          bearerAuth:
[]
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/GenerationTaskCreateRequest"
      responses:
        200:
          description: "Generation task created"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/GenerationTaskCreateResponse"
        401:
          description: "Missing or invalid API key"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    get:
      tags:
        - "AI Generations"
      summary: "List generation tasks"
      description: "List recent generation tasks for the authenticated Flux AI account."
      operationId: "listGenerationTasks"
      security:
        -
          bearerAuth:
[]
      parameters:
        -
          name: "page"
          in: "query"
          schema:
            type: "integer"
            minimum: 1
            default: 1
        -
          name: "pageSize"
          in: "query"
          schema:
            type: "integer"
            minimum: 1
            maximum: 100
            default: 20
      responses:
        200:
          description: "Generation task list"
          content:
            "application/json":
              schema:
                type: "object"
                additionalProperties: true
  "/api/v1/ai/generations/{taskId}":
    get:
      tags:
        - "AI Generations"
      summary: "Get a generation task"
      description: "Fetch status, output metadata, and error details for a generation task."
      operationId: "getGenerationTask"
      security:
        -
          bearerAuth:
[]
      parameters:
        -
          name: "taskId"
          in: "path"
          required: true
          schema:
            type: "string"
      responses:
        200:
          description: "Generation task"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/GenerationTask"
  "/api/v1/ai/generations/{taskId}/events":
    get:
      tags:
        - "AI Generations"
      summary: "Get generation task events"
      description: "Read the public status timeline for a Flux AI generation task."
      operationId: "getGenerationTaskEvents"
      security:
        -
          bearerAuth:
[]
      parameters:
        -
          name: "taskId"
          in: "path"
          required: true
          schema:
            type: "string"
      responses:
        200:
          description: "Generation task event list"
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  list:
                    type: "array"
                    items:
                      type: "object"
                      additionalProperties: true
  "/api/v1/ai/models":
    get:
      tags:
        - "Models"
      summary: "List available image models"
      description: "Discover Flux AI models available for ecommerce product photography, ad creatives, brand visuals, and general image generation."
      operationId: "listAiModels"
      security:
[]
      responses:
        200:
          description: "Available model list"
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ModelListResponse"
  "/mcp":
    get:
      tags:
        - "Agent Integration"
      summary: "Flux AI MCP Streamable HTTP endpoint"
      description: "Model Context Protocol endpoint for AI agents. See /mcp.json for the manifest."
      operationId: "getMcpEndpointInfo"
      security:
[]
      responses:
        200:
          description: "MCP endpoint metadata"
    post:
      tags:
        - "Agent Integration"
      summary: "Call Flux AI MCP tools"
      description: "JSON-RPC endpoint supporting initialize, tools/list, and tools/call for Flux AI generation automation."
      operationId: "callMcpTool"
      security:
        -
          bearerAuth:
[]
      responses:
        200:
          description: "JSON-RPC response"
