File Management
Upload, list, retrieve, and delete files for vision, documents, and batch jobs.
The File API stores files you can reference from chat, messages, and responses, or feed into Batch jobs. Files are private to your account and addressed by id.
Upload a file
POST /v1/filesSend the file and a purpose as multipart form data.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
file | file | Yes | The file to upload. |
purpose | string | Yes | One of vision, batch, document, assistants, fine-tune. |
The purpose constrains the accepted content types and the maximum size:
| Purpose | Max size | Typical use |
|---|---|---|
vision | ~20 MB | Images referenced by chat/vision models. |
batch | ~100 MB | JSONL input for the Batch API. |
document | ~512 MB | Documents (PDF, txt, docx, …) for analysis. |
assistants | ~512 MB | Documents and images for multi-step workflows. |
fine-tune | ~1 GB | JSONL training data. |
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["YUNXIN_API_KEY"],
base_url="https://api.yuhuanstudio.com/v1",
)
file = client.files.create(
file=open("report.pdf", "rb"),
purpose="document",
)
print(f"File ID: {file.id}")Response
{
"id": "file-abc123",
"object": "file",
"bytes": 184320,
"created_at": 1709251200,
"filename": "report.pdf",
"purpose": "document",
"status": "uploaded"
}List files
GET /v1/filesSupports a purpose filter and limit (1–100). Returns an OpenAI-style list:
for f in client.files.list().data:
print(f"{f.id} - {f.filename} ({f.bytes} bytes)")Retrieve file metadata
GET /v1/files/{id}Returns the FileObject for a single file.
Download file content
GET /v1/files/{id}/contentReturns the file's bytes (resolved via a presigned URL where available, otherwise streamed directly). This is also the URL you reference from a chat or messages request — the gateway resolves it automatically.
Delete a file
DELETE /v1/files/{id}client.files.delete("file-abc123")Using files in chat
Upload a file, then reference it by its content URL in a multimodal message:
file = client.files.create(
file=open("report.pdf", "rb"),
purpose="document",
)
response = client.chat.completions.create(
model="model-id",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "Summarize this document."},
{
"type": "file_url",
"file_url": {
"url": f"https://api.yuhuanstudio.com/v1/files/{file.id}/content"
},
},
],
}],
)
print(response.choices[0].message.content)The same file is referenceable from the Messages API (document content blocks) and the
Responses API (input file parts) by the same …/v1/files/{id}/content URL.
For passing images by URL or base64 directly, see Vision.
Rate limit
POST /v1/files is limited to 20 requests/min. See Rate Limits.
How is this guide?