docs/s3/upload.md

S3 Upload API

This endpoint allows you to stream a file from a remote URL directly to an S3-compatible storage service without using local disk space.

Endpoint

POST /v1/s3/upload

Authentication

This endpoint requires an API key to be provided in the X-API-Key header.

Request Body

The request body should be a JSON object with the following properties:

Property	Type	Required	Description
file_url	string	Yes	The URL of the file to upload to S3
filename	string	No	Custom filename to use for the uploaded file. If not provided, the original filename will be used
public	boolean	No	Whether to make the file publicly accessible. Defaults to false

Example request body:

{
  "file_url": "https://example.com/path/to/file.mp4",
  "filename": "custom-name.mp4",
  "public": true
}

Response

The response will be a JSON object with the following properties:

Property	Type	Description
url	string	The URL of the uploaded file. For public files, this is a direct URL. For private files, this is a pre-signed URL that will expire after 1 hour
filename	string	The filename of the uploaded file
bucket	string	The name of the S3 bucket where the file was uploaded
public	boolean	Whether the file is publicly accessible

Example response:

{
  "url": "https://bucket-name.s3.region.amazonaws.com/custom-name.mp4",
  "filename": "custom-name.mp4",
  "bucket": "bucket-name",
  "public": true
}

Error Handling

If an error occurs, the response will include an error message with an appropriate HTTP status code.

Technical Details

This endpoint uses the S3-compatible multipart upload API to stream the file directly from the source URL to S3 without saving it locally. This allows for efficient transfer of large files with minimal memory usage.

The implementation:

1. Streams the file from the source URL in chunks
2. Uploads each chunk to S3 as a part of a multipart upload
3. Completes the multipart upload once all parts are uploaded

This approach supports resumable uploads and can handle large files efficiently.