SOP 004: Send Files

Fresh 🌱

Document ID: SOP-004
Version: 1.0
Status: Active

Objective

Upload and send file attachments (PDFs, images, documents) with your API queries.

Prerequisites

• [x] API key obtained (SOP 001)
• [x] fastapi-poe installed (SOP 002)
• A file to upload (PDF, image, etc.)

Procedure

Step 1: Open File in Binary Mode

file_handle = open("document.pdf", "rb")

Step 2: Upload File (Synchronous)

attachment = fp.upload_file_sync(file_handle, api_key=api_key)
file_handle.close()

Step 3: Upload File (Asynchronous)

file_handle = open("document.pdf", "rb")
attachment = await fp.upload_file(file_handle, api_key=api_key)
file_handle.close()

Step 4: Include in Message

message = fp.ProtocolMessage(
    role="user",
    content="Analyze this document",
    attachments=[attachment]
)

Step 5: Send Query

for partial in fp.get_bot_response_sync(
    messages=[message],
    bot_name="GPT-5",
    api_key=api_key
):
    print(partial, end="", flush=True)

Complete Example

Synchronous File Upload

import fastapi_poe as fp
import os

api_key = os.getenv("POE_API_KEY")

# Upload file
print("Uploading file...")
with open("draconomicon.pdf", "rb") as f:
    pdf_attachment = fp.upload_file_sync(f, api_key=api_key)
print("✓ File uploaded")

# Create message with attachment
message = fp.ProtocolMessage(
    role="user",
    content="Summarize the key points in this document",
    attachments=[pdf_attachment]
)

# Query bot
print("Querying bot...")
for partial in fp.get_bot_response_sync(
    messages=[message],
    bot_name="Claude-Sonnet-4.5",
    api_key=api_key
):
    print(partial, end="", flush=True)
print("\n✓ Complete!")

Asynchronous File Upload

import asyncio
import fastapi_poe as fp
import os

async def analyze_document():
    api_key = os.getenv("POE_API_KEY")
    
    # Upload file
    print("Uploading file...")
    with open("document.pdf", "rb") as f:
        attachment = await fp.upload_file(f, api_key=api_key)
    print("✓ File uploaded")
    
    # Create message
    message = fp.ProtocolMessage(
        role="user",
        content="What are the main topics covered?",
        attachments=[attachment]
    )
    
    # Query bot
    print("Querying bot...")
    async for partial in fp.get_bot_response(
        messages=[message],
        bot_name="Claude-Sonnet-4.5",
        api_key=api_key
    ):
        print(partial, end="", flush=True)
    print("\n✓ Complete!")

asyncio.run(analyze_document())

Supported File Types

Common supported formats:

• PDF documents (.pdf)
• Images (.png, .jpg, .jpeg, .gif)
• Text files (.txt, .md)
• Other formats supported by Poe bots

Verification

Expected flow:

Uploading file...
✓ File uploaded
Querying bot...
[Bot analyzes file and responds...]
✓ Complete!

Troubleshooting

Problem: File not found
Solution:

• Check file path is correct
• Use absolute path if needed
• Verify file exists

Problem: File too large
Solution:

• Check Poe's file size limits
• Compress or split large files
• Use smaller test file first

Problem: Unsupported file type
Solution:

• Verify file format is supported
• Try converting to PDF
• Check bot's capabilities

Problem: Upload timeout
Solution:

• Check internet connection
• Use async for better handling
• Retry with exponential backoff

Best Practices

1. Use context managers (with statement) for file handling
2. Close files after upload
3. Handle large files with streaming if possible
4. Verify file size before upload
5. Use async for multiple file uploads

Multiple Files

You can attach multiple files:

attachments = []

# Upload multiple files
for file_path in ["doc1.pdf", "doc2.pdf", "image.png"]:
    with open(file_path, "rb") as f:
        attachment = fp.upload_file_sync(f, api_key=api_key)
        attachments.append(attachment)

message = fp.ProtocolMessage(
    role="user",
    content="Compare these documents",
    attachments=attachments
)

See Also

• SOP 003: Basic Query
• SOP 005: Custom Parameters
• Quick Reference: Commands

---

Next: 005: Custom Parameters