Responses API

Multi-turn conversations with video context

Quick Start

First, make sure you have Cloudglue set up by following the setup guide.

Create a Collection and Query with Responses

The Responses API provides an OpenAI Responses-compatible interface for multi-turn conversations with your video collections. Compared to Chat Completions, it offers richer annotations with timestamps, built-in multi-turn support, and system instructions for controlling response behavior.

To get started:

1. Create a media description collection
2. Add videos to your collection
3. Create a response

Python

from cloudglue import Cloudglue

client = Cloudglue()

# Create a media description collection
collection = client.collections.create(
    name='my-video-collection',
    collection_type='media-descriptions'
)

# Upload video
video = client.files.upload('path/to/video.mp4', wait_until_finish=True)

# Add video to collection
client.collections.add_video(
    collection_id=collection.id,
    file_id=video.id,
    wait_until_finish=True
)

# Create a response
response = client.responses.create(
    input="What are the key topics discussed in this video?",
    collections=[collection.id],
    model="nimbus-001",
    instructions="Provide detailed answers with timestamps when possible."
)

print(response.output[0].content[0].text)

For more details about the Python SDK, check out our Python SDK Documentation.

Node

import { Cloudglue } from '@cloudglue/cloudglue-js';
import * as fs from 'fs';

const client = new Cloudglue();

// Create a media description collection
const collection = await client.collections.createCollection({
  name: 'my-video-collection',
  collection_type: 'media-descriptions'
});

// Upload and process video
const file = new File(
  [await fs.promises.readFile('path/to/video.mp4')],
  'video.mp4'
);
const upload = await client.files.uploadFile({ file });
await client.files.waitForReady(upload.data.id);

const add = await client.collections.addVideo(collection.id, upload.data.id);
await client.collections.waitForReady(collection.id, add.file_id);

// Create a response
const response = await client.responses.createResponse({
  model: 'nimbus-001',
  input: 'What are the key topics discussed in this video?',
  knowledge_base: {
    collections: [collection.id]
  },
  instructions: 'Provide detailed answers with timestamps when possible.'
});

console.log(response.output?.[0]?.content?.[0]?.text);

For more details about the Node.js SDK, check out our JavaScript SDK Documentation.

Model Options

The Responses API supports two models:

Model	Best For
nimbus-001	Fast general question answering over media description collections
nimbus-002-preview	Light reasoning with multi-step analysis, entity-backed knowledge, cross-video synthesis

nimbus-002-preview can combine structured entity data with media descriptions for richer answers. See the Responses API deep dive for entity-backed knowledge examples.

nimbus-002-preview is a preview model. Behavior may change as we iterate.

Streaming

Stream responses in real-time via Server-Sent Events:

Python

from cloudglue import Cloudglue

client = Cloudglue()

events = client.responses.create(
    input="Summarize the main topics in these videos.",
    collections=["COLLECTION_ID"],
    model="nimbus-002-preview",
    stream=True,
)

for event in events:
    evt_type = event.get("event")
    data = event.get("data")
    if evt_type == "response.output_text.delta" and isinstance(data, dict):
        print(data.get("delta", ""), end="", flush=True)
    elif evt_type == "response.completed":
        print()

Node

import { Cloudglue } from '@cloudglue/cloudglue-js';

const client = new Cloudglue();

const stream = await client.responses.createStreamingResponse({
  model: 'nimbus-002-preview',
  input: 'Summarize the main topics in these videos.',
  knowledge_base: { collections: ['COLLECTION_ID'] },
});

for await (const event of stream) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta);
  } else if (event.type === 'response.completed') {
    console.log();
  }
}

Next Steps

For advanced features — entity-backed knowledge, background processing, multi-turn conversations, rich citations, and filters — see the Responses API deep dive.

For more detailed API parameters, check out our API Reference.