Pictomancer.ai Convert API

openapi: 3.2.0
info:
  title: Pictomancer.ai Gateway Convert API
  version: 0.1.0
tags:
- name: Convert
paths:
  /v1/convert:
    post:
      summary: Convert image format
      description: 'Convert an image to a different format (jpeg, png, webp, tiff, gif, avif). Optionally set quality, strip metadata, enable lossless mode (webp, avif), or tune encoder effort (avif). 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). Optional enhancement modifiers: denoise (1-3), equalize, sharpen (applied denoise -> equalize -> op -> sharpen).'
      operationId: convert_image
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConvertRequest'
        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:
      - Convert
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
    ConvertRequest:
      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,...).'
        format:
          type: string
          title: Format
          description: 'Target format: jpeg, png, webp, tiff, gif, or avif.'
        q:
          anyOf:
          - type: integer
          - type: 'null'
          title: Q
          description: Quality (1-100). Maps to libvips Q parameter.
        strip:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Strip
          description: Strip metadata (EXIF, ICC profile, etc.) from the output.
        lossless:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Lossless
          description: Enable lossless encoding. Only applies to webp and avif.
        effort:
          anyOf:
          - type: integer
          - type: 'null'
          title: Effort
          description: AV1 encoder CPU effort (0-9). Higher = smaller file, slower. Only applies to avif.
        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 and with lossless. Only for jpeg, webp, avif. Carries a flat surcharge for the extra encodes.'
        autorot:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Autorot
          description: Apply EXIF orientation before converting. Opt-in; default false, which preserves current byte-for-byte behavior.
        denoise:
          anyOf:
          - type: integer
          - type: 'null'
          title: Denoise
          description: 'Median denoise before converting: 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 converting. Opt-in.
        sharpen:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Sharpen
          description: Unsharp-mask sharpen after converting (libvips defaults). Opt-in.
      additionalProperties: true
      type: object
      required:
      - source
      - format
      title: ConvertRequest
    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
    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