openapi: 3.2.0
info:
  title: Pictomancer.ai Gateway Optimize For Vision API
  version: 0.1.0
tags:
- name: Optimize For Vision
paths:
  /v1/optimize_for_vision:
    post:
      summary: Resize an image for a vision model
      description: 'Resize an image to the largest size a given vision model still benefits from, and report what it costs that model in tokens before and after. Every provider downscales oversized input before counting tokens, so this alone saves bytes and upload latency rather than tokens. Pass max_tokens to trade resolution for tokens: that lever is continuous on Claude, unavailable on OpenAI (cost follows the aspect ratio alone), and on Gemini reaches only a flat 258. An image already within budget is returned untouched and free (X-Pig-Billed: 0).'
      operationId: optimize_for_vision
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OptimizeForVisionRequest'
        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:
      - Optimize For Vision
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
    OptimizeForVisionRequest:
      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,...).'
        target_model:
          type: string
          title: Target Model
          description: 'Vision model the image is being prepared for, e.g. claude-opus-5, gpt-4o, gemini-2.5-pro. Unknown ids are rejected rather than guessed: the wrong limits would silently resize to the wrong size.'
        max_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Tokens
          description: 'Optional cap on what the image may cost the target model. Without it the image is resized to the model''s own ceiling, which saves bytes and upload latency but no tokens, because every provider already downscales oversized input before counting. Set a budget to trade resolution for tokens. The response reports the cost actually achieved: on OpenAI it cannot be lowered by resizing at all, and on Gemini only down to a flat 258.'
        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.'
        q:
          anyOf:
          - type: integer
          - type: 'null'
          title: Q
          description: Quality (1-100). Maps to libvips Q parameter.
      additionalProperties: true
      type: object
      required:
      - source
      - target_model
      title: OptimizeForVisionRequest
    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