Freecaster Platform API (12.20.0)

Generate a JWT token used to access the API calls

Generate a signed URL to upload a video file to the ingest S3 bucket for transcoding.

Usage Guidelines

• File Size Limit: For files larger than 5GB, use the multipart upload
• Supported Formats: MP4, MOV, AVI, MKV, and other common video formats
• URL Expiration: Signed URLs expire after 30 minutes by default (configurable via expires_in parameter)

Upload Process

The upload must be done as a PUT request with the video file as body (see the AWS documentation for more information).

Example Workflow

# Step 1: Get signed URL (see request body schema for payload structure)
curl -X POST "https://api.freecaster.com/api/s3upload" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d @request-payload.json

# Step 2: Upload file using the returned signed URL
curl -X PUT -T "path/to/your/local/video-file.mp4" "$SIGNED_URL"

Multipart upload

When to Use Multipart Upload

• Large Files: Files larger than 5GB or when you want to optimize upload performance
• Unreliable Networks: Better resilience to network interruptions with resumable uploads
• Parallel Uploads: Upload multiple parts simultaneously for faster transfer

Multipart Upload Process

1. Initiate: Call this endpoint to get upload URLs for each part
2. Upload Parts: Upload each part using the provided signed URLs
3. Complete: Call /s3upload/complete to finalize the multipart upload

Technical Details

• Part Size: Each part should be 5MB to 5GB (except the last part which can be smaller)
• Maximum Parts: Up to 10,000 parts per upload
• Part Numbering: Parts are numbered sequentially starting from 1
• URL Expiration: Each signed URL expires after 30 minutes by default

Example Workflow

# Step 1: Initiate multipart upload (see request body schema for payload structure)
curl -X POST "https://api.freecaster.com/api/s3upload?multipart=true" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d @multipart-request.json

# Step 2: Upload each part (example for part 1)
curl -X PUT --data-binary @part1.bin "$PART_1_SIGNED_URL"

# Step 3: Complete multipart upload (see /s3upload/complete endpoint)

Error Handling

• Part Upload Failure: Retry individual parts without restarting the entire upload
• Invalid Part Size: Ensure all parts (except the last) are at least 5MB
• Missing Parts: All parts must be uploaded before calling complete endpoint

Complete the multipart upload by reassembling all uploaded parts into the final video file.

Purpose

This endpoint finalizes a multipart upload by instructing S3 to combine all uploaded parts into a single file. This must be called after all parts have been successfully uploaded using the URLs from the multipart initiation endpoint.

Prerequisites

• All parts must be uploaded successfully using the signed URLs from /s3upload?multipart=true
• You must have the upload_id and key from the multipart initiation response
• Parts must be uploaded in the correct order (part numbers 1, 2, 3, etc.)

Request Details

The request must include:

• upload_id: The AWS multipart upload identifier
• key: The S3 object key for the file
• parts: Array of part information including ETag and part number (optional but recommended for validation)

Example Request

# Complete multipart upload (see request body schema for payload structure)
curl -X POST "https://api.freecaster.com/api/s3upload/complete" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d @complete-request.json

Post-Completion Process

After successful completion:

1. File Assembly: S3 combines all parts into the final video file
2. Transcoding Queue: The video automatically enters the transcoding pipeline
3. Webhook Notifications: You'll receive transcoding.started followed by transcoding.completed or transcoding.failed

Error Scenarios

• Missing Parts: If any parts are missing, the completion will fail
• Invalid Upload ID: Ensure the upload_id matches the one from multipart initiation
• Expired Upload: Multipart uploads expire after 7 days if not completed
• Part Size Validation: All parts except the last must be at least 5MB

Troubleshooting

• 404 Error: Check that upload_id and key are correct
• 400 Error: Verify all parts were uploaded successfully
• Timeout: Large files may take time to assemble; implement appropriate timeout handling

Abort the upload of a file and remove the previous parts from S3 in case of a multipart upload. This can be done even without a part already sent to the S3.

List all videos

Create a new video

Get a video

Edit a video

Delete a video

Get the active poster of a video

Create and associate a poster to a video. There are two ways to attach a poster, either through an image upload or through extraction from the video given a timestamp.

Get all posters from a video

Delete poster

Create and transcode a video