Start a large file upload
curl --request POST \
--url https://api.varg.ai/v2/files/upload-session \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"media_type": "video/mp4",
"filename": "clip.mp4",
"size": 48234112,
"hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}
'import requests
url = "https://api.varg.ai/v2/files/upload-session"
payload = {
"media_type": "video/mp4",
"filename": "clip.mp4",
"size": 48234112,
"hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
media_type: 'video/mp4',
filename: 'clip.mp4',
size: 48234112,
hash: 'sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08'
})
};
fetch('https://api.varg.ai/v2/files/upload-session', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.varg.ai/v2/files/upload-session",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'media_type' => 'video/mp4',
'filename' => 'clip.mp4',
'size' => 48234112,
'hash' => 'sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.varg.ai/v2/files/upload-session"
payload := strings.NewReader("{\n \"media_type\": \"video/mp4\",\n \"filename\": \"clip.mp4\",\n \"size\": 48234112,\n \"hash\": \"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.varg.ai/v2/files/upload-session")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"media_type\": \"video/mp4\",\n \"filename\": \"clip.mp4\",\n \"size\": 48234112,\n \"hash\": \"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.varg.ai/v2/files/upload-session")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"media_type\": \"video/mp4\",\n \"filename\": \"clip.mp4\",\n \"size\": 48234112,\n \"hash\": \"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08\"\n}"
response = http.request(request)
puts response.read_body{
"deduplicated": false,
"session_id": "file_abc123",
"upload_url": "https://example.r2.cloudflarestorage.com/files/acc_x/file_abc123.mp4?X-Amz-Signature=...",
"public_url": "https://s3.varg.ai/files/acc_x/file_abc123.mp4",
"proxy_url": "/v2/files/upload/file_abc123",
"headers": {
"Content-Type": "video/mp4"
},
"expires_in": 3600,
"hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}Files
Start a large file upload
Upload flow for files too large or awkward for POST /files (up to
200 MB):
- Call this endpoint with the file’s
media_typeand, ideally, itssizeand sha256hash. - If the response has
deduplicated: true, the file already exists in your account: use the returnedfile_idandurland skip the upload. - Otherwise send the raw bytes with
PUT {upload_url}(direct to storage), orPUT /files/upload/{session_id}(proxy_url) when your environment can only reachapi.varg.ai. Use theContent-Typeinheaders. The session is valid for 1 hour and accepts one upload. - The proxy PUT registers the file and returns
file_id. If you uploaded toupload_urldirectly, register it afterwards withPOST /files/importusingpublic_url.
Send X-Workspace-Id (or workspace_id in the body) to file the
upload into a folder.
POST
/
files
/
upload-session
Start a large file upload
curl --request POST \
--url https://api.varg.ai/v2/files/upload-session \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"media_type": "video/mp4",
"filename": "clip.mp4",
"size": 48234112,
"hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}
'import requests
url = "https://api.varg.ai/v2/files/upload-session"
payload = {
"media_type": "video/mp4",
"filename": "clip.mp4",
"size": 48234112,
"hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
media_type: 'video/mp4',
filename: 'clip.mp4',
size: 48234112,
hash: 'sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08'
})
};
fetch('https://api.varg.ai/v2/files/upload-session', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.varg.ai/v2/files/upload-session",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'media_type' => 'video/mp4',
'filename' => 'clip.mp4',
'size' => 48234112,
'hash' => 'sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.varg.ai/v2/files/upload-session"
payload := strings.NewReader("{\n \"media_type\": \"video/mp4\",\n \"filename\": \"clip.mp4\",\n \"size\": 48234112,\n \"hash\": \"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.varg.ai/v2/files/upload-session")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"media_type\": \"video/mp4\",\n \"filename\": \"clip.mp4\",\n \"size\": 48234112,\n \"hash\": \"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.varg.ai/v2/files/upload-session")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"media_type\": \"video/mp4\",\n \"filename\": \"clip.mp4\",\n \"size\": 48234112,\n \"hash\": \"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08\"\n}"
response = http.request(request)
puts response.read_body{
"deduplicated": false,
"session_id": "file_abc123",
"upload_url": "https://example.r2.cloudflarestorage.com/files/acc_x/file_abc123.mp4?X-Amz-Signature=...",
"public_url": "https://s3.varg.ai/files/acc_x/file_abc123.mp4",
"proxy_url": "/v2/files/upload/file_abc123",
"headers": {
"Content-Type": "video/mp4"
},
"expires_in": 3600,
"hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}Authorizations
varg API key (varg_...). Get one at app.varg.ai
or run bunx vargai login. App sessions may alternatively send a
Supabase JWT.
Headers
Folder (id or slug) to file the upload into. Wins over workspace_id in the body.
Body
application/json
MIME type of the file. Defaults to application/octet-stream (the real type is then detected from the bytes on upload).
Example:
"video/mp4"
File size in bytes (max 200 MB)
Required range:
1 <= x <= 209715200sha256 of the file, with or without the sha256: prefix. Lets the API skip the upload when you already have the file.
Folder (id or slug) to file the upload into. X-Workspace-Id takes precedence.
Response
A new upload session, or the existing file when the hash matches
- Option 1
- Option 2
Available options:
false Id for PUT /files/upload/{session_id}. Also becomes the file id.
Presigned URL. PUT the bytes here directly, with the headers below.
URL the file will have once uploaded
Path of the proxy endpoint on this API, for clients that cannot reach upload_url
Example:
"/v2/files/upload/file_abc123"
Headers to send with the PUT
Show child attributes
Show child attributes
Seconds until the session expires
Example:
3600
Was this page helpful?