Files & Collections
Managing Files
The Files API provides a complete set of operations for managing your files. Before using files in chat conversations, you need to upload them using one of the methods described below.
Uploading Files
You can upload files in several ways: from a file path, raw bytes, BytesIO object, or an open file handle.
Upload from File Path
import os
from xai_sdk import Client
client = Client(api_key=os.getenv("XAI_API_KEY"))
# Upload a file from disk
file = client.files.upload("/path/to/your/document.pdf")
print(f"File ID: {file.id}")
print(f"Filename: {file.filename}")
print(f"Size: {file.size} bytes")
print(f"Created at: {file.created_at}")Upload from Bytes
Python
import os
from xai_sdk import Client
client = Client(api_key=os.getenv("XAI_API_KEY"))
# Upload file content directly from bytes
content = b"This is my document content.\nIt can span multiple lines."
file = client.files.upload(content, filename="document.txt")
print(f"File ID: {file.id}")
print(f"Filename: {file.filename}")Upload from file object
Python
import os
from xai_sdk import Client
client = Client(api_key=os.getenv("XAI_API_KEY"))
# Upload a file directly from disk
file = client.files.upload(open("document.pdf", "rb"), filename="document.pdf")
print(f"File ID: {file.id}")
print(f"Filename: {file.filename}")Upload with Progress Tracking
Track upload progress for large files using callbacks or progress bars.
Custom Progress Callback
Python
import os
from xai_sdk import Client
client = Client(api_key=os.getenv("XAI_API_KEY"))
# Define a custom progress callback
def progress_callback(bytes_uploaded: int, total_bytes: int):
percentage = (bytes_uploaded / total_bytes) * 100 if total_bytes else 0
mb_uploaded = bytes_uploaded / (1024 * 1024)
mb_total = total_bytes / (1024 * 1024)
print(f"Progress: {mb_uploaded:.2f}/{mb_total:.2f} MB ({percentage:.1f}%)")
# Upload with progress tracking
file = client.files.upload(
"/path/to/large-file.pdf",
on_progress=progress_callback
)
print(f"Successfully uploaded: {file.filename}")Progress Bar with tqdm
Python
import os
from xai_sdk import Client
from tqdm import tqdm
client = Client(api_key=os.getenv("XAI_API_KEY"))
file_path = "/path/to/large-file.pdf"
total_bytes = os.path.getsize(file_path)
# Upload with tqdm progress bar
with tqdm(total=total_bytes, unit="B", unit_scale=True, desc="Uploading") as pbar:
file = client.files.upload(
file_path,
on_progress=pbar.update
)
print(f"Successfully uploaded: {file.filename}")Listing Files
Retrieve a list of your uploaded files with pagination and sorting options.
Available Options
limit: Maximum number of files to return. If not specified, uses server default of 100.order: Sort order for the files. Either"asc"(ascending) or"desc"(descending).sort_by: Field to sort by. Options:"created_at","filename", or"size".pagination_token: Token for fetching the next page of results.
import os
from xai_sdk import Client
client = Client(api_key=os.getenv("XAI_API_KEY"))
# List files with pagination and sorting
response = client.files.list(
limit=10,
order="desc",
sort_by="created_at"
)
for file in response.data:
print(f"File: {file.filename} (ID: {file.id}, Size: {file.size} bytes)")Getting File Metadata
Retrieve detailed information about a specific file.
import os
from xai_sdk import Client
client = Client(api_key=os.getenv("XAI_API_KEY"))
# Get file metadata by ID
file = client.files.get("file-abc123")
print(f"Filename: {file.filename}")
print(f"Size: {file.size} bytes")
print(f"Created: {file.created_at}")
print(f"Team ID: {file.team_id}")Getting File Content
Download the actual content of a file.
import os
from xai_sdk import Client
client = Client(api_key=os.getenv("XAI_API_KEY"))
# Get file content
content = client.files.content("file-abc123")
# Content is returned as bytes
print(f"Content length: {len(content)} bytes")
print(f"Content preview: {content[:100]}")Deleting Files
Remove files when they're no longer needed.
import os
from xai_sdk import Client
client = Client(api_key=os.getenv("XAI_API_KEY"))
# Delete a file
delete_response = client.files.delete("file-abc123")
print(f"Deleted: {delete_response.deleted}")
print(f"File ID: {delete_response.id}")Limitations and Considerations
File Size Limits
- Maximum file size: 48 MB per file
- Processing time: Larger files may take longer to process
File Retention
- Cleanup: Delete files when no longer needed to manage storage
- Access: Files are scoped to your team/organization
Supported Formats
While many text-based formats are supported, the system works best with:
- Structured documents (with clear sections, headings)
- Plain text and markdown
- Documents with clear information hierarchy
Supported file types include:
- Plain text files (.txt)
- Markdown files (.md)
- Code files (.py, .js, .java, etc.)
- CSV files (.csv)
- JSON files (.json)
- PDF documents (.pdf)
- And many other text-based formats
Next Steps
Now that you know how to manage files, learn how to use them in chat conversations: