Files API

OpenAI-compatible file storage. Upload once, reference by file_id from the Responses API. PDFs, plain text, images — anything under 512 MB.

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 authenticated via the standard Authorization: Bearer $LAZU_API_KEY header.

Supported purposes

Every uploaded file must declare a purpose:

Purpose	Max size	Allowed mime types	What it's for
`user_data`	512 MB	Any non-executable	PDFs, text, structured data passed to the model
`vision`	20 MB	`image/png`, `image/jpeg`, `image/gif`, `image/webp`	Image inputs

OpenAI's batch, fine-tune and assistants purposes are not yet supported — contact support if you need them.

Executable file extensions (.exe, .dll, .sh, .bat, …) are rejected regardless of purpose.

1. Upload

cURL

curl https://api.lazu.ai/v1/files \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -F purpose=user_data \
  -F file=@./paper.pdf

Response:

{
  "id": "file-lazu-01KSBV4MC6THZ9TCZEM38KPYRX",
  "object": "file",
  "bytes": 1609275,
  "created_at": 1779587764,
  "filename": "paper.pdf",
  "purpose": "user_data",
  "status": "processed"
}

Python (OpenAI SDK)

from openai import OpenAI
 
client = OpenAI(
    base_url="https://api.lazu.ai/v1",
    api_key="YOUR_LAZU_KEY",
)
 
with open("paper.pdf", "rb") as f:
    file = client.files.create(file=f, purpose="user_data")
 
print(file.id)

2. Reference from the Responses API

curl https://api.lazu.ai/v1/responses \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": [{
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Summarize this document"},
        {"type": "input_file", "file_id": "file-lazu-01KSBV4MC6THZ9TCZEM38KPYRX"}
      ]
    }]
  }'

For images, use "type": "input_image" instead of input_file.

3. List, retrieve, delete

# List all files for the current key
curl https://api.lazu.ai/v1/files \
  -H "Authorization: Bearer $LAZU_API_KEY"
 
# Metadata for one file
curl https://api.lazu.ai/v1/files/file-lazu-... \
  -H "Authorization: Bearer $LAZU_API_KEY"
 
# Download bytes
curl https://api.lazu.ai/v1/files/file-lazu-.../content \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -o downloaded.pdf
 
# Delete
curl -X DELETE https://api.lazu.ai/v1/files/file-lazu-... \
  -H "Authorization: Bearer $LAZU_API_KEY"

Retention & cleanup

Files are kept for 30 days from upload.
After 30 days, the file is deleted from storage and the database in a daily cleanup job (runs around 04:30 Asia/Shanghai).
You cannot extend retention from the public API. Re-upload if you need it to live longer.
Deleted files are gone — there is no soft delete / recycle bin.

Limits

Limit	Value
Single file (`user_data`)	512 MB
Single file (`vision`)	20 MB
Total bytes dereferenced in one Responses call	64 MB

If a Responses call references too many files (or files too large) and the total exceeds 64 MB, Lazu returns 400 with code file_too_large.

Errors

HTTP	Code	Meaning
400	`missing_required_parameter`	Forgot `purpose`
400	`purpose_not_supported`	Used `batch` / `fine-tune` / `assistants`
400	`invalid_request`	Malformed multipart body / empty file
401	`invalid_api_key`	Auth header missing or wrong
404	`file_not_found`	`file_id` doesn't exist or isn't owned by this key
413	`file_too_large`	Single file exceeds purpose's max size

See Errors for the full table.