Upload File from Base64
Upload files to PoYo AI using Base64-encoded data or Data URL format
Usage Guide
- This endpoint accepts Base64-encoded file data for upload to PoYo AI storage
- Supports both Data URL format (with MIME type prefix) and pure Base64 strings
- Ideal for uploading files that are already Base64-encoded in your application, such as canvas drawings or client-side image manipulations
- Files are immediately accessible via the returned URL and remain available for 72 hours
Parameter Details
-
Base64 Data Format:
-
Data URL format:
data:image/png;base64,iVBORw0KGgo...(recommended) -
Pure Base64 string:
iVBORw0KGgo...(without MIME type prefix) - The Base64 string must not contain any whitespace, newline characters, or formatting
- Supported file formats: JPEG, PNG, GIF, WebP only
- Maximum upload limit: 1 image per request
-
Data URL format:
-
Storage Configuration:
-
All files are automatically stored with a
temp/prefix in the storage path -
If you specify
upload_path: "profile-images", the actual path will betemp/profile-images - Files will expire and be automatically deleted 72 hours after upload
-
All files are automatically stored with a
-
File Naming:
-
If
file_nameis not provided, the system generates a unique name in the format:{timestamp}_{random}_{extension} -
Example auto-generated name:
20251229130857_a8B9cD2e.png
-
If
Developer Notes
-
When to use Base64 upload:
- Client-side generated images (canvas, screenshots)
- Images already encoded in Base64 format in your application
- Small to medium-sized images where encoding overhead is acceptable
-
When NOT to use Base64 upload:
- Large image files (Base64 encoding increases size by ~33%)
- Files stored on disk (use stream upload instead)
- Files available via URL (use URL upload instead)
- Ensure your Base64 data is properly formatted without any line breaks or spaces
- For persistent storage needs, download and save the file locally before the 72-hour expiration
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 Requestserror - 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
- Invalid Base64 Encoding: The provided Base64 string cannot be decoded
-
Invalid Data URL Format: The Data URL format is malformed (e.g., missing
data:prefix or;base64,separator) - Unsupported File Type: The decoded file is not in a supported image format (JPEG, PNG, GIF, WebP)
- Invalid File Data: The decoded data is empty or corrupted
- Authentication Error: Missing or invalid API key in the Authorization header
Authorizations
All API endpoints require Bearer Token authentication.
Create an API key: sign in to PoYo, open Dashboard → API Key at poyo.ai/dashboard/api-key, and click to create a key.
Add it to the request header:
Authorization: Bearer YOUR_API_KEY
Body
Base64-encoded file data.
Supports two formats:
-
Data URL format:
data:image/png;base64,iVBORw0KGgo... -
Pure Base64 string:
iVBORw0KGgo...(without MIME type prefix)
Supported formats: JPEG, PNG, GIF, WebP
Note: The Base64 string should not include any whitespace or newline characters.
"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
Response
File uploaded successfully
Business status code. 200 means success; any other value means the request failed. Always check this field: some validation errors return HTTP 200 with code: 400 in the body.
200: Success400: Invalid request parameters401: Missing or invalid API key402: Insufficient credits403: Permission denied404: Resource not found408: Request timeout429: Rate limit exceeded500: Internal server error502: Upstream service error503: Service unavailable
See Error Codes for details.
200, 400, 401, 402, 403, 404, 408, 429, 500, 502, 503 200