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:
- Create a media description collection
- Add videos to your collection
- Create a response
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)
import { CloudGlue } from '@aviaryhq/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);
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:
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()
import { CloudGlue } from '@aviaryhq/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.