Files

Upload media to the Files API, then reference its file-... ID in requests. Reusing a file ID avoids uploading the same bytes again. Each occurrence still has its own position in the request’s asset ordering; file IDs and asset_idx serve different purposes.

Upload and use a local image

Install perceptron>=0.4.0 and set PERCEPTRON_API_KEY as shown in the quickstart. Replace ./image.png with a local PNG image. The SDK’s files.upload() sends the bytes to the Files API and returns a File; pass that object to image() to reference its ID in a completion.

from perceptron import Client, image

client = Client(provider="perceptron")
uploaded = client.files.upload("./image.png", purpose="vision")

response = client.chat.completions.create(
    model="perceptron-mk1.5",
    messages=[{
        "role": "user",
        "content": [
            image(uploaded),
            {"type": "text", "text": "Describe the scene and its main objects."},
        ],
    }],
    max_completion_tokens=1024,
)
if not response.complete or response.tool_calls:
    raise RuntimeError(f"Incomplete answer: {response.finish_reason}")
print(response.text)
print("Reusable file ID:", uploaded.id)

set -euo pipefail

file_id="$(
  curl --fail-with-body --silent --show-error \
    https://api.perceptron.inc/v1/files \
    -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
    -F 'purpose=vision' \
    -F 'file=@./image.png;type=image/png' \
    | jq -er '.id'
)"

jq -n --arg file_id "$file_id" '{
  model: "perceptron-mk1.5",
  messages: [{
    role: "user",
    content: [
      {type: "image_file_id", image_file_id: {file_id: $file_id}},
      {type: "text", text: "Describe the scene and its main objects."}
    ]
  }],
  max_completion_tokens: 1024
}' | curl --fail-with-body --silent --show-error \
  https://api.perceptron.inc/v1/chat/completions \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @-

For a file already uploaded, use image(file_id="file-...") instead. Calling image("./image.png") directly embeds the local image in the completion request; it does not upload to the Files API. The same distinction applies to video() and audio(). The curl example also needs Bash and jq. The upload uses multipart form data; let curl set its content type and boundary. The completion response has the same shape as any chat completion: read choices[0].message.content and check choices[0].finish_reason before treating the answer as complete.

Upload and use a local video

Use video(uploaded) to send a video_file_id content part. Replace ./video.mp4 with a local video:

from perceptron import Client, video

client = Client(provider="perceptron")
uploaded = client.files.upload("./video.mp4", purpose="vision")
response = client.chat.completions.create(
    model="perceptron-mk1.5",
    messages=[{
        "role": "user",
        "content": [
            video(uploaded),
            {"type": "text", "text": "Describe the main actions in chronological order."},
        ],
    }],
    max_completion_tokens=1024,
)
if not response.complete or response.tool_calls:
    raise RuntimeError(f"Incomplete answer: {response.finish_reason}")
print(response.text)

The soundtrack is disabled by default. To analyze it alongside the frames, explicitly pass vision_config={"enable_audio_in_video": True} to the completion request. See Video Q&A for soundtrack behavior.

Upload and use local audio

Audio uploads support these canonical content types:

Format	Content type	Accepted aliases
WAV	`audio/wav`	`audio/x-wav`, `audio/wave`
MP3	`audio/mpeg`	`audio/mp3`
FLAC	`audio/flac`	`audio/x-flac`

Use the content type matching the file’s actual bytes. Renaming a file does not convert its format. Replace ./recording.wav with a local WAV recording:

from perceptron import Client, audio

client = Client(provider="perceptron")
uploaded = client.files.upload("./recording.wav", purpose="vision")
response = client.chat.completions.create(
    model="perceptron-mk1.5",
    messages=[{
        "role": "user",
        "content": [
            audio(uploaded),
            {"type": "text", "text": "Transcribe the speech. Mark unclear words instead of guessing."},
        ],
    }],
    reasoning_effort="none",
    max_completion_tokens=2048,
)
if not response.complete or response.tool_calls:
    raise RuntimeError(f"Incomplete answer: {response.finish_reason}")
print(response.text)

set -euo pipefail

file_id="$(
  curl --fail-with-body --silent --show-error \
    https://api.perceptron.inc/v1/files \
    -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
    -F 'purpose=vision' \
    -F 'file=@./recording.wav;type=audio/wav' \
    | jq -er '.id'
)"

jq -n --arg file_id "$file_id" '{
  model: "perceptron-mk1.5",
  messages: [{
    role: "user",
    content: [
      {type: "audio_file_id", audio_file_id: {file_id: $file_id}},
      {type: "text", text: "Transcribe the speech. Mark unclear words instead of guessing."}
    ]
  }],
  reasoning_effort: "none",
  max_completion_tokens: 2048
}' | curl --fail-with-body --silent --show-error \
  https://api.perceptron.inc/v1/chat/completions \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @-

purpose=vision is the accepted Files API purpose for media uploads, including audio. An audio_file_id input is analyzed without enabling video soundtracks. For an uploaded video’s soundtrack, use video_file_id and set vision_config.enable_audio_in_video: true on the completion request. A successful upload does not guarantee that the recording fits the model’s audio or context limits. Each audio item is limited to 16,384 encoder tokens, approximately 21.8 minutes at 750 tokens per minute; timestamp tokens and other request content also consume context. See Audio and tokenization before submitting a long recording.

Manage uploaded files

The SDK also provides client.files.list() for one page of files, client.files.iter() to iterate across pages, client.files.retrieve(file_id) for metadata, and client.files.download(file_id, path) to save the bytes locally. Call client.files.delete(file_id) when you no longer need a file; subsequent requests cannot use the deleted ID. See Upload a file for accepted formats and Delete a file for the deletion endpoint.

Use presigned media uploads

POST /v1/media/upload-urls also accepts WAV, MP3, and FLAC with the content types above. This is a separate upload flow from the Files API:

Send files entries containing file_name, content_type, and the exact byte content_length to /v1/media/upload-urls, using your Perceptron API key.
Upload the bytes with PUT to the returned upload_url, using the same Content-Type you declared. Do not send your Perceptron API key to the presigned URL.
Send the returned object_key in an object_keys array to POST /v1/media/download-urls, using your Perceptron API key. Use the returned download_url in an audio_url content part while it remains valid.

An object_key is not a Files API file-... ID. Use /v1/files when you want to reference the recording with audio_file_id.

Referencing a file in a request

Reference an uploaded file in a chat completion by id with an image_file_id / video_file_id content part, or by passing its /v1/files/{file_id}/content URL as a standard image_url / video_url. All four forms are equivalent.

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

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

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

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

Limits

Files are capped at 128 MiB each, with 100 GiB of total storage per organization. Per-endpoint rate limits are listed on each API reference page. Need higher limits? Contact us.

Get Started

Capabilities

Developer Guides

Scaling & deployment

Best practices

Upload and use a local image

Upload and use a local video

Upload and use local audio

Manage uploaded files

Use presigned media uploads

Referencing a file in a request

Limits

​Upload and use a local image

​Upload and use a local video

​Upload and use local audio

​Manage uploaded files

​Use presigned media uploads

​Referencing a file in a request

​Limits

Upload and use a local image

Upload and use a local video

Upload and use local audio

Manage uploaded files

Use presigned media uploads

Referencing a file in a request

Limits