@pouchy_ai/admin-sdk 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.24.0 — 2026-08-08
+
+- **New method `synthesizeSpeech`** (additive; nothing renamed or removed):
+  `POST /v1/admin/utility/tts`. Text → a spoken-audio mp3 FILE, OUTSIDE the
+  companion and OUTSIDE a realtime `/call` — the audio sibling of `extractJson`.
+  Stateless (no session, no persona, no memory); the voice is a catalog id
+  (`std_…` / `hd_…`) or `providerVoiceId` from `listVoices()`, the same id used
+  for a call's voice, restricted to enabled catalog rows + the built-in OpenAI
+  roster. Returns `{ data: { audioBase64, mimeType, format, voiceId, provider,
+  model }, usage: { characterCount } }`; failures are typed
+  (`voice_not_found`, `text_too_long`, `unsupported_format`, `unavailable`,
+  `provider_error`). Synthesis bills on your provider account like the other
+  voice planes — no separate platform credit rate; bounded by an input cap +
+  a per-project rate limit.
+
 ## 0.23.0 — 2026-08-08
 
 - **`ChannelTransportType` grows 6 members** (additive; nothing renamed or

package/README.md

@@ -153,6 +153,34 @@ completion arrived but did not parse or satisfy the schema; the error carries
 `raw`, the text actually returned). Tokens roll into the project's month usage
 like any other model call.
 
+### Spoken audio — use `synthesizeSpeech`, not `/call`
+
+The audio sibling of `extractJson`: text → a downloadable **mp3 file**, OUTSIDE
+the companion and OUTSIDE a realtime call. `/call` is live ConvAI (a WebRTC
+session); when you need an audio **file** for a headless / Ops job — a reference
+clip for a downstream video / lip-sync API, a pre-rendered notification — this
+is the stateless path.
+
+```ts
+const { data, usage } = await admin.synthesizeSpeech({
+  text: 'Hey — just wanted to share this moment with you.',
+  voice: 'hd_ByhETIclHirOlWnWKhHc' // a catalog id OR providerVoiceId from listVoices()
+});
+// data.audioBase64 is the mp3 — decode and persist it (never hand a provider URL
+// to a client). In Node: Buffer.from(data.audioBase64, 'base64'); in a browser:
+// Uint8Array.from(atob(data.audioBase64), (c) => c.charCodeAt(0)).
+console.log(data.mimeType, data.voiceId, data.provider, usage.characterCount);
+```
+
+`voice` is the **same id you pass to a call's voice** (from `listVoices()`),
+restricted to enabled catalog rows plus the built-in OpenAI roster — so the Ops
+sample and the live call use one authoritative voice. Only `mp3` is produced in
+v1. Failures are typed: `voice_not_found` (404), `text_too_long` (413),
+`unsupported_format` (400), `unavailable` (503 — no TTS provider configured for
+that voice), `provider_error` (502). Synthesis bills on your provider account
+like the other voice planes — there is no separate platform credit rate; it is
+bounded by an input cap and a per-project rate limit.
+
 Every skill knob (`setSkillRate`, `setSkillDailyCap`, `grantSkill`) returns
 `SkillKnobResult<T>` — the knob you set plus `reprovisioned` (instances the new
 def reached) and `truncated`. A knob only binds a running agent once the def

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.23.0";
+export declare const ADMIN_SDK_VERSION = "0.24.0";
 export declare const DEFAULT_BASE_URL = "https://pouchy.ai/v1/admin";
 /** Deadline for the routes whose server handler declares `maxDuration: 300` —
  *  the server's own ceiling plus headroom, so a client abort can only ever mean
@@ -711,6 +711,43 @@ export interface AdminClient {
             completionTokens: number;
         };
     }>;
+    /** Text → a spoken-audio FILE, OUTSIDE the companion and OUTSIDE a realtime
+     *  call. The audio sibling of `extractJson`: stateless (no session, no
+     *  persona, no memory), one synthesis call, a downloadable clip back. Use it
+     *  for headless / Ops audio — e.g. a reference clip for a downstream
+     *  video / lip-sync API — where `/call` (live ConvAI) does not fit.
+     *
+     *  `voice` is a catalog id (`std_…` / `hd_…`) or a `providerVoiceId` from
+     *  `listVoices()` — the SAME id you pass to a call's voice — restricted to
+     *  enabled catalog rows plus the built-in OpenAI roster. `data.audioBase64`
+     *  is the mp3 bytes; decode and persist them (never hand a provider URL to a
+     *  client). Only `mp3` is produced in v1.
+     *
+     *  Failures are typed, not audio: `voice_not_found` (404),
+     *  `text_too_long` (413), `unsupported_format` (400), `unavailable` (503 —
+     *  no TTS provider configured for that voice), `provider_error` (502).
+     *
+     *  Synthesis bills on your provider account (like the platform voice
+     *  planes), bounded by an input cap and a per-project rate limit — there is
+     *  no separate platform credit rate. */
+    synthesizeSpeech(input: {
+        text: string;
+        voice: string;
+        format?: 'mp3';
+        model?: string;
+    }): Promise<{
+        data: {
+            audioBase64: string;
+            mimeType: string;
+            format: 'mp3';
+            voiceId: string;
+            provider: 'openAI' | 'elevenLabs';
+            model: string;
+        };
+        usage: {
+            characterCount: number;
+        };
+    }>;
     deleteKnowledge(docId: string): Promise<{
         deleted: boolean;
     }>;

package/dist/index.js

@@ -8,7 +8,7 @@
 //   import { createAdminClient } from '@pouchy_ai/admin-sdk';
 //   const admin = createAdminClient({ adminKey: process.env.POUCHY_ADMIN_KEY! });
 //   const { agents } = await admin.listAgents();
-export const ADMIN_SDK_VERSION = '0.23.0';
+export const ADMIN_SDK_VERSION = '0.24.0';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1/admin';
 /** Default per-request timeout (ms). A hung upstream otherwise never rejects. */
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -248,6 +248,7 @@ export function createAdminClient(opts) {
         ingestKnowledgeUrl: (input) => request('POST', '/knowledge/url', input),
         searchKnowledge: (query) => request('POST', '/knowledge/search', { query }),
         extractJson: (input) => request('POST', '/utility/json', input),
+        synthesizeSpeech: (input) => request('POST', '/utility/tts', input),
         deleteKnowledge: (id) => request('DELETE', `/knowledge/${encodeURIComponent(id)}`),
         listSkills: () => request('GET', '/skills'),
         installSkill: (input) => request('POST', '/skills', input),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pouchy_ai/admin-sdk",
-	"version": "0.23.0",
+	"version": "0.24.0",
 	"description": "Typed TypeScript client for the Pouchy Admin API \u2014 manage agents, keys, end users, knowledge, skills, channels, schedules, webhooks and credentials headlessly, with a project Admin key.",
 	"type": "module",
 	"license": "SEE LICENSE IN LICENSE",