Skip to main content

Files

Upload a file once and refer to it by its id: attach an image or a video to a message, or pass any file to a generation as input. Generations also produce files.

Upload​

Send the file as multipart/form-data, in the file field:

curl -s "$NEWEYES_API_BASE/v1/files" -X POST \
  -H "Authorization: Bearer $NEWEYES_USER_TOKEN" \
  -F "file=@living-room.jpg"
{
  "object": "file",
  "id": "3d0f…",
  "filename": "living-room.jpg",
  "size": 482113,
  "content_type": "image/jpeg",
  "created_at": "2026-10-19T08:05:00Z",
  "download_url": "https://…",
  "download_url_expires_at": "2026-10-19T09:05:00Z",
  "expires_at": "2026-11-18T08:05:00Z"
}
KindTypesLargest
ImageJPEG, PNG, WebP10 MB
VideoMP4, MOV50 MB
AudioMP3, WAV, M4A, AAC25 MB
  • The type is read from the file's bytes, not from its name or the declared content type. Any other type is refused with 422 unsupported_media_type; a file over its limit with 413 file_too_large.
  • Uploads have their own rate limit, on top of the request limit: see Rate limits.

Read a file​

GET /v1/files/{file_id} returns the file with a fresh download_url. A download link is signed afresh on every read and works for one hour (until download_url_expires_at); read the file again for a new link. download_url is null when a link cannot be made right now — retry shortly.

A file is visible only to the end user who uploaded or generated it.

How long a file is kept​

  • An uploaded file expires 30 days after its upload (its expires_at) unless it is sent in a message or used by a generation first. From then on it can no longer be read or used (404 file_expired), and its content is deleted.
  • A file sent in a message is kept with that conversation; a file a generation uses is kept; a generation's output is kept. Their expires_at is null.

Media made by tasks​

Images, videos, audio and documents a task makes during a conversation are not listed here: they arrive as media.updated frames on the event stream and as attachments on the reply in the session's message list, each with its own expiring link.