openapi: 3.1.0
info:
  title: Memesio API Contracts agent-infra ai-providers API
  version: 0.1.0
  description: Contract baseline for AI jobs, trend alerts, collaboration, and billing surfaces.
servers:
- url: /
tags:
- name: ai-providers
paths:
  /api/ai/memes/generate:
    get:
      summary: Read the Current Actor's Daily AI Meme Quota, Remaining Generations, and Next Action
      tags:
      - ai-providers
      security:
      - DeveloperApiKeyAuth: []
      - AgentApiKeyAuth: []
      - {}
      responses:
        '200':
          description: Current actor AI quota snapshot
    post:
      summary: Select an Existing Meme Template, Generate Captions, and Return Editor-Ready Meme Variants
      tags:
      - ai-providers
      security:
      - DeveloperApiKeyAuth: []
      - AgentApiKeyAuth: []
      - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - prompt
              properties:
                mode:
                  type: string
                  enum:
                  - template
                prompt:
                  type: string
                  minLength: 1
                  maxLength: 500
                flow:
                  type: string
                  enum:
                  - text_to_meme
                captionSource:
                  type: string
                  enum:
                  - input
                  - prompt
                imageUrl:
                  type: string
                templateId:
                  type: string
                captions:
                  type: array
                  items:
                    type: string
                  maxItems: 6
                editableCaptions:
                  type: array
                  items:
                    $ref: '#/components/schemas/MemeCaption'
                  maxItems: 8
                tone:
                  type: string
                  enum:
                  - sarcastic
                  - deadpan
                  - wholesome
                  - absurd
                  - corporate
                  - dark-lite
                  - brand
                toneCues:
                  type: array
                  items:
                    type: string
                  maxItems: 6
                rewriteNote:
                  type: string
                  maxLength: 160
                allowHeuristicFallback:
                  type: boolean
                variantCount:
                  type: number
                  minimum: 1
                  maximum: 5
                preferredProviderId:
                  type: string
                  enum:
                  - hyperswitch_vision
                  - onnx_local
                  - openai_vision
                workspaceId:
                  type: string
                correlationId:
                  type: string
      responses:
        '200':
          description: Meme variant generation payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiMemeGenerationSucceededResponse'
        '400':
          description: Validation error
        '429':
          description: Daily AI quota exceeded
        '500':
          description: Provider execution failure
  /api/ai/templates/suggest:
    post:
      summary: Rank Template Suggestions from Prompt + Trend Signals for Creative Ideation Flow
      tags:
      - ai-providers
      security:
      - DeveloperApiKeyAuth: []
      - AgentApiKeyAuth: []
      - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - prompt
              properties:
                prompt:
                  type: string
                  minLength: 1
                trendSignals:
                  type: array
                  items:
                    type: string
                  maxItems: 20
                limit:
                  type: number
                  minimum: 1
                  maximum: 60
      responses:
        '200':
          description: Template suggestion ranking payload
        '400':
          description: Validation error
  /api/ai/templates/detect:
    post:
      summary: Detect Meme Template from Source Image and Return 1-2 Caption Slot Placement with Single/Split Assignment Plan
      tags:
      - ai-providers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - sourceImageUrl
              properties:
                sourceImageUrl:
                  type: string
                texts:
                  type: array
                  items:
                    type: string
                  maxItems: 2
                maxSlots:
                  type: integer
                  minimum: 1
                  maximum: 2
                mappingMode:
                  type: string
                  enum:
                  - single_or_split
                actorId:
                  type: string
                workspaceId:
                  type: string
                correlationId:
                  type: string
      responses:
        '200':
          description: Template detection payload
        '400':
          description: Validation error
        '500':
          description: Detection failure
  /api/ai/providers/face-swap-benchmark:
    get:
      summary: Run or Retrieve Face-Swap Provider Benchmark and Recommendation
      tags:
      - ai-providers
      parameters:
      - name: refresh
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Face-swap provider benchmark report
  /api/ai/providers/background-remove-benchmark:
    get:
      summary: Run or Retrieve Background-Remove Provider Benchmark and Recommendation
      tags:
      - ai-providers
      parameters:
      - name: refresh
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Background-remove provider benchmark report
  /api/v1/templates/ideas:
    post:
      summary: Return Ranked Meme Template Ideas for a Prompt Using a Developer or Agent Key
      tags:
      - ai-providers
      security:
      - DeveloperApiKeyAuth: []
      - AgentApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - prompt
              properties:
                prompt:
                  type: string
                  minLength: 1
                trendSignals:
                  type: array
                  items:
                    type: string
                  maxItems: 20
                limit:
                  type: number
                  minimum: 1
                  maximum: 60
      responses:
        '200':
          description: Template idea ranking payload
        '400':
          description: Validation error
        '401':
          description: Developer or agent API key required
        '429':
          description: Rate limit exceeded
  /api/v1/memes/generate:
    get:
      summary: Read the Keyed Actor's Daily AI Meme Quota Snapshot
      tags:
      - ai-providers
      security:
      - DeveloperApiKeyAuth: []
      - AgentApiKeyAuth: []
      responses:
        '200':
          description: Current keyed actor AI quota snapshot
        '401':
          description: Developer or agent API key required
    post:
      summary: Generate AI Meme Variants Synchronously for a Developer or Standalone Agent Key
      tags:
      - ai-providers
      security:
      - DeveloperApiKeyAuth: []
      - AgentApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - prompt
              properties:
                mode:
                  type: string
                  enum:
                  - template
                prompt:
                  type: string
                  minLength: 1
                  maxLength: 500
                flow:
                  type: string
                  enum:
                  - text_to_meme
                captionSource:
                  type: string
                  enum:
                  - input
                  - prompt
                imageUrl:
                  type: string
                templateId:
                  type: string
                captions:
                  type: array
                  items:
                    type: string
                  maxItems: 6
                editableCaptions:
                  type: array
                  items:
                    $ref: '#/components/schemas/MemeCaption'
                  maxItems: 8
                tone:
                  type: string
                  enum:
                  - sarcastic
                  - deadpan
                  - wholesome
                  - absurd
                  - corporate
                  - dark-lite
                  - brand
                toneCues:
                  type: array
                  items:
                    type: string
                  maxItems: 6
                rewriteNote:
                  type: string
                  maxLength: 160
                allowHeuristicFallback:
                  type: boolean
                variantCount:
                  type: number
                  minimum: 1
                  maximum: 5
                preferredProviderId:
                  type: string
                  enum:
                  - hyperswitch_vision
                  - onnx_local
                  - openai_vision
                workspaceId:
                  type: string
                correlationId:
                  type: string
      responses:
        '200':
          description: Meme variant generation payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiMemeGenerationSucceededResponse'
        '400':
          description: Validation error
        '401':
          description: Developer or agent API key required
        '429':
          description: Daily AI quota exceeded
        '500':
          description: Provider execution failure
