API Reference

Quote request

{
  "request": {
    "name": "Paid quote test",
    "project_mode": "scene",
    "screenplay": "Shot 1: A glass airship drifts over a frozen city.",
    "shot_count": 1,
    "scene_target_duration_seconds": 4,
    "video_resolution": "720p"
  },
  "upload_urls": [
    {
      "url": "https://example.com/reference.jpg",
      "filename": "reference.jpg"
    }
  ]
}

402 response

HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment id="...", realm="app.future.video", method="stripe", intent="charge", request="...", expires="..."

{
  "type": "https://paymentauth.org/problems/payment-required",
  "title": "Payment Required",
  "status": 402,
  "payment_method": "stripe_mpp",
  "quote_id": "quote_...",
  "amount_cents": 120,
  "currency": "usd",
  "credits_quoted": 120,
  "payment_url": "https://fmv-studio-frontend-t7cat7yhuq-uc.a.run.app/api/agent/render-quotes/quote_.../pay?claim_token=...",
  "status_url": "https://fmv-studio-frontend-t7cat7yhuq-uc.a.run.app/api/agent/paid-renders/quote_...?claim_token=...",
  "claim_token": "...",
  "expires_at": "2026-04-30T12:30:00Z"
}

Client config

Use this shape for account mode. For paid quote mode, omit `headers`.

{
  "mcpServers": {
    "future-video-studio": {
      "type": "streamable-http",
      "url": "https://mcp.future.video/mcp",
      "headers": {
        "X-FVS-Agent-Key": "fvs_live_replace_me"
      }
    }
  }
}

Tools

• `fvs_submit_render` submits a new render request and returns status links.
• `fvs_create_paid_render_quote` returns a Link-compatible no-account quote.
• `fvs_get_render_status` polls by `project_id` or `status_url`.
• `fvs_get_paid_render_status` polls a paid quote by `status_url` or claim token.
• `fvs_cancel_render` cancels an in-flight render.
• `fvs_download_final_video` downloads a completed signed video URL to a local path.
• `fvs_example_render_request` returns a starter request body.
• `fvs_open_chatgpt_app` opens the ChatGPT app widget without creating a render.

Everything the studio already knows how to ingest.

• Text-only briefs with screenplay, instructions, lore, style controls, and shot targets.
• Uploaded image references for characters, environments, props, and mood boards.
• Uploaded audio tracks for `uploaded_track` music workflows.
• Uploaded video, PDF, and document assets using the same asset-analysis path as the studio UI.

Content type

• `multipart/form-data` with `request_json` as a JSON string.
• `files` can be repeated for image, audio, video, and document uploads.
• `assets[]` inside the payload labels and classifies those uploaded files.

Python

import json
import requests

BASE_URL = "https://fmv-studio-frontend-t7cat7yhuq-uc.a.run.app/api/agent"
AGENT_KEY = "replace-with-your-managed-key"

request_payload = {
    "name": "Archive corridor test",
    "project_mode": "scene",
    "screenplay": "Shot 1: A young woman enters a glowing archive corridor lined with suspended photographs. Shot 2: She reaches toward one moving photograph and the corridor bends into a luminous tunnel around her. Shot 3: She steps through the tunnel and arrives in a sunlit memory chamber as the photographs orbit overhead.",
    "instructions": "Create exactly three cinematic shots totaling about 24 seconds.",
    "shot_count": 3,
    "scene_target_duration_seconds": 24,
    "video_model": "veo-3.1-fast-generate-001",
    "video_resolution": "720p",
    "stage_voice_briefs_enabled": False,
}

response = requests.post(
    f"{BASE_URL}/renders",
    headers={"X-FVS-Agent-Key": AGENT_KEY},
    files={"request_json": (None, json.dumps(request_payload))},
)
response.raise_for_status()
job = response.json()

while True:
    status_response = requests.get(job["status_url"], headers={"X-FVS-Agent-Key": AGENT_KEY})
    status_response.raise_for_status()
    status = status_response.json()
    if status["status"] == "completed":
        print("Video ready:", status["final_video_url"])
        break
    if status["status"] == "failed":
        raise RuntimeError(status.get("last_error") or "Render failed")

JavaScript

const form = new FormData();
form.append("request_json", JSON.stringify({
  name: "Archive corridor test",
  project_mode: "scene",
  screenplay: "Three-shot cinematic archive corridor sequence.",
  instructions: "Keep the lead visually consistent and total runtime near 24 seconds.",
  shot_count: 3,
  scene_target_duration_seconds: 24,
  video_model: "veo-3.1-fast-generate-001",
  video_resolution: "720p"
}));

const submit = await fetch("https://fmv-studio-frontend-t7cat7yhuq-uc.a.run.app/api/agent/renders", {
  method: "POST",
  headers: {
    "X-FVS-Agent-Key": "replace-with-your-managed-key"
  },
  body: form
});

const job = await submit.json();
const status = await fetch(job.status_url, {
  headers: {
    "X-FVS-Agent-Key": "replace-with-your-managed-key"
  }
}).then((res) => res.json());