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 textimage_url: an imagefile: a document or other fileinput_audio: audio inwavormp3format
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:
file_url: a publicly reachablehttpsaddress. We fetch the file ourselves.file_data: the file as Base64, together withfilename. Data sent directly is limited to 8 MiB in total per request.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"
purposeisuser_dataorvision.- A file can be at most 32 MiB. The API rejects larger files with
413 file_too_large. - The response contains the
idthat you later use asfile_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 /modelsundercapabilities.vision. Otherwise you get400 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_modelwith an image: The model has no image recognition. Choose a model withvision: 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.