components:
  schemas:
    AiMemeGenerationSucceededResponse:
      type: object
      required:
      - ok
      - flow
      - mode
      - status
      - variantCount
      - variants
      properties:
        ok:
          type: boolean
          const: true
        runId:
          type: string
        flow:
          type: string
          enum:
          - text_to_meme
        mode:
          type: string
          enum:
          - template
        status:
          type: string
          const: succeeded
        variantCount:
          type: integer
          minimum: 0
        variants:
          type: array
          items:
            $ref: '#/components/schemas/MemeGenerationVariant'
        degradedFromAsync:
          type: boolean
    MemeGenerationVariant:
      type: object
      required:
      - id
      - mode
      - providerId
      - variantKind
      - memeUrl
      - pageUrl
      - templateName
      - fallbackUsed
      - attempts
      - estimatedCostUsd
      properties:
        id:
          type: string
        mode:
          type: string
          enum:
          - template
        providerId:
          type: string
        variantKind:
          type: string
          enum:
          - template_captioned
          - rendered_image
        memeUrl:
          type:
          - string
          - 'null'
        pageUrl:
          type:
          - string
          - 'null'
        templateName:
          type:
          - string
          - 'null'
        templateSlug:
          type:
          - string
          - 'null'
        sourceImageUrl:
          type:
          - string
          - 'null'
        templateSelectionStrategy:
          type:
          - string
          - 'null'
          enum:
          - provided_template
          - provided_image
          - library_search
          - recommendation
          - null
        captionGenerationStrategy:
          type:
          - string
          - 'null'
          enum:
          - openai
          - heuristic
          - provided
          - null
        captions:
          type: array
          items:
            $ref: '#/components/schemas/MemeCaption'
        editable:
          type: boolean
        fallbackUsed:
          type: boolean
        attempts:
          type: array
          items:
            type: object
            additionalProperties: true
        estimatedCostUsd:
          type: number
          minimum: 0
    MemeCaption:
      type: object
      required:
      - id
      - text
      - x
      - y
      - fontSize
      properties:
        id:
          type: string
        text:
          type: string
        x:
          type: number
        y:
          type: number
        fontSize:
          type: number
        rotationDeg:
          type: number
        hidden:
          type: boolean
        locked:
          type: boolean
        boxWidthPct:
          type: number
        boxHeightPct:
          type: number
        paddingPct:
          type: number
        maxLines:
          type: integer
        lineHeight:
          type: number
        backgroundEnabled:
          type: boolean
        backgroundColor:
          type: string
        backgroundOpacity:
          type: number
        letterSpacingEm:
          type: number
        shadowStrength:
          type: number
        color:
          type: string
        stroke:
          type: string
        fontFamily:
          type: string
          enum:
          - impact
          - arial
        textAlign:
          type: string
          enum:
          - left
          - center
          - right
        semanticRole:
          type: string
          enum:
          - setup
          - contrast
          - punchline
          - reaction
          - label
        preferredCase:
          type: string
          enum:
          - uppercase
          - sentence
          - title
          - preserve
        exampleText:
          type: string
        recommendedWordsMin:
          type: integer
          minimum: 1
        recommendedWordsMax:
          type: integer
          minimum: 1
        recommendedCharsMin:
          type: integer
          minimum: 1
        recommendedCharsMax:
          type: integer
          minimum: 1
  securitySchemes:
    DeveloperApiKeyAuth:
      type: apiKey
      in: header
      name: x-developer-api-key
      description: 'Optional higher-rate free-tier auth. You can also send the key as Authorization: Bearer <key>.'
    AgentApiKeyAuth:
      type: apiKey
      in: header
      name: x-agent-api-key
      description: 'Agent auth for free endpoints and agent-admin routes. You can also send the key as Authorization: Bearer <key>.'