Endpoints / Storage

Files API

POST/v1/files

Upload documents and images once, then reference them by file_id from the Responses API. The file API is OpenAI-compatible where possible, with explicit Lazu retention and purpose rules.

File endpoints

Method	Path	Purpose
POST	`/v1/files`	Upload
GET	`/v1/files`	List
GET	`/v1/files/:id`	Metadata
GET	`/v1/files/:id/content`	Download bytes
DELETE	`/v1/files/:id`	Delete

All endpoints use Authorization: Bearer $LAZU_API_KEY.

Upload request

purposestring

required

user_datavision

Declares how the file can be used.

filemultipart file

required

Uploaded file bytes.

Supported purposes

user_data

Up to 512 MB. Use for PDFs, text and structured data passed through Responses as input_file.

vision

Up to 20 MB. Allowed mime types: image/png, image/jpeg, image/gif, image/webp.

OpenAI's batch, fine-tune and

assistants purposes are not yet supported. Executable file extensions are rejected regardless of purpose.

Upload response

idstring

File ID, for example file-lazu-01KSBV4MC6THZ9TCZEM38KPYRX.

objectstring

Always file.

bytesinteger

Uploaded byte size.

filenamestring

Original filename.

purposestring

Stored purpose.

statusstring

Usually processed.

Lazu returns 201 Created for successful uploads. Treat it as success if your client SDK expects 200.

Reference from Responses

Lazu dereferences file_id only on Responses. Chat completions does not pull file content automatically.

For images uploaded with purpose=vision, use

input_image instead of input_file.

Limits

Limit	Value
Single file with `purpose=user_data`	512 MB
Single file with `purpose=vision`	20 MB
Total bytes dereferenced in one Responses call	64 MB

Errors

missing_required_parameter400

Missing purpose or file bytes.

purpose_not_supported400

Unsupported purpose such as batch or fine-tune.

file_too_large413

Single file or total dereferenced files exceed limits.

file_not_found404

File does not exist or is not owned by the current API key.