Upload a file

POST/v1/files

Upload a file.

Compatible with OpenAI's upload-file endpoint: send the file as multipart/form-data. The file is uploaded to the provider and recorded against your virtual key, and the response carries its VectorAxis id (vxf-...), which batch jobs, the Responses API and chat file parts accept in place of the provider's id. Returns 201.

Accepted content types are common image, document (PDF, text, CSV, Markdown, HTML, Word, Excel), audio, video and JSONL types and application/octet-stream; any other is a 400. Size limits by purpose: fine-tune 512 MB, batch 500 MB, anything else 20 MB (400 when exceeded).

Authenticate with a BYOK virtual key or with x-provider and x-api-key; a PLATFORM virtual key is a 400. OpenAI credentials only; any other provider is a 422. The key's checks, the plan's limits and the organization's approved-provider policy (403) apply. Without x-retry-count a failed upload is retried up to 3 times on 429 and 5xx.

Authorization

AuthorizationBearer <slug>.<secret>
A virtual key's API key (vk-....<secret>), as Authorization: Bearer. What the OpenAI SDK sends from its api_key. Used by the inference endpoints.
orx-virtual-keyheader
A virtual key's API key in the x-virtual-key header, for clients that keep Authorization for something else.
orx-api-keyheader
Direct credentials: the provider's own API key in x-api-key, with the provider named in x-provider (for example openai). On /v1/messages a virtual key is accepted in x-api-key too, which is what the Claude SDK sends.

Headers

x-providerstring
With direct credentials: the provider x-api-key belongs to, for example openai or anthropic (case and dashes are normalised). Not used with a virtual key.
x-retry-countinteger<int32>
How many times to retry a failed provider call, 0 to 5. Without the header, chat completions, Claude Messages and prompt completions do not retry, and the other endpoints retry up to 3 times. Retries back off exponentially from 1 second and honour a numeric Retry-After. The number made is in the x-retry-count response header.
x-retry-status-codesstring
Comma-separated provider status codes to retry on. Default 429,500,502,503,504,529.

Request body multipart/form-data

filestring<binary>required
the file to upload
purposestring
what the file is for: batch, fine-tune, assistants or vision; assistants when omitted

Responses

201application/json

Created

idstring
The VectorAxis file id: vxf- followed by a UUID.
providerstring
The provider the file was uploaded to, for example OPENAI.
filenamestring
The file's name as uploaded.
bytesinteger<int64>
The file's size in bytes, as the provider reported it. Absent when the provider did not report it.
mime_typestring
The file's content type as uploaded, for example application/jsonl.
purposeenum<string>
What the file is for: batch (input for a batch job), fine-tune (training data), assistants (documents for assistants and the Responses API, the default) or vision (an image for chat messages). Absent when the purpose given at upload is none of these.
One of "fine-tune", "batch", "assistants", "vision"
statusenum<string>
The file's state at VectorAxis: uploaded (received and sent to the provider), processing (the provider is processing it), processed (ready) or error (the provider rejected it; see provider_status).
One of "uploaded", "processing", "processed", "error"
provider_statusstring
The file's status as the provider reported it at upload. Absent when the provider reported none.
organizationstring
The organization the file belongs to. Absent for an upload with direct provider credentials and no x-organization.
virtual_key_slugstring
The slug of the virtual key the file was uploaded with (vk-...). Only that key can read, download or delete it. Absent for an upload with direct provider credentials.
created_atstring<date-time>
When the file was uploaded, ISO 8601.
expires_atstring<date-time>
When the file expires at the provider, ISO 8601. Absent when it does not expire.

VectorAxis is built by GK Labs, a member of NVIDIA Inception.