openapi: 3.1.0
info:
  title: Memesio API Contracts agent-infra developer-api API
  version: 0.1.0
  description: Contract baseline for AI jobs, trend alerts, collaboration, and billing surfaces.
servers:
- url: /
tags:
- name: developer-api
paths:
  /api/v1/templates/ideas:
    post:
      summary: Return Ranked Meme Template Ideas for a Prompt Using a Developer or Agent Key
      tags:
      - developer-api
      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/caption-template:
    post:
      summary: Render a Hosted Meme from a Stored Template Using Anonymous or Keyed Caption Input
      tags:
      - developer-api
      security:
      - DeveloperApiKeyAuth: []
      - AgentApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FreeCaptionMemeRequest'
      responses:
        '201':
          description: Captioned meme created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FreeCaptionMemeSuccessResponse'
        '400':
          description: Validation error or unsupported template
        '401':
          description: Invalid API key when one is provided
        '429':
          description: Rate limit exceeded
  /api/v1/memes/caption-upload:
    post:
      summary: Upload an Image, Place Top or Bottom Caption Boxes, and Store the Hosted Meme
      tags:
      - developer-api
      security:
      - DeveloperApiKeyAuth: []
      - AgentApiKeyAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              - captions
              properties:
                file:
                  type: string
                  format: binary
                captions:
                  type: string
                  description: JSON array of caption slot objects with text, x, y, boxWidthPct, boxHeightPct, fontSize, and alignment fields.
                title:
                  type: string
                  maxLength: 140
                visibility:
                  type: string
                  enum:
                  - private
                  - public
                watermark:
                  type: string
                  description: Optional JSON watermark object. Non-premium callers are forced to the default Memesio watermark; premium callers can customize enabled, text, position, and scale.
      responses:
        '201':
          description: Uploaded meme created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadCaptionMemeSuccessResponse'
        '400':
          description: Validation error
        '401':
          description: Invalid API key when one is provided
        '415':
          description: Unsupported upload content
        '429':
          description: Rate limit exceeded
  /api/v1/memes/generate:
    get:
      summary: Read the Keyed Actor's Daily AI Meme Quota Snapshot
      tags:
      - developer-api
      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:
      - developer-api
      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:
    FreeCaptionMemeSuccessResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          required:
          - slug
          - shareSlug
          - templateSlug
          - title
          - visibility
          - imageUrl
          - canonicalImageUrl
          - altText
          - tags
          - apiUrl
          - pageUrl
          - ownerToken
          - captions
          - watermark
          properties:
            slug:
              type: string
            shareSlug:
              type: string
            templateSlug:
              type: string
            title:
              type: string
            visibility:
              type: string
              enum:
              - private
              - public
            imageUrl:
              type: string
            canonicalImageUrl:
              type: string
            altText:
              type: string
            tags:
              type: array
              items:
                type: string
            apiUrl:
              type: string
            pageUrl:
              type: string
            ownerToken:
              type: string
            captions:
              type: array
              items:
                type: string
            watermark:
              $ref: '#/components/schemas/FreeMemeWatermark'
    CaptionInput:
      type: object
      required:
      - text
      properties:
        id:
          type: string
          maxLength: 64
        text:
          type: string
          maxLength: 300
        x:
          type: number
        y:
          type: number
        fontSize:
          type: number
        boxWidthPct:
          type: number
        boxHeightPct:
          type: number
        maxLines:
          type: integer
          minimum: 1
        textAlign:
          type: string
          enum:
          - left
          - center
          - right
        fontFamily:
          type: string
          enum:
          - impact
          - arial
    FreeMemeWatermark:
      type: object
      description: Caption API requests accept watermark input, but non-premium callers are forced to the default Memesio watermark. Premium callers can customize enabled, text, position, and scale.
      properties:
        enabled:
          type: boolean
        text:
          type: string
          maxLength: 64
        position:
          type: string
          enum:
          - top_left
          - top_right
          - bottom_left
          - bottom_right
        scale:
          type: number
          minimum: 0.6
          maximum: 3
    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
    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
    UploadCaptionMemeSuccessResponse:
      type: object
      required:
      - ok
      - data
      properties:
        ok:
          type: boolean
          const: true
        data:
          type: object
          required:
          - slug
          - shareSlug
          - templateSlug
          - title
          - visibility
          - sourceImageUrl
          - imageUrl
          - canonicalImageUrl
          - altText
          - tags
          - apiUrl
          - pageUrl
          - ownerToken
          - captions
          - watermark
          properties:
            slug:
              type: string
            shareSlug:
              type: string
            templateSlug:
              type: string
            title:
              type: string
            visibility:
              type: string
              enum:
              - private
              - public
            sourceImageUrl:
              type: string
            imageUrl:
              type: string
            canonicalImageUrl:
              type: string
            altText:
              type: string
            tags:
              type: array
              items:
                type: string
            apiUrl:
              type: string
            pageUrl:
              type: string
            ownerToken:
              type: string
            captions:
              type: array
              items:
                $ref: '#/components/schemas/CaptionInput'
            watermark:
              $ref: '#/components/schemas/FreeMemeWatermark'
    FreeCaptionMemeRequest:
      type: object
      required:
      - templateSlug
      - captions
      properties:
        templateSlug:
          type: string
        captions:
          type: array
          items:
            oneOf:
            - type: string
              maxLength: 300
            - $ref: '#/components/schemas/CaptionInput'
        title:
          type: string
          maxLength: 140
        visibility:
          type: string
          enum:
          - private
          - public
        watermark:
          $ref: '#/components/schemas/FreeMemeWatermark'
    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
  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>.'