SDKs

GPT-Video has official SDKs for JavaScript and Python, and nodes for n8n. They call the same API as the rest of these pages, with the same API keys. Each one has a method for every endpoint, named after its page in the API reference, and does for you the parts that cost money when they go wrong: retries that never pay twice, waiting for jobs, uploads in parts and webhook signatures.

Install

JavaScript and TypeScript, for Node.js 20.19 or later, Deno, Bun and Cloudflare Workers. The package has no dependencies, and its TypeScript types come with it.

npm install gpt-video

Python 3.10 or later. The package uses the standard library only, and you import it as gpt_video.

pip install gpt-video

n8n: in n8n, open Settings, then Community Nodes, select Install, and enter n8n-nodes-gpt-video. The GPT-Video node has an operation for each endpoint, and the GPT-Video Trigger starts a workflow when a job or an export ends.

The API key

Create a key on the Developers page of the GPT-Video app, with the scopes clips:read, clips:write and spend. Authentication has the details. Put the key in the environment variable GPT_VIDEO_API_KEY, where both SDKs read it. You can also pass it to the client, as apiKey in JavaScript and api_key in Python.

export GPT_VIDEO_API_KEY=gvk_...

The first call

getMe uses no credits. It shows that the key works and which scopes it has.

import { GptVideo } from "gpt-video";

const gv = new GptVideo();
const me = await gv.getMe();
console.log(me.key.scopes);

from gpt_video import GptVideo

gv = GptVideo()
me = gv.get_me()
print(me["key"]["scopes"])

The fields of a call keep the names of the API: projectId, sourceAssetId. A call returns the body of the answer as the API sends it. In Python, pass the fields as keyword arguments or as one dict.

Each operation page in the API reference shows its call with the JavaScript SDK next to curl, TypeScript and Python.

Retries and the Idempotency-Key

A call that spends or creates something gets an Idempotency-Key made once, before the first attempt, and the SDK sends that same key on every retry. Pagination and idempotency explains what the API does with it.

• The SDK retries a failure only when sending the call again is safe. It waits the seconds of Retry-After when the API sends them, and retries at most twice by default (maxRetries, max_retries in Python).
• IDEMPOTENCY_IN_PROGRESS means the first request with the key is still running. The SDK waits for its answer, and this does not count as a retry.
• One attempt has 60 seconds and a whole call has 180 seconds, pauses included.

When a call that spends ends without a clear answer, for example after a timeout, the API may have charged it. Its error then has mayHaveSpent (may_have_spent in Python) set to true. Call again with the key of the error: if the first request ran, you get its answer and pay nothing more. A new key is a new request, and it can be charged again.

import { GptVideoError } from "gpt-video";

try {
  await gv.analyzeProject({ projectId });
} catch (error) {
  if (!(error instanceof GptVideoError) || !error.mayHaveSpent) throw error;
  await gv.analyzeProject({ projectId }, { idempotencyKey: error.idempotencyKey });
}

from gpt_video import GptVideoError

try:
    gv.analyze_project(projectId=project_id)
except GptVideoError as error:
    if not error.may_have_spent:
        raise
    gv.analyze_project(projectId=project_id, idempotency_key=error.idempotency_key)

Errors lists every code and what to do next.

Lists

paginate follows nextCursor for you and asks for the next page only when your code reaches it.

for await (const project of gv.paginate("listProjects")) console.log(project.id);

for project in gv.paginate("list_projects"):
    print(project["id"])

Jobs

An analysis, an export and the other calls that start work answer at once. wait takes that answer and reads the work again until it is done, failed or cancelled. Work that failed or was cancelled ends the wait with an error. Jobs explains the states.

const analysis = await gv.analyzeProject({ projectId });
await gv.wait(analysis);

analysis = gv.analyze_project(projectId=project_id)
gv.wait(analysis)

Uploads and downloads

uploadFile (upload_file in Python) sends a video in parts, reads one part at a time from the disk, and retries each part on its own. download fetches the signed link of a finished export and never sends your API key to it. Upload a video file describes the parts.

Webhooks

Both SDKs check the signature of a webhook on the raw body of the request, before you parse it: constructEvent from gpt-video/webhooks in JavaScript, and construct_event from gpt_video.webhooks in Python. A delivery whose signature does not match raises an error. Receive webhooks in your app has a receiver.

From MCP to the SDK

Most MCP tools have a method in the SDKs with the same name: get_credits (GET /v1/credits) is getCredits in JavaScript and get_credits in Python. These tools have another name in the SDKs.

For close work, read the page of the method before you switch. Five of the first MCP tools, which came before the API, share a name with a method but take arguments of their own: list_projects (GET /v1/projects), create_project (POST /v1/projects), get_project (GET /v1/projects/{projectId}), list_clips (GET /v1/projects/{projectId}/clips) and get_job (GET /v1/jobs/{jobId}). Read the page of the method for these too.

On MCP, a tool that spends needs confirm: true. The SDKs have no such field: calling the method is the decision.

Versions and cost

Version 1.0.1 of each SDK calls /v1. Each package has its own changelog. A field the API adds reaches your code before the SDK knows it, because the SDKs return the answer as the API sends it.

The SDKs use credits the way the API does. API pricing says what each call uses and how the API bonus works.