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, Gcore provides a support-assisted batch workflow — contact support@gcore.com to arrange it. The Customer Portal upload workflow is covered in Upload a video. All requests 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 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.

Download behavior

Gcore attempts to download the source file three times, expecting a 200 OK response. If all three attempts fail, the video entity stays in Empty status and the error field contains details — delete the empty entity 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.

Batch migration

For migrating a large collection of videos, Gcore provides a support-assisted batch workflow. Contact support@gcore.com to arrange it. To prepare the migration, obtain an HTTP link to each file in the source storage: For storage types not listed, contact support@gcore.com.

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.

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.