Introducing Perceptron Files API

Abstract

Today we're releasing the Perceptron Files API. It simplifies the process of building agentic workflows and apps on Perceptron Mk1: upload an image or video once and reference it by id across as many requests as you want. Instead of encoding as base64 or re-sending the same media URL on every call, files are stored against your organization, addressed by a file-abc123, and the endpoints are OpenAI-compatible. Everything drops straight into the SDK and tooling you already use.

Challenges with bringing your own media

The default way to send an image or video to Perceptron Mk1 is to attach it to the request, either as a URL you host yourself or as a base64 blob pasted directly into the payload. That works for a one-off model call, but it's inefficient the moment you send the same media more than once:

Re-sending the bytes means every request that touches a file pays the full transfer cost again, even when you're only adjusting the prompt around an image or video.
Base64 inlining pushes large media straight into the request body, where big files bump into body-size limits long before the model’s context window is the bottleneck.
Self-hosting URLs means standing up a bucket, managing access, and keeping it alive for as long as the model might need to read from it.

Perceptron Files API removes all of that. You upload the bytes one time, get back a stable id, and point at the id from then on.

How it works

Upload a file as multipart/form-data with a purpose and you get back a file object with an id like file-abc123:

curl https://api.perceptron.inc/v1/files \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  -F purpose=vision \
  -F 'file=@scene.mp4;type=video/mp4'

From there, reference it in any chat completion. You can pass it as a typed content part with an image_file_id / video_file_id, or hand its content URL to a standard image_file_id / video_file_id. All four forms are equivalent:

{ "type": "video_file_id", "video_file_id": { "file_id": "file-abc123" } }

{ "type": "video_url",
  "video_url": { "url": "https://api.perceptron.inc/v1/files/file-abc123/content" 
} }

That id now stands in for the media on any call to Mk1. Upload a clip once, then put the model's video reasoning to work against it. Here’s an example asking for temporal grounding:

curl https://api.perceptron.inc/v1/chat/completions \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "perceptron-mk1",
    "messages": [
      { "role": "user", "content": [
        { "type": "video_file_id", "video_file_id": { "file_id": "file-abc123" } },
        { "type": "text", "text": "Find every grasp attempt and return the start/end timecodes." }
      ] }
    ]
  }'

The API exposes five endpoints, all OpenAI-compatible:

Upload File (POST /v1/files) — send the bytes, get back a file…id.
List Files (GET /v1/files) — page through your organization's files with cursor pagination and purpose filtering.
Retrieve File (GET /v1/files/{file_id}) — fetch a file's metadata (size, content type, purpose, creation time).
Retrieve File Content (GET /v1/files/{file_id}/content) — download the raw bytes, served with the same Content-Type you uploaded.
Delete File (DELETE /v1/files/{file_id}) — permanently remove a file when you're done with it.

Because the interface mirrors OpenAI's Files API, it’s easy and familiar to get started with a URL swap, all with minimal code changes to swap between APIs.

Built for production

The Files API is designed from the ground up for production workloads:

Generous limits. Files are capped at 128 MiB each, with 100 GiB of total storage per organization; comfortably enough for high-resolution video.
Streaming uploads with backpressure. Uploads are processed as a stream rather than buffered whole in memory, and the service reserves an upload-memory budget before reading the body. Under heavy concurrent load it returns a clean 503 instead of falling over, so a burst of large uploads degrades gracefully.
Organization-scoped and private. Every file is addressed within your organization. Ids from one org are invisible to another, and a deleted file immediately stops being retrievable or referenceable.

Where it matters

The Files API is most valuable anywhere the same media is used more than once:

Agentic and multi-turn workflows. Apps that ask several questions about a single media asset upload it once, receive a media id in return, and reference that id on every subsequent call.
Video understanding. Video is where this pays off most. Mk1 analyzes footage at a dynamic frame rate of up to 2 FPS across a 32K-token context window, then returns structured timecodes you can act on. Uploading a multi-hundred-megabyte clip a single time and addressing it by id thereafter is the difference between a temporal-grounding workflow that's practical and one that isn't.
Batch and pipeline processing. Stage a corpus of images or video, list and filter them by purpose, and fan out detection, captioning, OCR, or Q&A requests against stored ids.
One id, every API. The same file-abc123 works across Perceptron's API offerings, whether you are querying a Perceptron model, an Isaac model, or one of our agentic APIs. An asset you upload once is reusable everywhere.

Getting Started

The Perceptron Files API is available today on the Perceptron Platform.

API Endpoint: api.perceptron.inc/v1/files

Need higher limits? Reach out at support@perceptron.inc.

Read the docs

The Road Ahead

The Files API is one step in a broader push to make the Perceptron Platform the easiest place to build agentic workflows and apps with image and video understanding. Perceptron Mk1 brings frontier video and embodied reasoning into a single API call. We're investing in the capabilities around the model: storage, agents, and the tooling that makes physical intelligence easy to use. More to come.

Getting Started

The Perceptron Files API is available today on the Perceptron Platform.

API Endpoint: api.perceptron.inc/v1/files

Need higher limits? Reach out at support@perceptron.inc.

Read the docs