Temporary Files

Primex provides a temporary, account-scoped file transport for production requests that use file_id. It is separate from the unsupported OpenAI Files/Batch API.

The production lifecycle is:

1. Request an upload authorization with your normal Primex API key.
2. Upload the bytes to the returned one-object URL using the returned method and headers.
3. Finalize the file so Primex can verify its real size and detected content type.
4. Pass the finalized file_id to a compatible AI service endpoint.

from pathlib import Path
import requests

api_key = "prx-YOUR_KEY"
gateway = "https://gateway.primexos.com"
headers = {"Authorization": f"Bearer {api_key}"}
file_path = Path("invoice.pdf")

authorization = requests.post(
    f"{gateway}/v1/primex/files/upload-authorizations",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "purpose": "OCR_INPUT",
        "content_type": "application/pdf",
        "byte_size": file_path.stat().st_size,
    },
)
authorization.raise_for_status()
upload = authorization.json()

with file_path.open("rb") as file:
    uploaded = requests.put(upload["upload_url"], headers=upload["headers"], data=file)
uploaded.raise_for_status()

finalized = requests.post(
    f'{gateway}/v1/primex/files/{upload["file_id"]}/finalize',
    headers=headers,
)
finalized.raise_for_status()
file_id = finalized.json()["file_id"]

response = requests.post(
    f"{gateway}/v1/ocr",
    headers={**headers, "Content-Type": "application/json"},
    json={"model": "azure-ocr-read", "file_id": file_id},
)
response.raise_for_status()
print(response.json())

Upload purposes

Use the purpose that matches the intended input contract:

Purpose	Intended consumers
OCR_INPUT	OCR and compatible document-analysis endpoints
DOCUMENT_INPUT	Document analysis and compatible OCR endpoints
AUDIO_INPUT	Speech transcription or audio translation
MODERATION_INPUT	Image moderation
IMAGE_REFERENCE	Image editing and compatible image-reference consumers
VISION_INPUT	Image analysis and supported vision requests
VIDEO_REFERENCE	Video generation reference frames

The authorization response is the source of truth for upload_url, method, required upload headers, and upload_expires_at. Do not construct a Blob URL or storage key yourself.

Ownership and lifetime

Files belong to the canonical Primex account, not to one API key or Playground session. Any valid API key for the same account can reuse a finalized file with a compatible service until the expires_at returned by finalization. A different account receives 404, including when it guesses a real file ID.

Pending uploads use the configured pending lifetime (two hours by default); finalized inputs use the configured input lifetime (24 hours by default). An hourly cleanup deletes expired Blob objects and marks their records deleted. There is no manual deletion endpoint in this temporary transport. Upload URLs expire at the returned upload_expires_at (10 minutes by default) and grant create/write only; service/provider read URLs are separate, read-only URLs with a five-minute default.

The Gateway validates the declared size and content type before authorization, then verifies Blob size and detected MIME type during finalization. Invalid uploads are rejected and removed. See each service endpoint for its accepted input types and size limit.

Claude Files API

Claude Files are available for the Anthropic-hosted deployments listed below. OpenAI Files and Batch requests remain unsupported.

Use x-api-key: prx-… and anthropic-version: 2023-06-01 on these endpoints:

Request	Result
POST /v1/files	Multipart upload with one file and optional expires_in_seconds
GET /v1/files	Your account's files; optional limit and page
GET /v1/files/{id}	Your file's metadata
DELETE /v1/files/{id}	Delete your file; safe to repeat

The returned file_prx_… ID belongs to your Primex account. Reuse it from your other API keys in a native /v1/messages request. Another account receives 404. Use a document source for PDFs or plain text, or an image source for supported images. CSV or Markdown intended for text analysis can be uploaded as text/plain. These IDs cannot be used with the temporary Blob-media endpoints above or the OpenAI-compatible inference endpoints.

{
  "model": "YOUR_LIVE_ANTHROPIC_HOSTED_MODEL",
  "max_tokens": 512,
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Summarize this document."},
      {"type": "document", "source": {"type": "file", "file_id": "file_prx_YOUR_FILE_ID"}}
    ]
  }]
}

Uploads are limited to 20 MiB per file, 20 active or uncertain uploads and 100 MiB per account. Files expire after 24 hours by default; you may request between one and 24 hours. Expiry prevents further API use and releases supplier storage; it does not promise immediate erasure under the supplier's retention policy. You can delete a known file earlier. An uncertain upload retains its reservation until expiry; do not retry it automatically.

Uploaded inputs are not downloadable through GET /v1/files/{id}/content. Generated document/text downloads are available through the Skills execution API. They become available after successful billing and output publication. Generated files share the 20-file/100-MiB budget, expire after 24 hours and are deleted through a retrying supplier-cleanup queue. Their Primex expiry does not establish supplier deletion. Downloads are free, including at zero wallet balance. Use current stable Anthropic SDK Files types and page pagination; beta list shapes and workspace-wide listing are not implemented.

Uploading, listing, retrieving metadata and deleting files do not debit your wallet. Messages still charge their reported input/output/cache tokens at the selected model's prices. /v1/messages/count_tokens returns file_token_count_unsupported for an owned file reference: Foundry rejects file sources for counting, so Primex does not estimate their contents from the ID.

The reviewed hosting eligibility covers Fable 5, Fable 5.1, Opus 4.8, Sonnet 4.6 and Haiku 4.5. Availability still depends on the live catalogue and active route; there is no automatic model substitution. Built-in Skills have a separate per-model support table.