{"id":"bea2c9cc-69cc-4e96-82a3-e678f6082c39","entityType":"agent","slug":"clawhub-gladiaio-gladia-sdk-integration","name":"gladia-sdk-integration","canonicalUrl":"https://www.xpersona.co/agent/clawhub-gladiaio-gladia-sdk-integration","canonicalPath":"/agent/clawhub-gladiaio-gladia-sdk-integration","generatedAt":"2026-10-10T21:43:24.690Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T17:27:04.642Z","emptyReason":null},"description":"Install and configure the official Gladia SDKs (@gladiaio/sdk for JS/TS, gladiaio-sdk for Python). Use when the user asks about SDK setup, client initialization, API key configuration, choosing between JS and Python, browser usage, retry/timeout settings, error handling, or SDK vs raw API decisions. The SDK is the recommended default for all Gladia integrations.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.3K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s170451ybbxgxcc4es3g96b4fs8823td:gladia-sdk-integration","sourceUrl":"https://clawhub.ai/gladiaio/gladia-sdk-integration","homepage":"https://clawhub.ai/gladiaio/skills/gladia-sdk-integration","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/gladiaio/gladia-sdk-integration","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/gladiaio/skills/gladia-sdk-integration","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":62,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"gladia-sdk-integration technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T17:27:04.642Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T17:27:04.642Z","emptyReason":null},"stars":null,"forks":null,"downloads":1318,"packageName":null,"latestVersion":"1.0.5","tractionLabel":"1.3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T17:27:04.577Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T17:27:04.642Z","lastCrawledAt":"2026-10-10T17:27:04.577Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T17:27:04.577Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.5","createdAt":"2026-10-02T15:08:38.008Z","changelog":"gladia-sdk-integration 1.0.5 - Updated JS and Python SDK reference docs with latest patterns and clarified integration notes. - Synced SDK version listing in references/sdk-versions.md. - Removed outdated skill-card.md file to clean up documentation. - No breaking changes; documentation improvements only.","fileCount":7,"zipByteSize":11522},{"version":"1.0.4","createdAt":"2026-07-29T15:39:49.751Z","changelog":"gladia-sdk-integration 1.0.4 - Updated references for JavaScript and Python SDK usage patterns - Synced SDK version information in sdk-versions.md - Removed obsolete skill-card.md documentation file - No changes to main logic; updates are documentation and reference improvements","fileCount":7,"zipByteSize":11768},{"version":"1.0.3","createdAt":"2026-07-09T15:11:16.290Z","changelog":"- Added CLI routing information: skill now guides users to the CLI skill ([gladia-using-cli](../gladia-using-cli/SKILL.md)) when gladia-cli is requested or used from the terminal. - Updated decision table to include CLI as an option for terminal one-off usage. - Added reference to CLI integration under References. - Removed obsolete `skill-card.md` file.","fileCount":7,"zipByteSize":11763},{"version":"1.0.2","createdAt":"2026-07-09T14:06:17.774Z","changelog":"- Updated reference files: sdk-versions.md, javascript.md, python.md for improved documentation accuracy. - Removed obsolete or redundant file: skill-card.md. - No user-facing feature or behavior changes.","fileCount":7,"zipByteSize":11653},{"version":"1.0.1","createdAt":"2026-06-08T18:17:30.023Z","changelog":"- Documentation updated: SKILL.md trimmed incomplete code and text at the end for clarity and consistency. - No functional or behavioral changes; this release focuses on fixing documentation formatting and truncation. - All core usage instructions, reference links, and integration details remain unchanged.","fileCount":7,"zipByteSize":11732},{"version":"1.0.0","createdAt":"2026-06-08T18:01:56.164Z","changelog":"Version 1.0.0 of gladia-sdk-integration - Initial release providing guidance for installing, configuring, and using the official Gladia SDKs for JavaScript/TypeScript and Python. - Includes detailed usage decision guide (when to use SDK vs raw API) and scenario-based recommendations. - Documents installation steps, environment variable configuration, and client initialization for both languages. - Summarizes SDK client architecture, available methods, audio input types, and error handling patterns. - References related skills and resources for advanced configuration, troubleshooting, and use-case-specific integrations.","fileCount":7,"zipByteSize":11762}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s170451ybbxgxcc4es3g96b4fs8823td:gladia-sdk-integration","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s170451ybbxgxcc4es3g96b4fs8823td:gladia-sdk-integration` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/gladiaio/gladia-sdk-integration before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gladiaio-gladia-sdk-integration/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gladiaio-gladia-sdk-integration/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gladiaio-gladia-sdk-integration/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-gladiaio-gladia-sdk-integration/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-gladiaio-gladia-sdk-integration/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-gladiaio-gladia-sdk-integration/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T21:43:24.687Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gladiaio-gladia-sdk-integration/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gladiaio-gladia-sdk-integration/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gladiaio-gladia-sdk-integration/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gladiaio-gladia-sdk-integration/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T17:27:04.642Z","emptyReason":null},"readme":"Skill: gladia-sdk-integration\n\nOwner: gladiaio\n\nSummary: Install and configure the official Gladia SDKs (@gladiaio/sdk for JS/TS, gladiaio-sdk for Python). Use when the user asks about SDK setup, client initialization, API key configuration, choosing between JS and Python, browser usage, retry/timeout settings, error handling, or SDK vs raw API decisions. The SDK is the recommended default for all Gladia integrations.\n\nTags: latest:1.0.5\n\nVersion history:\n\nv1.0.5 | 2026-10-02T15:08:38.008Z | auto\n\ngladia-sdk-integration 1.0.5\n\n- Updated JS and Python SDK reference docs with latest patterns and clarified integration notes.\n- Synced SDK version listing in references/sdk-versions.md.\n- Removed outdated skill-card.md file to clean up documentation.\n- No breaking changes; documentation improvements only.\n\nv1.0.4 | 2026-07-29T15:39:49.751Z | auto\n\ngladia-sdk-integration 1.0.4\n\n- Updated references for JavaScript and Python SDK usage patterns\n- Synced SDK version information in sdk-versions.md\n- Removed obsolete skill-card.md documentation file\n- No changes to main logic; updates are documentation and reference improvements\n\nv1.0.3 | 2026-07-09T15:11:16.290Z | auto\n\n- Added CLI routing information: skill now guides users to the CLI skill ([gladia-using-cli](../gladia-using-cli/SKILL.md)) when gladia-cli is requested or used from the terminal.\n- Updated decision table to include CLI as an option for terminal one-off usage.\n- Added reference to CLI integration under References.\n- Removed obsolete `skill-card.md` file.\n\nv1.0.2 | 2026-07-09T14:06:17.774Z | auto\n\n- Updated reference files: sdk-versions.md, javascript.md, python.md for improved documentation accuracy.\n- Removed obsolete or redundant file: skill-card.md.\n- No user-facing feature or behavior changes.\n\nv1.0.1 | 2026-06-08T18:17:30.023Z | auto\n\n- Documentation updated: SKILL.md trimmed incomplete code and text at the end for clarity and consistency.\n- No functional or behavioral changes; this release focuses on fixing documentation formatting and truncation.\n- All core usage instructions, reference links, and integration details remain unchanged.\n\nv1.0.0 | 2026-06-08T18:01:56.164Z | auto\n\nVersion 1.0.0 of gladia-sdk-integration\n\n- Initial release providing guidance for installing, configuring, and using the official Gladia SDKs for JavaScript/TypeScript and Python.\n- Includes detailed usage decision guide (when to use SDK vs raw API) and scenario-based recommendations.\n- Documents installation steps, environment variable configuration, and client initialization for both languages.\n- Summarizes SDK client architecture, available methods, audio input types, and error handling patterns.\n- References related skills and resources for advanced configuration, troubleshooting, and use-case-specific integrations.\n\nArchive index:\n\nArchive v1.0.5: 7 files, 11522 bytes\n\nFiles: references/client-config.md (2299b), references/javascript.md (4866b), references/python.md (6658b), references/sdk-versions.md (543b), skill-card.md (2097b), SKILL.md (11715b), _meta.json (141b)\n\nFile v1.0.5:SKILL.md\n\n---\nname: gladia-sdk-integration\ndescription: Install and configure the official Gladia SDKs (@gladiaio/sdk for JS/TS, gladiaio-sdk for Python). Use when the user asks about SDK setup, client initialization, API key configuration, choosing between JS and Python, browser usage, retry/timeout settings, error handling, or SDK vs raw API decisions. The SDK is the recommended default for all Gladia integrations.\nlicense: MIT\n---\n\n# SDK Integration\n\nOfficial SDKs for integrating Gladia's speech-to-text API. Both SDKs share the same design and are generated from the Gladia OpenAPI schema.\n\n> **The SDK is the default for all Gladia integrations.** Always use the SDK unless there is a specific, documented reason not to (see decision guide below).\n\n## When to Use\n\n- User asks about installing, configuring, or initializing the Gladia SDK\n- Setting up API key, region, retry, timeout, or WebSocket configuration\n- Questions about SDK architecture, client methods, or type exports\n- Choosing between JS/TS and Python SDK, or between SDK and raw API\n- Browser-based integration, proxy setup, or bundle format questions\n- Error handling patterns for Gladia API responses\n\n**When NOT to use:** If the user is asking about a specific transcription use case (pre-recorded files or live streaming), start with the relevant use-case skill ([gladia-pre-recorded-transcription](../gladia-pre-recorded-transcription/SKILL.md) or [gladia-live-transcription](../gladia-live-transcription/SKILL.md)) instead — those skills reference back here for setup details.\n\n## When to Use SDK vs Raw API\n\n| Scenario                                 | Approach                                                                                                      |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- |\n| Any JS/TS or Python project              | **SDK** — always                                                                                              |\n| Browser app                              | **SDK** — JS SDK supports ESM/IIFE bundles                                                                    |\n| Need custom HTTP client or middleware    | SDK first; use `httpHeaders` / `httpTimeout` config. Fall back to raw REST only if SDK config is insufficient |\n| Language without an SDK (Go, Java, etc.) | Raw REST/WebSocket (SDK unavailable)                                                                          |\n| User explicitly requests raw calls       | Raw REST/WebSocket                                                                                            |\n| CI script or one-off curl test           | Raw REST is acceptable                                                                                        |\n| Terminal one-off with gladia-cli on PATH | **CLI** — see [gladia-using-cli](../gladia-using-cli/SKILL.md)                                                |\n\nWhen in doubt, use the SDK.\n\n## References\n\nConsult these resources as needed:\n\n- ./references/sdk-versions.md -- Current SDK versions (auto-synced by CI)\n- ./references/client-config.md -- Full client configuration reference (all options, defaults, timeouts)\n- ./references/javascript.md -- JS/TS-specific patterns (browser, proxy, File/Blob, Node requirements)\n- ./references/python.md -- Python-specific patterns (sync/async, typed requests, httpx/websockets)\n- ../gladia-using-cli/SKILL.md -- Terminal transcription with gladia-cli; CLI vs SDK routing\n- ../gladia-pre-recorded-transcription/SKILL.md -- Pre-recorded transcription options, response structure, and audio intelligence config\n- ../gladia-live-transcription/SKILL.md -- Live session config, audio streaming, and WebSocket event handling\n- ../gladia-troubleshooting/SKILL.md -- Common errors, gotchas, and verification checklist\n\n## Installation\n\n### JavaScript / TypeScript\n\n```bash\nnpm install @gladiaio/sdk\n# or\nbun add @gladiaio/sdk\n# or\nyarn add @gladiaio/sdk\n```\n\nRequires Node.js 20+ or Bun. Also works in browsers via ESM/IIFE bundles.\n\n### Python\n\n```bash\npip install gladiaio-sdk\n# or\nuv add gladiaio-sdk\n```\n\nRequires Python 3.10+.\n\n## Client Initialization\n\n### JavaScript/TypeScript\n\n```typescript\nimport { GladiaClient } from \"@gladiaio/sdk\";\n\nconst client = new GladiaClient({\n  apiKey: \"your-api-key\", // or set GLADIA_API_KEY env var\n  region: \"eu-west\", // or set GLADIA_REGION (eu-west | us-west)\n});\n```\n\n### Python\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\nclient = GladiaClient(\n    api_key=\"your-api-key\",      # or set GLADIA_API_KEY env var\n    region=\"eu-west\",            # or set GLADIA_REGION\n)\n```\n\n### Environment Variables\n\n| Variable         | Purpose                    | Default                 |\n| ---------------- | -------------------------- | ----------------------- |\n| `GLADIA_API_KEY` | API key for authentication | —                       |\n| `GLADIA_API_URL` | Base API URL               | `https://api.gladia.io` |\n| `GLADIA_REGION`  | Datacenter region          | —                       |\n\n## Client Architecture\n\n```\nGladiaClient\n├── preRecorded()  → PreRecordedV2Client    (JS)\n│   prerecorded()  → PreRecordedV2Client    (Python)\n│\n├── liveV2()       → LiveV2Client           (JS)\n│   live()         → LiveV2Client           (Python)\n│\n└── (Python only)\n    ├── prerecorded_async() → AsyncPreRecordedV2Client\n    └── live_async()        → AsyncLiveV2Client\n```\n\n### Pre-Recorded Client Methods\n\n| Method                               | Purpose                            |\n| ------------------------------------ | ---------------------------------- |\n| `transcribe(audio, options)`         | High-level: upload + create + poll |\n| `uploadFile(audio)`                  | Upload local file to `/v2/upload`  |\n| `create(options)`                    | Create transcription job           |\n| `createAndPoll(options)`             | Create + poll until done           |\n| `poll(jobId, { interval, timeout })` | Poll until complete                |\n| `get(jobId)`                         | Get job status/results             |\n| `delete(jobId)`                      | Delete job and data                |\n| `getFile(jobId)`                     | Download original audio            |\n\n### Live Client Methods\n\n| Method                  | Purpose                              |\n| ----------------------- | ------------------------------------ |\n| `startSession(options)` | Init session → returns LiveV2Session |\n| `get(sessionId)`        | Get completed session results        |\n| `delete(sessionId)`     | Delete session and data              |\n| `getFile(sessionId)`    | Download session audio               |\n\n### Live Session Methods\n\n| Method             | Purpose                                |\n| ------------------ | -------------------------------------- |\n| `sendAudio(chunk)` | Stream audio bytes to the session      |\n| `stopRecording()`  | End recording, trigger post-processing |\n| `endSession()`     | Force close without post-processing    |\n| `getSessionId()`   | Await session ID (async)               |\n\n## Configuration Options\n\nKey client options: `apiKey`, `apiUrl`, `region`, `httpTimeout`, `httpRetry`, `wsRetry`, `wsTimeout`, `prerecordedTimeouts`, `liveTimeouts`.\n\nFor the full config reference with all options and defaults, see [./references/client-config.md](./references/client-config.md).\n\n## Audio Input Types\n\n| Input                           |   JS/TS   | Python |\n| ------------------------------- | :-------: | :----: |\n| Local file path (string)        | Node only |  Yes   |\n| `Path` object                   |     —     |  Yes   |\n| HTTP(S) URL                     |    Yes    |  Yes   |\n| `File` / `Blob`                 |  Browser  |   —    |\n| Binary file object (`BinaryIO`) |     —     |  Yes   |\n\nURLs are passed directly as `audio_url` without upload. Local files are automatically uploaded via `/v2/upload`.\n\n## Error Handling\n\n### JavaScript/TypeScript\n\n```typescript\ntry {\n  const result = await client.preRecorded().transcribe(\"./audio.mp3\", options);\n} catch (error) {\n  if (error.message.includes(\"401\")) {\n    console.error(\"Invalid API key\");\n  } else if (error.message.includes(\"timeout\")) {\n    console.error(\"Request timed out\");\n  }\n}\n```\n\n### Python\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\ntry:\n    result = client.prerecorded().transcribe(\"audio.mp3\", options)\nexcept Exception as e:\n    print(f\"Error: {e}\")\n```\n\nPython exports `HttpError` and `TimeoutError` for specific error handling.\n\n## Key Differences Between JS and Python\n\n| Aspect          | JavaScript/TypeScript                       | Python                                   |\n| --------------- | ------------------------------------------- | ---------------------------------------- |\n| Async model     | Promise-based (async only)                  | Sync + async (separate clients)          |\n| Naming          | camelCase (`preRecorded`, `sendAudio`)      | snake_case (`prerecorded`, `send_audio`) |\n| Browser support | Yes (ESM, CJS, IIFE)                        | No (server only)                         |\n| Runtime         | Node 20+, Bun, browsers                     | Python 3.10+                             |\n| Dependencies    | 0 runtime deps (optional `ws` for Node <22) | httpx, websockets, pyee                  |\n| Options format  | Plain objects (snake_case keys)             | Dataclasses or dicts                     |\n| Untyped API     | `transcribeUntyped()`, `createUntyped()`    | Dict accepted on most methods            |\n\n## Type Exports\n\nBoth SDKs export all request/response types from the main package:\n\n```typescript\nimport type {\n  LiveV2InitRequest,\n  LiveV2WebSocketMessage,\n  PreRecordedV2Response,\n  PreRecordedV2TranscriptionOptions,\n} from \"@gladiaio/sdk\";\n```\n\n```python\nfrom gladiaio_sdk import (\n    LiveV2InitRequest,\n    LiveV2WebSocketMessage,\n    LiveV2LanguageConfig,\n    LiveV2MessagesConfig,\n    PreRecordedV2Response,\n)\n```\n\n## Common Mistakes\n\n- **Wrong sub-client method name between JS and Python**: JS uses `client.preRecorded()` and `client.liveV2()`; Python uses `client.prerecorded()` and `client.live()`. Mixing the naming conventions causes \"is not a function\" / `AttributeError` at runtime.\n- **Forgetting `await` in JavaScript**: every JS SDK method returns a Promise. Omitting `await` on `transcribe()`, `startSession()`, etc. lets the operation run silently in the background with no result or error surfaced to your code.\n- **API key exposed in browser-side code**: never embed the API key directly in front-end JavaScript — it becomes publicly readable. Use a backend proxy that forwards requests with the key server-side. See [./references/javascript.md](./references/javascript.md) for the proxy pattern.\n- **Node.js < 22 without the `ws` peer dependency**: the JS SDK requires the `ws` package for WebSocket on Node < 22, which lacks a native WebSocket. Without it, live sessions fail silently. Fix: `npm install ws`.\n- **Python async client in sync context**: `client.live_async()` and `client.prerecorded_async()` cannot be called from synchronous code — they require an active event loop. Use the sync client (`client.live()`, `client.prerecorded()`) unless you are inside an `async def`.\n\n## Further Reading\n\n- [SDK integration guide](https://docs.gladia.io/chapters/integrations/sdk)\n- [JS SDK on npm](https://www.npmjs.com/package/@gladiaio/sdk)\n- [Python SDK on PyPI](https://pypi.org/project/gladiaio-sdk/)\n- [SDK source code](https://github.com/gladiaio/sdk)\n- [Code samples](https://github.com/gladiaio/gladia-samples)\n\nFile v1.0.5:_meta.json\n\n{\n  \"ownerId\": \"kn7fs6cmj9hqg7232sbkacf31d882wp2\",\n  \"slug\": \"gladia-sdk-integration\",\n  \"version\": \"1.0.5\",\n  \"publishedAt\": 1790953718008\n}\n\nFile v1.0.5:references/client-config.md\n\n# Full Client Configuration Reference\n\nComplete configuration options for `GladiaClient` constructor.\n\n## Contents\n\n- Full Config Example (JavaScript/TypeScript)\n- Config Summary Table\n\n## Full Config Example\n\n```typescript\nconst client = new GladiaClient({\n  apiKey: \"your-key\",\n  apiUrl: \"https://api.gladia.io\",\n  region: \"eu-west\",\n\n  // HTTP settings\n  httpHeaders: { \"X-Custom-Header\": \"value\" },\n  httpTimeout: 10000, // 10s default\n  httpRetry: {\n    maxRetries: 3,\n    retryDelay: 1000,\n  },\n\n  // WebSocket settings\n  wsRetry: {\n    maxRetries: 5,\n    retryDelay: 1000,\n  },\n  wsTimeout: 30000,\n\n  // Pre-recorded operation timeouts\n  prerecordedTimeouts: {\n    transcribe: 7200000, // 2 hours (full flow)\n    poll: 7200000,\n    upload: 300000, // 5 minutes\n    create: 30000,\n    get: 10000,\n    delete: 10000,\n    getFile: 60000,\n  },\n\n  // Live operation timeouts\n  liveTimeouts: {\n    get: 10000,\n    delete: 10000,\n    getFile: 60000,\n  },\n});\n```\n\n## Config Summary\n\n| Option                  | Type     | Default                 | Description                |\n| ----------------------- | -------- | ----------------------- | -------------------------- |\n| `apiKey`                | `string` | `GLADIA_API_KEY` env    | API key                    |\n| `apiUrl`                | `string` | `https://api.gladia.io` | Base API URL               |\n| `region`                | `string` | `GLADIA_REGION` env     | `eu-west` or `us-west`     |\n| `httpHeaders`           | `object` | `{}`                    | Custom HTTP headers        |\n| `httpTimeout`           | `number` | `10000`                 | HTTP request timeout (ms)  |\n| `httpRetry.maxRetries`  | `number` | `3`                     | Max HTTP retries           |\n| `httpRetry.retryDelay`  | `number` | `1000`                  | Delay between retries (ms) |\n| `wsRetry.maxRetries`    | `number` | `5`                     | Max WebSocket reconnects   |\n| `wsRetry.retryDelay`    | `number` | `1000`                  | WS reconnect delay (ms)    |\n| `wsTimeout`             | `number` | `30000`                 | WebSocket timeout (ms)     |\n| `prerecordedTimeouts.*` | `number` | varies                  | Per-operation timeouts     |\n| `liveTimeouts.*`        | `number` | varies                  | Per-operation timeouts     |\n\nFile v1.0.5:references/javascript.md\n\n# JavaScript / TypeScript SDK\n\nPatterns and details specific to the `@gladiaio/sdk` package.\n\n## Contents\n\n- Package Info\n- Browser Usage (ESM, IIFE, API key security via proxy)\n- File Upload in Browsers\n- Node.js Specifics (file paths, WebSocket for Node < 22, streaming from file/mic)\n- Untyped API\n- TypeScript Types\n- Error Handling\n- Live Session Event Typing\n- CDN / IIFE Bundle\n- Package Size\n\n## Package Info\n\n- **npm**: [@gladiaio/sdk](https://www.npmjs.com/package/@gladiaio/sdk)\n- **Version**: 2.1.0\n- **Runtime**: Node.js 20+, Bun, browsers\n- **Bundle formats**: ESM, CJS, IIFE (via unpkg/jsdelivr)\n- **Dependencies**: 0 runtime deps\n- **Peer deps**: `ws` (only for Node < 22, which lacks native WebSocket)\n\n## Browser Usage\n\nThe SDK works in browsers out of the box. Use ESM imports or the IIFE bundle:\n\n```html\n<script src=\"https://unpkg.com/@gladiaio/sdk/dist/index.iife.js\"></script>\n<script>\n  const client = new GladiaSDK.GladiaClient({ apiKey: \"...\" });\n</script>\n```\n\n### API Key Security in Browsers\n\nNever expose your API key in client-side code for production. Instead, use a proxy:\n\n```typescript\n// Point the SDK at your backend proxy (no apiKey needed)\nconst client = new GladiaClient({\n  apiUrl: \"https://your-server.com/api/gladia\",\n});\n```\n\nYour backend proxy adds the `x-gladia-key` header before forwarding to `api.gladia.io`.\n\n## File Upload in Browsers\n\nUse `File` or `Blob` objects for uploads:\n\n```typescript\nconst fileInput = document.querySelector('input[type=\"file\"]');\nconst file = fileInput.files[0];\n\nconst result = await client.preRecorded().transcribe(file, {\n  language_config: { languages: [\"en\"] },\n});\n```\n\n## Node.js Specifics\n\n### File path input\n\n```typescript\n// Node: pass a file path string\nconst result = await client\n  .preRecorded()\n  .transcribe(\"./recordings/meeting.wav\", options);\n```\n\n### WebSocket for Node < 22\n\nNode versions before 22 don't have native WebSocket. Install the `ws` package:\n\n```bash\nnpm install ws\n```\n\nThe SDK auto-detects and uses it. Node 22+ uses the built-in `WebSocket` global.\n\n### Streaming audio from a file\n\n```typescript\nimport { createReadStream } from \"fs\";\n\nconst session = client.liveV2().startSession({\n  encoding: \"wav/pcm\",\n  sample_rate: 16000,\n  bit_depth: 16,\n  channels: 1,\n  language_config: { languages: [\"en\"] },\n});\n\nsession.once(\"started\", () => {\n  const stream = createReadStream(\"./audio.pcm\", { highWaterMark: 3200 });\n  stream.on(\"data\", (chunk) => session.sendAudio(chunk));\n  stream.on(\"end\", () => session.stopRecording());\n});\n```\n\n### Streaming from microphone (Node)\n\nUse a library like `node-mic` or `node-record-lpcm16`:\n\n```typescript\nimport mic from \"mic\";\n\nconst micInstance = mic({ rate: 16000, bitwidth: 16, channels: 1 });\nconst micStream = micInstance.getAudioStream();\n\nsession.once(\"started\", () => {\n  micStream.on(\"data\", (chunk) => session.sendAudio(chunk));\n  micInstance.start();\n});\n\n// Stop\nmicInstance.stop();\nsession.stopRecording();\n```\n\n## Untyped API\n\nFor maximum flexibility or when migrating from raw HTTP calls:\n\n```typescript\n// Pass raw JSON matching the API schema\nconst result = await client.preRecorded().createUntyped({\n  audio_url: \"https://example.com/audio.mp3\",\n  diarization: true,\n  custom_field: \"value\",\n});\n\n// Full untyped transcribe flow\nconst result = await client.preRecorded().transcribeUntyped(\"./file.mp3\", {\n  language_config: { languages: [\"en\"] },\n});\n```\n\n## TypeScript Types\n\nAll types are exported from the main package:\n\n```typescript\nimport type {\n  GladiaClientOptions,\n  PreRecordedV2TranscriptionOptions,\n  PreRecordedV2Response,\n  PreRecordedV2InitTranscriptionRequest,\n  LiveV2InitRequest,\n  LiveV2Session,\n  LiveV2WebSocketMessage,\n  LiveV2TranscriptMessage,\n} from \"@gladiaio/sdk\";\n```\n\n## Error Handling\n\nThe JS SDK throws standard `Error` objects. Check the message for HTTP status codes:\n\n```typescript\ntry {\n  await client.preRecorded().transcribe(audio, options);\n} catch (err) {\n  if (err instanceof Error) {\n    if (err.message.includes(\"401\")) {\n      /* auth error */\n    }\n    if (err.message.includes(\"429\")) {\n      /* rate limited */\n    }\n    if (err.message.includes(\"timeout\")) {\n      /* timed out */\n    }\n  }\n}\n```\n\n## Live Session Event Typing\n\n```typescript\nimport type { LiveV2WebSocketMessage } from \"@gladiaio/sdk\";\n\nsession.on(\"message\", (msg: LiveV2WebSocketMessage) => {\n  // msg.type is a discriminated union\n  if (msg.type === \"transcript\") {\n    msg.data.is_final; // boolean\n    msg.data.utterance.text; // string\n  }\n});\n```\n\n## CDN / IIFE Bundle\n\nFor quick prototyping without a bundler:\n\n```html\n<script src=\"https://cdn.jsdelivr.net/npm/@gladiaio/sdk/dist/index.iife.js\"></script>\n```\n\nGlobal namespace: `window.GladiaSDK`\n\n## Package Size\n\n~741 KB unpacked (134 files). Tree-shaking-friendly ESM exports keep bundle size small when using a bundler.\n\nFile v1.0.5:references/python.md\n\n# Python SDK\n\nPatterns and details specific to the `gladiaio-sdk` package.\n\n## Contents\n\n- Package Info\n- Sync vs Async (including async live session)\n- Client Method Aliases\n- Typed Request Objects (dataclass-style and dict alternative)\n- File Input Types\n- Session ID Access\n- Error Types\n- Event Handling (pyee EventEmitter pattern)\n- Streaming Audio from File\n- Streaming from Microphone (PyAudio)\n- Response Access\n- Package Structure (exports)\n\n## Package Info\n\n- **PyPI**: [gladiaio-sdk](https://pypi.org/project/gladiaio-sdk/)\n- **Version**: 2.1.0\n- **Runtime**: Python 3.10+\n- **Dependencies**: httpx, websockets, pyee\n\n## Sync vs Async\n\nThe Python SDK provides both synchronous and asynchronous clients:\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\nclient = GladiaClient(api_key=\"YOUR_KEY\")\n\n# Sync\nresult = client.prerecorded().transcribe(\"audio.mp3\", options)\n\n# Async\nresult = await client.prerecorded_async().transcribe(\"audio.mp3\", options)\n```\n\n### Async live session\n\n```python\nimport asyncio\nfrom gladiaio_sdk import GladiaClient, LiveV2InitRequest, LiveV2LanguageConfig\n\nasync def main():\n    client = GladiaClient(api_key=\"YOUR_KEY\")\n    live_client = client.live_async()\n    session_done = asyncio.Event()\n\n    session = live_client.start_session(\n        LiveV2InitRequest(\n            model=\"solaria-1\",\n            encoding=\"wav/pcm\",\n            sample_rate=16000,\n            bit_depth=16,\n            channels=1,\n            language_config=LiveV2LanguageConfig(languages=[\"en\"]),\n        )\n    )\n\n    @session.once(\"ended\")\n    def on_ended(msg):\n        session_done.set()\n\n    session.send_audio(audio_bytes)\n    session.stop_recording()\n    await session_done.wait()\n\nasyncio.run(main())\n```\n\n## Client Method Aliases\n\n| Primary                      | Aliases                                             |\n| ---------------------------- | --------------------------------------------------- |\n| `client.prerecorded()`       | `client.pre_recorded()`, `client.pre_recorded_v2()` |\n| `client.prerecorded_async()` | `client.pre_recorded_async()`                       |\n| `client.live()`              | `client.live_v2()`                                  |\n| `client.live_async()`        | `client.live_v2_async()`                            |\n\n## Typed Request Objects\n\nPython uses dataclass-style request objects for type safety:\n\n```python\nfrom gladiaio_sdk import (\n    LiveV2InitRequest,\n    LiveV2LanguageConfig,\n    LiveV2MessagesConfig,\n    LiveV2PreProcessing,\n    LiveV2RealtimeProcessing,\n    LiveV2PostProcessing,\n)\n\nrequest = LiveV2InitRequest(\n    model=\"solaria-1\",\n    encoding=\"wav/pcm\",\n    sample_rate=16000,\n    bit_depth=16,\n    channels=1,\n    language_config=LiveV2LanguageConfig(\n        languages=[\"en\", \"fr\"],\n        code_switching=True,\n    ),\n    messages_config=LiveV2MessagesConfig(\n        receive_partial_transcripts=True,\n        receive_speech_events=True,\n    ),\n    pre_processing=LiveV2PreProcessing(\n        audio_enhancer=True,\n    ),\n)\n```\n\n### Dict alternative\n\nYou can also pass plain dicts for pre-recorded options:\n\n```python\nresult = client.prerecorded().transcribe(\n    \"audio.mp3\",\n    {\n        \"language_config\": {\"languages\": [\"en\"]},\n        \"diarization\": True,\n        \"translation\": True,\n        \"translation_config\": {\"target_languages\": [\"fr\"]},\n    },\n)\n```\n\n## File Input Types\n\n```python\nfrom pathlib import Path\n\n# String path\nresult = client.prerecorded().transcribe(\"audio.mp3\", options)\n\n# Path object\nresult = client.prerecorded().transcribe(Path(\"audio.mp3\"), options)\n\n# URL (no upload needed)\nresult = client.prerecorded().transcribe(\"https://example.com/audio.mp3\", options)\n\n# Binary file object\nwith open(\"audio.mp3\", \"rb\") as f:\n    result = client.prerecorded().transcribe(f, options)\n```\n\n## Session ID Access\n\n```python\n# Sync: available after 'started' event fires\n@session.once(\"started\")\ndef on_started(response):\n    print(f\"Session ID: {response.id}\")\n    # Also: session.session_id\n\n# Async: use await\nsession_id = await session.get_session_id()\n```\n\n## Error Types\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\ntry:\n    result = client.prerecorded().transcribe(\"audio.mp3\", options)\nexcept Exception as e:\n    # HttpError for HTTP failures (401, 429, 500, etc.)\n    # TimeoutError for timeout\n    print(f\"Error: {type(e).__name__}: {e}\")\n```\n\n## Event Handling\n\nUses `pyee` (EventEmitter pattern):\n\n```python\nfrom gladiaio_sdk import LiveV2WebSocketMessage, LiveV2InitResponse, LiveV2EndedMessage\n\n@session.on(\"message\")\ndef on_message(message: LiveV2WebSocketMessage):\n    if message.type == \"transcript\":\n        if message.data.is_final:\n            print(f\"Final: {message.data.utterance.text}\")\n\n@session.once(\"started\")\ndef on_started(response: LiveV2InitResponse):\n    print(f\"Session {response.id} started\")\n\n@session.on(\"error\")\ndef on_error(error: Exception):\n    print(f\"Error: {error}\")\n\n@session.once(\"ended\")\ndef on_ended(ended: LiveV2EndedMessage):\n    print(\"Session ended\")\n```\n\n## Streaming Audio from File\n\n```python\nimport time\n\nCHUNK_SIZE = 3200  # 100ms of 16-bit mono at 16kHz\n\nwith open(\"audio.pcm\", \"rb\") as f:\n    while chunk := f.read(CHUNK_SIZE):\n        session.send_audio(chunk)\n        time.sleep(0.1)  # Real-time pacing\n\nsession.stop_recording()\n```\n\n## Streaming from Microphone\n\nUsing PyAudio:\n\n```python\nimport pyaudio\n\nRATE = 16000\nCHUNK = 3200\nFORMAT = pyaudio.paInt16\nCHANNELS = 1\n\np = pyaudio.PyAudio()\nstream = p.open(format=FORMAT, channels=CHANNELS, rate=RATE,\n                input=True, frames_per_buffer=CHUNK)\n\ntry:\n    while True:\n        data = stream.read(CHUNK)\n        session.send_audio(data)\nexcept KeyboardInterrupt:\n    pass\nfinally:\n    stream.stop_stream()\n    stream.close()\n    session.stop_recording()\n```\n\n## Response Access\n\nPre-recorded responses use attribute access:\n\n```python\nresult = client.prerecorded().transcribe(\"audio.mp3\", options)\n\n# Access nested fields\nprint(result.status)                                    # \"done\"\nprint(result.result.transcription.full_transcript)      # Full text\nfor utterance in result.result.transcription.utterances:\n    print(f\"[{utterance.start}-{utterance.end}] {utterance.text}\")\n```\n\n## Package Structure\n\nAll public types are exported from the top-level `gladiaio_sdk` module:\n\n```python\nfrom gladiaio_sdk import (\n    GladiaClient,\n    # Pre-recorded\n    PreRecordedV2Response,\n    # Live\n    LiveV2InitRequest,\n    LiveV2InitResponse,\n    LiveV2EndedMessage,\n    LiveV2WebSocketMessage,\n    LiveV2LanguageConfig,\n    LiveV2MessagesConfig,\n    LiveV2PreProcessing,\n    LiveV2RealtimeProcessing,\n    LiveV2PostProcessing,\n)\n```\n\nFile v1.0.5:references/sdk-versions.md\n\n# SDK Versions\n\n> This file is auto-synced by CI. Do not edit manually — changes will be overwritten.\n\n| SDK | Package | Latest Version | Registry |\n| --- | --- | --- | --- |\n| JavaScript/TypeScript | `@gladiaio/sdk` | 2.1.0 | [npm](https://www.npmjs.com/package/@gladiaio/sdk) |\n| Python | `gladiaio-sdk` | 2.1.0 | [PyPI](https://pypi.org/project/gladiaio-sdk/) |\n\nLast synced: 2026-10-02\n\nAlways install without pinning a version to get the latest release:\n\n```bash\n# JS/TS\nnpm install @gladiaio/sdk\n\n# Python\npip install gladiaio-sdk\n```\n\nFile v1.0.5:skill-card.md\n\n## Description:\n\nGuides developers in installing and configuring Gladia's JavaScript/TypeScript and Python SDKs for speech-to-text integrations.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[gladiaio](https://clawhub.ai/user/gladiaio)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers use this skill to choose, install, and configure Gladia's JavaScript/TypeScript or Python SDK for speech-to-text applications, including browser and live-session integrations.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Exposing Gladia API keys in browser code can compromise credentials.\n\nMitigation: Keep API keys server-side and use a backend proxy for browser integrations.\n\nRisk: Recording or streaming microphone audio may capture sensitive speech without consent.\n\nMitigation: Get consent before recording or streaming audio and handle it as sensitive data.\n\nRisk: Deleting a transcription job or live session removes stored data.\n\nMitigation: Confirm the intended job or session before invoking delete methods.\n\n## Reference(s):\n\n- [Gladia SDK integration guide](https://docs.gladia.io/chapters/integrations/sdk)\n- [Client configuration reference](references/client-config.md)\n- [JavaScript/TypeScript SDK reference](references/javascript.md)\n- [Python SDK reference](references/python.md)\n- [SDK versions](references/sdk-versions.md)\n- [JavaScript SDK package](https://www.npmjs.com/package/@gladiaio/sdk)\n- [Python SDK package](https://pypi.org/project/gladiaio-sdk/)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Code, Shell commands, Configuration instructions]\n\n**Output Format:** [Markdown with code examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [None]\n\n## Skill Version(s):\n\n1.0.5 (source: ClawHub release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.4: 7 files, 11768 bytes\n\nFiles: references/client-config.md (2299b), references/javascript.md (4866b), references/python.md (6658b), references/sdk-versions.md (543b), skill-card.md (2627b), SKILL.md (11715b), _meta.json (141b)\n\nFile v1.0.4:SKILL.md\n\n---\nname: gladia-sdk-integration\ndescription: Install and configure the official Gladia SDKs (@gladiaio/sdk for JS/TS, gladiaio-sdk for Python). Use when the user asks about SDK setup, client initialization, API key configuration, choosing between JS and Python, browser usage, retry/timeout settings, error handling, or SDK vs raw API decisions. The SDK is the recommended default for all Gladia integrations.\nlicense: MIT\n---\n\n# SDK Integration\n\nOfficial SDKs for integrating Gladia's speech-to-text API. Both SDKs share the same design and are generated from the Gladia OpenAPI schema.\n\n> **The SDK is the default for all Gladia integrations.** Always use the SDK unless there is a specific, documented reason not to (see decision guide below).\n\n## When to Use\n\n- User asks about installing, configuring, or initializing the Gladia SDK\n- Setting up API key, region, retry, timeout, or WebSocket configuration\n- Questions about SDK architecture, client methods, or type exports\n- Choosing between JS/TS and Python SDK, or between SDK and raw API\n- Browser-based integration, proxy setup, or bundle format questions\n- Error handling patterns for Gladia API responses\n\n**When NOT to use:** If the user is asking about a specific transcription use case (pre-recorded files or live streaming), start with the relevant use-case skill ([gladia-pre-recorded-transcription](../gladia-pre-recorded-transcription/SKILL.md) or [gladia-live-transcription](../gladia-live-transcription/SKILL.md)) instead — those skills reference back here for setup details.\n\n## When to Use SDK vs Raw API\n\n| Scenario                                 | Approach                                                                                                      |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- |\n| Any JS/TS or Python project              | **SDK** — always                                                                                              |\n| Browser app                              | **SDK** — JS SDK supports ESM/IIFE bundles                                                                    |\n| Need custom HTTP client or middleware    | SDK first; use `httpHeaders` / `httpTimeout` config. Fall back to raw REST only if SDK config is insufficient |\n| Language without an SDK (Go, Java, etc.) | Raw REST/WebSocket (SDK unavailable)                                                                          |\n| User explicitly requests raw calls       | Raw REST/WebSocket                                                                                            |\n| CI script or one-off curl test           | Raw REST is acceptable                                                                                        |\n| Terminal one-off with gladia-cli on PATH | **CLI** — see [gladia-using-cli](../gladia-using-cli/SKILL.md)                                                |\n\nWhen in doubt, use the SDK.\n\n## References\n\nConsult these resources as needed:\n\n- ./references/sdk-versions.md -- Current SDK versions (auto-synced by CI)\n- ./references/client-config.md -- Full client configuration reference (all options, defaults, timeouts)\n- ./references/javascript.md -- JS/TS-specific patterns (browser, proxy, File/Blob, Node requirements)\n- ./references/python.md -- Python-specific patterns (sync/async, typed requests, httpx/websockets)\n- ../gladia-using-cli/SKILL.md -- Terminal transcription with gladia-cli; CLI vs SDK routing\n- ../gladia-pre-recorded-transcription/SKILL.md -- Pre-recorded transcription options, response structure, and audio intelligence config\n- ../gladia-live-transcription/SKILL.md -- Live session config, audio streaming, and WebSocket event handling\n- ../gladia-troubleshooting/SKILL.md -- Common errors, gotchas, and verification checklist\n\n## Installation\n\n### JavaScript / TypeScript\n\n```bash\nnpm install @gladiaio/sdk\n# or\nbun add @gladiaio/sdk\n# or\nyarn add @gladiaio/sdk\n```\n\nRequires Node.js 20+ or Bun. Also works in browsers via ESM/IIFE bundles.\n\n### Python\n\n```bash\npip install gladiaio-sdk\n# or\nuv add gladiaio-sdk\n```\n\nRequires Python 3.10+.\n\n## Client Initialization\n\n### JavaScript/TypeScript\n\n```typescript\nimport { GladiaClient } from \"@gladiaio/sdk\";\n\nconst client = new GladiaClient({\n  apiKey: \"your-api-key\", // or set GLADIA_API_KEY env var\n  region: \"eu-west\", // or set GLADIA_REGION (eu-west | us-west)\n});\n```\n\n### Python\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\nclient = GladiaClient(\n    api_key=\"your-api-key\",      # or set GLADIA_API_KEY env var\n    region=\"eu-west\",            # or set GLADIA_REGION\n)\n```\n\n### Environment Variables\n\n| Variable         | Purpose                    | Default                 |\n| ---------------- | -------------------------- | ----------------------- |\n| `GLADIA_API_KEY` | API key for authentication | —                       |\n| `GLADIA_API_URL` | Base API URL               | `https://api.gladia.io` |\n| `GLADIA_REGION`  | Datacenter region          | —                       |\n\n## Client Architecture\n\n```\nGladiaClient\n├── preRecorded()  → PreRecordedV2Client    (JS)\n│   prerecorded()  → PreRecordedV2Client    (Python)\n│\n├── liveV2()       → LiveV2Client           (JS)\n│   live()         → LiveV2Client           (Python)\n│\n└── (Python only)\n    ├── prerecorded_async() → AsyncPreRecordedV2Client\n    └── live_async()        → AsyncLiveV2Client\n```\n\n### Pre-Recorded Client Methods\n\n| Method                               | Purpose                            |\n| ------------------------------------ | ---------------------------------- |\n| `transcribe(audio, options)`         | High-level: upload + create + poll |\n| `uploadFile(audio)`                  | Upload local file to `/v2/upload`  |\n| `create(options)`                    | Create transcription job           |\n| `createAndPoll(options)`             | Create + poll until done           |\n| `poll(jobId, { interval, timeout })` | Poll until complete                |\n| `get(jobId)`                         | Get job status/results             |\n| `delete(jobId)`                      | Delete job and data                |\n| `getFile(jobId)`                     | Download original audio            |\n\n### Live Client Methods\n\n| Method                  | Purpose                              |\n| ----------------------- | ------------------------------------ |\n| `startSession(options)` | Init session → returns LiveV2Session |\n| `get(sessionId)`        | Get completed session results        |\n| `delete(sessionId)`     | Delete session and data              |\n| `getFile(sessionId)`    | Download session audio               |\n\n### Live Session Methods\n\n| Method             | Purpose                                |\n| ------------------ | -------------------------------------- |\n| `sendAudio(chunk)` | Stream audio bytes to the session      |\n| `stopRecording()`  | End recording, trigger post-processing |\n| `endSession()`     | Force close without post-processing    |\n| `getSessionId()`   | Await session ID (async)               |\n\n## Configuration Options\n\nKey client options: `apiKey`, `apiUrl`, `region`, `httpTimeout`, `httpRetry`, `wsRetry`, `wsTimeout`, `prerecordedTimeouts`, `liveTimeouts`.\n\nFor the full config reference with all options and defaults, see [./references/client-config.md](./references/client-config.md).\n\n## Audio Input Types\n\n| Input                           |   JS/TS   | Python |\n| ------------------------------- | :-------: | :----: |\n| Local file path (string)        | Node only |  Yes   |\n| `Path` object                   |     —     |  Yes   |\n| HTTP(S) URL                     |    Yes    |  Yes   |\n| `File` / `Blob`                 |  Browser  |   —    |\n| Binary file object (`BinaryIO`) |     —     |  Yes   |\n\nURLs are passed directly as `audio_url` without upload. Local files are automatically uploaded via `/v2/upload`.\n\n## Error Handling\n\n### JavaScript/TypeScript\n\n```typescript\ntry {\n  const result = await client.preRecorded().transcribe(\"./audio.mp3\", options);\n} catch (error) {\n  if (error.message.includes(\"401\")) {\n    console.error(\"Invalid API key\");\n  } else if (error.message.includes(\"timeout\")) {\n    console.error(\"Request timed out\");\n  }\n}\n```\n\n### Python\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\ntry:\n    result = client.prerecorded().transcribe(\"audio.mp3\", options)\nexcept Exception as e:\n    print(f\"Error: {e}\")\n```\n\nPython exports `HttpError` and `TimeoutError` for specific error handling.\n\n## Key Differences Between JS and Python\n\n| Aspect          | JavaScript/TypeScript                       | Python                                   |\n| --------------- | ------------------------------------------- | ---------------------------------------- |\n| Async model     | Promise-based (async only)                  | Sync + async (separate clients)          |\n| Naming          | camelCase (`preRecorded`, `sendAudio`)      | snake_case (`prerecorded`, `send_audio`) |\n| Browser support | Yes (ESM, CJS, IIFE)                        | No (server only)                         |\n| Runtime         | Node 20+, Bun, browsers                     | Python 3.10+                             |\n| Dependencies    | 0 runtime deps (optional `ws` for Node <22) | httpx, websockets, pyee                  |\n| Options format  | Plain objects (snake_case keys)             | Dataclasses or dicts                     |\n| Untyped API     | `transcribeUntyped()`, `createUntyped()`    | Dict accepted on most methods            |\n\n## Type Exports\n\nBoth SDKs export all request/response types from the main package:\n\n```typescript\nimport type {\n  LiveV2InitRequest,\n  LiveV2WebSocketMessage,\n  PreRecordedV2Response,\n  PreRecordedV2TranscriptionOptions,\n} from \"@gladiaio/sdk\";\n```\n\n```python\nfrom gladiaio_sdk import (\n    LiveV2InitRequest,\n    LiveV2WebSocketMessage,\n    LiveV2LanguageConfig,\n    LiveV2MessagesConfig,\n    PreRecordedV2Response,\n)\n```\n\n## Common Mistakes\n\n- **Wrong sub-client method name between JS and Python**: JS uses `client.preRecorded()` and `client.liveV2()`; Python uses `client.prerecorded()` and `client.live()`. Mixing the naming conventions causes \"is not a function\" / `AttributeError` at runtime.\n- **Forgetting `await` in JavaScript**: every JS SDK method returns a Promise. Omitting `await` on `transcribe()`, `startSession()`, etc. lets the operation run silently in the background with no result or error surfaced to your code.\n- **API key exposed in browser-side code**: never embed the API key directly in front-end JavaScript — it becomes publicly readable. Use a backend proxy that forwards requests with the key server-side. See [./references/javascript.md](./references/javascript.md) for the proxy pattern.\n- **Node.js < 22 without the `ws` peer dependency**: the JS SDK requires the `ws` package for WebSocket on Node < 22, which lacks a native WebSocket. Without it, live sessions fail silently. Fix: `npm install ws`.\n- **Python async client in sync context**: `client.live_async()` and `client.prerecorded_async()` cannot be called from synchronous code — they require an active event loop. Use the sync client (`client.live()`, `client.prerecorded()`) unless you are inside an `async def`.\n\n## Further Reading\n\n- [SDK integration guide](https://docs.gladia.io/chapters/integrations/sdk)\n- [JS SDK on npm](https://www.npmjs.com/package/@gladiaio/sdk)\n- [Python SDK on PyPI](https://pypi.org/project/gladiaio-sdk/)\n- [SDK source code](https://github.com/gladiaio/sdk)\n- [Code samples](https://github.com/gladiaio/gladia-samples)\n\nFile v1.0.4:_meta.json\n\n{\n  \"ownerId\": \"kn7fs6cmj9hqg7232sbkacf31d882wp2\",\n  \"slug\": \"gladia-sdk-integration\",\n  \"version\": \"1.0.4\",\n  \"publishedAt\": 1785339589751\n}\n\nFile v1.0.4:references/client-config.md\n\n# Full Client Configuration Reference\n\nComplete configuration options for `GladiaClient` constructor.\n\n## Contents\n\n- Full Config Example (JavaScript/TypeScript)\n- Config Summary Table\n\n## Full Config Example\n\n```typescript\nconst client = new GladiaClient({\n  apiKey: \"your-key\",\n  apiUrl: \"https://api.gladia.io\",\n  region: \"eu-west\",\n\n  // HTTP settings\n  httpHeaders: { \"X-Custom-Header\": \"value\" },\n  httpTimeout: 10000, // 10s default\n  httpRetry: {\n    maxRetries: 3,\n    retryDelay: 1000,\n  },\n\n  // WebSocket settings\n  wsRetry: {\n    maxRetries: 5,\n    retryDelay: 1000,\n  },\n  wsTimeout: 30000,\n\n  // Pre-recorded operation timeouts\n  prerecordedTimeouts: {\n    transcribe: 7200000, // 2 hours (full flow)\n    poll: 7200000,\n    upload: 300000, // 5 minutes\n    create: 30000,\n    get: 10000,\n    delete: 10000,\n    getFile: 60000,\n  },\n\n  // Live operation timeouts\n  liveTimeouts: {\n    get: 10000,\n    delete: 10000,\n    getFile: 60000,\n  },\n});\n```\n\n## Config Summary\n\n| Option                  | Type     | Default                 | Description                |\n| ----------------------- | -------- | ----------------------- | -------------------------- |\n| `apiKey`                | `string` | `GLADIA_API_KEY` env    | API key                    |\n| `apiUrl`                | `string` | `https://api.gladia.io` | Base API URL               |\n| `region`                | `string` | `GLADIA_REGION` env     | `eu-west` or `us-west`     |\n| `httpHeaders`           | `object` | `{}`                    | Custom HTTP headers        |\n| `httpTimeout`           | `number` | `10000`                 | HTTP request timeout (ms)  |\n| `httpRetry.maxRetries`  | `number` | `3`                     | Max HTTP retries           |\n| `httpRetry.retryDelay`  | `number` | `1000`                  | Delay between retries (ms) |\n| `wsRetry.maxRetries`    | `number` | `5`                     | Max WebSocket reconnects   |\n| `wsRetry.retryDelay`    | `number` | `1000`                  | WS reconnect delay (ms)    |\n| `wsTimeout`             | `number` | `30000`                 | WebSocket timeout (ms)     |\n| `prerecordedTimeouts.*` | `number` | varies                  | Per-operation timeouts     |\n| `liveTimeouts.*`        | `number` | varies                  | Per-operation timeouts     |\n\nFile v1.0.4:references/javascript.md\n\n# JavaScript / TypeScript SDK\n\nPatterns and details specific to the `@gladiaio/sdk` package.\n\n## Contents\n\n- Package Info\n- Browser Usage (ESM, IIFE, API key security via proxy)\n- File Upload in Browsers\n- Node.js Specifics (file paths, WebSocket for Node < 22, streaming from file/mic)\n- Untyped API\n- TypeScript Types\n- Error Handling\n- Live Session Event Typing\n- CDN / IIFE Bundle\n- Package Size\n\n## Package Info\n\n- **npm**: [@gladiaio/sdk](https://www.npmjs.com/package/@gladiaio/sdk)\n- **Version**: 1.1.0\n- **Runtime**: Node.js 20+, Bun, browsers\n- **Bundle formats**: ESM, CJS, IIFE (via unpkg/jsdelivr)\n- **Dependencies**: 0 runtime deps\n- **Peer deps**: `ws` (only for Node < 22, which lacks native WebSocket)\n\n## Browser Usage\n\nThe SDK works in browsers out of the box. Use ESM imports or the IIFE bundle:\n\n```html\n<script src=\"https://unpkg.com/@gladiaio/sdk/dist/index.iife.js\"></script>\n<script>\n  const client = new GladiaSDK.GladiaClient({ apiKey: \"...\" });\n</script>\n```\n\n### API Key Security in Browsers\n\nNever expose your API key in client-side code for production. Instead, use a proxy:\n\n```typescript\n// Point the SDK at your backend proxy (no apiKey needed)\nconst client = new GladiaClient({\n  apiUrl: \"https://your-server.com/api/gladia\",\n});\n```\n\nYour backend proxy adds the `x-gladia-key` header before forwarding to `api.gladia.io`.\n\n## File Upload in Browsers\n\nUse `File` or `Blob` objects for uploads:\n\n```typescript\nconst fileInput = document.querySelector('input[type=\"file\"]');\nconst file = fileInput.files[0];\n\nconst result = await client.preRecorded().transcribe(file, {\n  language_config: { languages: [\"en\"] },\n});\n```\n\n## Node.js Specifics\n\n### File path input\n\n```typescript\n// Node: pass a file path string\nconst result = await client\n  .preRecorded()\n  .transcribe(\"./recordings/meeting.wav\", options);\n```\n\n### WebSocket for Node < 22\n\nNode versions before 22 don't have native WebSocket. Install the `ws` package:\n\n```bash\nnpm install ws\n```\n\nThe SDK auto-detects and uses it. Node 22+ uses the built-in `WebSocket` global.\n\n### Streaming audio from a file\n\n```typescript\nimport { createReadStream } from \"fs\";\n\nconst session = client.liveV2().startSession({\n  encoding: \"wav/pcm\",\n  sample_rate: 16000,\n  bit_depth: 16,\n  channels: 1,\n  language_config: { languages: [\"en\"] },\n});\n\nsession.once(\"started\", () => {\n  const stream = createReadStream(\"./audio.pcm\", { highWaterMark: 3200 });\n  stream.on(\"data\", (chunk) => session.sendAudio(chunk));\n  stream.on(\"end\", () => session.stopRecording());\n});\n```\n\n### Streaming from microphone (Node)\n\nUse a library like `node-mic` or `node-record-lpcm16`:\n\n```typescript\nimport mic from \"mic\";\n\nconst micInstance = mic({ rate: 16000, bitwidth: 16, channels: 1 });\nconst micStream = micInstance.getAudioStream();\n\nsession.once(\"started\", () => {\n  micStream.on(\"data\", (chunk) => session.sendAudio(chunk));\n  micInstance.start();\n});\n\n// Stop\nmicInstance.stop();\nsession.stopRecording();\n```\n\n## Untyped API\n\nFor maximum flexibility or when migrating from raw HTTP calls:\n\n```typescript\n// Pass raw JSON matching the API schema\nconst result = await client.preRecorded().createUntyped({\n  audio_url: \"https://example.com/audio.mp3\",\n  diarization: true,\n  custom_field: \"value\",\n});\n\n// Full untyped transcribe flow\nconst result = await client.preRecorded().transcribeUntyped(\"./file.mp3\", {\n  language_config: { languages: [\"en\"] },\n});\n```\n\n## TypeScript Types\n\nAll types are exported from the main package:\n\n```typescript\nimport type {\n  GladiaClientOptions,\n  PreRecordedV2TranscriptionOptions,\n  PreRecordedV2Response,\n  PreRecordedV2InitTranscriptionRequest,\n  LiveV2InitRequest,\n  LiveV2Session,\n  LiveV2WebSocketMessage,\n  LiveV2TranscriptMessage,\n} from \"@gladiaio/sdk\";\n```\n\n## Error Handling\n\nThe JS SDK throws standard `Error` objects. Check the message for HTTP status codes:\n\n```typescript\ntry {\n  await client.preRecorded().transcribe(audio, options);\n} catch (err) {\n  if (err instanceof Error) {\n    if (err.message.includes(\"401\")) {\n      /* auth error */\n    }\n    if (err.message.includes(\"429\")) {\n      /* rate limited */\n    }\n    if (err.message.includes(\"timeout\")) {\n      /* timed out */\n    }\n  }\n}\n```\n\n## Live Session Event Typing\n\n```typescript\nimport type { LiveV2WebSocketMessage } from \"@gladiaio/sdk\";\n\nsession.on(\"message\", (msg: LiveV2WebSocketMessage) => {\n  // msg.type is a discriminated union\n  if (msg.type === \"transcript\") {\n    msg.data.is_final; // boolean\n    msg.data.utterance.text; // string\n  }\n});\n```\n\n## CDN / IIFE Bundle\n\nFor quick prototyping without a bundler:\n\n```html\n<script src=\"https://cdn.jsdelivr.net/npm/@gladiaio/sdk/dist/index.iife.js\"></script>\n```\n\nGlobal namespace: `window.GladiaSDK`\n\n## Package Size\n\n~741 KB unpacked (134 files). Tree-shaking-friendly ESM exports keep bundle size small when using a bundler.\n\nFile v1.0.4:references/python.md\n\n# Python SDK\n\nPatterns and details specific to the `gladiaio-sdk` package.\n\n## Contents\n\n- Package Info\n- Sync vs Async (including async live session)\n- Client Method Aliases\n- Typed Request Objects (dataclass-style and dict alternative)\n- File Input Types\n- Session ID Access\n- Error Types\n- Event Handling (pyee EventEmitter pattern)\n- Streaming Audio from File\n- Streaming from Microphone (PyAudio)\n- Response Access\n- Package Structure (exports)\n\n## Package Info\n\n- **PyPI**: [gladiaio-sdk](https://pypi.org/project/gladiaio-sdk/)\n- **Version**: 1.0.5\n- **Runtime**: Python 3.10+\n- **Dependencies**: httpx, websockets, pyee\n\n## Sync vs Async\n\nThe Python SDK provides both synchronous and asynchronous clients:\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\nclient = GladiaClient(api_key=\"YOUR_KEY\")\n\n# Sync\nresult = client.prerecorded().transcribe(\"audio.mp3\", options)\n\n# Async\nresult = await client.prerecorded_async().transcribe(\"audio.mp3\", options)\n```\n\n### Async live session\n\n```python\nimport asyncio\nfrom gladiaio_sdk import GladiaClient, LiveV2InitRequest, LiveV2LanguageConfig\n\nasync def main():\n    client = GladiaClient(api_key=\"YOUR_KEY\")\n    live_client = client.live_async()\n    session_done = asyncio.Event()\n\n    session = live_client.start_session(\n        LiveV2InitRequest(\n            model=\"solaria-1\",\n            encoding=\"wav/pcm\",\n            sample_rate=16000,\n            bit_depth=16,\n            channels=1,\n            language_config=LiveV2LanguageConfig(languages=[\"en\"]),\n        )\n    )\n\n    @session.once(\"ended\")\n    def on_ended(msg):\n        session_done.set()\n\n    session.send_audio(audio_bytes)\n    session.stop_recording()\n    await session_done.wait()\n\nasyncio.run(main())\n```\n\n## Client Method Aliases\n\n| Primary                      | Aliases                                             |\n| ---------------------------- | --------------------------------------------------- |\n| `client.prerecorded()`       | `client.pre_recorded()`, `client.pre_recorded_v2()` |\n| `client.prerecorded_async()` | `client.pre_recorded_async()`                       |\n| `client.live()`              | `client.live_v2()`                                  |\n| `client.live_async()`        | `client.live_v2_async()`                            |\n\n## Typed Request Objects\n\nPython uses dataclass-style request objects for type safety:\n\n```python\nfrom gladiaio_sdk import (\n    LiveV2InitRequest,\n    LiveV2LanguageConfig,\n    LiveV2MessagesConfig,\n    LiveV2PreProcessing,\n    LiveV2RealtimeProcessing,\n    LiveV2PostProcessing,\n)\n\nrequest = LiveV2InitRequest(\n    model=\"solaria-1\",\n    encoding=\"wav/pcm\",\n    sample_rate=16000,\n    bit_depth=16,\n    channels=1,\n    language_config=LiveV2LanguageConfig(\n        languages=[\"en\", \"fr\"],\n        code_switching=True,\n    ),\n    messages_config=LiveV2MessagesConfig(\n        receive_partial_transcripts=True,\n        receive_speech_events=True,\n    ),\n    pre_processing=LiveV2PreProcessing(\n        audio_enhancer=True,\n    ),\n)\n```\n\n### Dict alternative\n\nYou can also pass plain dicts for pre-recorded options:\n\n```python\nresult = client.prerecorded().transcribe(\n    \"audio.mp3\",\n    {\n        \"language_config\": {\"languages\": [\"en\"]},\n        \"diarization\": True,\n        \"translation\": True,\n        \"translation_config\": {\"target_languages\": [\"fr\"]},\n    },\n)\n```\n\n## File Input Types\n\n```python\nfrom pathlib import Path\n\n# String path\nresult = client.prerecorded().transcribe(\"audio.mp3\", options)\n\n# Path object\nresult = client.prerecorded().transcribe(Path(\"audio.mp3\"), options)\n\n# URL (no upload needed)\nresult = client.prerecorded().transcribe(\"https://example.com/audio.mp3\", options)\n\n# Binary file object\nwith open(\"audio.mp3\", \"rb\") as f:\n    result = client.prerecorded().transcribe(f, options)\n```\n\n## Session ID Access\n\n```python\n# Sync: available after 'started' event fires\n@session.once(\"started\")\ndef on_started(response):\n    print(f\"Session ID: {response.id}\")\n    # Also: session.session_id\n\n# Async: use await\nsession_id = await session.get_session_id()\n```\n\n## Error Types\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\ntry:\n    result = client.prerecorded().transcribe(\"audio.mp3\", options)\nexcept Exception as e:\n    # HttpError for HTTP failures (401, 429, 500, etc.)\n    # TimeoutError for timeout\n    print(f\"Error: {type(e).__name__}: {e}\")\n```\n\n## Event Handling\n\nUses `pyee` (EventEmitter pattern):\n\n```python\nfrom gladiaio_sdk import LiveV2WebSocketMessage, LiveV2InitResponse, LiveV2EndedMessage\n\n@session.on(\"message\")\ndef on_message(message: LiveV2WebSocketMessage):\n    if message.type == \"transcript\":\n        if message.data.is_final:\n            print(f\"Final: {message.data.utterance.text}\")\n\n@session.once(\"started\")\ndef on_started(response: LiveV2InitResponse):\n    print(f\"Session {response.id} started\")\n\n@session.on(\"error\")\ndef on_error(error: Exception):\n    print(f\"Error: {error}\")\n\n@session.once(\"ended\")\ndef on_ended(ended: LiveV2EndedMessage):\n    print(\"Session ended\")\n```\n\n## Streaming Audio from File\n\n```python\nimport time\n\nCHUNK_SIZE = 3200  # 100ms of 16-bit mono at 16kHz\n\nwith open(\"audio.pcm\", \"rb\") as f:\n    while chunk := f.read(CHUNK_SIZE):\n        session.send_audio(chunk)\n        time.sleep(0.1)  # Real-time pacing\n\nsession.stop_recording()\n```\n\n## Streaming from Microphone\n\nUsing PyAudio:\n\n```python\nimport pyaudio\n\nRATE = 16000\nCHUNK = 3200\nFORMAT = pyaudio.paInt16\nCHANNELS = 1\n\np = pyaudio.PyAudio()\nstream = p.open(format=FORMAT, channels=CHANNELS, rate=RATE,\n                input=True, frames_per_buffer=CHUNK)\n\ntry:\n    while True:\n        data = stream.read(CHUNK)\n        session.send_audio(data)\nexcept KeyboardInterrupt:\n    pass\nfinally:\n    stream.stop_stream()\n    stream.close()\n    session.stop_recording()\n```\n\n## Response Access\n\nPre-recorded responses use attribute access:\n\n```python\nresult = client.prerecorded().transcribe(\"audio.mp3\", options)\n\n# Access nested fields\nprint(result.status)                                    # \"done\"\nprint(result.result.transcription.full_transcript)      # Full text\nfor utterance in result.result.transcription.utterances:\n    print(f\"[{utterance.start}-{utterance.end}] {utterance.text}\")\n```\n\n## Package Structure\n\nAll public types are exported from the top-level `gladiaio_sdk` module:\n\n```python\nfrom gladiaio_sdk import (\n    GladiaClient,\n    # Pre-recorded\n    PreRecordedV2Response,\n    # Live\n    LiveV2InitRequest,\n    LiveV2InitResponse,\n    LiveV2EndedMessage,\n    LiveV2WebSocketMessage,\n    LiveV2LanguageConfig,\n    LiveV2MessagesConfig,\n    LiveV2PreProcessing,\n    LiveV2RealtimeProcessing,\n    LiveV2PostProcessing,\n)\n```\n\nFile v1.0.4:references/sdk-versions.md\n\n# SDK Versions\n\n> This file is auto-synced by CI. Do not edit manually — changes will be overwritten.\n\n| SDK | Package | Latest Version | Registry |\n| --- | --- | --- | --- |\n| JavaScript/TypeScript | `@gladiaio/sdk` | 1.1.0 | [npm](https://www.npmjs.com/package/@gladiaio/sdk) |\n| Python | `gladiaio-sdk` | 1.0.5 | [PyPI](https://pypi.org/project/gladiaio-sdk/) |\n\nLast synced: 2026-07-29\n\nAlways install without pinning a version to get the latest release:\n\n```bash\n# JS/TS\nnpm install @gladiaio/sdk\n\n# Python\npip install gladiaio-sdk\n```\n\nFile v1.0.4:skill-card.md\n\n## Description:\n\nHelps agents install, configure, and use the official Gladia JS/TS and Python SDKs for speech-to-text integrations.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[gladiaio](https://clawhub.ai/user/gladiaio)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and integration engineers use this skill to set up Gladia SDK clients, choose JS/TS or Python patterns, configure API keys and regions, and handle SDK-specific runtime concerns.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Unpinned package and CDN examples can pull changed SDK code into production without review.\n\nMitigation: Pin SDK versions, use lockfiles or reviewed requirements, and avoid unversioned CDN scripts in production.\n\nRisk: Browser examples can expose Gladia API keys if copied directly into client-side code.\n\nMitigation: Keep Gladia API keys on a backend and route browser calls through a proxy that adds credentials server-side.\n\nRisk: Live microphone streaming examples can capture audio without sufficient user awareness or consent.\n\nMitigation: Add explicit consent, visible recording controls, and clear stop behavior before enabling microphone streaming.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/gladiaio/skills/gladia-sdk-integration)\n- [Full Client Configuration Reference](artifact/references/client-config.md)\n- [JavaScript / TypeScript SDK](artifact/references/javascript.md)\n- [Python SDK](artifact/references/python.md)\n- [SDK Versions](artifact/references/sdk-versions.md)\n- [SDK integration guide](https://docs.gladia.io/chapters/integrations/sdk)\n- [JS SDK on npm](https://www.npmjs.com/package/@gladiaio/sdk)\n- [Python SDK on PyPI](https://pypi.org/project/gladiaio-sdk/)\n- [SDK source code](https://github.com/gladiaio/sdk)\n- [Code samples](https://github.com/gladiaio/gladia-samples)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell, TypeScript, Python, and configuration snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include SDK install commands, client initialization examples, runtime notes, and security guidance for API key handling.]\n\n## Skill Version(s):\n\n1.0.4 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.3: 7 files, 11763 bytes\n\nFiles: references/client-config.md (2299b), references/javascript.md (4866b), references/python.md (6658b), references/sdk-versions.md (543b), skill-card.md (2831b), SKILL.md (11715b), _meta.json (141b)\n\nFile v1.0.3:SKILL.md\n\n---\nname: gladia-sdk-integration\ndescription: Install and configure the official Gladia SDKs (@gladiaio/sdk for JS/TS, gladiaio-sdk for Python). Use when the user asks about SDK setup, client initialization, API key configuration, choosing between JS and Python, browser usage, retry/timeout settings, error handling, or SDK vs raw API decisions. The SDK is the recommended default for all Gladia integrations.\nlicense: MIT\n---\n\n# SDK Integration\n\nOfficial SDKs for integrating Gladia's speech-to-text API. Both SDKs share the same design and are generated from the Gladia OpenAPI schema.\n\n> **The SDK is the default for all Gladia integrations.** Always use the SDK unless there is a specific, documented reason not to (see decision guide below).\n\n## When to Use\n\n- User asks about installing, configuring, or initializing the Gladia SDK\n- Setting up API key, region, retry, timeout, or WebSocket configuration\n- Questions about SDK architecture, client methods, or type exports\n- Choosing between JS/TS and Python SDK, or between SDK and raw API\n- Browser-based integration, proxy setup, or bundle format questions\n- Error handling patterns for Gladia API responses\n\n**When NOT to use:** If the user is asking about a specific transcription use case (pre-recorded files or live streaming), start with the relevant use-case skill ([gladia-pre-recorded-transcription](../gladia-pre-recorded-transcription/SKILL.md) or [gladia-live-transcription](../gladia-live-transcription/SKILL.md)) instead — those skills reference back here for setup details.\n\n## When to Use SDK vs Raw API\n\n| Scenario                                 | Approach                                                                                                      |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- |\n| Any JS/TS or Python project              | **SDK** — always                                                                                              |\n| Browser app                              | **SDK** — JS SDK supports ESM/IIFE bundles                                                                    |\n| Need custom HTTP client or middleware    | SDK first; use `httpHeaders` / `httpTimeout` config. Fall back to raw REST only if SDK config is insufficient |\n| Language without an SDK (Go, Java, etc.) | Raw REST/WebSocket (SDK unavailable)                                                                          |\n| User explicitly requests raw calls       | Raw REST/WebSocket                                                                                            |\n| CI script or one-off curl test           | Raw REST is acceptable                                                                                        |\n| Terminal one-off with gladia-cli on PATH | **CLI** — see [gladia-using-cli](../gladia-using-cli/SKILL.md)                                                |\n\nWhen in doubt, use the SDK.\n\n## References\n\nConsult these resources as needed:\n\n- ./references/sdk-versions.md -- Current SDK versions (auto-synced by CI)\n- ./references/client-config.md -- Full client configuration reference (all options, defaults, timeouts)\n- ./references/javascript.md -- JS/TS-specific patterns (browser, proxy, File/Blob, Node requirements)\n- ./references/python.md -- Python-specific patterns (sync/async, typed requests, httpx/websockets)\n- ../gladia-using-cli/SKILL.md -- Terminal transcription with gladia-cli; CLI vs SDK routing\n- ../gladia-pre-recorded-transcription/SKILL.md -- Pre-recorded transcription options, response structure, and audio intelligence config\n- ../gladia-live-transcription/SKILL.md -- Live session config, audio streaming, and WebSocket event handling\n- ../gladia-troubleshooting/SKILL.md -- Common errors, gotchas, and verification checklist\n\n## Installation\n\n### JavaScript / TypeScript\n\n```bash\nnpm install @gladiaio/sdk\n# or\nbun add @gladiaio/sdk\n# or\nyarn add @gladiaio/sdk\n```\n\nRequires Node.js 20+ or Bun. Also works in browsers via ESM/IIFE bundles.\n\n### Python\n\n```bash\npip install gladiaio-sdk\n# or\nuv add gladiaio-sdk\n```\n\nRequires Python 3.10+.\n\n## Client Initialization\n\n### JavaScript/TypeScript\n\n```typescript\nimport { GladiaClient } from \"@gladiaio/sdk\";\n\nconst client = new GladiaClient({\n  apiKey: \"your-api-key\", // or set GLADIA_API_KEY env var\n  region: \"eu-west\", // or set GLADIA_REGION (eu-west | us-west)\n});\n```\n\n### Python\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\nclient = GladiaClient(\n    api_key=\"your-api-key\",      # or set GLADIA_API_KEY env var\n    region=\"eu-west\",            # or set GLADIA_REGION\n)\n```\n\n### Environment Variables\n\n| Variable         | Purpose                    | Default                 |\n| ---------------- | -------------------------- | ----------------------- |\n| `GLADIA_API_KEY` | API key for authentication | —                       |\n| `GLADIA_API_URL` | Base API URL               | `https://api.gladia.io` |\n| `GLADIA_REGION`  | Datacenter region          | —                       |\n\n## Client Architecture\n\n```\nGladiaClient\n├── preRecorded()  → PreRecordedV2Client    (JS)\n│   prerecorded()  → PreRecordedV2Client    (Python)\n│\n├── liveV2()       → LiveV2Client           (JS)\n│   live()         → LiveV2Client           (Python)\n│\n└── (Python only)\n    ├── prerecorded_async() → AsyncPreRecordedV2Client\n    └── live_async()        → AsyncLiveV2Client\n```\n\n### Pre-Recorded Client Methods\n\n| Method                               | Purpose                            |\n| ------------------------------------ | ---------------------------------- |\n| `transcribe(audio, options)`         | High-level: upload + create + poll |\n| `uploadFile(audio)`                  | Upload local file to `/v2/upload`  |\n| `create(options)`                    | Create transcription job           |\n| `createAndPoll(options)`             | Create + poll until done           |\n| `poll(jobId, { interval, timeout })` | Poll until complete                |\n| `get(jobId)`                         | Get job status/results             |\n| `delete(jobId)`                      | Delete job and data                |\n| `getFile(jobId)`                     | Download original audio            |\n\n### Live Client Methods\n\n| Method                  | Purpose                              |\n| ----------------------- | ------------------------------------ |\n| `startSession(options)` | Init session → returns LiveV2Session |\n| `get(sessionId)`        | Get completed session results        |\n| `delete(sessionId)`     | Delete session and data              |\n| `getFile(sessionId)`    | Download session audio               |\n\n### Live Session Methods\n\n| Method             | Purpose                                |\n| ------------------ | -------------------------------------- |\n| `sendAudio(chunk)` | Stream audio bytes to the session      |\n| `stopRecording()`  | End recording, trigger post-processing |\n| `endSession()`     | Force close without post-processing    |\n| `getSessionId()`   | Await session ID (async)               |\n\n## Configuration Options\n\nKey client options: `apiKey`, `apiUrl`, `region`, `httpTimeout`, `httpRetry`, `wsRetry`, `wsTimeout`, `prerecordedTimeouts`, `liveTimeouts`.\n\nFor the full config reference with all options and defaults, see [./references/client-config.md](./references/client-config.md).\n\n## Audio Input Types\n\n| Input                           |   JS/TS   | Python |\n| ------------------------------- | :-------: | :----: |\n| Local file path (string)        | Node only |  Yes   |\n| `Path` object                   |     —     |  Yes   |\n| HTTP(S) URL                     |    Yes    |  Yes   |\n| `File` / `Blob`                 |  Browser  |   —    |\n| Binary file object (`BinaryIO`) |     —     |  Yes   |\n\nURLs are passed directly as `audio_url` without upload. Local files are automatically uploaded via `/v2/upload`.\n\n## Error Handling\n\n### JavaScript/TypeScript\n\n```typescript\ntry {\n  const result = await client.preRecorded().transcribe(\"./audio.mp3\", options);\n} catch (error) {\n  if (error.message.includes(\"401\")) {\n    console.error(\"Invalid API key\");\n  } else if (error.message.includes(\"timeout\")) {\n    console.error(\"Request timed out\");\n  }\n}\n```\n\n### Python\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\ntry:\n    result = client.prerecorded().transcribe(\"audio.mp3\", options)\nexcept Exception as e:\n    print(f\"Error: {e}\")\n```\n\nPython exports `HttpError` and `TimeoutError` for specific error handling.\n\n## Key Differences Between JS and Python\n\n| Aspect          | JavaScript/TypeScript                       | Python                                   |\n| --------------- | ------------------------------------------- | ---------------------------------------- |\n| Async model     | Promise-based (async only)                  | Sync + async (separate clients)          |\n| Naming          | camelCase (`preRecorded`, `sendAudio`)      | snake_case (`prerecorded`, `send_audio`) |\n| Browser support | Yes (ESM, CJS, IIFE)                        | No (server only)                         |\n| Runtime         | Node 20+, Bun, browsers                     | Python 3.10+                             |\n| Dependencies    | 0 runtime deps (optional `ws` for Node <22) | httpx, websockets, pyee                  |\n| Options format  | Plain objects (snake_case keys)             | Dataclasses or dicts                     |\n| Untyped API     | `transcribeUntyped()`, `createUntyped()`    | Dict accepted on most methods            |\n\n## Type Exports\n\nBoth SDKs export all request/response types from the main package:\n\n```typescript\nimport type {\n  LiveV2InitRequest,\n  LiveV2WebSocketMessage,\n  PreRecordedV2Response,\n  PreRecordedV2TranscriptionOptions,\n} from \"@gladiaio/sdk\";\n```\n\n```python\nfrom gladiaio_sdk import (\n    LiveV2InitRequest,\n    LiveV2WebSocketMessage,\n    LiveV2LanguageConfig,\n    LiveV2MessagesConfig,\n    PreRecordedV2Response,\n)\n```\n\n## Common Mistakes\n\n- **Wrong sub-client method name between JS and Python**: JS uses `client.preRecorded()` and `client.liveV2()`; Python uses `client.prerecorded()` and `client.live()`. Mixing the naming conventions causes \"is not a function\" / `AttributeError` at runtime.\n- **Forgetting `await` in JavaScript**: every JS SDK method returns a Promise. Omitting `await` on `transcribe()`, `startSession()`, etc. lets the operation run silently in the background with no result or error surfaced to your code.\n- **API key exposed in browser-side code**: never embed the API key directly in front-end JavaScript — it becomes publicly readable. Use a backend proxy that forwards requests with the key server-side. See [./references/javascript.md](./references/javascript.md) for the proxy pattern.\n- **Node.js < 22 without the `ws` peer dependency**: the JS SDK requires the `ws` package for WebSocket on Node < 22, which lacks a native WebSocket. Without it, live sessions fail silently. Fix: `npm install ws`.\n- **Python async client in sync context**: `client.live_async()` and `client.prerecorded_async()` cannot be called from synchronous code — they require an active event loop. Use the sync client (`client.live()`, `client.prerecorded()`) unless you are inside an `async def`.\n\n## Further Reading\n\n- [SDK integration guide](https://docs.gladia.io/chapters/integrations/sdk)\n- [JS SDK on npm](https://www.npmjs.com/package/@gladiaio/sdk)\n- [Python SDK on PyPI](https://pypi.org/project/gladiaio-sdk/)\n- [SDK source code](https://github.com/gladiaio/sdk)\n- [Code samples](https://github.com/gladiaio/gladia-samples)\n\nFile v1.0.3:_meta.json\n\n{\n  \"ownerId\": \"kn7fs6cmj9hqg7232sbkacf31d882wp2\",\n  \"slug\": \"gladia-sdk-integration\",\n  \"version\": \"1.0.3\",\n  \"publishedAt\": 1783609876290\n}\n\nFile v1.0.3:references/client-config.md\n\n# Full Client Configuration Reference\n\nComplete configuration options for `GladiaClient` constructor.\n\n## Contents\n\n- Full Config Example (JavaScript/TypeScript)\n- Config Summary Table\n\n## Full Config Example\n\n```typescript\nconst client = new GladiaClient({\n  apiKey: \"your-key\",\n  apiUrl: \"https://api.gladia.io\",\n  region: \"eu-west\",\n\n  // HTTP settings\n  httpHeaders: { \"X-Custom-Header\": \"value\" },\n  httpTimeout: 10000, // 10s default\n  httpRetry: {\n    maxRetries: 3,\n    retryDelay: 1000,\n  },\n\n  // WebSocket settings\n  wsRetry: {\n    maxRetries: 5,\n    retryDelay: 1000,\n  },\n  wsTimeout: 30000,\n\n  // Pre-recorded operation timeouts\n  prerecordedTimeouts: {\n    transcribe: 7200000, // 2 hours (full flow)\n    poll: 7200000,\n    upload: 300000, // 5 minutes\n    create: 30000,\n    get: 10000,\n    delete: 10000,\n    getFile: 60000,\n  },\n\n  // Live operation timeouts\n  liveTimeouts: {\n    get: 10000,\n    delete: 10000,\n    getFile: 60000,\n  },\n});\n```\n\n## Config Summary\n\n| Option                  | Type     | Default                 | Description                |\n| ----------------------- | -------- | ----------------------- | -------------------------- |\n| `apiKey`                | `string` | `GLADIA_API_KEY` env    | API key                    |\n| `apiUrl`                | `string` | `https://api.gladia.io` | Base API URL               |\n| `region`                | `string` | `GLADIA_REGION` env     | `eu-west` or `us-west`     |\n| `httpHeaders`           | `object` | `{}`                    | Custom HTTP headers        |\n| `httpTimeout`           | `number` | `10000`                 | HTTP request timeout (ms)  |\n| `httpRetry.maxRetries`  | `number` | `3`                     | Max HTTP retries           |\n| `httpRetry.retryDelay`  | `number` | `1000`                  | Delay between retries (ms) |\n| `wsRetry.maxRetries`    | `number` | `5`                     | Max WebSocket reconnects   |\n| `wsRetry.retryDelay`    | `number` | `1000`                  | WS reconnect delay (ms)    |\n| `wsTimeout`             | `number` | `30000`                 | WebSocket timeout (ms)     |\n| `prerecordedTimeouts.*` | `number` | varies                  | Per-operation timeouts     |\n| `liveTimeouts.*`        | `number` | varies                  | Per-operation timeouts     |\n\nFile v1.0.3:references/javascript.md\n\n# JavaScript / TypeScript SDK\n\nPatterns and details specific to the `@gladiaio/sdk` package.\n\n## Contents\n\n- Package Info\n- Browser Usage (ESM, IIFE, API key security via proxy)\n- File Upload in Browsers\n- Node.js Specifics (file paths, WebSocket for Node < 22, streaming from file/mic)\n- Untyped API\n- TypeScript Types\n- Error Handling\n- Live Session Event Typing\n- CDN / IIFE Bundle\n- Package Size\n\n## Package Info\n\n- **npm**: [@gladiaio/sdk](https://www.npmjs.com/package/@gladiaio/sdk)\n- **Version**: 1.0.7\n- **Runtime**: Node.js 20+, Bun, browsers\n- **Bundle formats**: ESM, CJS, IIFE (via unpkg/jsdelivr)\n- **Dependencies**: 0 runtime deps\n- **Peer deps**: `ws` (only for Node < 22, which lacks native WebSocket)\n\n## Browser Usage\n\nThe SDK works in browsers out of the box. Use ESM imports or the IIFE bundle:\n\n```html\n<script src=\"https://unpkg.com/@gladiaio/sdk/dist/index.iife.js\"></script>\n<script>\n  const client = new GladiaSDK.GladiaClient({ apiKey: \"...\" });\n</script>\n```\n\n### API Key Security in Browsers\n\nNever expose your API key in client-side code for production. Instead, use a proxy:\n\n```typescript\n// Point the SDK at your backend proxy (no apiKey needed)\nconst client = new GladiaClient({\n  apiUrl: \"https://your-server.com/api/gladia\",\n});\n```\n\nYour backend proxy adds the `x-gladia-key` header before forwarding to `api.gladia.io`.\n\n## File Upload in Browsers\n\nUse `File` or `Blob` objects for uploads:\n\n```typescript\nconst fileInput = document.querySelector('input[type=\"file\"]');\nconst file = fileInput.files[0];\n\nconst result = await client.preRecorded().transcribe(file, {\n  language_config: { languages: [\"en\"] },\n});\n```\n\n## Node.js Specifics\n\n### File path input\n\n```typescript\n// Node: pass a file path string\nconst result = await client\n  .preRecorded()\n  .transcribe(\"./recordings/meeting.wav\", options);\n```\n\n### WebSocket for Node < 22\n\nNode versions before 22 don't have native WebSocket. Install the `ws` package:\n\n```bash\nnpm install ws\n```\n\nThe SDK auto-detects and uses it. Node 22+ uses the built-in `WebSocket` global.\n\n### Streaming audio from a file\n\n```typescript\nimport { createReadStream } from \"fs\";\n\nconst session = client.liveV2().startSession({\n  encoding: \"wav/pcm\",\n  sample_rate: 16000,\n  bit_depth: 16,\n  channels: 1,\n  language_config: { languages: [\"en\"] },\n});\n\nsession.once(\"started\", () => {\n  const stream = createReadStream(\"./audio.pcm\", { highWaterMark: 3200 });\n  stream.on(\"data\", (chunk) => session.sendAudio(chunk));\n  stream.on(\"end\", () => session.stopRecording());\n});\n```\n\n### Streaming from microphone (Node)\n\nUse a library like `node-mic` or `node-record-lpcm16`:\n\n```typescript\nimport mic from \"mic\";\n\nconst micInstance = mic({ rate: 16000, bitwidth: 16, channels: 1 });\nconst micStream = micInstance.getAudioStream();\n\nsession.once(\"started\", () => {\n  micStream.on(\"data\", (chunk) => session.sendAudio(chunk));\n  micInstance.start();\n});\n\n// Stop\nmicInstance.stop();\nsession.stopRecording();\n```\n\n## Untyped API\n\nFor maximum flexibility or when migrating from raw HTTP calls:\n\n```typescript\n// Pass raw JSON matching the API schema\nconst result = await client.preRecorded().createUntyped({\n  audio_url: \"https://example.com/audio.mp3\",\n  diarization: true,\n  custom_field: \"value\",\n});\n\n// Full untyped transcribe flow\nconst result = await client.preRecorded().transcribeUntyped(\"./file.mp3\", {\n  language_config: { languages: [\"en\"] },\n});\n```\n\n## TypeScript Types\n\nAll types are exported from the main package:\n\n```typescript\nimport type {\n  GladiaClientOptions,\n  PreRecordedV2TranscriptionOptions,\n  PreRecordedV2Response,\n  PreRecordedV2InitTranscriptionRequest,\n  LiveV2InitRequest,\n  LiveV2Session,\n  LiveV2WebSocketMessage,\n  LiveV2TranscriptMessage,\n} from \"@gladiaio/sdk\";\n```\n\n## Error Handling\n\nThe JS SDK throws standard `Error` objects. Check the message for HTTP status codes:\n\n```typescript\ntry {\n  await client.preRecorded().transcribe(audio, options);\n} catch (err) {\n  if (err instanceof Error) {\n    if (err.message.includes(\"401\")) {\n      /* auth error */\n    }\n    if (err.message.includes(\"429\")) {\n      /* rate limited */\n    }\n    if (err.message.includes(\"timeout\")) {\n      /* timed out */\n    }\n  }\n}\n```\n\n## Live Session Event Typing\n\n```typescript\nimport type { LiveV2WebSocketMessage } from \"@gladiaio/sdk\";\n\nsession.on(\"message\", (msg: LiveV2WebSocketMessage) => {\n  // msg.type is a discriminated union\n  if (msg.type === \"transcript\") {\n    msg.data.is_final; // boolean\n    msg.data.utterance.text; // string\n  }\n});\n```\n\n## CDN / IIFE Bundle\n\nFor quick prototyping without a bundler:\n\n```html\n<script src=\"https://cdn.jsdelivr.net/npm/@gladiaio/sdk/dist/index.iife.js\"></script>\n```\n\nGlobal namespace: `window.GladiaSDK`\n\n## Package Size\n\n~741 KB unpacked (134 files). Tree-shaking-friendly ESM exports keep bundle size small when using a bundler.\n\nFile v1.0.3:references/python.md\n\n# Python SDK\n\nPatterns and details specific to the `gladiaio-sdk` package.\n\n## Contents\n\n- Package Info\n- Sync vs Async (including async live session)\n- Client Method Aliases\n- Typed Request Objects (dataclass-style and dict alternative)\n- File Input Types\n- Session ID Access\n- Error Types\n- Event Handling (pyee EventEmitter pattern)\n- Streaming Audio from File\n- Streaming from Microphone (PyAudio)\n- Response Access\n- Package Structure (exports)\n\n## Package Info\n\n- **PyPI**: [gladiaio-sdk](https://pypi.org/project/gladiaio-sdk/)\n- **Version**: 1.0.4\n- **Runtime**: Python 3.10+\n- **Dependencies**: httpx, websockets, pyee\n\n## Sync vs Async\n\nThe Python SDK provides both synchronous and asynchronous clients:\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\nclient = GladiaClient(api_key=\"YOUR_KEY\")\n\n# Sync\nresult = client.prerecorded().transcribe(\"audio.mp3\", options)\n\n# Async\nresult = await client.prerecorded_async().transcribe(\"audio.mp3\", options)\n```\n\n### Async live session\n\n```python\nimport asyncio\nfrom gladiaio_sdk import GladiaClient, LiveV2InitRequest, LiveV2LanguageConfig\n\nasync def main():\n    client = GladiaClient(api_key=\"YOUR_KEY\")\n    live_client = client.live_async()\n    session_done = asyncio.Event()\n\n    session = live_client.start_session(\n        LiveV2InitRequest(\n            model=\"solaria-1\",\n            encoding=\"wav/pcm\",\n            sample_rate=16000,\n            bit_depth=16,\n            channels=1,\n            language_config=LiveV2LanguageConfig(languages=[\"en\"]),\n        )\n    )\n\n    @session.once(\"ended\")\n    def on_ended(msg):\n        session_done.set()\n\n    session.send_audio(audio_bytes)\n    session.stop_recording()\n    await session_done.wait()\n\nasyncio.run(main())\n```\n\n## Client Method Aliases\n\n| Primary                      | Aliases                                             |\n| ---------------------------- | --------------------------------------------------- |\n| `client.prerecorded()`       | `client.pre_recorded()`, `client.pre_recorded_v2()` |\n| `client.prerecorded_async()` | `client.pre_recorded_async()`                       |\n| `client.live()`              | `client.live_v2()`                                  |\n| `client.live_async()`        | `client.live_v2_async()`                            |\n\n## Typed Request Objects\n\nPython uses dataclass-style request objects for type safety:\n\n```python\nfrom gladiaio_sdk import (\n    LiveV2InitRequest,\n    LiveV2LanguageConfig,\n    LiveV2MessagesConfig,\n    LiveV2PreProcessing,\n    LiveV2RealtimeProcessing,\n    LiveV2PostProcessing,\n)\n\nrequest = LiveV2InitRequest(\n    model=\"solaria-1\",\n    encoding=\"wav/pcm\",\n    sample_rate=16000,\n    bit_depth=16,\n    channels=1,\n    language_config=LiveV2LanguageConfig(\n        languages=[\"en\", \"fr\"],\n        code_switching=True,\n    ),\n    messages_config=LiveV2MessagesConfig(\n        receive_partial_transcripts=True,\n        receive_speech_events=True,\n    ),\n    pre_processing=LiveV2PreProcessing(\n        audio_enhancer=True,\n    ),\n)\n```\n\n### Dict alternative\n\nYou can also pass plain dicts for pre-recorded options:\n\n```python\nresult = client.prerecorded().transcribe(\n    \"audio.mp3\",\n    {\n        \"language_config\": {\"languages\": [\"en\"]},\n        \"diarization\": True,\n        \"translation\": True,\n        \"translation_config\": {\"target_languages\": [\"fr\"]},\n    },\n)\n```\n\n## File Input Types\n\n```python\nfrom pathlib import Path\n\n# String path\nresult = client.prerecorded().transcribe(\"audio.mp3\", options)\n\n# Path object\nresult = client.prerecorded().transcribe(Path(\"audio.mp3\"), options)\n\n# URL (no upload needed)\nresult = client.prerecorded().transcribe(\"https://example.com/audio.mp3\", options)\n\n# Binary file object\nwith open(\"audio.mp3\", \"rb\") as f:\n    result = client.prerecorded().transcribe(f, options)\n```\n\n## Session ID Access\n\n```python\n# Sync: available after 'started' event fires\n@session.once(\"started\")\ndef on_started(response):\n    print(f\"Session ID: {response.id}\")\n    # Also: session.session_id\n\n# Async: use await\nsession_id = await session.get_session_id()\n```\n\n## Error Types\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\ntry:\n    result = client.prerecorded().transcribe(\"audio.mp3\", options)\nexcept Exception as e:\n    # HttpError for HTTP failures (401, 429, 500, etc.)\n    # TimeoutError for timeout\n    print(f\"Error: {type(e).__name__}: {e}\")\n```\n\n## Event Handling\n\nUses `pyee` (EventEmitter pattern):\n\n```python\nfrom gladiaio_sdk import LiveV2WebSocketMessage, LiveV2InitResponse, LiveV2EndedMessage\n\n@session.on(\"message\")\ndef on_message(message: LiveV2WebSocketMessage):\n    if message.type == \"transcript\":\n        if message.data.is_final:\n            print(f\"Final: {message.data.utterance.text}\")\n\n@session.once(\"started\")\ndef on_started(response: LiveV2InitResponse):\n    print(f\"Session {response.id} started\")\n\n@session.on(\"error\")\ndef on_error(error: Exception):\n    print(f\"Error: {error}\")\n\n@session.once(\"ended\")\ndef on_ended(ended: LiveV2EndedMessage):\n    print(\"Session ended\")\n```\n\n## Streaming Audio from File\n\n```python\nimport time\n\nCHUNK_SIZE = 3200  # 100ms of 16-bit mono at 16kHz\n\nwith open(\"audio.pcm\", \"rb\") as f:\n    while chunk := f.read(CHUNK_SIZE):\n        session.send_audio(chunk)\n        time.sleep(0.1)  # Real-time pacing\n\nsession.stop_recording()\n```\n\n## Streaming from Microphone\n\nUsing PyAudio:\n\n```python\nimport pyaudio\n\nRATE = 16000\nCHUNK = 3200\nFORMAT = pyaudio.paInt16\nCHANNELS = 1\n\np = pyaudio.PyAudio()\nstream = p.open(format=FORMAT, channels=CHANNELS, rate=RATE,\n                input=True, frames_per_buffer=CHUNK)\n\ntry:\n    while True:\n        data = stream.read(CHUNK)\n        session.send_audio(data)\nexcept KeyboardInterrupt:\n    pass\nfinally:\n    stream.stop_stream()\n    stream.close()\n    session.stop_recording()\n```\n\n## Response Access\n\nPre-recorded responses use attribute access:\n\n```python\nresult = client.prerecorded().transcribe(\"audio.mp3\", options)\n\n# Access nested fields\nprint(result.status)                                    # \"done\"\nprint(result.result.transcription.full_transcript)      # Full text\nfor utterance in result.result.transcription.utterances:\n    print(f\"[{utterance.start}-{utterance.end}] {utterance.text}\")\n```\n\n## Package Structure\n\nAll public types are exported from the top-level `gladiaio_sdk` module:\n\n```python\nfrom gladiaio_sdk import (\n    GladiaClient,\n    # Pre-recorded\n    PreRecordedV2Response,\n    # Live\n    LiveV2InitRequest,\n    LiveV2InitResponse,\n    LiveV2EndedMessage,\n    LiveV2WebSocketMessage,\n    LiveV2LanguageConfig,\n    LiveV2MessagesConfig,\n    LiveV2PreProcessing,\n    LiveV2RealtimeProcessing,\n    LiveV2PostProcessing,\n)\n```\n\nFile v1.0.3:references/sdk-versions.md\n\n# SDK Versions\n\n> This file is auto-synced by CI. Do not edit manually — changes will be overwritten.\n\n| SDK | Package | Latest Version | Registry |\n| --- | --- | --- | --- |\n| JavaScript/TypeScript | `@gladiaio/sdk` | 1.0.7 | [npm](https://www.npmjs.com/package/@gladiaio/sdk) |\n| Python | `gladiaio-sdk` | 1.0.4 | [PyPI](https://pypi.org/project/gladiaio-sdk/) |\n\nLast synced: 2026-07-09\n\nAlways install without pinning a version to get the latest release:\n\n```bash\n# JS/TS\nnpm install @gladiaio/sdk\n\n# Python\npip install gladiaio-sdk\n```\n\nFile v1.0.3:skill-card.md\n\n## Description: <br>\nHelps agents install, configure, and choose the official Gladia JavaScript/TypeScript and Python SDKs for speech-to-text integrations. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[gladiaio](https://clawhub.ai/user/gladiaio) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers use this skill when adding Gladia speech-to-text SDK support to JavaScript, TypeScript, or Python applications. It guides SDK installation, client initialization, API key and region setup, browser proxy patterns, retry and timeout configuration, and SDK-versus-raw-API decisions. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: API keys can be exposed if embedded in browser-side code. <br>\nMitigation: Keep API keys server-side where possible and use a backend proxy for browser applications. <br>\nRisk: Speech-to-text workflows may send user audio to Gladia. <br>\nMitigation: Make audio capture opt-in with visible start and stop controls, and disclose that audio is sent to Gladia. <br>\nRisk: Delete operations can remove remote jobs or sessions. <br>\nMitigation: Require clear user confirmation before deleting remote jobs or sessions. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/gladiaio/skills/gladia-sdk-integration) <br>\n- [SDK integration guide](https://docs.gladia.io/chapters/integrations/sdk) <br>\n- [JavaScript SDK on npm](https://www.npmjs.com/package/@gladiaio/sdk) <br>\n- [Python SDK on PyPI](https://pypi.org/project/gladiaio-sdk/) <br>\n- [SDK source code](https://github.com/gladiaio/sdk) <br>\n- [Code samples](https://github.com/gladiaio/gladia-samples) <br>\n- [Current SDK versions](references/sdk-versions.md) <br>\n- [Client configuration reference](references/client-config.md) <br>\n- [JavaScript and TypeScript SDK patterns](references/javascript.md) <br>\n- [Python SDK patterns](references/python.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown guidance with code snippets, install commands, configuration examples, and reference links.] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Language-specific guidance for JavaScript/TypeScript and Python SDK setup, including runtime requirements, API key handling, retry and timeout configuration, and error-handling patterns.] <br>\n\n## Skill Version(s): <br>\n1.0.3 (source: server release metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v1.0.2: 7 files, 11653 bytes\n\nFiles: references/client-config.md (2299b), references/javascript.md (4866b), references/python.md (6658b), references/sdk-versions.md (543b), skill-card.md (2673b), SKILL.md (11463b), _meta.json (141b)\n\nFile v1.0.2:SKILL.md\n\n---\nname: gladia-sdk-integration\ndescription: Install and configure the official Gladia SDKs (@gladiaio/sdk for JS/TS, gladiaio-sdk for Python). Use when the user asks about SDK setup, client initialization, API key configuration, choosing between JS and Python, browser usage, retry/timeout settings, error handling, or SDK vs raw API decisions. The SDK is the recommended default for all Gladia integrations.\nlicense: MIT\n---\n\n# SDK Integration\n\nOfficial SDKs for integrating Gladia's speech-to-text API. Both SDKs share the same design and are generated from the Gladia OpenAPI schema.\n\n> **The SDK is the default for all Gladia integrations.** Always use the SDK unless there is a specific, documented reason not to (see decision guide below).\n\n## When to Use\n\n- User asks about installing, configuring, or initializing the Gladia SDK\n- Setting up API key, region, retry, timeout, or WebSocket configuration\n- Questions about SDK architecture, client methods, or type exports\n- Choosing between JS/TS and Python SDK, or between SDK and raw API\n- Browser-based integration, proxy setup, or bundle format questions\n- Error handling patterns for Gladia API responses\n\n**When NOT to use:** If the user is asking about a specific transcription use case (pre-recorded files or live streaming), start with the relevant use-case skill ([gladia-pre-recorded-transcription](../gladia-pre-recorded-transcription/SKILL.md) or [gladia-live-transcription](../gladia-live-transcription/SKILL.md)) instead — those skills reference back here for setup details.\n\n## When to Use SDK vs Raw API\n\n| Scenario                                 | Approach                                                                                                      |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- |\n| Any JS/TS or Python project              | **SDK** — always                                                                                              |\n| Browser app                              | **SDK** — JS SDK supports ESM/IIFE bundles                                                                    |\n| Need custom HTTP client or middleware    | SDK first; use `httpHeaders` / `httpTimeout` config. Fall back to raw REST only if SDK config is insufficient |\n| Language without an SDK (Go, Java, etc.) | Raw REST/WebSocket (SDK unavailable)                                                                          |\n| User explicitly requests raw calls       | Raw REST/WebSocket                                                                                            |\n| CI script or one-off curl test           | Raw REST is acceptable                                                                                        |\n\nWhen in doubt, use the SDK.\n\n## References\n\nConsult these resources as needed:\n\n- ./references/sdk-versions.md -- Current SDK versions (auto-synced by CI)\n- ./references/client-config.md -- Full client configuration reference (all options, defaults, timeouts)\n- ./references/javascript.md -- JS/TS-specific patterns (browser, proxy, File/Blob, Node requirements)\n- ./references/python.md -- Python-specific patterns (sync/async, typed requests, httpx/websockets)\n- ../gladia-pre-recorded-transcription/SKILL.md -- Pre-recorded transcription options, response structure, and audio intelligence config\n- ../gladia-live-transcription/SKILL.md -- Live session config, audio streaming, and WebSocket event handling\n- ../gladia-troubleshooting/SKILL.md -- Common errors, gotchas, and verification checklist\n\n## Installation\n\n### JavaScript / TypeScript\n\n```bash\nnpm install @gladiaio/sdk\n# or\nbun add @gladiaio/sdk\n# or\nyarn add @gladiaio/sdk\n```\n\nRequires Node.js 20+ or Bun. Also works in browsers via ESM/IIFE bundles.\n\n### Python\n\n```bash\npip install gladiaio-sdk\n# or\nuv add gladiaio-sdk\n```\n\nRequires Python 3.10+.\n\n## Client Initialization\n\n### JavaScript/TypeScript\n\n```typescript\nimport { GladiaClient } from \"@gladiaio/sdk\";\n\nconst client = new GladiaClient({\n  apiKey: \"your-api-key\", // or set GLADIA_API_KEY env var\n  region: \"eu-west\", // or set GLADIA_REGION (eu-west | us-west)\n});\n```\n\n### Python\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\nclient = GladiaClient(\n    api_key=\"your-api-key\",      # or set GLADIA_API_KEY env var\n    region=\"eu-west\",            # or set GLADIA_REGION\n)\n```\n\n### Environment Variables\n\n| Variable         | Purpose                    | Default                 |\n| ---------------- | -------------------------- | ----------------------- |\n| `GLADIA_API_KEY` | API key for authentication | —                       |\n| `GLADIA_API_URL` | Base API URL               | `https://api.gladia.io` |\n| `GLADIA_REGION`  | Datacenter region          | —                       |\n\n## Client Architecture\n\n```\nGladiaClient\n├── preRecorded()  → PreRecordedV2Client    (JS)\n│   prerecorded()  → PreRecordedV2Client    (Python)\n│\n├── liveV2()       → LiveV2Client           (JS)\n│   live()         → LiveV2Client           (Python)\n│\n└── (Python only)\n    ├── prerecorded_async() → AsyncPreRecordedV2Client\n    └── live_async()        → AsyncLiveV2Client\n```\n\n### Pre-Recorded Client Methods\n\n| Method                               | Purpose                            |\n| ------------------------------------ | ---------------------------------- |\n| `transcribe(audio, options)`         | High-level: upload + create + poll |\n| `uploadFile(audio)`                  | Upload local file to `/v2/upload`  |\n| `create(options)`                    | Create transcription job           |\n| `createAndPoll(options)`             | Create + poll until done           |\n| `poll(jobId, { interval, timeout })` | Poll until complete                |\n| `get(jobId)`                         | Get job status/results             |\n| `delete(jobId)`                      | Delete job and data                |\n| `getFile(jobId)`                     | Download original audio            |\n\n### Live Client Methods\n\n| Method                  | Purpose                              |\n| ----------------------- | ------------------------------------ |\n| `startSession(options)` | Init session → returns LiveV2Session |\n| `get(sessionId)`        | Get completed session results        |\n| `delete(sessionId)`     | Delete session and data              |\n| `getFile(sessionId)`    | Download session audio               |\n\n### Live Session Methods\n\n| Method             | Purpose                                |\n| ------------------ | -------------------------------------- |\n| `sendAudio(chunk)` | Stream audio bytes to the session      |\n| `stopRecording()`  | End recording, trigger post-processing |\n| `endSession()`     | Force close without post-processing    |\n| `getSessionId()`   | Await session ID (async)               |\n\n## Configuration Options\n\nKey client options: `apiKey`, `apiUrl`, `region`, `httpTimeout`, `httpRetry`, `wsRetry`, `wsTimeout`, `prerecordedTimeouts`, `liveTimeouts`.\n\nFor the full config reference with all options and defaults, see [./references/client-config.md](./references/client-config.md).\n\n## Audio Input Types\n\n| Input                           |   JS/TS   | Python |\n| ------------------------------- | :-------: | :----: |\n| Local file path (string)        | Node only |  Yes   |\n| `Path` object                   |     —     |  Yes   |\n| HTTP(S) URL                     |    Yes    |  Yes   |\n| `File` / `Blob`                 |  Browser  |   —    |\n| Binary file object (`BinaryIO`) |     —     |  Yes   |\n\nURLs are passed directly as `audio_url` without upload. Local files are automatically uploaded via `/v2/upload`.\n\n## Error Handling\n\n### JavaScript/TypeScript\n\n```typescript\ntry {\n  const result = await client.preRecorded().transcribe(\"./audio.mp3\", options);\n} catch (error) {\n  if (error.message.includes(\"401\")) {\n    console.error(\"Invalid API key\");\n  } else if (error.message.includes(\"timeout\")) {\n    console.error(\"Request timed out\");\n  }\n}\n```\n\n### Python\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\ntry:\n    result = client.prerecorded().transcribe(\"audio.mp3\", options)\nexcept Exception as e:\n    print(f\"Error: {e}\")\n```\n\nPython exports `HttpError` and `TimeoutError` for specific error handling.\n\n## Key Differences Between JS and Python\n\n| Aspect          | JavaScript/TypeScript                       | Python                                   |\n| --------------- | ------------------------------------------- | ---------------------------------------- |\n| Async model     | Promise-based (async only)                  | Sync + async (separate clients)          |\n| Naming          | camelCase (`preRecorded`, `sendAudio`)      | snake_case (`prerecorded`, `send_audio`) |\n| Browser support | Yes (ESM, CJS, IIFE)                        | No (server only)                         |\n| Runtime         | Node 20+, Bun, browsers                     | Python 3.10+                             |\n| Dependencies    | 0 runtime deps (optional `ws` for Node <22) | httpx, websockets, pyee                  |\n| Options format  | Plain objects (snake_case keys)             | Dataclasses or dicts                     |\n| Untyped API     | `transcribeUntyped()`, `createUntyped()`    | Dict accepted on most methods            |\n\n## Type Exports\n\nBoth SDKs export all request/response types from the main package:\n\n```typescript\nimport type {\n  LiveV2InitRequest,\n  LiveV2WebSocketMessage,\n  PreRecordedV2Response,\n  PreRecordedV2TranscriptionOptions,\n} from \"@gladiaio/sdk\";\n```\n\n```python\nfrom gladiaio_sdk import (\n    LiveV2InitRequest,\n    LiveV2WebSocketMessage,\n    LiveV2LanguageConfig,\n    LiveV2MessagesConfig,\n    PreRecordedV2Response,\n)\n```\n\n## Common Mistakes\n\n- **Wrong sub-client method name between JS and Python**: JS uses `client.preRecorded()` and `client.liveV2()`; Python uses `client.prerecorded()` and `client.live()`. Mixing the naming conventions causes \"is not a function\" / `AttributeError` at runtime.\n- **Forgetting `await` in JavaScript**: every JS SDK method returns a Promise. Omitting `await` on `transcribe()`, `startSession()`, etc. lets the operation run silently in the background with no result or error surfaced to your code.\n- **API key exposed in browser-side code**: never embed the API key directly in front-end JavaScript — it becomes publicly readable. Use a backend proxy that forwards requests with the key server-side. See [./references/javascript.md](./references/javascript.md) for the proxy pattern.\n- **Node.js < 22 without the `ws` peer dependency**: the JS SDK requires the `ws` package for WebSocket on Node < 22, which lacks a native WebSocket. Without it, live sessions fail silently. Fix: `npm install ws`.\n- **Python async client in sync context**: `client.live_async()` and `client.prerecorded_async()` cannot be called from synchronous code — they require an active event loop. Use the sync client (`client.live()`, `client.prerecorded()`) unless you are inside an `async def`.\n\n## Further Reading\n\n- [SDK integration guide](https://docs.gladia.io/chapters/integrations/sdk)\n- [JS SDK on npm](https://www.npmjs.com/package/@gladiaio/sdk)\n- [Python SDK on PyPI](https://pypi.org/project/gladiaio-sdk/)\n- [SDK source code](https://github.com/gladiaio/sdk)\n- [Code samples](https://github.com/gladiaio/gladia-samples)\n\nFile v1.0.2:_meta.json\n\n{\n  \"ownerId\": \"kn7fs6cmj9hqg7232sbkacf31d882wp2\",\n  \"slug\": \"gladia-sdk-integration\",\n  \"version\": \"1.0.2\",\n  \"publishedAt\": 1783605977774\n}\n\nFile v1.0.2:references/client-config.md\n\n# Full Client Configuration Reference\n\nComplete configuration options for `GladiaClient` constructor.\n\n## Contents\n\n- Full Config Example (JavaScript/TypeScript)\n- Config Summary Table\n\n## Full Config Example\n\n```typescript\nconst client = new GladiaClient({\n  apiKey: \"your-key\",\n  apiUrl: \"https://api.gladia.io\",\n  region: \"eu-west\",\n\n  // HTTP settings\n  httpHeaders: { \"X-Custom-Header\": \"value\" },\n  httpTimeout: 10000, // 10s default\n  httpRetry: {\n    maxRetries: 3,\n    retryDelay: 1000,\n  },\n\n  // WebSocket settings\n  wsRetry: {\n    maxRetries: 5,\n    retryDelay: 1000,\n  },\n  wsTimeout: 30000,\n\n  // Pre-recorded operation timeouts\n  prerecordedTimeouts: {\n    transcribe: 7200000, // 2 hours (full flow)\n    poll: 7200000,\n    upload: 300000, // 5 minutes\n    create: 30000,\n    get: 10000,\n    delete: 10000,\n    getFile: 60000,\n  },\n\n  // Live operation timeouts\n  liveTimeouts: {\n    get: 10000,\n    delete: 10000,\n    getFile: 60000,\n  },\n});\n```\n\n## Config Summary\n\n| Option                  | Type     | Default                 | Description                |\n| ----------------------- | -------- | ----------------------- | -------------------------- |\n| `apiKey`                | `string` | `GLADIA_API_KEY` env    | API key                    |\n| `apiUrl`                | `string` | `https://api.gladia.io` | Base API URL               |\n| `region`                | `string` | `GLADIA_REGION` env     | `eu-west` or `us-west`     |\n| `httpHeaders`           | `object` | `{}`                    | Custom HTTP headers        |\n| `httpTimeout`           | `number` | `10000`                 | HTTP request timeout (ms)  |\n| `httpRetry.maxRetries`  | `number` | `3`                     | Max HTTP retries           |\n| `httpRetry.retryDelay`  | `number` | `1000`                  | Delay between retries (ms) |\n| `wsRetry.maxRetries`    | `number` | `5`                     | Max WebSocket reconnects   |\n| `wsRetry.retryDelay`    | `number` | `1000`                  | WS reconnect delay (ms)    |\n| `wsTimeout`             | `number` | `30000`                 | WebSocket timeout (ms)     |\n| `prerecordedTimeouts.*` | `number` | varies                  | Per-operation timeouts     |\n| `liveTimeouts.*`        | `number` | varies                  | Per-operation timeouts     |\n\nFile v1.0.2:references/javascript.md\n\n# JavaScript / TypeScript SDK\n\nPatterns and details specific to the `@gladiaio/sdk` package.\n\n## Contents\n\n- Package Info\n- Browser Usage (ESM, IIFE, API key security via proxy)\n- File Upload in Browsers\n- Node.js Specifics (file paths, WebSocket for Node < 22, streaming from file/mic)\n- Untyped API\n- TypeScript Types\n- Error Handling\n- Live Session Event Typing\n- CDN / IIFE Bundle\n- Package Size\n\n## Package Info\n\n- **npm**: [@gladiaio/sdk](https://www.npmjs.com/package/@gladiaio/sdk)\n- **Version**: 1.0.7\n- **Runtime**: Node.js 20+, Bun, browsers\n- **Bundle formats**: ESM, CJS, IIFE (via unpkg/jsdelivr)\n- **Dependencies**: 0 runtime deps\n- **Peer deps**: `ws` (only for Node < 22, which lacks native WebSocket)\n\n## Browser Usage\n\nThe SDK works in browsers out of the box. Use ESM imports or the IIFE bundle:\n\n```html\n<script src=\"https://unpkg.com/@gladiaio/sdk/dist/index.iife.js\"></script>\n<script>\n  const client = new GladiaSDK.GladiaClient({ apiKey: \"...\" });\n</script>\n```\n\n### API Key Security in Browsers\n\nNever expose your API key in client-side code for production. Instead, use a proxy:\n\n```typescript\n// Point the SDK at your backend proxy (no apiKey needed)\nconst client = new GladiaClient({\n  apiUrl: \"https://your-server.com/api/gladia\",\n});\n```\n\nYour backend proxy adds the `x-gladia-key` header before forwarding to `api.gladia.io`.\n\n## File Upload in Browsers\n\nUse `File` or `Blob` objects for uploads:\n\n```typescript\nconst fileInput = document.querySelector('input[type=\"file\"]');\nconst file = fileInput.files[0];\n\nconst result = await client.preRecorded().transcribe(file, {\n  language_config: { languages: [\"en\"] },\n});\n```\n\n## Node.js Specifics\n\n### File path input\n\n```typescript\n// Node: pass a file path string\nconst result = await client\n  .preRecorded()\n  .transcribe(\"./recordings/meeting.wav\", options);\n```\n\n### WebSocket for Node < 22\n\nNode versions before 22 don't have native WebSocket. Install the `ws` package:\n\n```bash\nnpm install ws\n```\n\nThe SDK auto-detects and uses it. Node 22+ uses the built-in `WebSocket` global.\n\n### Streaming audio from a file\n\n```typescript\nimport { createReadStream } from \"fs\";\n\nconst session = client.liveV2().startSession({\n  encoding: \"wav/pcm\",\n  sample_rate: 16000,\n  bit_depth: 16,\n  channels: 1,\n  language_config: { languages: [\"en\"] },\n});\n\nsession.once(\"started\", () => {\n  const stream = createReadStream(\"./audio.pcm\", { highWaterMark: 3200 });\n  stream.on(\"data\", (chunk) => session.sendAudio(chunk));\n  stream.on(\"end\", () => session.stopRecording());\n});\n```\n\n### Streaming from microphone (Node)\n\nUse a library like `node-mic` or `node-record-lpcm16`:\n\n```typescript\nimport mic from \"mic\";\n\nconst micInstance = mic({ rate: 16000, bitwidth: 16, channels: 1 });\nconst micStream = micInstance.getAudioStream();\n\nsession.once(\"started\", () => {\n  micStream.on(\"data\", (chunk) => session.sendAudio(chunk));\n  micInstance.start();\n});\n\n// Stop\nmicInstance.stop();\nsession.stopRecording();\n```\n\n## Untyped API\n\nFor maximum flexibility or when migrating from raw HTTP calls:\n\n```typescript\n// Pass raw JSON matching the API schema\nconst result = await client.preRecorded().createUntyped({\n  audio_url: \"https://example.com/audio.mp3\",\n  diarization: true,\n  custom_field: \"value\",\n});\n\n// Full untyped transcribe flow\nconst result = await client.preRecorded().transcribeUntyped(\"./file.mp3\", {\n  language_config: { languages: [\"en\"] },\n});\n```\n\n## TypeScript Types\n\nAll types are exported from the main package:\n\n```typescript\nimport type {\n  GladiaClientOptions,\n  PreRecordedV2TranscriptionOptions,\n  PreRecordedV2Response,\n  PreRecordedV2InitTranscriptionRequest,\n  LiveV2InitRequest,\n  LiveV2Session,\n  LiveV2WebSocketMessage,\n  LiveV2TranscriptMessage,\n} from \"@gladiaio/sdk\";\n```\n\n## Error Handling\n\nThe JS SDK throws standard `Error` objects. Check the message for HTTP status codes:\n\n```typescript\ntry {\n  await client.preRecorded().transcribe(audio, options);\n} catch (err) {\n  if (err instanceof Error) {\n    if (err.message.includes(\"401\")) {\n      /* auth error */\n    }\n    if (err.message.includes(\"429\")) {\n      /* rate limited */\n    }\n    if (err.message.includes(\"timeout\")) {\n      /* timed out */\n    }\n  }\n}\n```\n\n## Live Session Event Typing\n\n```typescript\nimport type { LiveV2WebSocketMessage } from \"@gladiaio/sdk\";\n\nsession.on(\"message\", (msg: LiveV2WebSocketMessage) => {\n  // msg.type is a discriminated union\n  if (msg.type === \"transcript\") {\n    msg.data.is_final; // boolean\n    msg.data.utterance.text; // string\n  }\n});\n```\n\n## CDN / IIFE Bundle\n\nFor quick prototyping without a bundler:\n\n```html\n<script src=\"https://cdn.jsdelivr.net/npm/@gladiaio/sdk/dist/index.iife.js\"></script>\n```\n\nGlobal namespace: `window.GladiaSDK`\n\n## Package Size\n\n~741 KB unpacked (134 files). Tree-shaking-friendly ESM exports keep bundle size small when using a bundler.\n\nFile v1.0.2:references/python.md\n\n# Python SDK\n\nPatterns and details specific to the `gladiaio-sdk` package.\n\n## Contents\n\n- Package Info\n- Sync vs Async (including async live session)\n- Client Method Aliases\n- Typed Request Objects (dataclass-style and dict alternative)\n- File Input Types\n- Session ID Access\n- Error Types\n- Event Handling (pyee EventEmitter pattern)\n- Streaming Audio from File\n- Streaming from Microphone (PyAudio)\n- Response Access\n- Package Structure (exports)\n\n## Package Info\n\n- **PyPI**: [gladiaio-sdk](https://pypi.org/project/gladiaio-sdk/)\n- **Version**: 1.0.4\n- **Runtime**: Python 3.10+\n- **Dependencies**: httpx, websockets, pyee\n\n## Sync vs Async\n\nThe Python SDK provides both synchronous and asynchronous clients:\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\nclient = GladiaClient(api_key=\"YOUR_KEY\")\n\n# Sync\nresult = client.prerecorded().transcribe(\"audio.mp3\", options)\n\n# Async\nresult = await client.prerecorded_async().transcribe(\"audio.mp3\", options)\n```\n\n### Async live session\n\n```python\nimport asyncio\nfrom gladiaio_sdk import GladiaClient, LiveV2InitRequest, LiveV2LanguageConfig\n\nasync def main():\n    client = GladiaClient(api_key=\"YOUR_KEY\")\n    live_client = client.live_async()\n    session_done = asyncio.Event()\n\n    session = live_client.start_session(\n        LiveV2InitRequest(\n            model=\"solaria-1\",\n            encoding=\"wav/pcm\",\n            sample_rate=16000,\n            bit_depth=16,\n            channels=1,\n            language_config=LiveV2LanguageConfig(languages=[\"en\"]),\n        )\n    )\n\n    @session.once(\"ended\")\n    def on_ended(msg):\n        session_done.set()\n\n    session.send_audio(audio_bytes)\n    session.stop_recording()\n    await session_done.wait()\n\nasyncio.run(main())\n```\n\n## Client Method Aliases\n\n| Primary                      | Aliases                                             |\n| ---------------------------- | --------------------------------------------------- |\n| `client.prerecorded()`       | `client.pre_recorded()`, `client.pre_recorded_v2()` |\n| `client.prerecorded_async()` | `client.pre_recorded_async()`                       |\n| `client.live()`              | `client.live_v2()`                                  |\n| `client.live_async()`        | `client.live_v2_async()`                            |\n\n## Typed Request Objects\n\nPython uses dataclass-style request objects for type safety:\n\n```python\nfrom gladiaio_sdk import (\n    LiveV2InitRequest,\n    LiveV2LanguageConfig,\n    LiveV2MessagesConfig,\n    LiveV2PreProcessing,\n    LiveV2RealtimeProcessing,\n    LiveV2PostProcessing,\n)\n\nrequest = LiveV2InitRequest(\n    model=\"solaria-1\",\n    encoding=\"wav/pcm\",\n    sample_rate=16000,\n    bit_depth=16,\n    channels=1,\n    language_config=LiveV2LanguageConfig(\n        languages=[\"en\", \"fr\"],\n        code_switching=True,\n    ),\n    messages_config=LiveV2MessagesConfig(\n        receive_partial_transcripts=True,\n        receive_speech_events=True,\n    ),\n    pre_processing=LiveV2PreProcessing(\n        audio_enhancer=True,\n    ),\n)\n```\n\n### Dict alternative\n\nYou can also pass plain dicts for pre-recorded options:\n\n```python\nresult = client.prerecorded().transcribe(\n    \"audio.mp3\",\n    {\n        \"language_config\": {\"languages\": [\"en\"]},\n        \"diarization\": True,\n        \"translation\": True,\n        \"translation_config\": {\"target_languages\": [\"fr\"]},\n    },\n)\n```\n\n## File Input Types\n\n```python\nfrom pathlib import Path\n\n# String path\nresult = client.prerecorded().transcribe(\"audio.mp3\", options)\n\n# Path object\nresult = client.prerecorded().transcribe(Path(\"audio.mp3\"), options)\n\n# URL (no upload needed)\nresult = client.prerecorded().transcribe(\"https://example.com/audio.mp3\", options)\n\n# Binary file object\nwith open(\"audio.mp3\", \"rb\") as f:\n    result = client.prerecorded().transcribe(f, options)\n```\n\n## Session ID Access\n\n```python\n# Sync: available after 'started' event fires\n@session.once(\"started\")\ndef on_started(response):\n    print(f\"Session ID: {response.id}\")\n    # Also: session.session_id\n\n# Async: use await\nsession_id = await session.get_session_id()\n```\n\n## Error Types\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\ntry:\n    result = client.prerecorded().transcribe(\"audio.mp3\", options)\nexcept Exception as e:\n    # HttpError for HTTP failures (401, 429, 500, etc.)\n    # TimeoutError for timeout\n    print(f\"Error: {type(e).__name__}: {e}\")\n```\n\n## Event Handling\n\nUses `pyee` (EventEmitter pattern):\n\n```python\nfrom gladiaio_sdk import LiveV2WebSocketMessage, LiveV2InitResponse, LiveV2EndedMessage\n\n@session.on(\"message\")\ndef on_message(message: LiveV2WebSocketMessage):\n    if message.type == \"transcript\":\n        if message.data.is_final:\n            print(f\"Final: {message.data.utterance.text}\")\n\n@session.once(\"started\")\ndef on_started(response: LiveV2InitResponse):\n    print(f\"Session {response.id} started\")\n\n@session.on(\"error\")\ndef on_error(error: Exception):\n    print(f\"Error: {error}\")\n\n@session.once(\"ended\")\ndef on_ended(ended: LiveV2EndedMessage):\n    print(\"Session ended\")\n```\n\n## Streaming Audio from File\n\n```python\nimport time\n\nCHUNK_SIZE = 3200  # 100ms of 16-bit mono at 16kHz\n\nwith open(\"audio.pcm\", \"rb\") as f:\n    while chunk := f.read(CHUNK_SIZE):\n        session.send_audio(chunk)\n        time.sleep(0.1)  # Real-time pacing\n\nsession.stop_recording()\n```\n\n## Streaming from Microphone\n\nUsing PyAudio:\n\n```python\nimport pyaudio\n\nRATE = 16000\nCHUNK = 3200\nFORMAT = pyaudio.paInt16\nCHANNELS = 1\n\np = pyaudio.PyAudio()\nstream = p.open(format=FORMAT, channels=CHANNELS, rate=RATE,\n                input=True, frames_per_buffer=CHUNK)\n\ntry:\n    while True:\n        data = stream.read(CHUNK)\n        session.send_audio(data)\nexcept KeyboardInterrupt:\n    pass\nfinally:\n    stream.stop_stream()\n    stream.close()\n    session.stop_recording()\n```\n\n## Response Access\n\nPre-recorded responses use attribute access:\n\n```python\nresult = client.prerecorded().transcribe(\"audio.mp3\", options)\n\n# Access nested fields\nprint(result.status)                                    # \"done\"\nprint(result.result.transcription.full_transcript)      # Full text\nfor utterance in result.result.transcription.utterances:\n    print(f\"[{utterance.start}-{utterance.end}] {utterance.text}\")\n```\n\n## Package Structure\n\nAll public types are exported from the top-level `gladiaio_sdk` module:\n\n```python\nfrom gladiaio_sdk import (\n    GladiaClient,\n    # Pre-recorded\n    PreRecordedV2Response,\n    # Live\n    LiveV2InitRequest,\n    LiveV2InitResponse,\n    LiveV2EndedMessage,\n    LiveV2WebSocketMessage,\n    LiveV2LanguageConfig,\n    LiveV2MessagesConfig,\n    LiveV2PreProcessing,\n    LiveV2RealtimeProcessing,\n    LiveV2PostProcessing,\n)\n```\n\nFile v1.0.2:references/sdk-versions.md\n\n# SDK Versions\n\n> This file is auto-synced by CI. Do not edit manually — changes will be overwritten.\n\n| SDK | Package | Latest Version | Registry |\n| --- | --- | --- | --- |\n| JavaScript/TypeScript | `@gladiaio/sdk` | 1.0.7 | [npm](https://www.npmjs.com/package/@gladiaio/sdk) |\n| Python | `gladiaio-sdk` | 1.0.4 | [PyPI](https://pypi.org/project/gladiaio-sdk/) |\n\nLast synced: 2026-07-09\n\nAlways install without pinning a version to get the latest release:\n\n```bash\n# JS/TS\nnpm install @gladiaio/sdk\n\n# Python\npip install gladiaio-sdk\n```\n\nFile v1.0.2:skill-card.md\n\n## Description: <br>\nInstall and configure the official Gladia SDKs for JavaScript, TypeScript, and Python integrations. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[gladiaio](https://clawhub.ai/user/gladiaio) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and engineers use this skill to install, configure, and initialize Gladia's JavaScript/TypeScript and Python SDKs for speech-to-text integrations. It helps choose SDK usage over raw APIs, set API keys and regions, configure retries and timeouts, and apply language-specific error-handling patterns. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Integrations built from this guidance may send audio files or live audio to Gladia. <br>\nMitigation: Confirm user authorization and data-handling requirements before uploading or streaming sensitive audio. <br>\nRisk: API keys embedded in browser-side code can become publicly readable. <br>\nMitigation: Keep GLADIA_API_KEY server-side and route browser requests through a backend proxy. <br>\nRisk: SDK delete methods can remove hosted job or session data. <br>\nMitigation: Confirm intent before calling delete methods for transcription jobs or live sessions. <br>\n\n\n## Reference(s): <br>\n- [SDK Versions](references/sdk-versions.md) <br>\n- [Full Client Configuration Reference](references/client-config.md) <br>\n- [JavaScript / TypeScript SDK](references/javascript.md) <br>\n- [Python SDK](references/python.md) <br>\n- [Gladia SDK integration guide](https://docs.gladia.io/chapters/integrations/sdk) <br>\n- [@gladiaio/sdk on npm](https://www.npmjs.com/package/@gladiaio/sdk) <br>\n- [gladiaio-sdk on PyPI](https://pypi.org/project/gladiaio-sdk/) <br>\n- [Gladia SDK source code](https://github.com/gladiaio/sdk) <br>\n- [Gladia code samples](https://github.com/gladiaio/gladia-samples) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown with inline code blocks and shell commands] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [May include JavaScript/TypeScript or Python snippets, install commands, environment variable guidance, and SDK configuration examples.] <br>\n\n## Skill Version(s): <br>\n1.0.2 (source: server release evidence) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v1.0.1: 7 files, 11732 bytes\n\nFiles: references/client-config.md (2299b), references/javascript.md (4931b), references/python.md (6723b), references/sdk-versions.md (737b), skill-card.md (2623b), SKILL.md (11463b), _meta.json (141b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: gladia-sdk-integration\ndescription: Install and configure the official Gladia SDKs (@gladiaio/sdk for JS/TS, gladiaio-sdk for Python). Use when the user asks about SDK setup, client initialization, API key configuration, choosing between JS and Python, browser usage, retry/timeout settings, error handling, or SDK vs raw API decisions. The SDK is the recommended default for all Gladia integrations.\nlicense: MIT\n---\n\n# SDK Integration\n\nOfficial SDKs for integrating Gladia's speech-to-text API. Both SDKs share the same design and are generated from the Gladia OpenAPI schema.\n\n> **The SDK is the default for all Gladia integrations.** Always use the SDK unless there is a specific, documented reason not to (see decision guide below).\n\n## When to Use\n\n- User asks about installing, configuring, or initializing the Gladia SDK\n- Setting up API key, region, retry, timeout, or WebSocket configuration\n- Questions about SDK architecture, client methods, or type exports\n- Choosing between JS/TS and Python SDK, or between SDK and raw API\n- Browser-based integration, proxy setup, or bundle format questions\n- Error handling patterns for Gladia API responses\n\n**When NOT to use:** If the user is asking about a specific transcription use case (pre-recorded files or live streaming), start with the relevant use-case skill ([gladia-pre-recorded-transcription](../gladia-pre-recorded-transcription/SKILL.md) or [gladia-live-transcription](../gladia-live-transcription/SKILL.md)) instead — those skills reference back here for setup details.\n\n## When to Use SDK vs Raw API\n\n| Scenario                                 | Approach                                                                                                      |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- |\n| Any JS/TS or Python project              | **SDK** — always                                                                                              |\n| Browser app                              | **SDK** — JS SDK supports ESM/IIFE bundles                                                                    |\n| Need custom HTTP client or middleware    | SDK first; use `httpHeaders` / `httpTimeout` config. Fall back to raw REST only if SDK config is insufficient |\n| Language without an SDK (Go, Java, etc.) | Raw REST/WebSocket (SDK unavailable)                                                                          |\n| User explicitly requests raw calls       | Raw REST/WebSocket                                                                                            |\n| CI script or one-off curl test           | Raw REST is acceptable                                                                                        |\n\nWhen in doubt, use the SDK.\n\n## References\n\nConsult these resources as needed:\n\n- ./references/sdk-versions.md -- Current SDK versions (auto-synced by CI)\n- ./references/client-config.md -- Full client configuration reference (all options, defaults, timeouts)\n- ./references/javascript.md -- JS/TS-specific patterns (browser, proxy, File/Blob, Node requirements)\n- ./references/python.md -- Python-specific patterns (sync/async, typed requests, httpx/websockets)\n- ../gladia-pre-recorded-transcription/SKILL.md -- Pre-recorded transcription options, response structure, and audio intelligence config\n- ../gladia-live-transcription/SKILL.md -- Live session config, audio streaming, and WebSocket event handling\n- ../gladia-troubleshooting/SKILL.md -- Common errors, gotchas, and verification checklist\n\n## Installation\n\n### JavaScript / TypeScript\n\n```bash\nnpm install @gladiaio/sdk\n# or\nbun add @gladiaio/sdk\n# or\nyarn add @gladiaio/sdk\n```\n\nRequires Node.js 20+ or Bun. Also works in browsers via ESM/IIFE bundles.\n\n### Python\n\n```bash\npip install gladiaio-sdk\n# or\nuv add gladiaio-sdk\n```\n\nRequires Python 3.10+.\n\n## Client Initialization\n\n### JavaScript/TypeScript\n\n```typescript\nimport { GladiaClient } from \"@gladiaio/sdk\";\n\nconst client = new GladiaClient({\n  apiKey: \"your-api-key\", // or set GLADIA_API_KEY env var\n  region: \"eu-west\", // or set GLADIA_REGION (eu-west | us-west)\n});\n```\n\n### Python\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\nclient = GladiaClient(\n    api_key=\"your-api-key\",      # or set GLADIA_API_KEY env var\n    region=\"eu-west\",            # or set GLADIA_REGION\n)\n```\n\n### Environment Variables\n\n| Variable         | Purpose                    | Default                 |\n| ---------------- | -------------------------- | ----------------------- |\n| `GLADIA_API_KEY` | API key for authentication | —                       |\n| `GLADIA_API_URL` | Base API URL               | `https://api.gladia.io` |\n| `GLADIA_REGION`  | Datacenter region          | —                       |\n\n## Client Architecture\n\n```\nGladiaClient\n├── preRecorded()  → PreRecordedV2Client    (JS)\n│   prerecorded()  → PreRecordedV2Client    (Python)\n│\n├── liveV2()       → LiveV2Client           (JS)\n│   live()         → LiveV2Client           (Python)\n│\n└── (Python only)\n    ├── prerecorded_async() → AsyncPreRecordedV2Client\n    └── live_async()        → AsyncLiveV2Client\n```\n\n### Pre-Recorded Client Methods\n\n| Method                               | Purpose                            |\n| ------------------------------------ | ---------------------------------- |\n| `transcribe(audio, options)`         | High-level: upload + create + poll |\n| `uploadFile(audio)`                  | Upload local file to `/v2/upload`  |\n| `create(options)`                    | Create transcription job           |\n| `createAndPoll(options)`             | Create + poll until done           |\n| `poll(jobId, { interval, timeout })` | Poll until complete                |\n| `get(jobId)`                         | Get job status/results             |\n| `delete(jobId)`                      | Delete job and data                |\n| `getFile(jobId)`                     | Download original audio            |\n\n### Live Client Methods\n\n| Method                  | Purpose                              |\n| ----------------------- | ------------------------------------ |\n| `startSession(options)` | Init session → returns LiveV2Session |\n| `get(sessionId)`        | Get completed session results        |\n| `delete(sessionId)`     | Delete session and data              |\n| `getFile(sessionId)`    | Download session audio               |\n\n### Live Session Methods\n\n| Method             | Purpose                                |\n| ------------------ | -------------------------------------- |\n| `sendAudio(chunk)` | Stream audio bytes to the session      |\n| `stopRecording()`  | End recording, trigger post-processing |\n| `endSession()`     | Force close without post-processing    |\n| `getSessionId()`   | Await session ID (async)               |\n\n## Configuration Options\n\nKey client options: `apiKey`, `apiUrl`, `region`, `httpTimeout`, `httpRetry`, `wsRetry`, `wsTimeout`, `prerecordedTimeouts`, `liveTimeouts`.\n\nFor the full config reference with all options and defaults, see [./references/client-config.md](./references/client-config.md).\n\n## Audio Input Types\n\n| Input                           |   JS/TS   | Python |\n| ------------------------------- | :-------: | :----: |\n| Local file path (string)        | Node only |  Yes   |\n| `Path` object                   |     —     |  Yes   |\n| HTTP(S) URL                     |    Yes    |  Yes   |\n| `File` / `Blob`                 |  Browser  |   —    |\n| Binary file object (`BinaryIO`) |     —     |  Yes   |\n\nURLs are passed directly as `audio_url` without upload. Local files are automatically uploaded via `/v2/upload`.\n\n## Error Handling\n\n### JavaScript/TypeScript\n\n```typescript\ntry {\n  const result = await client.preRecorded().transcribe(\"./audio.mp3\", options);\n} catch (error) {\n  if (error.message.includes(\"401\")) {\n    console.error(\"Invalid API key\");\n  } else if (error.message.includes(\"timeout\")) {\n    console.error(\"Request timed out\");\n  }\n}\n```\n\n### Python\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\ntry:\n    result = client.prerecorded().transcribe(\"audio.mp3\", options)\nexcept Exception as e:\n    print(f\"Error: {e}\")\n```\n\nPython exports `HttpError` and `TimeoutError` for specific error handling.\n\n## Key Differences Between JS and Python\n\n| Aspect          | JavaScript/TypeScript                       | Python                                   |\n| --------------- | ------------------------------------------- | ---------------------------------------- |\n| Async model     | Promise-based (async only)                  | Sync + async (separate clients)          |\n| Naming          | camelCase (`preRecorded`, `sendAudio`)      | snake_case (`prerecorded`, `send_audio`) |\n| Browser support | Yes (ESM, CJS, IIFE)                        | No (server only)                         |\n| Runtime         | Node 20+, Bun, browsers                     | Python 3.10+                             |\n| Dependencies    | 0 runtime deps (optional `ws` for Node <22) | httpx, websockets, pyee                  |\n| Options format  | Plain objects (snake_case keys)             | Dataclasses or dicts                     |\n| Untyped API     | `transcribeUntyped()`, `createUntyped()`    | Dict accepted on most methods            |\n\n## Type Exports\n\nBoth SDKs export all request/response types from the main package:\n\n```typescript\nimport type {\n  LiveV2InitRequest,\n  LiveV2WebSocketMessage,\n  PreRecordedV2Response,\n  PreRecordedV2TranscriptionOptions,\n} from \"@gladiaio/sdk\";\n```\n\n```python\nfrom gladiaio_sdk import (\n    LiveV2InitRequest,\n    LiveV2WebSocketMessage,\n    LiveV2LanguageConfig,\n    LiveV2MessagesConfig,\n    PreRecordedV2Response,\n)\n```\n\n## Common Mistakes\n\n- **Wrong sub-client method name between JS and Python**: JS uses `client.preRecorded()` and `client.liveV2()`; Python uses `client.prerecorded()` and `client.live()`. Mixing the naming conventions causes \"is not a function\" / `AttributeError` at runtime.\n- **Forgetting `await` in JavaScript**: every JS SDK method returns a Promise. Omitting `await` on `transcribe()`, `startSession()`, etc. lets the operation run silently in the background with no result or error surfaced to your code.\n- **API key exposed in browser-side code**: never embed the API key directly in front-end JavaScript — it becomes publicly readable. Use a backend proxy that forwards requests with the key server-side. See [./references/javascript.md](./references/javascript.md) for the proxy pattern.\n- **Node.js < 22 without the `ws` peer dependency**: the JS SDK requires the `ws` package for WebSocket on Node < 22, which lacks a native WebSocket. Without it, live sessions fail silently. Fix: `npm install ws`.\n- **Python async client in sync context**: `client.live_async()` and `client.prerecorded_async()` cannot be called from synchronous code — they require an active event loop. Use the sync client (`client.live()`, `client.prerecorded()`) unless you are inside an `async def`.\n\n## Further Reading\n\n- [SDK integration guide](https://docs.gladia.io/chapters/integrations/sdk)\n- [JS SDK on npm](https://www.npmjs.com/package/@gladiaio/sdk)\n- [Python SDK on PyPI](https://pypi.org/project/gladiaio-sdk/)\n- [SDK source code](https://github.com/gladiaio/sdk)\n- [Code samples](https://github.com/gladiaio/gladia-samples)\n\nFile v1.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn7fs6cmj9hqg7232sbkacf31d882wp2\",\n  \"slug\": \"gladia-sdk-integration\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1780942650023\n}\n\nFile v1.0.1:references/client-config.md\n\n# Full Client Configuration Reference\n\nComplete configuration options for `GladiaClient` constructor.\n\n## Contents\n\n- Full Config Example (JavaScript/TypeScript)\n- Config Summary Table\n\n## Full Config Example\n\n```typescript\nconst client = new GladiaClient({\n  apiKey: \"your-key\",\n  apiUrl: \"https://api.gladia.io\",\n  region: \"eu-west\",\n\n  // HTTP settings\n  httpHeaders: { \"X-Custom-Header\": \"value\" },\n  httpTimeout: 10000, // 10s default\n  httpRetry: {\n    maxRetries: 3,\n    retryDelay: 1000,\n  },\n\n  // WebSocket settings\n  wsRetry: {\n    maxRetries: 5,\n    retryDelay: 1000,\n  },\n  wsTimeout: 30000,\n\n  // Pre-recorded operation timeouts\n  prerecordedTimeouts: {\n    transcribe: 7200000, // 2 hours (full flow)\n    poll: 7200000,\n    upload: 300000, // 5 minutes\n    create: 30000,\n    get: 10000,\n    delete: 10000,\n    getFile: 60000,\n  },\n\n  // Live operation timeouts\n  liveTimeouts: {\n    get: 10000,\n    delete: 10000,\n    getFile: 60000,\n  },\n});\n```\n\n## Config Summary\n\n| Option                  | Type     | Default                 | Description                |\n| ----------------------- | -------- | ----------------------- | -------------------------- |\n| `apiKey`                | `string` | `GLADIA_API_KEY` env    | API key                    |\n| `apiUrl`                | `string` | `https://api.gladia.io` | Base API URL               |\n| `region`                | `string` | `GLADIA_REGION` env     | `eu-west` or `us-west`     |\n| `httpHeaders`           | `object` | `{}`                    | Custom HTTP headers        |\n| `httpTimeout`           | `number` | `10000`                 | HTTP request timeout (ms)  |\n| `httpRetry.maxRetries`  | `number` | `3`                     | Max HTTP retries           |\n| `httpRetry.retryDelay`  | `number` | `1000`                  | Delay between retries (ms) |\n| `wsRetry.maxRetries`    | `number` | `5`                     | Max WebSocket reconnects   |\n| `wsRetry.retryDelay`    | `number` | `1000`                  | WS reconnect delay (ms)    |\n| `wsTimeout`             | `number` | `30000`                 | WebSocket timeout (ms)     |\n| `prerecordedTimeouts.*` | `number` | varies                  | Per-operation timeouts     |\n| `liveTimeouts.*`        | `number` | varies                  | Per-operation timeouts     |\n\nFile v1.0.1:references/javascript.md\n\n# JavaScript / TypeScript SDK\n\nPatterns and details specific to the `@gladiaio/sdk` package.\n\n## Contents\n\n- Package Info\n- Browser Usage (ESM, IIFE, API key security via proxy)\n- File Upload in Browsers\n- Node.js Specifics (file paths, WebSocket for Node < 22, streaming from file/mic)\n- Untyped API\n- TypeScript Types\n- Error Handling\n- Live Session Event Typing\n- CDN / IIFE Bundle\n- Package Size\n\n## Package Info\n\n- **npm**: [@gladiaio/sdk](https://www.npmjs.com/package/@gladiaio/sdk)\n- **Version**: 1.0.4 (auto-synced by CI — see [sdk-versions.md](./sdk-versions.md))\n- **Runtime**: Node.js 20+, Bun, browsers\n- **Bundle formats**: ESM, CJS, IIFE (via unpkg/jsdelivr)\n- **Dependencies**: 0 runtime deps\n- **Peer deps**: `ws` (only for Node < 22, which lacks native WebSocket)\n\n## Browser Usage\n\nThe SDK works in browsers out of the box. Use ESM imports or the IIFE bundle:\n\n```html\n<script src=\"https://unpkg.com/@gladiaio/sdk/dist/index.iife.js\"></script>\n<script>\n  const client = new GladiaSDK.GladiaClient({ apiKey: \"...\" });\n</script>\n```\n\n### API Key Security in Browsers\n\nNever expose your API key in client-side code for production. Instead, use a proxy:\n\n```typescript\n// Point the SDK at your backend proxy (no apiKey needed)\nconst client = new GladiaClient({\n  apiUrl: \"https://your-server.com/api/gladia\",\n});\n```\n\nYour backend proxy adds the `x-gladia-key` header before forwarding to `api.gladia.io`.\n\n## File Upload in Browsers\n\nUse `File` or `Blob` objects for uploads:\n\n```typescript\nconst fileInput = document.querySelector('input[type=\"file\"]');\nconst file = fileInput.files[0];\n\nconst result = await client.preRecorded().transcribe(file, {\n  language_config: { languages: [\"en\"] },\n});\n```\n\n## Node.js Specifics\n\n### File path input\n\n```typescript\n// Node: pass a file path string\nconst result = await client\n  .preRecorded()\n  .transcribe(\"./recordings/meeting.wav\", options);\n```\n\n### WebSocket for Node < 22\n\nNode versions before 22 don't have native WebSocket. Install the `ws` package:\n\n```bash\nnpm install ws\n```\n\nThe SDK auto-detects and uses it. Node 22+ uses the built-in `WebSocket` global.\n\n### Streaming audio from a file\n\n```typescript\nimport { createReadStream } from \"fs\";\n\nconst session = client.liveV2().startSession({\n  encoding: \"wav/pcm\",\n  sample_rate: 16000,\n  bit_depth: 16,\n  channels: 1,\n  language_config: { languages: [\"en\"] },\n});\n\nsession.once(\"started\", () => {\n  const stream = createReadStream(\"./audio.pcm\", { highWaterMark: 3200 });\n  stream.on(\"data\", (chunk) => session.sendAudio(chunk));\n  stream.on(\"end\", () => session.stopRecording());\n});\n```\n\n### Streaming from microphone (Node)\n\nUse a library like `node-mic` or `node-record-lpcm16`:\n\n```typescript\nimport mic from \"mic\";\n\nconst micInstance = mic({ rate: 16000, bitwidth: 16, channels: 1 });\nconst micStream = micInstance.getAudioStream();\n\nsession.once(\"started\", () => {\n  micStream.on(\"data\", (chunk) => session.sendAudio(chunk));\n  micInstance.start();\n});\n\n// Stop\nmicInstance.stop();\nsession.stopRecording();\n```\n\n## Untyped API\n\nFor maximum flexibility or when migrating from raw HTTP calls:\n\n```typescript\n// Pass raw JSON matching the API schema\nconst result = await client.preRecorded().createUntyped({\n  audio_url: \"https://example.com/audio.mp3\",\n  diarization: true,\n  custom_field: \"value\",\n});\n\n// Full untyped transcribe flow\nconst result = await client.preRecorded().transcribeUntyped(\"./file.mp3\", {\n  language_config: { languages: [\"en\"] },\n});\n```\n\n## TypeScript Types\n\nAll types are exported from the main package:\n\n```typescript\nimport type {\n  GladiaClientOptions,\n  PreRecordedV2TranscriptionOptions,\n  PreRecordedV2Response,\n  PreRecordedV2InitTranscriptionRequest,\n  LiveV2InitRequest,\n  LiveV2Session,\n  LiveV2WebSocketMessage,\n  LiveV2TranscriptMessage,\n} from \"@gladiaio/sdk\";\n```\n\n## Error Handling\n\nThe JS SDK throws standard `Error` objects. Check the message for HTTP status codes:\n\n```typescript\ntry {\n  await client.preRecorded().transcribe(audio, options);\n} catch (err) {\n  if (err instanceof Error) {\n    if (err.message.includes(\"401\")) {\n      /* auth error */\n    }\n    if (err.message.includes(\"429\")) {\n      /* rate limited */\n    }\n    if (err.message.includes(\"timeout\")) {\n      /* timed out */\n    }\n  }\n}\n```\n\n## Live Session Event Typing\n\n```typescript\nimport type { LiveV2WebSocketMessage } from \"@gladiaio/sdk\";\n\nsession.on(\"message\", (msg: LiveV2WebSocketMessage) => {\n  // msg.type is a discriminated union\n  if (msg.type === \"transcript\") {\n    msg.data.is_final; // boolean\n    msg.data.utterance.text; // string\n  }\n});\n```\n\n## CDN / IIFE Bundle\n\nFor quick prototyping without a bundler:\n\n```html\n<script src=\"https://cdn.jsdelivr.net/npm/@gladiaio/sdk/dist/index.iife.js\"></script>\n```\n\nGlobal namespace: `window.GladiaSDK`\n\n## Package Size\n\n~741 KB unpacked (134 files). Tree-shaking-friendly ESM exports keep bundle size small when using a bundler.\n\nFile v1.0.1:references/python.md\n\n# Python SDK\n\nPatterns and details specific to the `gladiaio-sdk` package.\n\n## Contents\n\n- Package Info\n- Sync vs Async (including async live session)\n- Client Method Aliases\n- Typed Request Objects (dataclass-style and dict alternative)\n- File Input Types\n- Session ID Access\n- Error Types\n- Event Handling (pyee EventEmitter pattern)\n- Streaming Audio from File\n- Streaming from Microphone (PyAudio)\n- Response Access\n- Package Structure (exports)\n\n## Package Info\n\n- **PyPI**: [gladiaio-sdk](https://pypi.org/project/gladiaio-sdk/)\n- **Version**: 1.0.2 (auto-synced by CI — see [sdk-versions.md](./sdk-versions.md))\n- **Runtime**: Python 3.10+\n- **Dependencies**: httpx, websockets, pyee\n\n## Sync vs Async\n\nThe Python SDK provides both synchronous and asynchronous clients:\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\nclient = GladiaClient(api_key=\"YOUR_KEY\")\n\n# Sync\nresult = client.prerecorded().transcribe(\"audio.mp3\", options)\n\n# Async\nresult = await client.prerecorded_async().transcribe(\"audio.mp3\", options)\n```\n\n### Async live session\n\n```python\nimport asyncio\nfrom gladiaio_sdk import GladiaClient, LiveV2InitRequest, LiveV2LanguageConfig\n\nasync def main():\n    client = GladiaClient(api_key=\"YOUR_KEY\")\n    live_client = client.live_async()\n    session_done = asyncio.Event()\n\n    session = live_client.start_session(\n        LiveV2InitRequest(\n            model=\"solaria-1\",\n            encoding=\"wav/pcm\",\n            sample_rate=16000,\n            bit_depth=16,\n            channels=1,\n            language_config=LiveV2LanguageConfig(languages=[\"en\"]),\n        )\n    )\n\n    @session.once(\"ended\")\n    def on_ended(msg):\n        session_done.set()\n\n    session.send_audio(audio_bytes)\n    session.stop_recording()\n    await session_done.wait()\n\nasyncio.run(main())\n```\n\n## Client Method Aliases\n\n| Primary                      | Aliases                                             |\n| ---------------------------- | --------------------------------------------------- |\n| `client.prerecorded()`       | `client.pre_recorded()`, `client.pre_recorded_v2()` |\n| `client.prerecorded_async()` | `client.pre_recorded_async()`                       |\n| `client.live()`              | `client.live_v2()`                                  |\n| `client.live_async()`        | `client.live_v2_async()`                            |\n\n## Typed Request Objects\n\nPython uses dataclass-style request objects for type safety:\n\n```python\nfrom gladiaio_sdk import (\n    LiveV2InitRequest,\n    LiveV2LanguageConfig,\n    LiveV2MessagesConfig,\n    LiveV2PreProcessing,\n    LiveV2RealtimeProcessing,\n    LiveV2PostProcessing,\n)\n\nrequest = LiveV2InitRequest(\n    model=\"solaria-1\",\n    encoding=\"wav/pcm\",\n    sample_rate=16000,\n    bit_depth=16,\n    channels=1,\n    language_config=LiveV2LanguageConfig(\n        languages=[\"en\", \"fr\"],\n        code_switching=True,\n    ),\n    messages_config=LiveV2MessagesConfig(\n        receive_partial_transcripts=True,\n        receive_speech_events=True,\n    ),\n    pre_processing=LiveV2PreProcessing(\n        audio_enhancer=True,\n    ),\n)\n```\n\n### Dict alternative\n\nYou can also pass plain dicts for pre-recorded options:\n\n```python\nresult = client.prerecorded().transcribe(\n    \"audio.mp3\",\n    {\n        \"language_config\": {\"languages\": [\"en\"]},\n        \"diarization\": True,\n        \"translation\": True,\n        \"translation_config\": {\"target_languages\": [\"fr\"]},\n    },\n)\n```\n\n## File Input Types\n\n```python\nfrom pathlib import Path\n\n# String path\nresult = client.prerecorded().transcribe(\"audio.mp3\", options)\n\n# Path object\nresult = client.prerecorded().transcribe(Path(\"audio.mp3\"), options)\n\n# URL (no upload needed)\nresult = client.prerecorded().transcribe(\"https://example.com/audio.mp3\", options)\n\n# Binary file object\nwith open(\"audio.mp3\", \"rb\") as f:\n    result = client.prerecorded().transcribe(f, options)\n```\n\n## Session ID Access\n\n```python\n# Sync: available after 'started' event fires\n@session.once(\"started\")\ndef on_started(response):\n    print(f\"Session ID: {response.id}\")\n    # Also: session.session_id\n\n# Async: use await\nsession_id = await session.get_session_id()\n```\n\n## Error Types\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\ntry:\n    result = client.prerecorded().transcribe(\"audio.mp3\", options)\nexcept Exception as e:\n    # HttpError for HTTP failures (401, 429, 500, etc.)\n    # TimeoutError for timeout\n    print(f\"Error: {type(e).__name__}: {e}\")\n```\n\n## Event Handling\n\nUses `pyee` (EventEmitter pattern):\n\n```python\nfrom gladiaio_sdk import LiveV2WebSocketMessage, LiveV2InitResponse, LiveV2EndedMessage\n\n@session.on(\"message\")\ndef on_message(message: LiveV2WebSocketMessage):\n    if message.type == \"transcript\":\n        if message.data.is_final:\n            print(f\"Final: {message.data.utterance.text}\")\n\n@session.once(\"started\")\ndef on_started(response: LiveV2InitResponse):\n    print(f\"Session {response.id} started\")\n\n@session.on(\"error\")\ndef on_error(error: Exception):\n    print(f\"Error: {error}\")\n\n@session.once(\"ended\")\ndef on_ended(ended: LiveV2EndedMessage):\n    print(\"Session ended\")\n```\n\n## Streaming Audio from File\n\n```python\nimport time\n\nCHUNK_SIZE = 3200  # 100ms of 16-bit mono at 16kHz\n\nwith open(\"audio.pcm\", \"rb\") as f:\n    while chunk := f.read(CHUNK_SIZE):\n        session.send_audio(chunk)\n        time.sleep(0.1)  # Real-time pacing\n\nsession.stop_recording()\n```\n\n## Streaming from Microphone\n\nUsing PyAudio:\n\n```python\nimport pyaudio\n\nRATE = 16000\nCHUNK = 3200\nFORMAT = pyaudio.paInt16\nCHANNELS = 1\n\np = pyaudio.PyAudio()\nstream = p.open(format=FORMAT, channels=CHANNELS, rate=RATE,\n                input=True, frames_per_buffer=CHUNK)\n\ntry:\n    while True:\n        data = stream.read(CHUNK)\n        session.send_audio(data)\nexcept KeyboardInterrupt:\n    pass\nfinally:\n    stream.stop_stream()\n    stream.close()\n    session.stop_recording()\n```\n\n## Response Access\n\nPre-recorded responses use attribute access:\n\n```python\nresult = client.prerecorded().transcribe(\"audio.mp3\", options)\n\n# Access nested fields\nprint(result.status)                                    # \"done\"\nprint(result.result.transcription.full_transcript)      # Full text\nfor utterance in result.result.transcription.utterances:\n    print(f\"[{utterance.start}-{utterance.end}] {utterance.text}\")\n```\n\n## Package Structure\n\nAll public types are exported from the top-level `gladiaio_sdk` module:\n\n```python\nfrom gladiaio_sdk import (\n    GladiaClient,\n    # Pre-recorded\n    PreRecordedV2Response,\n    # Live\n    LiveV2InitRequest,\n    LiveV2InitResponse,\n    LiveV2EndedMessage,\n    LiveV2WebSocketMessage,\n    LiveV2LanguageConfig,\n    LiveV2MessagesConfig,\n    LiveV2PreProcessing,\n    LiveV2RealtimeProcessing,\n    LiveV2PostPr\n\nArchive v1.0.0: 7 files, 11762 bytes\n\nFiles: references/client-config.md (2299b), references/javascript.md (4931b), references/python.md (6723b), references/sdk-versions.md (737b), skill-card.md (2697b), SKILL.md (11459b), _meta.json (141b)","readmeExcerpt":"Skill: gladia-sdk-integration Owner: gladiaio Summary: Install and configure the official Gladia SDKs (@gladiaio/sdk for JS/TS, gladiaio-sdk for Python). Use when the user asks about SDK setup, client initialization, API key configuration, choosing between JS and Python, browser usage, retry/timeout settings, error handling, or SDK vs raw API decisions. The SDK is the recommended default for all Gladia integrations. ","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"npm install @gladiaio/sdk\n# or\nbun add @gladiaio/sdk\n# or\nyarn add @gladiaio/sdk"},{"language":"bash","snippet":"pip install gladiaio-sdk\n# or\nuv add gladiaio-sdk"},{"language":"typescript","snippet":"import { GladiaClient } from \"@gladiaio/sdk\";\n\nconst client = new GladiaClient({\n  apiKey: \"your-api-key\", // or set GLADIA_API_KEY env var\n  region: \"eu-west\", // or set GLADIA_REGION (eu-west | us-west)\n});"},{"language":"python","snippet":"from gladiaio_sdk import GladiaClient\n\nclient = GladiaClient(\n    api_key=\"your-api-key\",      # or set GLADIA_API_KEY env var\n    region=\"eu-west\",            # or set GLADIA_REGION\n)"},{"language":"text","snippet":"GladiaClient\n├── preRecorded()  → PreRecordedV2Client    (JS)\n│   prerecorded()  → PreRecordedV2Client    (Python)\n│\n├── liveV2()       → LiveV2Client           (JS)\n│   live()         → LiveV2Client           (Python)\n│\n└── (Python only)\n    ├── prerecorded_async() → AsyncPreRecordedV2Client\n    └── live_async()        → AsyncLiveV2Client"},{"language":"typescript","snippet":"try {\n  const result = await client.preRecorded().transcribe(\"./audio.mp3\", options);\n} catch (error) {\n  if (error.message.includes(\"401\")) {\n    console.error(\"Invalid API key\");\n  } else if (error.message.includes(\"timeout\")) {\n    console.error(\"Request timed out\");\n  }\n}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: gladia-sdk-integration\ndescription: Install and configure the official Gladia SDKs (@gladiaio/sdk for JS/TS, gladiaio-sdk for Python). Use when the user asks about SDK setup, client initialization, API key configuration, choosing between JS and Python, browser usage, retry/timeout settings, error handling, or SDK vs raw API decisions. The SDK is the recommended default for all Gladia integrations.\nlicense: MIT\n---\n\n# SDK Integration\n\nOfficial SDKs for integrating Gladia's speech-to-text API. Both SDKs share the same design and are generated from the Gladia OpenAPI schema.\n\n> **The SDK is the default for all Gladia integrations.** Always use the SDK unless there is a specific, documented reason not to (see decision guide below).\n\n## When to Use\n\n- User asks about installing, configuring, or initializing the Gladia SDK\n- Setting up API key, region, retry, timeout, or WebSocket configuration\n- Questions about SDK architecture, client methods, or type exports\n- Choosing between JS/TS and Python SDK, or between SDK and raw API\n- Browser-based integration, proxy setup, or bundle format questions\n- Error handling patterns for Gladia API responses\n\n**When NOT to use:** If the user is asking about a specific transcription use case (pre-recorded files or live streaming), start with the relevant use-case skill ([gladia-pre-recorded-transcription](../gladia-pre-recorded-transcription/SKILL.md) or [gladia-live-transcription](../gladia-live-transcription/SKILL.md)) instead — those skills reference back here for setup details.\n\n## When to Use SDK vs Raw API\n\n| Scenario                                 | Approach                                                                                                      |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- |\n| Any JS/TS or Python project              | **SDK** — always                                                                                              |\n| Browser app                              | **SDK** — JS SDK supports ESM/IIFE bundles                                                                    |\n| Need custom HTTP client or middleware    | SDK first; use `httpHeaders` / `httpTimeout` config. Fall back to raw REST only if SDK config is insufficient |\n| Language without an SDK (Go, Java, etc.) | Raw REST/WebSocket (SDK unavailable)                                                                          |\n| User explicitly requests raw calls       | Raw REST/WebSocket                                                                                            |\n| CI script or one-off curl test           | Raw REST is acceptable                                                                                        |\n| Terminal one-off with gladia-cli on PATH | **CLI** — see [gladia-using-cli](../gladia-using-cli/SKILL.md)                                                |\n\nWhen i"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7fs6cmj9hqg7232sbkacf31d882wp2\",\n  \"slug\": \"gladia-sdk-integration\",\n  \"version\": \"1.0.5\",\n  \"publishedAt\": 1790953718008\n}"},{"path":"references/client-config.md","content":"# Full Client Configuration Reference\n\nComplete configuration options for `GladiaClient` constructor.\n\n## Contents\n\n- Full Config Example (JavaScript/TypeScript)\n- Config Summary Table\n\n## Full Config Example\n\n```typescript\nconst client = new GladiaClient({\n  apiKey: \"your-key\",\n  apiUrl: \"https://api.gladia.io\",\n  region: \"eu-west\",\n\n  // HTTP settings\n  httpHeaders: { \"X-Custom-Header\": \"value\" },\n  httpTimeout: 10000, // 10s default\n  httpRetry: {\n    maxRetries: 3,\n    retryDelay: 1000,\n  },\n\n  // WebSocket settings\n  wsRetry: {\n    maxRetries: 5,\n    retryDelay: 1000,\n  },\n  wsTimeout: 30000,\n\n  // Pre-recorded operation timeouts\n  prerecordedTimeouts: {\n    transcribe: 7200000, // 2 hours (full flow)\n    poll: 7200000,\n    upload: 300000, // 5 minutes\n    create: 30000,\n    get: 10000,\n    delete: 10000,\n    getFile: 60000,\n  },\n\n  // Live operation timeouts\n  liveTimeouts: {\n    get: 10000,\n    delete: 10000,\n    getFile: 60000,\n  },\n});\n```\n\n## Config Summary\n\n| Option                  | Type     | Default                 | Description                |\n| ----------------------- | -------- | ----------------------- | -------------------------- |\n| `apiKey`                | `string` | `GLADIA_API_KEY` env    | API key                    |\n| `apiUrl`                | `string` | `https://api.gladia.io` | Base API URL               |\n| `region`                | `string` | `GLADIA_REGION` env     | `eu-west` or `us-west`     |\n| `httpHeaders`           | `object` | `{}`                    | Custom HTTP headers        |\n| `httpTimeout`           | `number` | `10000`                 | HTTP request timeout (ms)  |\n| `httpRetry.maxRetries`  | `number` | `3`                     | Max HTTP retries           |\n| `httpRetry.retryDelay`  | `number` | `1000`                  | Delay between retries (ms) |\n| `wsRetry.maxRetries`    | `number` | `5`                     | Max WebSocket reconnects   |\n| `wsRetry.retryDelay`    | `number` | `1000`                  | WS reconnect delay (ms)    |\n| `wsTimeout`             | `number` | `30000`                 | WebSocket timeout (ms)     |\n| `prerecordedTimeouts.*` | `number` | varies                  | Per-operation timeouts     |\n| `liveTimeouts.*`        | `number` | varies                  | Per-operation timeouts     |"},{"path":"references/javascript.md","content":"# JavaScript / TypeScript SDK\n\nPatterns and details specific to the `@gladiaio/sdk` package.\n\n## Contents\n\n- Package Info\n- Browser Usage (ESM, IIFE, API key security via proxy)\n- File Upload in Browsers\n- Node.js Specifics (file paths, WebSocket for Node < 22, streaming from file/mic)\n- Untyped API\n- TypeScript Types\n- Error Handling\n- Live Session Event Typing\n- CDN / IIFE Bundle\n- Package Size\n\n## Package Info\n\n- **npm**: [@gladiaio/sdk](https://www.npmjs.com/package/@gladiaio/sdk)\n- **Version**: 2.1.0\n- **Runtime**: Node.js 20+, Bun, browsers\n- **Bundle formats**: ESM, CJS, IIFE (via unpkg/jsdelivr)\n- **Dependencies**: 0 runtime deps\n- **Peer deps**: `ws` (only for Node < 22, which lacks native WebSocket)\n\n## Browser Usage\n\nThe SDK works in browsers out of the box. Use ESM imports or the IIFE bundle:\n\n```html\n<script src=\"https://unpkg.com/@gladiaio/sdk/dist/index.iife.js\"></script>\n<script>\n  const client = new GladiaSDK.GladiaClient({ apiKey: \"...\" });\n</script>\n```\n\n### API Key Security in Browsers\n\nNever expose your API key in client-side code for production. Instead, use a proxy:\n\n```typescript\n// Point the SDK at your backend proxy (no apiKey needed)\nconst client = new GladiaClient({\n  apiUrl: \"https://your-server.com/api/gladia\",\n});\n```\n\nYour backend proxy adds the `x-gladia-key` header before forwarding to `api.gladia.io`.\n\n## File Upload in Browsers\n\nUse `File` or `Blob` objects for uploads:\n\n```typescript\nconst fileInput = document.querySelector('input[type=\"file\"]');\nconst file = fileInput.files[0];\n\nconst result = await client.preRecorded().transcribe(file, {\n  language_config: { languages: [\"en\"] },\n});\n```\n\n## Node.js Specifics\n\n### File path input\n\n```typescript\n// Node: pass a file path string\nconst result = await client\n  .preRecorded()\n  .transcribe(\"./recordings/meeting.wav\", options);\n```\n\n### WebSocket for Node < 22\n\nNode versions before 22 don't have native WebSocket. Install the `ws` package:\n\n```bash\nnpm install ws\n```\n\nThe SDK auto-detects and uses it. Node 22+ uses the built-in `WebSocket` global.\n\n### Streaming audio from a file\n\n```typescript\nimport { createReadStream } from \"fs\";\n\nconst session = client.liveV2().startSession({\n  encoding: \"wav/pcm\",\n  sample_rate: 16000,\n  bit_depth: 16,\n  channels: 1,\n  language_config: { languages: [\"en\"] },\n});\n\nsession.once(\"started\", () => {\n  const stream = createReadStream(\"./audio.pcm\", { highWaterMark: 3200 });\n  stream.on(\"data\", (chunk) => session.sendAudio(chunk));\n  stream.on(\"end\", () => session.stopRecording());\n});\n```\n\n### Streaming from microphone (Node)\n\nUse a library like `node-mic` or `node-record-lpcm16`:\n\n```typescript\nimport mic from \"mic\";\n\nconst micInstance = mic({ rate: 16000, bitwidth: 16, channels: 1 });\nconst micStream = micInstance.getAudioStream();\n\nsession.once(\"started\", () => {\n  micStream.on(\"data\", (chunk) => session.sendAudio(chunk));\n  micInstance.start();\n});\n\n// Stop\nmicInstance.stop();\nsession.stopRecording();\n```\n\n## Untyped API\n\nFor max"},{"path":"references/python.md","content":"# Python SDK\n\nPatterns and details specific to the `gladiaio-sdk` package.\n\n## Contents\n\n- Package Info\n- Sync vs Async (including async live session)\n- Client Method Aliases\n- Typed Request Objects (dataclass-style and dict alternative)\n- File Input Types\n- Session ID Access\n- Error Types\n- Event Handling (pyee EventEmitter pattern)\n- Streaming Audio from File\n- Streaming from Microphone (PyAudio)\n- Response Access\n- Package Structure (exports)\n\n## Package Info\n\n- **PyPI**: [gladiaio-sdk](https://pypi.org/project/gladiaio-sdk/)\n- **Version**: 2.1.0\n- **Runtime**: Python 3.10+\n- **Dependencies**: httpx, websockets, pyee\n\n## Sync vs Async\n\nThe Python SDK provides both synchronous and asynchronous clients:\n\n```python\nfrom gladiaio_sdk import GladiaClient\n\nclient = GladiaClient(api_key=\"YOUR_KEY\")\n\n# Sync\nresult = client.prerecorded().transcribe(\"audio.mp3\", options)\n\n# Async\nresult = await client.prerecorded_async().transcribe(\"audio.mp3\", options)\n```\n\n### Async live session\n\n```python\nimport asyncio\nfrom gladiaio_sdk import GladiaClient, LiveV2InitRequest, LiveV2LanguageConfig\n\nasync def main():\n    client = GladiaClient(api_key=\"YOUR_KEY\")\n    live_client = client.live_async()\n    session_done = asyncio.Event()\n\n    session = live_client.start_session(\n        LiveV2InitRequest(\n            model=\"solaria-1\",\n            encoding=\"wav/pcm\",\n            sample_rate=16000,\n            bit_depth=16,\n            channels=1,\n            language_config=LiveV2LanguageConfig(languages=[\"en\"]),\n        )\n    )\n\n    @session.once(\"ended\")\n    def on_ended(msg):\n        session_done.set()\n\n    session.send_audio(audio_bytes)\n    session.stop_recording()\n    await session_done.wait()\n\nasyncio.run(main())\n```\n\n## Client Method Aliases\n\n| Primary                      | Aliases                                             |\n| ---------------------------- | --------------------------------------------------- |\n| `client.prerecorded()`       | `client.pre_recorded()`, `client.pre_recorded_v2()` |\n| `client.prerecorded_async()` | `client.pre_recorded_async()`                       |\n| `client.live()`              | `client.live_v2()`                                  |\n| `client.live_async()`        | `client.live_v2_async()`                            |\n\n## Typed Request Objects\n\nPython uses dataclass-style request objects for type safety:\n\n```python\nfrom gladiaio_sdk import (\n    LiveV2InitRequest,\n    LiveV2LanguageConfig,\n    LiveV2MessagesConfig,\n    LiveV2PreProcessing,\n    LiveV2RealtimeProcessing,\n    LiveV2PostProcessing,\n)\n\nrequest = LiveV2InitRequest(\n    model=\"solaria-1\",\n    encoding=\"wav/pcm\",\n    sample_rate=16000,\n    bit_depth=16,\n    channels=1,\n    language_config=LiveV2LanguageConfig(\n        languages=[\"en\", \"fr\"],\n        code_switching=True,\n    ),\n    messages_config=LiveV2MessagesConfig(\n        receive_partial_transcripts=True,\n        receive_speech_events=True,\n    ),\n    pre_processing=LiveV2PreProcessing(\n        audio_enhancer=True,"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1551,"uniquenessScore":42,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T17:27:04.642Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T17:27:04.642Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T21:43:24.690Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}