Start an upload

About

Use it to send a video from your computer or server. Send the name of the file and its exact size; the answer says how many parts to send and how big each one is. Then send every part with upload_part (PUT /v1/uploads/{uploadId}/parts/{partNumber}), in any order and in parallel, and finish with complete_upload (POST /v1/uploads/{uploadId}/complete), which turns the file into an asset you can analyze. Only MP4, MOV, MKV, WebM, AVI and MPEG-TS video files are accepted, up to 8 GB, and the file counts toward the storage of the account. A video in another format, such as MPG, FLV, WMV or OGV, is refused before the upload opens: convert it to MP4 or MOV first. Send an Idempotency-Key: a retry with the same key returns the same upload instead of opening a second one.

Example use

A backend that receives a two-hour webinar from its customer opens an upload with the exact file size. It then sends the parts in parallel with upload_part (PUT /v1/uploads/{uploadId}/parts/{partNumber}) and finishes with complete_upload (POST /v1/uploads/{uploadId}/complete).

Endpoint

POST https://api.gpt-video.com/v1/uploads

• Scope clips:write.
• Rate limit 60 requests a minute for each key and 120 for each account, shared by every write call. See rate limits.
• Idempotency-Key is optional.

Parameters

Headers

Body

Send only the fields listed here. Any other field is refused with UNKNOWN_PARAMETER.

Request

Start the upload of a 20 MB video.

# Create the key once. Send this same key again if you retry this request.
IDEMPOTENCY_KEY=$(uuidgen)
curl -X POST "https://api.gpt-video.com/v1/uploads" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "keynote.mp4",
    "sizeBytes": 20971520,
    "contentType": "video/mp4"
  }'

// Create the key once. Send this same key again if you retry this request.
const idempotencyKey = crypto.randomUUID();
const res = await fetch("https://api.gpt-video.com/v1/uploads", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.GPT_VIDEO_API_KEY}`,
    "Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "filename": "keynote.mp4",
    "sizeBytes": 20971520,
    "contentType": "video/mp4"
  }),
});
const data = await res.json();
console.log(data);

import os
import uuid

import requests

# Create the key once. Send this same key again if you retry this request.
idempotency_key = str(uuid.uuid4())
r = requests.post(
    "https://api.gpt-video.com/v1/uploads",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
        "Idempotency-Key": idempotency_key,
    },
    json={
        "filename": "keynote.mp4",
        "sizeBytes": 20971520,
        "contentType": "video/mp4"
    },
)
data = r.json()
print(data)

{
  "method": "tools/call",
  "params": {
    "name": "create_upload",
    "arguments": {
      "filename": "keynote.mp4",
      "sizeBytes": 20971520,
      "contentType": "video/mp4"
    }
  }
}

Response

A successful call answers HTTP 201. Returns a Upload object in upload.

Fields to check

Response example

{
  "upload": {
    "id": "upl_9c4e1a7d2b5f4e6083b1",
    "filename": "keynote.mp4",
    "contentType": "video/mp4",
    "sizeBytes": 20971520,
    "partSizeBytes": 8388608,
    "partCount": 3,
    "receivedParts": [],
    "createdAt": "2026-09-01T10:30:00.000Z",
    "expiresAt": "2026-09-01T16:30:00.000Z"
  }
}

{
  "filename": "slides.pdf",
  "sizeBytes": 524288,
  "contentType": "application/pdf"
}

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Only video files can be uploaded through the API for now.",
    "hint": "Fix the request as the message says, then send it again.",
    "requestId": "req_2b7e4a9c1d5f8e3a6b0c9d4e"
  }
}

{
  "filename": "talk.mpg",
  "sizeBytes": 4000000000,
  "contentType": "video/mpeg"
}

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "GPT-Video reads MP4, MOV, MKV, WebM, AVI and MPEG-TS files. Convert this video to MP4 or MOV, then upload it.",
    "hint": "Fix the request as the message says, then send it again.",
    "requestId": "req_d12173c7e361c8964781331b"
  }
}

{
  "filename": "conference.mp4",
  "sizeBytes": 1610612736,
  "contentType": "video/mp4"
}

{
  "error": {
    "code": "CONFLICT",
    "message": "Your stored videos and uploads in progress would take 2.3 GB, over the 2 GB this account can store. Delete videos you no longer need in the GPT-Video app, or cancel uploads in progress, then try again. A paid plan stores up to 50 GB.",
    "requestId": "req_8d3f1b6e0a4c7d2e9f5a1b8c"
  }
}

{
  "filename": "panel.mp4",
  "sizeBytes": 104857600,
  "contentType": "video/mp4"
}

{
  "error": {
    "code": "CONFLICT",
    "message": "You already have 10 uploads in progress. Complete or cancel one of them first; an upload with no activity for 6 hours is removed.",
    "requestId": "req_5a9c2e7f1b4d8a3c6e0f2b7d"
  }
}

{
  "filename": "festival.mp4",
  "sizeBytes": 6442450944,
  "contentType": "video/mp4"
}

{
  "error": {
    "code": "UNAVAILABLE",
    "message": "GPT-Video cannot take new work right now. Try again in a few minutes.",
    "hint": "Retry later.",
    "requestId": "req_0e6b3d9a2c5f7e1b4a8d3c6f"
  }
}

Errors

Every call can also answer these errors. VALIDATION_FAILED, UNKNOWN_PARAMETER, UNAUTHORIZED, SCOPE_MISSING, IDEMPOTENCY_IN_PROGRESS, PAYLOAD_TOO_LARGE, IDEMPOTENCY_KEY_REUSED, RATE_LIMITED, INTERNAL, UNAVAILABLE.

Cost

No credits are used. The file counts toward the storage of the account.

Related operations

• upload_part (PUT /v1/uploads/{uploadId}/parts/{partNumber}) Send a part of an upload
• get_upload (GET /v1/uploads/{uploadId}) Get an upload
• complete_upload (POST /v1/uploads/{uploadId}/complete) Complete an upload
• cancel_upload (DELETE /v1/uploads/{uploadId}) Cancel an upload
• get_asset (GET /v1/assets/{assetId}) Get an asset

Questions

How many uploads can be open at the same time?

There is a limit per account, and it counts the uploads started in the GPT-Video app too. When you reach it, the refusal says how many uploads are open. Complete or cancel one to open another; an upload with no activity is removed when its expiresAt passes.

What happens if I lose the answer of this call?

Send the same request again with the same Idempotency-Key: you get the same upload back. Without a key, a second call opens a second upload.

Which video formats can I send?

MP4, MOV, MKV, WebM, AVI and MPEG-TS files up to 8 GB. MP4 and MOV work best. complete_upload (POST /v1/uploads/{uploadId}/complete) checks the start of the file and refuses anything else, such as a playlist or a text file, and a file that cannot be read as a video.

View as Markdown