@vidlab/cli 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +51 -2
- package/bin/vidlab.mjs +12 -0
- package/lib/args.mjs +56 -0
- package/lib/client.mjs +96 -0
- package/lib/commands.mjs +324 -0
- package/lib/credentials.mjs +136 -0
- package/lib/main.mjs +408 -0
- package/lib/setup.mjs +175 -0
- package/lib/version.mjs +1 -0
- package/package.json +34 -4
- package/skill/SKILL.md +235 -0
package/lib/setup.mjs
ADDED
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
// `vidlab setup` and `vidlab skill install`: load the VidLab skill into Claude Code and Codex, and with `setup --mcp`
|
|
2
|
+
// connect Claude Code, Claude desktop, Cursor and Codex to VidLab's MCP (where it is open to the account), in one command.
|
|
3
|
+
//
|
|
4
|
+
// The key is never written anywhere here. Two ways in, chosen by what is in the environment:
|
|
5
|
+
// - oauth (default): the client's config holds the URL only; the client signs in in your browser.
|
|
6
|
+
// - key (VIDLAB_API_KEY is set, or --auth key): the config holds a reference the client fills in from its own
|
|
7
|
+
// environment (`${VIDLAB_API_KEY}`, `${env:VIDLAB_API_KEY}`, bearer_token_env_var), never the value.
|
|
8
|
+
// Clients that have a command for it (claude, codex) are configured through their own command, with the arguments passed
|
|
9
|
+
// as a list (no shell, so nothing is expanded or logged); the others have their config file merged.
|
|
10
|
+
|
|
11
|
+
import { spawnSync } from "node:child_process";
|
|
12
|
+
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
|
|
13
|
+
import { homedir, platform } from "node:os";
|
|
14
|
+
import path from "node:path";
|
|
15
|
+
import { fileURLToPath } from "node:url";
|
|
16
|
+
|
|
17
|
+
export const SERVER_NAME = "vidlab";
|
|
18
|
+
export const MCP_PATH = "/api/developers/v1/mcp?profile=api";
|
|
19
|
+
export const CLIENT_IDS = ["claude-code", "claude-desktop", "cursor", "codex"];
|
|
20
|
+
const LABEL = { "claude-code": "Claude Code", "claude-desktop": "Claude desktop", cursor: "Cursor", codex: "Codex" };
|
|
21
|
+
const KEY_REF = { claude: "Bearer ${VIDLAB_API_KEY}", cursor: "Bearer ${env:VIDLAB_API_KEY}" };
|
|
22
|
+
|
|
23
|
+
export const mcpUrlOf = (baseUrl) => `${baseUrl}${MCP_PATH}`;
|
|
24
|
+
|
|
25
|
+
function onPath(bin, env) {
|
|
26
|
+
const dirs = String(env.PATH ?? "").split(path.delimiter).filter(Boolean);
|
|
27
|
+
const exts = platform() === "win32" ? ["", ".exe", ".cmd", ".bat"] : [""];
|
|
28
|
+
return dirs.some((d) => exts.some((e) => existsSync(path.join(d, bin + e))));
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
const codexHome = (home, env) => env.CODEX_HOME || path.join(home, ".codex");
|
|
32
|
+
const desktopConfig = (home, env) =>
|
|
33
|
+
platform() === "darwin"
|
|
34
|
+
? path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json")
|
|
35
|
+
: platform() === "win32"
|
|
36
|
+
? path.join(env.APPDATA || path.join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json")
|
|
37
|
+
: path.join(env.XDG_CONFIG_HOME || path.join(home, ".config"), "Claude", "claude_desktop_config.json");
|
|
38
|
+
|
|
39
|
+
/** Which of the four clients this computer has. */
|
|
40
|
+
export function detectClients({ home = homedir(), env = process.env } = {}) {
|
|
41
|
+
const has = {
|
|
42
|
+
"claude-code": onPath("claude", env) || existsSync(path.join(home, ".claude")) || existsSync(path.join(home, ".claude.json")),
|
|
43
|
+
"claude-desktop": existsSync(path.dirname(desktopConfig(home, env))),
|
|
44
|
+
cursor: onPath("cursor", env) || existsSync(path.join(home, ".cursor")),
|
|
45
|
+
codex: onPath("codex", env) || existsSync(codexHome(home, env)),
|
|
46
|
+
};
|
|
47
|
+
return CLIENT_IDS.filter((id) => has[id]);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** The folder each skill-reading client keeps skills in. */
|
|
51
|
+
export const skillDirOf = (client, { home = homedir() } = {}) => (client === "claude-code" ? path.join(home, ".claude", "skills", SERVER_NAME) : client === "codex" ? path.join(home, ".agents", "skills", SERVER_NAME) : null); // Codex reads user skills from ~/.agents/skills (its docs, 2026-11)
|
|
52
|
+
|
|
53
|
+
function readJsonFile(file) {
|
|
54
|
+
if (!existsSync(file)) return {};
|
|
55
|
+
try {
|
|
56
|
+
const v = JSON.parse(readFileSync(file, "utf8"));
|
|
57
|
+
return v && typeof v === "object" && !Array.isArray(v) ? v : null;
|
|
58
|
+
} catch {
|
|
59
|
+
return null;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
function writeAtomic(file, text, mode = 0o600) {
|
|
64
|
+
mkdirSync(path.dirname(file), { recursive: true });
|
|
65
|
+
const tmp = `${file}.${process.pid}.tmp`;
|
|
66
|
+
writeFileSync(tmp, text, { mode });
|
|
67
|
+
renameSync(tmp, file);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** Puts `entry` under mcpServers.vidlab in a JSON config, leaving everything else as it was. */
|
|
71
|
+
function mergeJsonServer(file, entry, dry) {
|
|
72
|
+
const cfg = readJsonFile(file);
|
|
73
|
+
if (cfg === null) return { ok: false, reason: `${file} is not valid JSON; fix or remove it, then run setup again.` };
|
|
74
|
+
const before = JSON.stringify(cfg.mcpServers?.[SERVER_NAME] ?? null);
|
|
75
|
+
cfg.mcpServers = { ...(cfg.mcpServers ?? {}), [SERVER_NAME]: entry };
|
|
76
|
+
if (!dry) writeAtomic(file, `${JSON.stringify(cfg, null, 2)}\n`);
|
|
77
|
+
return { ok: true, changed: before !== JSON.stringify(entry) };
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** The codex config.toml with [mcp_servers.vidlab] set (the block replaced when it is there, else appended). */
|
|
81
|
+
export function tomlWithServer(text, url, keyMode) {
|
|
82
|
+
const block = `[mcp_servers.${SERVER_NAME}]\nurl = ${JSON.stringify(url)}\n${keyMode ? 'bearer_token_env_var = "VIDLAB_API_KEY"\n' : ""}`;
|
|
83
|
+
const re = new RegExp(`^\\[mcp_servers\\.${SERVER_NAME}\\][^\\[]*`, "m");
|
|
84
|
+
if (re.test(text)) return text.replace(re, `${block}\n`);
|
|
85
|
+
return `${text}${text && !text.endsWith("\n") ? "\n" : ""}${text ? "\n" : ""}${block}`;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* Connects one client. Returns { client, label, status, how, next }:
|
|
90
|
+
* status "configured" | "unchanged" | "dry-run" | "failed", `how` says where, `next` what the person does now.
|
|
91
|
+
*/
|
|
92
|
+
export function connectClient(client, { baseUrl, keyMode, dry, home = homedir(), env = process.env, run = spawnSync }) {
|
|
93
|
+
const url = mcpUrlOf(baseUrl);
|
|
94
|
+
const label = LABEL[client];
|
|
95
|
+
const done = (status, how, next) => ({ client, label, status, how, ...(next ? { next } : {}) });
|
|
96
|
+
const fail = (reason) => ({ client, label, status: "failed", how: reason });
|
|
97
|
+
if (client === "claude-code") {
|
|
98
|
+
const args = ["mcp", "add", "--transport", "http", "--scope", "user", SERVER_NAME, url, ...(keyMode ? ["--header", `Authorization: ${KEY_REF.claude}`] : [])];
|
|
99
|
+
if (!onPath("claude", env)) return { client, label, status: "failed", how: `The claude command was not found. Run this once Claude Code is installed: claude ${args.map((a) => (/[\s$]/.test(a) ? `'${a}'` : a)).join(" ")}` };
|
|
100
|
+
if (dry) return done("dry-run", `claude ${args.join(" ")}`);
|
|
101
|
+
run("claude", ["mcp", "remove", "--scope", "user", SERVER_NAME], { env: { ...env, HOME: home }, stdio: "ignore" });
|
|
102
|
+
const r = run("claude", args, { env: { ...env, HOME: home }, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" });
|
|
103
|
+
if (r.status !== 0) return fail(`claude mcp add failed: ${String(r.stderr ?? r.stdout ?? "").trim().split("\n")[0] || "no output"}`);
|
|
104
|
+
return done("configured", "claude mcp add (user scope)", keyMode ? "Start Claude Code from a terminal where VIDLAB_API_KEY is set." : "In Claude Code run /mcp, pick vidlab and sign in.");
|
|
105
|
+
}
|
|
106
|
+
if (client === "codex") {
|
|
107
|
+
const args = ["mcp", "add", SERVER_NAME, "--url", url, ...(keyMode ? ["--bearer-token-env-var", "VIDLAB_API_KEY"] : [])];
|
|
108
|
+
// `codex mcp add --url` without a key starts the browser sign-in at once and waits for it, so the sign-in mode writes the
|
|
109
|
+
// config instead (the person runs `codex mcp login vidlab` when ready); with a key its own command is used.
|
|
110
|
+
if (keyMode && onPath("codex", env)) {
|
|
111
|
+
if (dry) return done("dry-run", `codex ${args.join(" ")}`);
|
|
112
|
+
run("codex", ["mcp", "remove", SERVER_NAME], { env: { ...env, HOME: home }, stdio: "ignore" });
|
|
113
|
+
const r = run("codex", args, { env: { ...env, HOME: home }, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" });
|
|
114
|
+
if (r.status !== 0) return fail(`codex mcp add failed: ${String(r.stderr ?? r.stdout ?? "").trim().split("\n")[0] || "no output"}`);
|
|
115
|
+
return done("configured", "codex mcp add", keyMode ? "Start Codex from a terminal where VIDLAB_API_KEY is set." : "Run: codex mcp login vidlab");
|
|
116
|
+
}
|
|
117
|
+
const file = path.join(codexHome(home, env), "config.toml");
|
|
118
|
+
if (dry) return done("dry-run", `write [mcp_servers.${SERVER_NAME}] in ${file}`);
|
|
119
|
+
const text = existsSync(file) ? readFileSync(file, "utf8") : "";
|
|
120
|
+
writeAtomic(file, tomlWithServer(text, url, keyMode));
|
|
121
|
+
return done("configured", file, keyMode ? "Start Codex from a terminal where VIDLAB_API_KEY is set." : "Run: codex mcp login vidlab");
|
|
122
|
+
}
|
|
123
|
+
if (client === "cursor") {
|
|
124
|
+
const file = path.join(home, ".cursor", "mcp.json");
|
|
125
|
+
const entry = keyMode ? { url, headers: { Authorization: KEY_REF.cursor } } : { url };
|
|
126
|
+
const r = mergeJsonServer(file, entry, dry);
|
|
127
|
+
if (!r.ok) return fail(r.reason);
|
|
128
|
+
return done(dry ? "dry-run" : r.changed ? "configured" : "unchanged", file, keyMode ? "Start Cursor from a terminal where VIDLAB_API_KEY is set." : "In Cursor open Settings, MCP, and connect vidlab (it signs in in your browser).");
|
|
129
|
+
}
|
|
130
|
+
if (client === "claude-desktop") {
|
|
131
|
+
const file = desktopConfig(home, env);
|
|
132
|
+
// Claude desktop starts local programs only: mcp-remote bridges to the remote server and signs in in the browser.
|
|
133
|
+
const r = mergeJsonServer(file, { command: "npx", args: ["-y", "mcp-remote", url] }, dry);
|
|
134
|
+
if (!r.ok) return fail(r.reason);
|
|
135
|
+
return done(dry ? "dry-run" : r.changed ? "configured" : "unchanged", file, "Restart Claude desktop; your browser opens to sign in to VidLab. Or add the URL as a custom connector in Settings.");
|
|
136
|
+
}
|
|
137
|
+
return fail(`Unknown client ${client}.`);
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/** The skill's text: from the server (it carries the site's own address), else the copy bundled in this package. */
|
|
141
|
+
export async function fetchSkill(baseUrl, { fetch: f = globalThis.fetch } = {}) {
|
|
142
|
+
try {
|
|
143
|
+
const res = await f(`${baseUrl}/vidlab-api/SKILL.md`, { signal: AbortSignal.timeout(10_000), headers: { accept: "text/markdown" } });
|
|
144
|
+
const text = res.ok ? await res.text() : "";
|
|
145
|
+
if (/^---\s*\nname: vidlab/.test(text)) return { text, from: `${baseUrl}/vidlab-api/SKILL.md` };
|
|
146
|
+
} catch {}
|
|
147
|
+
const bundled = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "skill", "SKILL.md");
|
|
148
|
+
if (!existsSync(bundled)) return null;
|
|
149
|
+
return { text: withoutMcp(readFileSync(bundled, "utf8")).split("{ORIGIN}").join(baseUrl), from: "the copy in this package" };
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/**
|
|
153
|
+
* The bundled copy is the site's SKILL.md as written, with its MCP blocks (apps/web-v2/lib/mcp-public.mjs): the site
|
|
154
|
+
* keeps one side while VidLab's MCP is open and the other while it is not. Offline we cannot ask, so the copy takes the
|
|
155
|
+
* API side, which works either way: the MCP blocks go, the API blocks stay, and no marker is left.
|
|
156
|
+
*/
|
|
157
|
+
export function withoutMcp(text) {
|
|
158
|
+
return text
|
|
159
|
+
.replace(/^[ \t]*<!--[ \t]*mcp[ \t]*-->[ \t]*\n[\s\S]*?^[ \t]*<!--[ \t]*\/mcp[ \t]*-->[ \t]*(?:\n|$)/gm, "")
|
|
160
|
+
.replace(/<!--[ \t]*mcp[ \t]*-->[\s\S]*?<!--[ \t]*\/mcp[ \t]*-->/g, "")
|
|
161
|
+
.replace(/^[ \t]*<!--[ \t]*\/?no-mcp[ \t]*-->[ \t]*\n/gm, "")
|
|
162
|
+
.replace(/<!--[ \t]*\/?no-mcp[ \t]*-->/g, "");
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/** Writes the skill for each client that reads skills (or into `dir`). */
|
|
166
|
+
export async function installSkill({ clients, dir, baseUrl, dry, home = homedir(), env = process.env, fetch: f }) {
|
|
167
|
+
const skill = await fetchSkill(baseUrl, { fetch: f });
|
|
168
|
+
if (!skill) return [{ status: "failed", how: "The skill could not be fetched, and no copy is bundled." }];
|
|
169
|
+
const targets = dir ? [{ client: "dir", folder: path.resolve(dir) }] : clients.map((c) => ({ client: c, folder: skillDirOf(c, { home, env }) })).filter((t) => t.folder);
|
|
170
|
+
return targets.map((t) => {
|
|
171
|
+
const file = path.join(t.folder, "SKILL.md");
|
|
172
|
+
if (!dry) writeAtomic(file, skill.text, 0o644);
|
|
173
|
+
return { client: t.client, status: dry ? "dry-run" : "installed", how: file, from: skill.from };
|
|
174
|
+
});
|
|
175
|
+
}
|
package/lib/version.mjs
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export const VERSION = "0.1.0";
|
package/package.json
CHANGED
|
@@ -1,6 +1,36 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vidlab/cli",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "The VidLab API from your shell: one key for every top image, video and audio model, routed to the best provider at the lowest price. Pay only for successful runs. --json on every command for agents.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"engines": {
|
|
8
|
+
"node": ">=18.17"
|
|
9
|
+
},
|
|
10
|
+
"bin": {
|
|
11
|
+
"vidlab": "./bin/vidlab.mjs"
|
|
12
|
+
},
|
|
13
|
+
"files": [
|
|
14
|
+
"bin",
|
|
15
|
+
"lib",
|
|
16
|
+
"skill",
|
|
17
|
+
"README.md",
|
|
18
|
+
"LICENSE"
|
|
19
|
+
],
|
|
20
|
+
"keywords": [
|
|
21
|
+
"vidlab",
|
|
22
|
+
"cli",
|
|
23
|
+
"ai",
|
|
24
|
+
"video generation",
|
|
25
|
+
"image generation",
|
|
26
|
+
"agents"
|
|
27
|
+
],
|
|
28
|
+
"homepage": "https://vidlab.ai",
|
|
29
|
+
"scripts": {
|
|
30
|
+
"test": "node --test \"test/*.test.mjs\"",
|
|
31
|
+
"prepack": "node scripts/sync-skill.mjs"
|
|
32
|
+
},
|
|
33
|
+
"bugs": {
|
|
34
|
+
"email": "support@vidlab.ai"
|
|
35
|
+
}
|
|
36
|
+
}
|
package/skill/SKILL.md
ADDED
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vidlab
|
|
3
|
+
description: Add the VidLab API to an app (one key for every top image, video and audio model, each call routed to the lowest price, failed runs free), switch existing image or video generation calls over to it, or use it to make images, video, voice-overs, music, lip sync and upscales. Use when the user asks to add VidLab, to switch generation to VidLab, to generate or edit media with VidLab, or to check a VidLab generation.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# VidLab
|
|
7
|
+
|
|
8
|
+
VidLab is one API for every top image, video and audio model (Seedance, Veo, Kling, Gemini Omni, Nano Banana, GPT Image, Grok Imagine, Seedream, Wan and 130 more). One key, one request shape. Every call goes to the lowest-priced route that is up, at the model's full quality. You pay per generation from a prepaid balance, and only for runs that succeed: a failed run costs $0.00.
|
|
9
|
+
|
|
10
|
+
- Base URL: `{ORIGIN}/v1`. Auth: `Authorization: Bearer $VIDLAB_API_KEY`.
|
|
11
|
+
- Docs: `{ORIGIN}/vidlab-api/llms.txt` (index) and `{ORIGIN}/vidlab-api/llms-full.txt` (everything). OpenAPI: `{ORIGIN}/v1/openapi.json`. Setup and troubleshooting for agents: `{ORIGIN}/vidlab-api/docs/ai-agents.md`, `{ORIGIN}/vidlab-api/docs/agent-troubleshooting.md`.
|
|
12
|
+
|
|
13
|
+
The user asked for one of two things. Pick the matching part:
|
|
14
|
+
|
|
15
|
+
- **Add VidLab to their app, or switch their app's generation calls to VidLab**: follow "Add VidLab to an app" below.
|
|
16
|
+
- **Make something with VidLab now** (an image, a video, a voice-over): skip to "Use VidLab".
|
|
17
|
+
|
|
18
|
+
# Add VidLab to an app
|
|
19
|
+
|
|
20
|
+
## Before you start
|
|
21
|
+
|
|
22
|
+
Show the user this checklist and wait for a yes:
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
Here's what I'll do to add VidLab to this project.
|
|
26
|
+
|
|
27
|
+
1. Look at how the app generates images, video or audio today (if it does).
|
|
28
|
+
2. Get you a VidLab API key into your environment (you paste it, I never see it).
|
|
29
|
+
3. Add a small VidLab client on the server side and wire it in, keeping your models.
|
|
30
|
+
4. Check the key works, then run one cheap test call if you say so.
|
|
31
|
+
|
|
32
|
+
Shall I proceed?
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Step 1: Read the project
|
|
36
|
+
|
|
37
|
+
From the project root, find:
|
|
38
|
+
|
|
39
|
+
- The language, framework and package manager (lockfiles, `package.json`, `pyproject.toml`, `requirements.txt`, `go.mod`).
|
|
40
|
+
- Where the app already calls another image, video or audio generation API: an SDK import or HTTP calls that send a model name and a prompt and wait for a file. Note each call's model, options (resolution, duration, aspect ratio, size), how it waits for the result and what it does with the file.
|
|
41
|
+
- Where server-side secrets live (`.env`, `.env.local`, a secrets manager) and whether that file is gitignored.
|
|
42
|
+
|
|
43
|
+
Do not read or print the contents of any environment file. Check a variable is set with `test -n "$VIDLAB_API_KEY" && echo set || echo missing`, never by printing it.
|
|
44
|
+
|
|
45
|
+
## Step 2: The API key
|
|
46
|
+
|
|
47
|
+
If `VIDLAB_API_KEY` is already set, go to Step 3.
|
|
48
|
+
|
|
49
|
+
Otherwise tell the user, in these words or close to them:
|
|
50
|
+
|
|
51
|
+
```
|
|
52
|
+
You need a VidLab API key:
|
|
53
|
+
1. Open {ORIGIN}/vidlab-api/api-keys (sign up takes a minute) and press Create key.
|
|
54
|
+
2. Add credit on {ORIGIN}/vidlab-api/billing: any amount from $10, spent per generation.
|
|
55
|
+
3. Put the key in your environment file yourself, as VIDLAB_API_KEY=<your key>.
|
|
56
|
+
Tell me when it's done. Please don't paste the key here.
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Make sure the environment file is in `.gitignore` before the key goes in. Never ask for the key in the chat, never write it into code, a command, a test or a commit.
|
|
60
|
+
|
|
61
|
+
## Step 3: Add the client
|
|
62
|
+
|
|
63
|
+
Add one small module on the server side (never in browser or mobile client code: the key must not ship to users). It does four things: submit, poll, download, and turn errors into exceptions the app already handles. Use the project's own HTTP client and style. The shape, in TypeScript:
|
|
64
|
+
|
|
65
|
+
```ts
|
|
66
|
+
const API = "{ORIGIN}/v1";
|
|
67
|
+
const headers = { Authorization: `Bearer ${process.env.VIDLAB_API_KEY}`, "Content-Type": "application/json" };
|
|
68
|
+
|
|
69
|
+
export async function generate(model: string, input: Record<string, unknown>, maxCostUsd?: number) {
|
|
70
|
+
const res = await fetch(`${API}/generations`, {
|
|
71
|
+
method: "POST",
|
|
72
|
+
headers: { ...headers, "Idempotency-Key": crypto.randomUUID() },
|
|
73
|
+
body: JSON.stringify({ model, input, ...(maxCostUsd ? { max_cost_usd: maxCostUsd } : {}) }),
|
|
74
|
+
});
|
|
75
|
+
const body = await res.json();
|
|
76
|
+
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
|
|
77
|
+
let job = body.data;
|
|
78
|
+
while (job.status === "queued" || job.status === "running") {
|
|
79
|
+
await new Promise((r) => setTimeout(r, 5000)); // polling is free
|
|
80
|
+
job = (await (await fetch(`${API}/generations/${job.id}`, { headers })).json()).data;
|
|
81
|
+
}
|
|
82
|
+
if (job.status === "failed") throw new Error(`${job.error.code}: ${job.error.message}`); // never charged
|
|
83
|
+
return job; // job.outputs[].url (valid 6 hours), job.price_usd (what was charged)
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Python is the same with `requests`: `POST {ORIGIN}/v1/generations`, then `GET {ORIGIN}/v1/generations/{id}` until `succeeded` or `failed`. A new `Idempotency-Key` per new job; reuse it only to retry the same job after a network error. Output links last 6 hours: if the app keeps files, download `outputs[].url` (or `GET /v1/generations/{id}/content`) and store them.
|
|
88
|
+
|
|
89
|
+
## Step 4: Switch the existing calls
|
|
90
|
+
|
|
91
|
+
For each generation call found in Step 1:
|
|
92
|
+
|
|
93
|
+
1. Find the same model on VidLab: `GET {ORIGIN}/v1/models?search=<model name>` (no key needed). Keep the model the app uses. Never invent an id: take it from the list.
|
|
94
|
+
2. Read it: `GET {ORIGIN}/v1/models/{id}`. Map the old options onto the fields it lists under `params` (usually `prompt`, `images`, `resolution`, `duration`, `aspect_ratio`). Send only listed fields with listed values.
|
|
95
|
+
3. Replace the call with the client from Step 3, keeping the app's inputs, outputs and error handling the same. Remove the old provider's key and SDK only when the user agrees.
|
|
96
|
+
|
|
97
|
+
If the app has no generation yet, add the call where the user wants it and ask which model to start with (see "Pick a model by task").
|
|
98
|
+
|
|
99
|
+
## Step 5: Verify
|
|
100
|
+
|
|
101
|
+
1. `GET {ORIGIN}/v1/balance` with the key: a 200 means the key works (free, nothing runs).
|
|
102
|
+
2. Price one small test call: `POST {ORIGIN}/v1/generations/quote` with the exact body (free, nothing held). Tell the user the price.
|
|
103
|
+
3. Only with their yes, run that one call through the app's own code path and show them the result link and `price_usd`.
|
|
104
|
+
|
|
105
|
+
## After setup
|
|
106
|
+
|
|
107
|
+
- Their coding agent can use VidLab too: this skill and `VIDLAB_API_KEY` in its environment (`{ORIGIN}/vidlab-api/docs/agent-skill`).
|
|
108
|
+
- Spend limits per key (a monthly budget, a model list, an expiry) are on the API keys page.
|
|
109
|
+
- Questions: support@vidlab.ai.
|
|
110
|
+
|
|
111
|
+
# Use VidLab
|
|
112
|
+
|
|
113
|
+
## The key
|
|
114
|
+
|
|
115
|
+
- The key is in the `VIDLAB_API_KEY` environment variable. Send it as `Authorization: Bearer $VIDLAB_API_KEY`.
|
|
116
|
+
- Never print, log or echo the key, never write it into a file or a command, never ask the user to paste it into the chat. Refer to the variable only.
|
|
117
|
+
- No key set: tell the user to make one at `{ORIGIN}/vidlab-api/api-keys` and set `VIDLAB_API_KEY` (Step 2 above).
|
|
118
|
+
- Listing models and estimating prices need no key.
|
|
119
|
+
|
|
120
|
+
## The calls
|
|
121
|
+
|
|
122
|
+
Plain HTTPS, JSON in and out, the key as `Authorization: Bearer $VIDLAB_API_KEY`. Run them with `curl` from the shell, or with the language's HTTP client in code.
|
|
123
|
+
|
|
124
|
+
| Step | Call |
|
|
125
|
+
| - | - |
|
|
126
|
+
| find | `GET /v1/models?kind=video&search=` |
|
|
127
|
+
| read | `GET /v1/models/{id}` |
|
|
128
|
+
| price | `POST /v1/estimate` (no key) or `POST /v1/generations/quote` |
|
|
129
|
+
| run | `POST /v1/generations` (header `Idempotency-Key`) |
|
|
130
|
+
| poll | `GET /v1/generations/{id}` |
|
|
131
|
+
| download | `GET /v1/generations/{id}/content` |
|
|
132
|
+
| money | `GET /v1/balance` |
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
curl -s -X POST {ORIGIN}/v1/generations \
|
|
136
|
+
-H "Authorization: Bearer $VIDLAB_API_KEY" -H "Content-Type: application/json" \
|
|
137
|
+
-H "Idempotency-Key: $(uuidgen)" \
|
|
138
|
+
-d '{"model": "gpt-image-2", "input": {"prompt": "a red sneaker on white", "aspect_ratio": "1:1"}, "max_cost_usd": 0.10}'
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
## Run a model
|
|
142
|
+
|
|
143
|
+
1. **Find** with `kind` (`video`, `image`, `audio`, `lipsync`, `upscale`) and `search` words. Prefer `status: "operational"`. Never invent an id: take it from the list.
|
|
144
|
+
2. **Read** the model. Send only the fields it lists under `params` (`GET /v1/models/{id}`): `values` are the only allowed values, `min` and `max` are limits, `required` must be sent. Fields that are not listed are refused.
|
|
145
|
+
3. **Price** it. `price_usd` is what a success costs on the cheapest route. Tell the user the price before any paid run, and ask when it is more than they expect.
|
|
146
|
+
4. **Run** it with `max_cost_usd` (the most the user will pay) and an idempotency key (the `Idempotency-Key` header, a fresh UUID per new job). Answer: a `gen_...` id, `status: "queued"`.
|
|
147
|
+
5. **Poll** every 3 seconds for images and 10 for video until `status` is `succeeded` or `failed`. Polling is free.
|
|
148
|
+
6. **Deliver** `outputs[].url`: links valid for 6 hours, so download what is worth keeping. Read the generation again for fresh links.
|
|
149
|
+
|
|
150
|
+
## Read the price
|
|
151
|
+
|
|
152
|
+
`prices` maps an option to dollars per unit; `unit` says what a unit is:
|
|
153
|
+
|
|
154
|
+
| unit | counts | example |
|
|
155
|
+
| - | - | - |
|
|
156
|
+
| `per_second` | seconds of output (`duration`) | 5 s at `720p` = 5 x the `720p` price |
|
|
157
|
+
| `per_image` | images (`n`) | `n: 4` = 4 x the price |
|
|
158
|
+
| `per_job` | one run | flat |
|
|
159
|
+
| `per_1k_chars` | 1,000 characters of `text` | 2,500 characters = 2.5 units |
|
|
160
|
+
| `per_minute` | minutes of output | |
|
|
161
|
+
|
|
162
|
+
The option that sets the price is usually `resolution` (or `quality`). Models with `duration_must_cover` (lip sync, speech to video, upscales) bill the length of the input file: send `duration` at least as long, in whole seconds rounded up.
|
|
163
|
+
|
|
164
|
+
Routes: every call starts on the cheapest route. If it is busy or fails, the call moves to the next route by itself. A backup route can cost more per unit (each model page shows its price by route); the generation's `price_usd` then shows what was charged, once, for the route that finished it. `max_cost_usd` set to the quoted price keeps a call on cheapest-price routes only.
|
|
165
|
+
|
|
166
|
+
## Pick a model by task
|
|
167
|
+
|
|
168
|
+
Starting points, not rules. Search, then compare `from_usd` and the description.
|
|
169
|
+
|
|
170
|
+
| Task | Try |
|
|
171
|
+
| - | - |
|
|
172
|
+
| Video from text or an image | `seedance-2.5`, `kling-4.0`, `gemini-omni-1.1-flash` |
|
|
173
|
+
| Cheap video drafts | `seedance-1.0-pro-fast`, `hailuo-02`, `wan-3.0` |
|
|
174
|
+
| Video with sound | `veo-3.1-fast`, `veo-3.1`, `grok-imagine-video-1.5` |
|
|
175
|
+
| UGC style ad clip | `minimax-h3-ugc` |
|
|
176
|
+
| Video from a reference video (motion) | `kling-3.0-motion-control` |
|
|
177
|
+
| Image from text | `nano-banana-pro`, `gpt-image-2.5-sunburst` |
|
|
178
|
+
| Image with readable text, logos | `ideogram-v3` |
|
|
179
|
+
| Edit an image (needs `images`) | `nano-banana-2`, `gpt-image-2`, `flux-kontext-pro` |
|
|
180
|
+
| Many cheap images | `flux-3-klein`, `z-image` |
|
|
181
|
+
| Remove a background / upscale a picture | `recraft-remove-bg` / `topaz-image-upscale` |
|
|
182
|
+
| Upscale a video | `topaz-video-upscale` |
|
|
183
|
+
| Voice-over | `elevenlabs-tts`, `gpt-4o-mini-tts` |
|
|
184
|
+
| Song or background music | `suno-v6`, `flowmusic` |
|
|
185
|
+
| Talking person from a photo and audio | `omnihuman-2.0`, `kling-avatar-pro`, `infinitalk` |
|
|
186
|
+
| Lip sync a video to audio | `bytedance-lipsync` |
|
|
187
|
+
|
|
188
|
+
## Files
|
|
189
|
+
|
|
190
|
+
Images, video and audio go in as public https URLs (`images` is a list, the first is the first frame or the reference; `video`, `audio`, `end_image` are one URL each; `videos` and `audios` are lists of more reference clips and sounds on models that list them, such as `seedance-2.5`). A local file: upload it first, then use the returned `url`: `POST {ORIGIN}/v1/uploads` with the raw file as the body, its `Content-Type`, and an `X-File-Name` header. The answer has `data.url`. If uploads answer 404, they are not enabled yet: ask the user for a public link.
|
|
191
|
+
|
|
192
|
+
## Formats (a finished video from a brief)
|
|
193
|
+
|
|
194
|
+
A format is our own recipe, run end to end, that returns a finished video. REST: `GET /v1/formats`, `POST /v1/formats/{id}/runs`, `POST /v1/formats/runs/{run_id}/answers`, `GET /v1/formats/runs/{run_id}`, `POST /v1/formats/runs/{run_id}/cancel`.
|
|
195
|
+
|
|
196
|
+
1. `GET /v1/formats`, pick one, read its `inputs`.
|
|
197
|
+
2. `POST /v1/formats/{id}/runs` with `{"inputs": {...}}` and the inputs you have. Leave out what you do not know.
|
|
198
|
+
3. While `status` is `needs_input`, read `questions[]`. Ask the user what only they know (the product, the idea); answer the rest yourself. Send every required answer at once: `POST /v1/formats/runs/{run_id}/answers` with `{"answers": {...}}`.
|
|
199
|
+
4. The last question is the price (`confirm_price`). It is the user's approval: send `approve` only after they agreed to the price, or pass `max_price_usd` at the start to approve up to a cap.
|
|
200
|
+
5. Poll `GET /v1/formats/runs/{run_id}` every 10 to 20 seconds until `succeeded` (`output.videos[].url`), `failed` or `cancelled`. A format takes minutes.
|
|
201
|
+
|
|
202
|
+
## Errors
|
|
203
|
+
|
|
204
|
+
Errors are `{"error": {"message", "type", "code"}}`. Branch on `code`:
|
|
205
|
+
|
|
206
|
+
| Code | Do |
|
|
207
|
+
| - | - |
|
|
208
|
+
| `invalid_input`, `invalid_request`, `variant_unavailable` | Fix the input against the model (`GET /v1/models/{id}`). Do not retry unchanged. |
|
|
209
|
+
| `max_cost_exceeded` | Re-estimate and ask the user before raising the cap. |
|
|
210
|
+
| `unauthorized`, `api_key_required` | The key is missing or wrong: ask the user to check `VIDLAB_API_KEY`. |
|
|
211
|
+
| `key_expired`, `ip_not_allowed`, `model_not_allowed`, `key_quota_exceeded`, `key_spend_limit_reached` | The key's own controls (an expiry date, an IP allowlist, its allowed models, a safe-spend limit per hour, day or in total) stop this call. Do not retry in a loop; tell the user. They change them on the API keys page or use another key. |
|
|
212
|
+
| `developer_access_forbidden` | The account has no API access yet: tell the user to write to support@vidlab.ai. |
|
|
213
|
+
| `api_wallet_exhausted`, `api_key_budget_exhausted` | The balance or the key's budget is used up. Tell the user to add credit at `{ORIGIN}/vidlab-api/billing`. Do not retry. |
|
|
214
|
+
| `request_per_minute`, `request_per_day`, `rate_limited`, `api_error` | Wait for `Retry-After` (or a few seconds), then retry with the same idempotency key. |
|
|
215
|
+
| `model_not_found`, `generation_not_found` | Wrong id: list again. A generation is visible only to the account that started it. |
|
|
216
|
+
| job `failed`: `invalid_input` | A file link did not open, or a file was the wrong type or too long (the message says which). Send a public https URL or upload it, then run again with a new key. |
|
|
217
|
+
| job `failed`: `content_policy` (with `reason`), `model_declined`, `reference_changed`, `max_cost_exceeded`, `max_wait_exceeded` (`retryable: false`) | Not charged. Change the prompt, the options or the cap as the message says; do not send the same request again. |
|
|
218
|
+
| job `failed`: `model_busy`, `all_routes_failed`, `timeout`, `processing_failed` (`retryable: true`) | Not charged. Run again with a new key, or pick another model. |
|
|
219
|
+
|
|
220
|
+
A failed job costs nothing; the same idempotency key returns the same failed job, so use a new key to try again.
|
|
221
|
+
|
|
222
|
+
## Price it first, cap it, download it
|
|
223
|
+
|
|
224
|
+
- `POST /v1/generations/quote` takes the same body as a generation and returns `quoted_usd`, `reserved_usd` and `enough_credit`. It is free and holds nothing. Quote the exact request before a big job.
|
|
225
|
+
- `max_cost_usd` caps what a generation may cost (a dearer route is skipped; if none is left the answer is `max_cost_exceeded`); `max_wait_s` skips slow routes.
|
|
226
|
+
- Download a finished file with `GET {ORIGIN}/v1/generations/{id}/content` (and `/content/2` ... for several images), sending the same key.
|
|
227
|
+
- A price listed "with video input" bills the reference clip's seconds too (output seconds plus reference seconds at that rate).
|
|
228
|
+
|
|
229
|
+
## Rules
|
|
230
|
+
|
|
231
|
+
- One generation per request from the user unless they ask for more. Never loop paid calls.
|
|
232
|
+
- Never invent a model id, option or price: read them from the API.
|
|
233
|
+
- Give the user the file links (or the saved file paths) and the price charged.
|
|
234
|
+
- Keep the key server-side and out of the chat, the code, logs and commits.
|
|
235
|
+
- There are no webhooks for single generations: poll. Format runs may take a `webhook_url`.
|