openapi: 3.2.0
info:
  title: Pictomancer.ai Gateway Compress API
  version: 0.1.0
tags:
- name: Compress
paths:
  /v1/compress:
    post:
      summary: Compress an image
      description: 'Re-encode an image with quality/format options to reduce file size. Supports jpeg, png, webp, tiff, gif. Instead of a q number you can set quality_target (0-1]: the smallest file with SSIM at or above the target, searched on the worker (jpeg, webp, avif; flat surcharge; outcome reported in X-Pictomancer-Quality-* headers). If the output is not smaller than the input, the request is free (X-Pig-Billed: 0) and does not consume free-tier quota. Optional enhancement modifiers: denoise (1-3), equalize, sharpen (applied denoise -> equalize -> op -> sharpen).'
      operationId: compress_image
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompressRequest'
        required: true
      responses:
        '200':
          description: Processed image binary
          content:
            application/json:
              schema: {}
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Compress
components:
  schemas:
    PutUrlDelivery:
      properties:
        mode:
          type: string
          const: put_url
          title: Mode
        put_url:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Put Url
          description: Customer-signed presigned PUT URL where the optimized bytes will be written. Must be https://. Cloud credentials never reach our infrastructure; only the URL itself is used and discarded after the request.
        headers:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Headers
          description: Optional storage headers to include on the PUT call (Content-Type, Cache-Control, x-amz-acl, etc.). Whitelisted at SSRF layer.
      additionalProperties: false
      type: object
      required:
      - mode
      - put_url
      title: PutUrlDelivery
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    InlineDelivery:
      properties:
        mode:
          type: string
          const: inline
          title: Mode
          default: inline
      additionalProperties: false
      type: object
      title: InlineDelivery
    CompressRequest:
      properties:
        delivery:
          oneOf:
          - $ref: '#/components/schemas/InlineDelivery'
          - $ref: '#/components/schemas/PutUrlDelivery'
          - $ref: '#/components/schemas/CallbackDelivery'
          title: Delivery
          discriminator:
            propertyName: mode
            mapping:
              callback_url: '#/components/schemas/CallbackDelivery'
              inline: '#/components/schemas/InlineDelivery'
              put_url: '#/components/schemas/PutUrlDelivery'
        source:
          type: string
          title: Source
          description: 'Image source: a public URL (https://...) or a base64-encoded string (optionally as a data URI like data:image/png;base64,...).'
        q:
          anyOf:
          - type: integer
          - type: 'null'
          title: Q
          description: 'Quality (1-100). Lower = smaller file. Typical values: 60-80 for web, 85-95 for print. Maps to libvips Q parameter.'
        format:
          anyOf:
          - type: string
          - type: 'null'
          title: Format
          description: 'Output format: jpeg, png, webp, tiff, gif, or avif. If omitted, the original format is preserved.'
        strip:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Strip
          description: Strip metadata (EXIF, ICC profile, etc.) from the output. Reduces file size slightly.
        quality_target:
          anyOf:
          - type: number
          - type: 'null'
          title: Quality Target
          description: 'Target SSIM (0-1]: the worker searches for the smallest file that still scores at least this. Alternative to q; mutually exclusive with it. Requires an explicit format among jpeg, webp, avif. Carries a flat surcharge for the extra encodes.'
        autorot:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Autorot
          description: Apply EXIF orientation before compressing. Opt-in; default false, which preserves current byte-for-byte behavior.
        denoise:
          anyOf:
          - type: integer
          - type: 'null'
          title: Denoise
          description: 'Median denoise before compressing: radius 1-3 (window 3x3 to 7x7). Opt-in; no surcharge.'
        equalize:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Equalize
          description: Auto-contrast (histogram equalisation of the value channel; hue and saturation preserved) before compressing. Opt-in.
        sharpen:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Sharpen
          description: Unsharp-mask sharpen after compressing (libvips defaults). Opt-in.
      additionalProperties: true
      type: object
      required:
      - source
      title: CompressRequest
    CallbackDelivery:
      properties:
        mode:
          type: string
          const: callback_url
          title: Mode
        callback_url:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Callback Url
          description: Customer endpoint where the optimized bytes will be POSTed. Must be https://. For async/large jobs. We send an X-Pig-Sha256 header of the body so the receiver can verify integrity. No credentials are stored on our side; secure the endpoint with a token in the URL itself.
        headers:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Headers
          description: Optional headers to include on the POST call (Content-Type, Cache-Control, x-amz-*, etc.). Whitelisted at SSRF layer.
        secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Secret
          description: 'Optional HMAC secret. When set, we sign the POST body with HMAC-SHA256 and send ''X-Pig-Signature: sha256=<hex>''. Used per request and never stored. Recompute the HMAC on your endpoint to authenticate the callback (constant-time compare).'
      additionalProperties: false
      type: object
      required:
      - mode
      - callback_url
      title: CallbackDelivery