cloudglue（cloudglue 搜索）

Cloudglue SDK Guide

Build AI-powered video applications with Cloudglue. This skill teaches you how to find current documentation, verify API signatures, and use the Cloudglue JS SDK to upload, describe, extract, search, and chat over video content.

Critical: Do not trust internal knowledge

Everything you know about Cloudglue is likely outdated or wrong. Never rely on memory. Always verify against current documentation.

Your training data may contain obsolete APIs, deprecated patterns, and incorrect usage. Cloudglue evolves rapidly — APIs change between versions, method signatures shift, and patterns get refactored. Always check the embedded docs or source code for the installed SDK version before writing any code.

Finding Documentation

Use this 3-tier hierarchy — start with tier 1 and fall back as needed:

Tier 1: Embedded Docs (most reliable, version-locked)

node_modules/@cloudglue/cloudglue-js/docs/

Read these first. They contain exact method signatures, parameters, code snippets, and types for the installed SDK version. See references/embedded-docs.md for a file listing and decision tree.

Tier 2: Source Code

node_modules/@cloudglue/cloudglue-js/src/api/*.api.ts

Each Enhanced*Api class wraps a generated client with user-friendly methods. Read the source when embedded docs lack detail on edge cases or internal behavior.

Tier 3: Remote Docs

https://docs.cloudglue.dev/llms.txt

Use when you need conceptual deep dives, data connector setup, or features not yet in the installed SDK version. See references/remote-docs.md for navigation.

Quick Start

npm install @cloudglue/cloudglue-js

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

const client = new Cloudglue({
  apiKey: process.env.CLOUDGLUE_API_KEY,  // keys start with 'cg-'
});

Core Mental Model

Files (upload video/audio)
  → Processing (describe, extract, face detection)
    → Collections (group processed files by type)
      → Querying (chat, search, deep search, responses API)

Files

Upload video/audio files or provide URLs. Files go through processing (pending → processing → completed). Use waitForReady() to poll until done.

Describe

Generate multimodal descriptions: speech transcription, visual scene descriptions, scene text (OCR), audio descriptions, summaries. This is the primary way to analyze video content. Note: transcribe is deprecated — use describe instead.

Extract

Pull structured data from videos using custom prompts and JSON schemas. Supports segment-level (default) or video-level extraction.

Collections

Group videos for querying. Each collection has a type that determines what data is generated:

See references/collection-types.md for detailed comparison and selection guidance.

Chat

Q&A over collections using nimbus-001. Simple synchronous API. For streaming, background jobs, or function calling, use the Responses API instead.

Responses API

Next-generation query interface (OpenAI Responses-compatible). Supports streaming, background jobs, function calling (tools), and multiple knowledge base sources (collections, files, or default index). Models: nimbus-001 (fast), nimbus-002-preview (reasoning, entity-backed).

Search

Semantic search across collections at segment scope (find specific moments) or file scope (find relevant videos). Supports metadata and property filters.

Deep Search

Agentic retrieval — runs multiple search passes with LLM reasoning to find and synthesize answers. Supports streaming and the same knowledge base sources as the Responses API.

API Quick Reference

Key Patterns

Async Job Polling

All processing jobs use waitForReady():

const result = await client.describe.waitForReady(jobId, {
  pollingInterval: 5000,  // ms between polls (default)
  maxAttempts: 36,        // max attempts (default, = 3 min)
});

Knowledge Base Sources

The Responses API and Deep Search share three knowledge base types:

{ source: 'collections', collections: ['col_id'] }  // query specific collections
{ source: 'files', files: ['file_id'] }              // query specific files
{ source: 'default' }                                // files with use_in_default_index

Streaming

Responses API and Deep Search support SSE streaming:

const stream = await client.responses.createStreamingResponse({ ... });
for await (const event of stream) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta);
  }
}

Filters

Search and list operations accept metadata/property filters:

import { FilterOperator } from '@cloudglue/cloudglue-js';
filter: {
  metadata: [{ path: 'key', operator: FilterOperator.Equal, valueText: 'value' }],
}

Common Gotchas

• transcribe is deprecated — use describe for all transcription/description needs
• rich-transcripts collection type is deprecated — use media-descriptions (the default) instead; it provides full multimodal output including speech
• Chat requires collections — videos must be added to a collection before querying with chat/search
• nimbus-002-preview for entity-backed — entity-backed knowledge in Responses API requires this model
• File uploads use FormData — the SDK handles this internally via axios, not Zodios
• waitForReady defaults — 5s interval × 36 attempts = 3 min max; increase for large videos
• Streaming requires Node 18+ — uses ReadableStream / fetch APIs
• addVideo/addVideoByUrl are deprecated — use addMedia/addMediaByUrl

References

• Embedded docs guide — how to find and use version-locked SDK docs
• Remote docs guide — navigating the online documentation
• Common errors — troubleshooting guide
• Core workflows — end-to-end code patterns
• Collection types — choosing the right collection type