Skip to main content
Two API upload methods are available: copy a file from an external URL, or upload a local file using the TUS resumable protocol. For large-scale migrations, the batch migration endpoint creates up to 500 videos in one request. The Customer Portal upload workflow is covered in Upload a video. Requests to the Gcore API require an API token. Set it as an environment variable before running the examples:
The source file must comply with the input parameters and codec requirements in Input parameters and codecs. Only files with supported protocols, video/audio codecs, profiles, GOP structure, and bitrate constraints are accepted and reliably transcoded. Source properties such as pixel format, color range, or codec profile must remain stable throughout the file; reprocessing cannot fix mid-stream changes. Processing statuses for uploaded videos are described in VOD status.

Copy from external storage

If the source file is available at a public HTTP, HTTPS, or SFTP URL, Gcore downloads it server-side. Supported protocols:
  • HTTP/HTTPS from external video hosting services (Vimeo, Mux)
  • HTTP/HTTPS from S3-compatible storages (AWS S3, Azure Blob Storage)
  • SFTP
The source file must be in one of these formats: MP4, 3g2, 3gp, asf, avi, dif, dv, flv, f4v, m4v, mov, mpeg, mpg, mts, m2t, m2ts, qt, wmv, vob, mkv, ogv, webm, ogg, mxf, quicktime, x-ms-wmv, mpeg-tts, vnd.dlna.mpeg-tts.Streaming formats such as HLS (.m3u8/.ts) and DASH (.mpd/.m4v) are intended for end-viewer delivery and cannot be used as source files.
Valid and invalid source URL examples:
  • Valid: https://demo-files.gvideo.io/gcore.mp4 (13.8 MB from S3)
  • Valid SFTP: sftp://login:password@domain.com/path/file.mp4
  • Invalid (HLS): https://demo-files.gvideo.io/hls/master.m3u8
Send POST /streaming/videos with the source URL in the origin_url attribute:
The API returns:
There is no limit on the number of videos that can wait in the transcoding queue. API requests are still subject to the RPS limits. Copying an existing video has no dedicated endpoint. Create a new video with an origin_url that points to a reachable copy of the source file, optionally with clip_start_seconds and clip_duration_seconds to copy only a fragment. The copy gets a new video ID and playback URL, and it’s transcoded again. The same request works across accounts, as long as Gcore can reach the source URL. The source file of an existing video can’t be replaced. origin_url is set only when the video is created, with POST /streaming/videos or the batch endpoint. After that the field is read-only, and an update request ignores a new value. To publish a new version of a video, create a new video and point the player to the new ID, or keep a stable alias in the application that maps to the current video ID.

Download behavior

For an HTTP or HTTPS source, Gcore attempts to download the file three times and expects a 200 OK response. If the attempts fail, the video status becomes error and the error field contains the details. Delete that video and create a new one with a correct URL. If the download succeeds, Gcore starts transcoding the video. Check transcoding progress via the GET /streaming/videos/ endpoint or webhook notifications.

Upload from a local device

For uploads from a backend server or from a browser or mobile app, Gcore uses the TUS resumable upload protocol. TUS splits the file into segments and resumes from the last successful segment if an interruption occurs. The upload process consists of three steps.

Step 1. Create a video entity

Send POST /streaming/videos without the origin_url attribute to create a video entity and receive its ID and client_id:
The API returns:
Save id and client_id — both are required in Step 3.

Step 2. Get TUS session parameters

Use the id from Step 1 to request the TUS upload server URL and session token:
The API returns:
Fields in the response:
  • servers — available upload servers; use any server where active is true.
  • token — session token valid for 4 hours. Once the TUS session starts, the token is no longer needed.
  • video — a copy of the video entity data.

Step 3. Upload via TUS

Use the values collected from Steps 1 and 2 as the TUS client configuration: Choose a chunk size that fits the network conditions: larger chunks use maximum bandwidth but require re-uploading a larger segment after a failure; smaller chunks are more resilient but slower due to per-request HTTP overhead.
Transmitted data must comply with the Upload-Metadata header rules:
  • Header fields must be comma-separated.
  • All values are Base64-encoded.
  • All keys are unique.
Bash upload command:
JavaScript upload with the CodePen template — copy token, video_id, and client_id to test the TUS upload flow:
CodePen TUS upload template showing token, video_id, and client_id input fields
Available TUS client implementations:

TUS error reference

Common errors returned by the TUS upload server and their causes:
  • HTTP 405 Method Not Allowed — unexpected response when creating the upload session; check the request parameters.
  • HTTP 429 Too Many Requests — retry the request after a delay.
  • HTTP 500 Internal Server Error:
    • token invalid (null) — check parameter format, Base64 encoding, and key-value separation.
    • token invalid (eyJhbGciOi...) — same as above.
    • token video (12345) does not match this video (23456) — video_id mismatch; do not retry.
    • token client (123) does not match this client (234) — client_id mismatch; do not retry.

