Files are uploaded inputs. Artifacts are request outputs. Their IDs and endpoints are separate.
Upload a file
Use multipart form field file, with an optional lifetime of ephemeral or persistent. The filename determines the input format; Content-Type is advisory. Uploads are currently limited to 18 MiB.
Use persistent files for templates you intend to submit to multiple jobs. GET /v1/files/{id} returns metadata. There is no REST endpoint for downloading an uploaded file’s original bytes; retain your original if you need them later.
Download an artifact
Read metadata from a completed receipt or GET /v1/artifacts/{id}. Metadata includes filename, content_type, bytes, sha256, variant, input_eligible, expiry/deletion fields, and optional encryption information.
Fetch bytes from GET /v1/artifacts/{id}/content with bearer authentication. Construct the URL from your configured API base and the artifact ID. Do not forward your API key to arbitrary response URLs or follow redirects to other hosts.
Before consuming the result, compare its length and SHA-256 with metadata. For encrypted output these describe the ciphertext. The HTTP headers then report application/jose and a .jwe filename; artifact metadata still describes the original plaintext format.
Retention
- Ephemeral uploads can be claimed by one job. Unclaimed uploads normally expire after 24 hours. Successful work deletes claimed ephemeral input data; failed/cancelled work follows the server’s failure-retention policy.
- Persistent files remain until explicitly deleted. Active work can pin a file and prevent deletion.
- Completed request content normally expires after 24 hours. Download and store results your application needs to retain.
- Deleting prompt or conversion content removes retained content and output bytes but preserves billing and operational receipts. It does not cancel work. Repeated content deletion succeeds; active/pinned content can return
409.
- Expired or deleted bytes cannot be restored by replaying an idempotency key. A retained metadata record does not prove the content remains downloadable.
With retention.delete_after_webhook_id, a successful completion-webhook acknowledgement can trigger deletion. Download and durably store results before returning 2xx from that webhook.
TypeScript
For large outputs, artifacts.content(id) exposes a raw Response. Your code then owns stream cleanup and verification. Source.stream() buffers before returning a fresh stream; it is not a streaming passthrough. 
