Files

Use a provider’s files() client when a request needs a durable provider file reference rather than inline bytes. Every AIFileClient advertises supportedFileOperations, so applications can distinguish an upload-only provider from a complete Files V4 implementation before starting I/O.

let client = try AIProviders.openAI().files()
print(client.supportedFileOperations)

let uploaded = try await AI.uploadFile(
    client: client,
    request: FileUploadRequest(
        data: documentData,
        mediaType: "application/pdf",
        filename: "report.pdf",
        purpose: "assistants"
    )
)

let reference = uploaded.providerReference
let metadata = try await AI.getFileMetadata(
    client: client,
    request: FileMetadataRequest(file: reference)
)
let download = try await AI.downloadFile(
    client: client,
    request: FileDownloadRequest(file: reference)
)

for try await bytes in download.content {
    consume(bytes)
}

let deletion = try await AI.deleteFile(
    client: client,
    request: FileDeleteRequest(file: reference)
)

OpenAI and xAI implement upload, metadata, streamed download, and deletion. Other clients can remain upload-only; their default protocol implementations reject unsupported operations before network I/O.

Streaming Uploads

Use FileUploadRequest(stream:mediaType:filename:...) to avoid buffering a large input in memory:

let uploaded = try await AI.uploadFile(
    client: client,
    request: FileUploadRequest(
        stream: byteStream,
        mediaType: "application/jsonl",
        filename: "requests.jsonl",
        purpose: "batch"
    )
)

A stream-backed upload is single-use. The facade disables automatic retry and cancels the producer when upload fails, including when a custom client rejects the request before reading it. Buffered Data uploads remain replayable and use the supplied AIRetryPolicy. Download setup can retry normally, but failures encountered while consuming the returned byte stream are delivered to that consumer rather than replaying already-read bytes.

Results and Provider Options

Upload and metadata results include the provider reference, filename, media type, byte size, creation/expiry dates, warnings, raw response, request/response metadata, and provider metadata when available. Download returns an AsyncThrowingStream<Data, Error> plus its media type and metadata. Delete returns the provider reference and a typed deleted flag.

Pass the exact providerReference returned by upload. File IDs are encoded as path components, including dot-segment-like IDs, rather than concatenated as raw URL paths. xAI’s expiresAfter upload option accepts an integer from 3,600 to 2,592,000 seconds. OpenAI preserves its provider-native expiry metadata.

Download transport security

Downloads outside an explicitly trusted provider origin resolve DNS once, reject any private or disallowed address in the answer set, and connect to a validated numeric address. HTTPS keeps the original hostname for SNI and system certificate verification. Each redirect is validated independently; credentials are stripped when leaving their allowed origin.

Custom transports must implement sendValidatedDownload and, when streaming, streamValidatedDownload. Their default implementations reject untrusted downloads. A URLSessionTransport with an injected session also rejects these downloads, since DNS pinning cannot preserve arbitrary session proxy, delegate and authentication behavior. Ordinary provider requests are unchanged. If a custom transport intentionally uses the standard protected downloader, its hooks can explicitly delegate to URLSessionTransport.shared.

The native protected connector accepts HTTP/HTTPS GET responses with identity content encoding, Content-Length, chunked framing or EOF framing. It enforces size limits, deadlines and cancellation. An explicit trustedOrigin is a security exception for that exact scheme, host and port; never derive it from an arbitrary URL supplied by a user.