openapi: 3.0.3
info:
  title: OG Image API
  version: 0.2.0
  description: Generate deterministic 1200x630 Open Graph images with template and theme presets for articles and AI agents.
servers:
  - url: https://twittershots.com
    description: Production
paths:
  /api/og-image:
    get:
      operationId: renderOgImage
      summary: Render an OG image from URL parameters
      parameters:
        - $ref: "#/components/parameters/Title"
        - $ref: "#/components/parameters/Description"
        - $ref: "#/components/parameters/SiteName"
        - $ref: "#/components/parameters/Category"
        - $ref: "#/components/parameters/Accent"
        - $ref: "#/components/parameters/Template"
        - $ref: "#/components/parameters/Theme"
      responses:
        "200":
          description: A 1200x630 PNG image
          content:
            image/png:
              schema:
                type: string
                format: binary
        "400":
          description: Invalid parameters
    post:
      operationId: generateOgImage
      summary: Generate an OG image URL or PNG
      description: The default response is agent-friendly JSON. Set response to image for PNG bytes.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateOgImageRequest"
      responses:
        "200":
          description: Generated image metadata or PNG bytes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenerateOgImageResponse"
            image/png:
              schema:
                type: string
                format: binary
        "400":
          description: Invalid request body
        "401":
          description: Missing X-API-KEY header
        "403":
          description: Invalid or inactive X-API-KEY
        "503":
          description: Authentication service unavailable
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Use the TwitterShots API key created at https://twittershots.com/settings/keys.
  parameters:
    Title:
      name: title
      in: query
      required: true
      schema:
        type: string
        maxLength: 110
    Description:
      name: description
      in: query
      schema:
        type: string
        maxLength: 180
    SiteName:
      name: siteName
      in: query
      schema:
        type: string
        maxLength: 40
    Category:
      name: category
      in: query
      schema:
        type: string
        maxLength: 32
    Accent:
      name: accent
      in: query
      schema:
        type: string
        pattern: '^#[0-9a-fA-F]{6}$'
        example: "#1d9bf0"
    Template:
      name: template
      in: query
      schema:
        type: string
        enum: [editorial, gradient-title]
        default: editorial
    Theme:
      name: theme
      in: query
      description: Applied by the gradient-title template.
      schema:
        type: string
        enum: [ocean, sunset, violet, midnight, emerald]
        default: ocean
  schemas:
    GenerateOgImageRequest:
      type: object
      required: [title]
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 110
        description:
          type: string
          maxLength: 180
        siteName:
          type: string
          maxLength: 40
        category:
          type: string
          maxLength: 32
        accent:
          type: string
          pattern: '^#[0-9a-fA-F]{6}$'
          example: "#1d9bf0"
        template:
          type: string
          enum: [editorial, gradient-title]
          default: editorial
        theme:
          type: string
          description: Applied by the gradient-title template.
          enum: [ocean, sunset, violet, midnight, emerald]
          default: ocean
        response:
          type: string
          enum: [json, image]
          default: json
    GenerateOgImageResponse:
      type: object
      required: [name, imageUrl, width, height, contentType, alt, template, theme, metadata]
      properties:
        name:
          type: string
          example: OG Image API
        imageUrl:
          type: string
          format: uri
        width:
          type: integer
          example: 1200
        height:
          type: integer
          example: 630
        contentType:
          type: string
          example: image/png
        alt:
          type: string
        template:
          type: string
          enum: [editorial, gradient-title]
        theme:
          type: string
          enum: [ocean, sunset, violet, midnight, emerald]
        metadata:
          type: object
          additionalProperties: true