Upload File

Upload a file for use with various OpenAI endpoints

Method Signature

client.files.create(
    file: FileTypes,
    purpose: FilePurpose,
    expires_after: Optional[ExpiresAfter] = None
) -> FileObject

Parameters

file · FileTypes · required

The File object (not file name) to be uploaded. This should be a file-like object opened in binary mode.

Size limits:

• Individual files: up to 512 MB
• Per project: up to 2.5 TB total
• No organization-wide limit

purpose · FilePurpose · required

The intended purpose of the uploaded file. Must be one of:

• assistants - Used in the Assistants API
• batch - Used in the Batch API
• fine-tune - Used for fine-tuning (.jsonl files only)
• vision - Images used for vision fine-tuning
• user_data - Flexible file type for any purpose
• evals - Used for eval data sets

Purpose-specific requirements:

• Assistants API: Files up to 2 million tokens, specific file types only
• Fine-tuning API: Only .jsonl files with specific formats for chat or completions
• Batch API: Only .jsonl files up to 200 MB with specific format

expires_after · ExpiresAfter

The expiration policy for the file.

Default behavior:

• Files with purpose=batch: expire after 30 days
• All other files: persisted until manually deleted

{
    "anchor": "created_at",  # Only supported anchor
    "seconds": 3600  # Between 3600 (1 hour) and 2592000 (30 days)
}

Response

Returns a FileObject:

class FileObject(BaseModel):
    id: str  # File identifier
    bytes: int  # File size in bytes
    created_at: int  # Unix timestamp
    filename: str  # Original file name
    object: Literal["file"]  # Always "file"
    purpose: str  # File purpose
    status: Literal["uploaded", "processed", "error"]  # Processing status
    expires_at: Optional[int]  # Unix timestamp when file expires
    status_details: Optional[str]  # Error details if status is "error"

Examples

Upload Training File for Fine-tuning

from openai import OpenAI

client = OpenAI()

# Upload a JSONL file for fine-tuning
with open("training_data.jsonl", "rb") as file:
    response = client.files.create(
        file=file,
        purpose="fine-tune"
    )

print(f"File ID: {response.id}")
print(f"File size: {response.bytes} bytes")
print(f"Status: {response.status}")

Upload File for Assistants

with open("knowledge_base.pdf", "rb") as file:
    response = client.files.create(
        file=file,
        purpose="assistants"
    )

print(f"Uploaded: {response.filename}")
print(f"File ID: {response.id}")

Upload Batch File with Expiration

with open("batch_requests.jsonl", "rb") as file:
    response = client.files.create(
        file=file,
        purpose="batch",
        expires_after={
            "anchor": "created_at",
            "seconds": 86400  # Expire after 1 day
        }
    )

print(f"File expires at: {response.expires_at}")

Upload from Path Using Pathlib

from pathlib import Path

file_path = Path("data/training.jsonl")

with file_path.open("rb") as file:
    response = client.files.create(
        file=file,
        purpose="fine-tune"
    )

Wait for File Processing

with open("data.jsonl", "rb") as file:
    uploaded_file = client.files.create(
        file=file,
        purpose="fine-tune"
    )

# Wait for the file to be processed (30 min timeout by default)
processed_file = client.files.wait_for_processing(
    uploaded_file.id,
    poll_interval=5.0,  # Check every 5 seconds
    max_wait_seconds=1800  # Wait up to 30 minutes
)

if processed_file.status == "processed":
    print("File is ready to use!")
else:
    print(f"File processing failed: {processed_file.status_details}")

Async Usage

from openai import AsyncOpenAI

client = AsyncOpenAI()

with open("training_data.jsonl", "rb") as file:
    response = await client.files.create(
        file=file,
        purpose="fine-tune"
    )

# Wait for processing asynchronously
processed_file = await client.files.wait_for_processing(response.id)

File Format Requirements

Fine-tuning (JSONL)

{"messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"}, {"role": "assistant", "content": "Hi there!"}]}
{"messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "How are you?"}, {"role": "assistant", "content": "I'm doing well!"}]}

Batch API (JSONL)

{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello!"}]}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "How are you?"}]}}

Notes

• Files are uploaded using multipart/form-data encoding
• The file parameter must be a file object, not a file path string
• Always open files in binary mode ("rb")
• Use context managers (with statement) to ensure files are properly closed
• Contact OpenAI support to increase storage limits