> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudglue.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses API

> Multi-turn conversations with video context

## Quick Start

First, make sure you have Cloudglue set up by following the [setup guide](/getting-started/setup-cloudglue).

## 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

<Tabs>
  <Tab title="Python" value="python">
    ```python theme={null}
    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](/sdks/python).
  </Tab>

  <Tab title="Node" value="node">
    ```typescript theme={null}
    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](/sdks/javascript).
  </Tab>
</Tabs>

## 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](/deep-dives/responses-api#entity-backed-knowledge) for entity-backed knowledge examples.

<Warning>
  `nimbus-002-preview` is a preview model. Behavior may change as we iterate.
</Warning>

## Streaming

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

<Tabs>
  <Tab title="Python" value="python">
    ```python theme={null}
    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()
    ```
  </Tab>

  <Tab title="Node" value="node">
    ```typescript theme={null}
    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();
      }
    }
    ```
  </Tab>
</Tabs>

## Next Steps

For advanced features — entity-backed knowledge, background processing, multi-turn conversations, rich citations, and filters — see the [Responses API deep dive](/deep-dives/responses-api).

For more detailed API parameters, check out our [API Reference](/api-reference/endpoint/responses/post).