Files API

The Files API lets you upload, list, inspect, download, and delete files stored on a provider's platform. It's most useful for supplying batch input to the Batch API, but any file you store with a provider can be referenced wherever that provider accepts a file ID.

Quick Start#

use Prism\Prism\Facades\Prism;
use Prism\Prism\Enums\Provider;

// Upload a file
$file = Prism::files()
    ->using(Provider::OpenAI)
    ->upload(
        content: file_get_contents('/path/to/data.jsonl'),
        filename: 'data.jsonl',
    );

echo $file->id; // "file-abc123"

Uploading Files#

Pass the raw file content and a filename. The optional mimeType argument lets you set the content type explicitly — useful when the filename alone isn't enough for the provider to infer the format.

$file = Prism::files()
    ->using(Provider::Anthropic)
    ->upload(
        content: file_get_contents('/path/to/document.pdf'),
        filename: 'document.pdf',
        mimeType: 'application/pdf',
    );

echo $file->id;        // provider file ID
echo $file->filename;  // "document.pdf"
echo $file->sizeBytes; // size in bytes
echo $file->purpose;   // provider-specific purpose string
echo $file->createdAt; // creation timestamp

Provider-specific options#

OpenAI requires a purpose field on upload. Accepted values are assistants, batch, fine-tune, vision, user_data, and evals. Pass it via withProviderOptions():

$file = Prism::files()
    ->using(Provider::OpenAI)
    ->withProviderOptions(['purpose' => 'batch'])
    ->upload(
        content: $jsonlContent,
        filename: 'batch-input.jsonl',
    );

Listing Files#

$list = Prism::files()
    ->using(Provider::OpenAI)
    ->list();

foreach ($list->data as $file) {
    echo "{$file->id}: {$file->filename} ({$file->sizeBytes} bytes)\n";
}

Pagination#

list() supports cursor-based pagination via limit, afterId, and beforeId:

$page1 = Prism::files()
    ->using(Provider::Anthropic)
    ->list(limit: 20);

if ($page1->hasMore) {
    // Forward pagination — fetch the page after the last item
    $page2 = Prism::files()
        ->using(Provider::Anthropic)
        ->list(limit: 20, afterId: $page1->lastId);

    // Backward pagination — fetch the page before the first item
    $prevPage = Prism::files()
        ->using(Provider::Anthropic)
        ->list(limit: 20, beforeId: $page1->firstId);
}

The FileListResult has four properties:

Provider support#

Not all parameters are supported by every provider:

The purpose filter for OpenAI is passed via withProviderOptions():

$list = Prism::files()
    ->using(Provider::OpenAI)
    ->withProviderOptions(['purpose' => 'batch'])
    ->list(limit: 50);

Retrieving File Metadata#

$file = Prism::files()
    ->using(Provider::OpenAI)
    ->getMetadata(fileId: 'file-abc123');

echo $file->filename;
echo $file->sizeBytes;
echo $file->createdAt;

Downloading File Contents#

download() fetches the full file body and returns it as a string — already buffered, so you can pass it straight to storage or parse it directly.

$contents = Prism::files()
    ->using(Provider::OpenAI)
    ->download(fileId: 'file-abc123');

// Write to disk
Storage::put('output.jsonl', $contents);

// Or parse in-memory
foreach (explode("\n", $contents) as $line) {
    $row = json_decode($line, true);
    // ...
}

Deleting Files#

$result = Prism::files()
    ->using(Provider::OpenAI)
    ->delete(fileId: 'file-abc123');

echo $result->id;      // "file-abc123"
echo $result->deleted; // true

Using an uploaded file in a prompt#

Use the file ID with the provider that owns it:

use Prism\Prism\Facades\Prism;
use Prism\Prism\ValueObjects\Media\Document;

// $pdfBytes is validated PDF content supplied by your application.
$file = Prism::files()->using('openai')
    ->withProviderOptions(['purpose' => 'user_data'])
    ->upload($pdfBytes, 'report.pdf', 'application/pdf');

$response = Prism::text()->using('openai', 'gpt-4.1')
    ->withPrompt('Summarize this report.', [Document::fromFileId($file->id)])
    ->asText();

File IDs are provider-scoped references. They do not make a file uploaded to OpenAI available to Anthropic or another provider. Your application must authorize access to the file before including it in a prompt.

Errors#

Providers without a Files implementation raise an unsupported-action PrismException. Provider error responses also raise PrismException; inspect the selected provider's requirements for purpose, file type and download permission. Catch Laravel ConnectionException separately for transport failures. Do not assume a failed deletion or upload succeeded.

The FileData Object#

Every operation that returns a single file gives back a FileData value object:

Client Options#

All the same HTTP client helpers available on other Prism builders work here too:

$file = Prism::files()
    ->using(Provider::OpenAI)
    ->withClientOptions(['timeout' => 120])
    ->withClientRetry(3, 500)
    ->upload(content: $largeFile, filename: 'big-upload.jsonl');

Provider-Conditional Options#

Use whenProvider() to set options that only apply to a specific provider, which is handy when the same code path runs against multiple providers:

$file = Prism::files()
    ->using($providerName)
    ->whenProvider('openai', fn ($r) => $r->withProviderOptions(['purpose' => 'batch']))
    ->upload(content: $content, filename: 'data.jsonl');