Backboard API home pagelight logo
  1. SDK
  2. Video Tool

Video generation follows the image-tool flow: a normal thread LLM decides whether to call a built-in tool, while a separate model generates the media. Pass video_generation="auto", video_model_provider="openrouter", and video_model_name on every turn where generation is needed. The default is "off".

Choose video_model_name from client.list_video_models() (Python), client.listVideoModels() (JavaScript), or GET /models/video/all. Use the model’s id, not its display name. Optional video_config fields are duration, resolution, aspect_ratio, size, generate_audio, seed, provider, upscale_factor, and creativity; use only supported options and combinations.

​
Python SDK: streaming

For explicit generation without a chat model, see stateless video calls. They use the same video model and config fields, with named frame and reference uploads.

Both send_message and add_message accept video_config; both sendMessage and addMessage accept video_config or videoConfig. This works with JSON and multipart uploads, with stream either true or false. For local video-to-video inputs, use add_message(..., files=["input.mp4"]) or addMessage(threadId, { files: ["input.mp4"], ... }), select a video-input-capable model, and ask for the intended edit.

Caller-supplied settings are fixed. The dynamically generated tool definition exposes supported settings so the conversation model can fill omitted values. See model-specific rules. provider is a routing object, not unrestricted passthrough.

This example requires a Python SDK version exposing the video fields on send_message(). If your installed SDK does not expose them, use POST /threads/messages directly as shown in the concept guide; do not silently omit them.

import asyncio
import os
from backboard import BackboardClient

async def main():
    client = BackboardClient(api_key=os.environ["BACKBOARD_API_KEY"], timeout=1900)
    stream = await client.send_message(
        "Generate a video of a sunflower opening in the morning light.",
        thread_id="THREAD_ID",
        llm_provider="openai",
        model_name="gpt-4.1",
        video_generation="auto",
        video_model_provider="openrouter",
        video_model_name=os.environ["VIDEO_MODEL_ID"],
        stream=True,
    )

    async for chunk in stream:
        if chunk.get("type") == "media_generated":
            media = chunk.get("media") or {}
            if media.get("mime_type") == "video/mp4":
                print("video url:", media.get("url"))
                print("document_id:", media.get("document_id"))
        elif chunk.get("type") == "content_streaming":
            print(chunk.get("content", ""), end="", flush=True)

asyncio.run(main())

​
JavaScript and TypeScript SDK

import { BackboardClient } from "backboard-sdk";

const client = new BackboardClient({ apiKey: process.env.BACKBOARD_API_KEY, timeout: 1900000 });
const response = await client.sendMessage({
    content: "Generate a video of a sunflower opening in the morning light.",
    threadId: "THREAD_ID",
    llm_provider: "openai",
    model_name: "gpt-4.1",
    video_generation: "auto",
    video_model_provider: "openrouter",
    video_model_name: "VIDEO_MODEL_ID",
    stream: false,
});
if ("messages" in response) {
  console.log(response.messages.flatMap(message => message.generatedMedia ?? []));
}

Non-streaming responses use the existing generated_media message metadata. Streaming uses media_generated with a stored video’s document_id, url, and video/mp4 MIME type. Do not treat assistant text alone as proof that a clip was generated.

Video generation can take minutes. Prefer streaming (the API sends keepalives) and allow a longer client timeout. Do not automatically retry a timed-out generation request: its upstream job may still be running and billable.

​
Media-guided follow-ups

Reuse the thread and identify uploaded or previously generated media documents in your prompt. Ask the assistant to pass them to generate_video as:

  • input_image_document_id: first frame
  • input_last_frame_document_id: last frame
  • input_video_document_id: source video for a compatible video-to-video model
  • input_reference_document_ids: image, audio, or video reference list, subject to model capabilities

The tool also accepts prompt. Enable video generation and provide the video model again on the follow-up turn. First/last frames must be images. References cannot be combined with frame images. These examples do not certify every combination as tested; audio/video reference support and audio within generated clips depend on the selected video model, independently of the chat model.

​
Related pages