Optional upload settings

The following parameters can be included in any POST /streaming/videos request body to configure transcoding behavior at upload time.

Processing priority

Every uploaded video enters a transcoding queue. Two priority levels influence scheduling:
  • Global priority — managed automatically by the system at the infrastructure level and is not user-configurable.
  • Account priority — applied within an account, controlled via the priority field.
Use the priority field to adjust scheduling order for transcoding tasks within an account:
  • Type: integer
  • Range: -10 to 10
    • -10 — lowest priority (processed after other jobs)
    • 0 — default
    • 10 — highest priority (processed first)
This value adjusts relative job weight in the queue; it does not guarantee absolute ordering.

Poster and screenshots

Every video gets five automatic screenshots in the screenshots field, spread across the video, including recordings, copies, and videos created from clips. They are generated even when transcoding ends in error, and screenshot_id selects the default one. The index in screenshots and screenshot_id is zero-based, while the numbers in the screenshot URLs are one-based, so the first screenshot in the array is the URL that contains _1_.

The example shows the five screenshots of one video. The default is screenshots[0], and it is black because the video opens on a black frame.

Five automatically generated screenshots of a video, with the first one marked as the default

The first screenshot is taken at the start of the video, so it is black when the video starts from a black image. If the default screenshot isn’t suitable as a thumbnail, set screenshot_id to another screenshot or upload a custom poster.

A custom poster is optional. Pass the image in poster as a base64 string, or pass a URL in remote_poster_url. The image must be JPEG, WebP, or PNG, up to 1 MB. Set screenshot_id to -1 to use the custom poster instead of a screenshot, and set remove_poster to true to remove it. While a poster is set, selecting another screenshot with screenshot_id doesn’t change the thumbnail, so remove the poster first.

AI subtitles

AI-generated subtitles can be created automatically at upload time by adding two parameters to the request body:
  • auto_transcribe_audio_language — transcribes the audio track into subtitles. Set to auto for language detection, or specify a language code such as en or fr.
  • auto_translate_subtitles_language — translates the transcribed subtitles into additional languages. Set to default for the account language, or provide a comma-separated list of language codes.
Language codes and translation options are documented in Generate AI subtitles.

Batch migration

The batch endpoint POST /streaming/videos/batch creates many videos in one aggregated request instead of one request per file, so a large library moves in a few calls. The videos array holds one object per video with the same fields as a single POST /streaming/videos request, including origin_url, priority, and optional subtitles. Videos from one request enter the transcoding queue in order of priority.
The response is an array of the created videos. Each one follows the same download behavior and status flow as a single video created from a URL. Each request is limited as follows:
  • 500 videos per request
  • 64 MB request body
  • 30 s API connection timeout
A library with more than 500 files is sent as several consecutive requests, which still count toward the RPS limits. To prepare the migration, obtain an HTTP link to each file in the source storage: For storage types not listed, contact support@gcore.com.

Batch migration example

This example shows how to run a batch migration correctly: one request creates the videos in a new directory, downloads each poster by URL, and attaches English subtitles to one video. Gcore prepared a demo bucket with public HTTP access, so the same steps can be run as they are to test batch migration, and the same flow applies to a real library after the URLs are replaced. The demo bucket https://demo-files.gvideo.io/bucket/ holds four Blender Studio open movies. Every video is a 720p H.264 MP4, every poster is a JPEG under the 1 MB poster limit, and the files are public, so no origin_http_headers are needed:

Step 1. Check the source files

Gcore downloads videos and posters from their URLs, so every file must be reachable without authentication. Posters must be JPEG, WebP, or PNG, up to 1 MB each. A HEAD request shows the status and size of each file:
Every file answers 200, and each poster reports a content-length below 1048576.

Step 2. Create a directory

A directory keeps the migrated videos together, so the batch can be checked and removed as one unit. Send POST /streaming/directories:
The response wraps the new directory in directory. Take its ID from directory.id:
Save the ID for the next steps. To migrate into an existing directory, take its ID from GET /streaming/directories instead.

Step 3. Download the subtitles

The batch endpoint takes the subtitle text inside the request instead of a URL, so the .vtt file is downloaded first:

Step 4. Build the batch request

Each object in the videos array describes one video, and only name is required. The script builds the request from these fields: Save the script as build_batch.py:
Run it with the directory ID to write batch.json:

Step 5. Send the batch request

One request creates all four videos:
The response is an array with the IDs of the new videos. The videos start as empty or pending while Gcore downloads and transcodes them.

Step 6. Check the result

The directory lists all four videos with their statuses. Poll it until every video is ready or viewable:
To see the source link of a migrated video, request it with GET /streaming/videos/. The origin_url field holds the link.