FlowModels

Send images, PDFs and audio to a model

Published on 11. November 2026

Besides text, you can also send a model images, PDFs, Office documents and audio, for example to have an invoice read or a photo described. The attachments go directly into the message, in OpenAI's format. Here's which options exist, how large attachments can be, and what happens when a model doesn't understand a file type by itself.

Attachments in a message

Instead of plain text, you send a list of blocks in content. These types are allowed:

  • text: normal text
  • image_url: an image
  • file: a document or other file
  • input_audio: audio in wav or mp3 format

Attachments are only allowed in messages with role: "user". In system, assistant or tool messages, the API rejects them with 400 unsupported_field.

{
  "model": "openai/gpt-5.6-luna",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "What can be seen in the photo?"},
      {"type": "image_url", "image_url": {"url": "https://www.example.de/bilder/lager.jpg"}}
    ]
  }]
}

Three ways to pass a file

A file block contains exactly one of these sources:

  1. file_url: a publicly reachable https address. We fetch the file ourselves.
  2. file_data: the file as Base64, together with filename. Data sent directly is limited to 8 MiB in total per request.
  3. file_id: a file you uploaded beforehand (see below).
{"type": "file", "file": {"file_id": "file-018f1234-5678-7abc-9def-0123456789ab"}}

Images go through image_url as an https address or as a data: address with Base64. If you send several sources at once in one block, the request is rejected.

Upload files beforehand

For large files, or if you need the same file several times, upload it once:

curl -X POST https://api.flowmodels.one/v1/files \
  -H "Authorization: Bearer at_your_key" \
  -F "file=@invoice-2026-117.pdf" \
  -F "purpose=user_data"
  • purpose is user_data or vision.
  • A file can be at most 32 MiB. The API rejects larger files with 413 file_too_large.
  • The response contains the id that you later use as file_id.
  • Uploaded files stay stored until you delete them. There is no automatic deletion period. Delete files you no longer need with DELETE /v1/files/{id}.

GET /v1/files lists your files, GET /v1/files/{id} shows only the file's details, and GET /v1/files/{id}/content downloads the content.

What the model does with the attachment

  • Images and videos are only seen by a model that supports this type. Whether it understands images is shown in GET /models under capabilities.vision. Otherwise you get 400 unsupported_for_model.
  • Documents that a model can't read by itself are converted to text first. The model then receives the extracted text.
  • Audio that a model can't hear by itself is transcribed first. This transcription is billed additionally.

How this differs from end-user files

Attachments on a message go directly to the model and only for this request. If you want to permanently assign documents to an end user of your application, for the Brain to draw on in later questions, use end-user files, see Upload documents for an end user and use them as context.

If something goes wrong

  • 400 unsupported_for_model with an image: The model has no image recognition. Choose a model with vision: true.
  • 400 unsupported_field: The attachment isn't in a user message, or the block type is unknown.
  • File URL is rejected: It must start with https:// and be publicly reachable. Internal addresses and addresses that require a login don't work.
  • 413 file_too_large: A file is larger than 32 MiB, or the data sent directly exceeds 8 MiB. Reduce the file size, upload it beforehand or pass a URL.

Was this article helpful?

Back to Models, limits & errors