Files

Upload a document or image with POST /files, then send its file_id in a request. Olive reads the text, so you can ask about a discharge summary, a lab report or a scanned referral letter without pasting it into the prompt.

When to use it

The file fits the context window with your prompt and the answer. For larger documents, use a vector store.
You ask about one or a few documents in a request.
The document is a scan in English or Arabic.

The SDK samples assume the client from the Quickstart.

Upload

Any file type uploads. Olive reads it the first time a request uses it, so a format it cannot read is refused then, not at upload. Upload an image the same way as a document.

De-identify before you upload

Do not upload protected health information. Remove names, contact details, identifiers and dates of birth first. A file stays until you delete it.

curl https://api.avey.ai/llm/files \
  -H "Authorization: Bearer $AVEY_API_KEY" \
  -F purpose=user_data \
  -F file=@discharge-summary.pdf

Ask about the file

Put an input_file part in the message content. Use input_image for an image.

curl https://api.avey.ai/llm/responses \
  -H "Authorization: Bearer $AVEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "olive",
    "input": [{
      "role": "user",
      "content": [
        { "type": "input_text", "text": "List every medication and its dose." },
        { "type": "input_file", "file_id": "file-..." }
      ]
    }]
  }'

The Go samples reuse the Quickstart client. Add the imports each sample uses.

On Chat Completions, send a file or an image as a file part with the same file_id.

Read a file ahead

The first request that uses a file reads it, and a long scan can take minutes. Right after the upload, send the file to POST /responses/input_tokens. It reads and keeps the text, returns the file's token count, and is not billed.

curl https://api.avey.ai/llm/responses/input_tokens \
  -H "Authorization: Bearer $AVEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "olive",
    "input": [{
      "role": "user",
      "content": [{ "type": "input_file", "file_id": "file-..." }]
    }]
  }'

The answer is {"object": "response.input_tokens", "input_tokens": ...}. A 400 here means the file cannot be read, so you learn it before a user waits on it.

Limits

Limit	Value
File size	5 MB
Pages per document	100
File types	Any type uploads. HEIC and HEIF photos cannot be read. Convert them to PNG first.
Scanned pages	Read in English and Arabic
Retention	A file stays until you delete it.

Errors

Status	Message	What to do
413	`the file is over 5 MB, the most that can be uploaded`	Send a smaller file.
503	`file transfers are busy; retry later`	Retry after the `Retry-After` header.
400	`send files and images as file_id: upload them with POST /v1/files first`	A file or image was sent inline, as a URL, or as an `image_url` part. Upload it, then send its `file_id`.
400	`this file's format cannot be read: {file_id}`	Convert the file to PDF, plain text or PNG.
400	`file {file_id} took too long to read; send a shorter file`	Split the file.
400	`file {file_id} is too complex to read; send a smaller file`	Split the file.
400	`no readable content in file {file_id}`	The file has no text and no picture Olive can describe. Check the file.
400	`file {file_id} is over 5 MB, the most that can be read`	The file was uploaded before the limit was lowered. Upload a smaller file.
400	`no such file: {file_id}`	The request names a file that does not exist or belongs to another user. Check the ID.
404	`no such file: {file_id}`	Retrieve or delete of a file that does not exist or belongs to another user.
502	`file processing is unavailable; retry later`	Retry. If the file was still being read, the reading carries on and a later request uses the text.
502	`file deletion is unavailable; retry later`	Retry the delete.

Errors use OpenAI's error body, with type and message and no code field. Match on the status and the message. A rejected request does not run the model.

Things to know

The full text of each file goes into the prompt, and nothing trims it. Count the input before you send it. Keep the total within 65,536 tokens.
Olive reads text only. For an image, and for each picture in a document, Olive reads a text description. It does not see the image, so a finding that shows only in a picture can be missed. detail on an input_image part has no effect.
Deleting a file also removes it from every vector store that holds it. Stored responses keep the file text they used. Delete those responses too. See Conversation state.