Upload File Stream

​

Usage Guide

• This endpoint enables direct file uploads using the standard multipart/form-data format
• Supports uploading files directly from local storage with automatic file type identification
• Best suited for local file uploads from desktop applications, mobile apps, or web forms
• Files are immediately accessible via the returned URL. Images remain available for 72 hours; videos remain available for 24 hours when stored under the temp/videos lifecycle prefix

​

Parameter Details

• File Upload Requirement:
  • The file field must contain binary file data
  • Supported image formats: JPEG, PNG, GIF, WebP
  • Supported video formats: MP4, WebM, MOV/QuickTime, AVI, MKV
  • Maximum upload limit: 1 file per request. Videos are limited to 100MB
  • The system automatically identifies the file type from the binary data
• Parameter Naming Convention:
  • This endpoint supports both snake_case and camelCase naming conventions
  • upload_path or uploadPath - both are accepted
  • file_name or fileName - both are accepted
  • Use whichever convention matches your application’s coding style
• Storage Configuration:
  • All files are automatically stored with a temp/ prefix in the storage path
  • If you specify upload_path: "photos", the actual path will be temp/photos
  • Images expire and are automatically deleted 72 hours after upload
  • Videos uploaded with the default path are stored under temp/videos/ and expire after 24 hours when the R2 lifecycle rule is configured for that prefix
• File Naming:
  • If file_name is not provided, the system generates a unique name in the format: {timestamp}_{random}_{extension}
  • Example auto-generated name: 20251229130857_a8B9cD2e.png

​

Developer Notes

• When to use file stream upload:
  • Direct file uploads from user’s local storage
  • Form-based file uploads from web applications
  • Mobile app file uploads
  • Server-to-server file transfers
• This is the most efficient upload method for files already stored on disk
• The multipart/form-data format is standard across all programming languages and HTTP clients
• For persistent storage needs, download and save the file locally before expiration: 72 hours for images, 24 hours for videos

​

Rate Limits and Quotas

• Rate Limit: 10 requests per 60-second fixed window per authenticated user, per upload endpoint
• When the rate limit is exceeded, you will receive a 429 Too Many Requests error
• The fixed window starts with the first request in the window and is shared by JWT and API key requests from the same user
• Implement exponential backoff retry logic for handling rate limit errors

​

Common Error Scenarios

• Missing File: No file was provided in the request body (422 error)
• Unsupported File Type: The uploaded file is not a supported image format (JPEG, PNG, GIF, WebP) or video format (MP4, WebM, MOV/QuickTime, AVI, MKV)
• Video Too Large: The uploaded video exceeds the 100MB limit (413 error)
• Empty File: The uploaded file has zero bytes or is corrupted
• Authentication Error: Missing or invalid API key in the Authorization header

​

Example Usage

​

cURL Example

curl -X POST "https://api.poyo.ai/api/common/upload/stream" \
  -H "Authorization: Bearer PoYo_API_KEY" \
  -F "file=@/path/to/image.png" \
  -F "file_name=my-image.png"

​

Python Example

import requests

url = "https://api.poyo.ai/api/common/upload/stream"
headers = {"Authorization": "Bearer PoYo_API_KEY"}

files = {"file": open("/path/to/image.png", "rb")}  # or /path/to/video.mp4
data = {"file_name": "my-image.png"}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

​

JavaScript Example (Node.js)

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

const form = new FormData();
form.append('file', fs.createReadStream('/path/to/image.png')); // or /path/to/video.mp4
form.append('file_name', 'my-image.png');

axios.post('https://api.poyo.ai/api/common/upload/stream', form, {
  headers: {
    'Authorization': 'Bearer PoYo_API_KEY',
    ...form.getHeaders()
  }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

​

Video Upload Example

curl -X POST "https://api.poyo.ai/api/common/upload/stream"   -H "Authorization: Bearer PoYo_API_KEY"   -F "file=@/path/to/video.mp4"   -F "file_name=my-video.mp4"

Authorization: Bearer PoYo_API_KEY