Quickstart

Base URL https://quantumplations.ai/api/v1. Everything speaks JSON, your plan decides what you may order, and your key is the only credential.

curl -X POST https://quantumplations.ai/api/v1/videos \
  -H "Authorization: Bearer $QP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"prompt": "Explain how a Kalman filter works.", "duration_seconds": 60}'

{
  "id": "425e4bbe-5d63-4343-b0ad-8d90dc5805b4",
  "status": "queued",
  "duration_seconds": 60,
  "videos_left": null,
  "video": null
}

curl https://quantumplations.ai/api/v1/videos/$RENDER_ID \
  -H "Authorization: Bearer $QP_API_KEY"

"video": {
  "url": "https://…/425e4bbe….mp4?token=…",
  "poster_url": "https://…/425e4bbe….jpg?token=…",
  "duration_seconds": 59.8,
  "expires_in": 3600
}

Endpoints

Render options

Everything but prompt has a default. Anything else you send is ignored.

Errors

Every failure is {"error": "<code>", "message": "…"} with a matching status.

Webhooks

Give callback_url and we post once, when the render settles: { event, id, status, error, completed_at }, with X-Quantumplations-Signature: t=<unix>,v1=<hex>. There's no retry, so keep polling as your fallback.

The signature is an HMAC-SHA256 of "<t>.<raw body>" keyed with the webhook secret shown beside your key. Verify against the raw bytes, before parsing:

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyWebhook(rawBody, header, secret,
                              nowS = Math.floor(Date.now() / 1000)) {
  const parts = Object.fromEntries(String(header || '').split(',').map((p) => {
    const i = p.indexOf('=');
    return i < 0 ? ['', ''] : [p.slice(0, i).trim(), p.slice(i + 1).trim()];
  }));

  // Reject a replay of anything older than five minutes.
  const t = Number(parts.t);
  if (!/^[0-9]+$/.test(parts.t || '') || Math.abs(nowS - t) > 300) return false;

  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest();
  const given = Buffer.from(String(parts.v1 || ''), 'hex');
  // timingSafeEqual throws on a length mismatch, so check length first.
  return given.length === expected.length && timingSafeEqual(given, expected);
}

Answer with a 2xx quickly. Nothing you return is read.

Use it from an agent

There's an MCP server at https://quantumplations.ai/api/mcp, so any agent or editor that speaks MCP can order a video without leaving the conversation. It's the same API and the same key.

{
  "mcpServers": {
    "quantumplations": {
      "type": "http",
      "url": "https://quantumplations.ai/api/mcp",
      "headers": { "Authorization": "Bearer qp_live_…" }
    }
  }
}

Five tools: generate_video, answer_questions, get_video, list_videos and get_credits. The one worth knowing about is answer_questions: the agent making your video stops and asks when a brief is ambiguous, and get_video reports awaiting_answers with the questions and how long is left to answer. Only generate_video makes a video, and it's annotated so your client asks before it does. There's deliberately no cancel tool: an agent that can cancel renders it didn't order is a footgun, and cancelling stays on the REST surface where a person presses the button.

A key in an MCP config is still a secret key. It sits on the machine running the client, which is a server-side place, but treat the config file the way you'd treat any file holding a credential.

API keys

Keys belong to your Quantumplations account and carry your plan and your beta access. Mint one per application, so you can revoke or roll one without breaking the rest. Twenty live keys is the ceiling.

Plans

An API key orders under the same plan as the website, and the plan decides four things: how long a video may run, how many renders you may have going at once, on the free plan how many videos you get in total, and which of the render options above you may set at all. GET /options publishes those limits for the key that calls it, and GET /credits reports what is left. A video longer than the plan allows is refused with duration_over_plan before anything is queued, so nothing is half-ordered. On the free and starter plans, tone, focus, web images and clarifying questions are set for you, and so is personalizing; on the free plan captions are set for you too. An order that sends one of them is accepted all the same and the video is made with the standard value, so read plan.locked from GET /options, which names them, before you rely on one. The free plan gives three videos in total; a render that fails or is cancelled puts its video back. Downloading the finished video, its transcript and its subtitles is part of the paid plans; a free key renders and reports progress, and answers download_locked: true with no file. See the plans.