Batch Multimodal Inference: Images and PDFs at ~40% Off

Vision and document requests are the most expensive calls most teams make. An image or a multi-page PDF in the prompt multiplies input tokens, and running those requests through a real-time API means paying the real-time premium on every one. Here is the irony: they are also the workloads that least need to be instant. Nobody sits refreshing a page while a model reads 10,000 receipts. Classifying screenshots, extracting fields from invoices, summarizing contracts — these run in the background by nature, which makes them the single best candidate for batch pricing.

Convoy now supports exactly that. On the Starter and Pro plans, you can upload images and PDFs to your project, then reference them by ID in batch requests — same one-endpoint workflow, now with files.

What shipped: project Files

Every Convoy project now has a Files store, and uploading files for multimodal batches is included on the Starter and Pro plans:

• Upload via the dashboard or the API. The API issues short-lived presigned grants and your bytes go straight to S3 — they never transit Convoy's servers.
• Every file is validated and malware-scanned before it can be used. Content types are verified from the actual bytes (not the filename), images are checked against provider dimension limits, PDFs against page caps, and every object passes a malware scan before it reaches ready.
• A simple lifecycle. Files move uploading → validating → ready, carry a TTL (30 days by default), and are pinned automatically while a batch that references them is in flight — a file cannot expire out from under your job.
• Reference by ID in /cargo/load. Message content accepts image and document blocks alongside text, each pointing at a file_id.

Current limits: images up to 20 MB, PDFs up to 50 MB and 100 pages, and up to 20 file references per request.

Walkthrough: from PDF to batch result

Three steps: create an upload session, upload the bytes, then submit batch requests that reference the file.

1. Create the file. Declare the name, type, size, and SHA-256 of the bytes you are about to upload (shasum -a 256 receipt.png gives you the digest):

curl -X POST https://api.cnvy.ai/files \
  -H "Content-Type: application/json" \
  -H "X-API-Key: convoy_sk_your_key_here" \
  -d '{
    "filename": "receipt.png",
    "media_type": "image/png",
    "size_bytes": 482113,
    "sha256": "9c56cc51b374c3ba189210d5b6d4bf57790d351c96c47c02190ecf1e430635ab"
  }'

The response includes a file ID and a presigned upload grant. The declared size and checksum are signed into the grant, so S3 itself rejects any bytes that differ from what you committed to.

2. Upload and finalize. POST the file to the presigned URL with the returned fields, then call complete. Convoy validates the bytes server-side and runs the malware scan:

curl -X POST "https://your-bucket.s3.amazonaws.com/" \
  -F key="files/…" -F policy="…" -F x-amz-signature="…" \
  -F file=@receipt.png

curl -X POST https://api.cnvy.ai/files/file_9f8e7d6c5b4a3210fedcba9876543210/complete \
  -H "X-API-Key: convoy_sk_your_key_here" \
  -d '{}'

When validation and scanning pass, the file returns "status": "ready" and can be referenced in batches.

3. Submit batch requests that reference the file. Content blocks accept image and document types with a file source:

curl -X POST https://api.cnvy.ai/cargo/load \
  -H "Content-Type: application/json" \
  -H "X-API-Key: convoy_sk_your_key_here" \
  -d '{
    "params": {
      "model": "claude-sonnet-4.5",
      "max_tokens": 1024,
      "messages": [{
        "role": "user",
        "content": [
          {"type": "text", "text": "Extract the vendor, date, and total from this receipt as JSON."},
          {"type": "image", "source": {"type": "file", "file_id": "file_9f8e7d6c5b4a3210fedcba9876543210"}}
        ]
      }]
    },
    "callback_url": "https://your-server.com/callback"
  }'

From here it works like any Convoy request: you get a cargo_id back immediately, Convoy groups requests into batches, runs them at batch pricing, and delivers results to your callback. PDFs work the same way with a document block. The models catalog shows which models support vision and document input.

Patterns worth knowing

Upload once, prompt thousands of times. A file_id is reusable across as many requests as you like, within your plan's monthly token quota and rate limits. Asking fifty different questions about the same contract means one upload and fifty cheap batch requests — you never re-send the bytes, and the file stays pinned until every referencing batch completes.

Document pipelines. Insurance claims, contract review, invoice extraction, lab-report triage: these are high-volume, latency-tolerant, and heavy on input tokens — exactly where the batch discount, which lands around 40 percent in practice, pays for itself fastest.

Backlog runs. Have an archive of scanned documents or screenshots? Upload the set, fan out one request per file, and let the batch window do the work overnight. There is no minimum volume and nothing to schedule.

Running self-hosted?

Convoy Enterprise gets the same Files API in your own AWS account. Uploads land in your S3 bucket, malware scanning runs on your GuardDuty, and no file bytes ever leave your infrastructure — the workflow above is identical.

Vision and document workloads are the most expensive thing on your AI bill and the easiest thing to batch. Create a Convoy account and run your first multimodal batch in minutes, see the pricing, or read the API docs.