BACK

API Guide: Collaborative Cinematics with Video Bridge

Harnessing multi-model cinematic generation via a human-in-the-loop Consultant Dialogue.

API Guide: Collaborative Cinematics with Video Bridge

Harnessing multi-model cinematic generation via a human-in-the-loop Consultant Dialogue.

01. The Stack — Context

Video Bridge API (Skill ID: F1E1443E-F36B-1410-8462-00039CE7DF11)

  • Primary engine for multi-model cinematic generation and orchestration.
  • Acts as the stable interface between your front-end and various underlying video models.

Reference-Image Workflow

  • Uses the /api/images/upload endpoint to host base image foundations (characters, environments).
  • Returned imageUrl values are used to maintain visual consistency across clips.

MindsPage

  • Branded video hosting and distribution infrastructure for playback and sharing.

02. Prompting the Heartbeat — The Consultant Dialogue

The Video Bridge does not use "one-shot" prompting. It operates via a Consultant Dialogue. Upon initialization, a virtual "Director" persona asks clarifying questions regarding camera motion, lighting, and style. Generation is only triggered once the synthesized, machine-ready prompt is explicitly approved by the human creator. This ensures narrative intent is preserved before compute resources are spent.

03. Project Structure — The Workflow

  • Initialize: Call POST /api/video/conversations with your initial vision and a selected Director Persona (hollywood_director, anime_director, asian_film_director, or european_director).
  • Upload: Use POST /api/images/upload to store reference images and capture the imageUrl for use in the conversation.
  • Refine: Facilitate the consultation loop via POST /api/video/conversations/:id/messages, relaying Director questions to the user and their answers back to the API.
  • Approve: Lock the final synthesized prompt via POST /api/video/conversations/:id/approve to transition the job to generating status.
  • Poll: Use GET /api/video/conversations/:id/status to check progress. A polling interval of ~4 seconds is recommended for optimal responsiveness.
  • Deliver: Return the sharePageUrl to the user once the status reaches completed.

04. Prompt Templates — Mastering the Consultation

Template: High-Control Blockbuster

  • Weak: "Make a cinematic video of a samurai."
  • Strong: "Create a 15s sequence of a lone samurai at dusk. Persona: hollywood_director. Prioritize atmospheric rim lighting during consultation; await explicit approval."

Template: Stylized Narrative

  • Weak: "Anime girl in a forest."
  • Strong: "Generate an 8s anime-style clip of a protagonist discovering a hidden shrine. Use persona 'anime_director'. Focus on dramatic low camera angles and lush forest textures."

Template: Moody Realism

  • Weak: "A sad person in a cafe."
  • Strong: "12-second asian_film_director-style scene in a dimly lit noodle shop. Static low-angle shot focusing on subtle facial expressions and rising steam. Persona: asian_film_director. Prioritize naturalistic lighting."

05. Boilerplate — The API Integration Core

The loop below wires the consultant dialogue and image-upload workflow into a single async flow; adapt the human-interaction logic to your specific UI layer.

async function generateVideo(userPrompt, file) {
  // 1. Upload reference image if provided
  let imageUrl = null;
  if (file) {
    const upload = await UPLOAD("/api/images/upload", file);
    imageUrl = upload.imageUrl;
  }

  // 2. Initialize with a specific Persona and optional image
  const init = await POST("/api/video/conversations", {
    prompt: userPrompt,
    persona: "hollywood_director",
    ...(imageUrl && { imageUrl })
  });

  // 3. Consultation Loop (Human-in-the-loop)
  while(init.status === "consulting") {
    const feedback = await askHuman(init.lastMessage);
    if(feedback === "APPROVE") break;
    await POST(`/api/video/conversations/${init.id}/messages`, {
      message: feedback
    });
  }

  // 4. Trigger & Poll
  await POST(`/api/video/conversations/${init.id}/approve`, {});
  while(true) {
    const res = await GET(`/api/video/conversations/${init.id}/status`);
    if(res.status === "completed") return res.sharePageUrl;
    if(res.status === "failed") throw new Error("Generation failed");
    await sleep(4000); // Recommended polling cadence
  }
}