Skip to main content
This guide uses V2 of the upload-link API: POST /api/upload-links-v2. V1 (POST /api/upload-links) is deprecated and stops working on December 24, 2026. If your integration calls V1, follow Migrate from V1. The change takes a few minutes.

Overview

This guide shows how to upload a video file to Google Cloud Storage (GCS) with the Opus API and then create a clip project from it. There are four steps: get an upload link, start a resumable upload session, upload the video, and create the clip project.

Authentication

All API requests require an API key:
Replace <API_KEY> with your valid API token.

Endpoint

Headers

Request Body

Response Example

  • url is a signed URL. The file’s content type is part of the signature.
  • requiredHeaders lists the headers you must send in Step 2, exactly as returned.
  • Keep uploadId for Step 4.

cURL Example


Step 2: Initiate Resumable Upload Session

Endpoint

Headers

Send every header in requiredHeaders from Step 1, plus Content-Length: 0:

Request Body

(empty)
Send the requiredHeaders values exactly as returned. If a header is missing or different, GCS rejects the request with 403.
  • Replace <url_from_previous_step> with the url received from Step 1
  • No response body is returned
  • Look for the location header in the response which contains the resumable upload URL

Example Response Headers

cURL Example


Step 3: Upload Video File

Endpoint

Headers

Upload File

Use the --upload-file option with your actual video file (e.g., test.mp4).

cURL Example

Replace <location> with the location URL from Step 2 response headers.

Step 4: Create Clip Project

Endpoint

Headers

Response Headers

Request Body

cURL Example

forceStrategy (optional, advanced) pins curation to an explicit strategy instead of letting OpusClip auto-select one. Talk to our support team to learn how to use it.
  • Replace <uploadId> with the ID returned in Step 1
For detailed explanations of the project-creation request body, refer to Create a New Project, which documents the POST /api/clip-projects API.

Full Workflow Summary

1

Generate Upload Link

Get url, uploadId, and requiredHeaders from POST /api/upload-links-v2
2

Start Resumable Session

Send requiredHeaders to the url from Step 1 and get location from the response headers
3

Upload Video File

Upload your video file to the location from Step 2
4

Create Clip Project

Create a new clip project using the uploadId from Step 1

Migrate from V1

V1 (POST /api/upload-links) stops working on December 24, 2026. After that date, V1 requests fail and uploads stop. V2 sets the file’s content type on the server and signs it into the upload URL, so a file cannot be stored with a type the client chose. To move an existing integration, make two changes. Steps 3 and 4 stay the same.
The V1 guide stays available for reference: Upload Video and Create Clip Project (V1, deprecated).

POST /api/clip-projects

Refer to the full API reference for creating a clip project.

Get Clips

Retrieve clips from your created projects