API

Attachments

The image and PDF object shared by chat and the API.

Chat, the partner message route, and POST /api/v1/chat/completions share one attachment object. content may stay a string. The field name is attachments.

json

{
  "role": "user",
  "content": "What is on page 1 of this drawing?",
  "attachments": [
    {"type": "image", "name": "part.jpg", "mime": "image/jpeg", "data": "data:image/jpeg;base64,..."},
    {"type": "pdf", "name": "diagram.pdf", "mime": "application/pdf", "data": "data:application/pdf;base64,..."}
  ]
}

Rules

type is image or pdf. name, mime, and data are required in the OpenAPI schema. data is a base64 data URL. filename is accepted as another name for name, and file_data as another name for data.
4 images, 10 MB each. PDFs on one turn are capped at 25 MB together.
The declared type must match the bytes. PDFs with scripts, a launch action, or an embedded file are rejected.
The partner message route returns 403 scope_denied when the key lacks the files scope (also named file-upload).
The whole chat-completions body, attachments included, must be at most 36 MB.

Upload first

POST /api/partner/v1/files stores an image or PDF and returns a file id shaped file_ plus 16 hex characters. The limit on that route is 8 MB. Over that, the error is 413 “That file is over 8 MB.” Send the raw bytes with Content-Type set to the mime type and X-Filename set to the name, or send JSON with bytes_base64.

A PDF is read as text first. A page that is only a drawing is not sent to xAI or Gemini. Those providers stay on image and video generation.