@runapi.ai/elevenlabs 0.2.0 → 0.2.3

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { AsyncTaskStatus, HttpClient, RequestOptions, PollingOptions, ClientOptions } from '@runapi.ai/core';
 export { AuthenticationError, InsufficientCreditsError, NetworkError, NotFoundError, RateLimitError, RunApiError, ServiceUnavailableError, TaskFailedError, TaskTimeoutError, TimeoutError, ValidationError } from '@runapi.ai/core';
 
-type ElevenlabsSpeechModel = 'text-to-speech-turbo-2-5' | 'text-to-speech-multilingual-v2';
+type ElevenlabsSpeechModel = 'text-to-speech-turbo-v2.5' | 'text-to-speech-multilingual-v2';
 type ElevenlabsSoundEffectOutputFormat = 'mp3_22050_32' | 'mp3_44100_32' | 'mp3_44100_64' | 'mp3_44100_96' | 'mp3_44100_128' | 'mp3_44100_192' | 'pcm_8000' | 'pcm_16000' | 'pcm_22050' | 'pcm_24000' | 'pcm_44100' | 'pcm_48000' | 'ulaw_8000' | 'alaw_8000' | 'opus_48000_32' | 'opus_48000_64' | 'opus_48000_96' | 'opus_48000_128' | 'opus_48000_192';
 interface TaskCreateResponse {
     id: string;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { AsyncTaskStatus, HttpClient, RequestOptions, PollingOptions, ClientOptions } from '@runapi.ai/core';
 export { AuthenticationError, InsufficientCreditsError, NetworkError, NotFoundError, RateLimitError, RunApiError, ServiceUnavailableError, TaskFailedError, TaskTimeoutError, TimeoutError, ValidationError } from '@runapi.ai/core';
 
-type ElevenlabsSpeechModel = 'text-to-speech-turbo-2-5' | 'text-to-speech-multilingual-v2';
+type ElevenlabsSpeechModel = 'text-to-speech-turbo-v2.5' | 'text-to-speech-multilingual-v2';
 type ElevenlabsSoundEffectOutputFormat = 'mp3_22050_32' | 'mp3_44100_32' | 'mp3_44100_64' | 'mp3_44100_96' | 'mp3_44100_128' | 'mp3_44100_192' | 'pcm_8000' | 'pcm_16000' | 'pcm_22050' | 'pcm_24000' | 'pcm_44100' | 'pcm_48000' | 'ulaw_8000' | 'alaw_8000' | 'opus_48000_32' | 'opus_48000_64' | 'opus_48000_96' | 'opus_48000_128' | 'opus_48000_192';
 interface TaskCreateResponse {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runapi.ai/elevenlabs",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "RunAPI ElevenLabs SDK for JavaScript, Ruby, and Go",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -28,7 +28,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@runapi.ai/core": "^0.2.0"
+    "@runapi.ai/core": "^0.2.3"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/skills/elevenlabs/README.md

@@ -1,4 +1,25 @@
-# ElevenLabs API Skill for RunAPI
+<p align="center">
+  <a href="https://github.com/runapi-ai/elevenlabs">
+    <h3 align="center">ElevenLabs API Skill for RunAPI</h3>
+  </a>
+</p>
+
+<p align="center">
+  Install this agent skill, inspect ElevenLabs fields, then run jobs through the RunAPI CLI.
+</p>
+
+<p align="center">
+  <a href="https://runapi.ai/models/elevenlabs"><strong>Model Reference</strong></a> · <a href="https://github.com/runapi-ai/cli"><strong>CLI</strong></a> · <a href="https://github.com/runapi-ai/elevenlabs-sdk"><strong>SDK</strong></a>
+</p>
+
+<div align="center">
+
+[![skills.sh](https://www.skills.sh/b/runapi-ai/elevenlabs)](https://www.skills.sh/runapi-ai/elevenlabs/elevenlabs)
+[![ClawHub](https://img.shields.io/badge/ClawHub-runapi--elevenlabs-111827)](https://clawhub.ai/runapi-ai/runapi-elevenlabs)
+[![License](https://img.shields.io/github/license/runapi-ai/elevenlabs)](https://github.com/runapi-ai/elevenlabs/blob/main/LICENSE)
+
+</div>
+<br/>
 
 Generate speech, dialogue, sound effects, transcriptions, and isolated audio with the ElevenLabs SDK. This skill helps Claude Code, Codex, Gemini CLI, Cursor, and 50+ agents integrate ElevenLabs through RunAPI.
 
@@ -10,7 +31,18 @@ The canonical agent file is `skills/elevenlabs/SKILL.md`.
 npx skills add runapi-ai/elevenlabs -g
 ```
 
-Or manually: clone this repo and copy `skills/elevenlabs/` into your agent's skills directory.
+Or paste this prompt to your AI agent:
+
+```text
+Install the elevenlabs skill for me:
+
+1. Clone https://github.com/runapi-ai/elevenlabs
+2. Copy the skills/elevenlabs/ directory into your
+   user-level skills directory (e.g. ~/.claude/skills/
+   for Claude Code, ~/.codex/skills/ for Codex).
+3. Verify that SKILL.md is present.
+4. Confirm the install path when done.
+```
 
 ## Quick example
 
@@ -19,7 +51,7 @@ import { ElevenlabsClient } from '@runapi.ai/elevenlabs';
 
 const client = new ElevenlabsClient();
 const result = await client.textToSpeech.run({
-  model: 'text-to-speech-turbo-2-5',
+  model: 'text-to-speech-turbo-v2.5',
   text: 'Hello from RunAPI.',
   voice: 'Rachel',
 });

package/skills/elevenlabs/SKILL.md

@@ -1,211 +1,81 @@
 ---
 name: elevenlabs
-description: Generate and process audio (text-to-speech, multi-voice text-to-dialogue, text-to-sound, speech-to-text, isolate audio) through RunAPI.ai using the @runapi.ai/elevenlabs Node/TypeScript SDK. Use when the user asks to add text-to-speech, voice synthesis, speech-to-text, or text-to-sound, or writes against @runapi.ai/elevenlabs. Triggers on "elevenlabs", "text to speech", "TTS", "语音合成", "speech-to-text", "转录", "text-to-sound", "@runapi.ai/elevenlabs".
-documentation: https://runapi.ai/models/elevenlabs
-provider_page: https://runapi.ai/providers/elevenlabs
-catalog: https://runapi.ai/models
+description: Generate speech, dialogue, and sound with ElevenLabs through RunAPI. Use when the user asks an agent to create speech, dialogue, or sound effects, or transcribe audio with ElevenLabs. Default to the RunAPI CLI for one-off generation; use SDKs only when the user is integrating RunAPI into an app or backend.
+documentation: https://runapi.ai/models/elevenlabs.md
+provider_page: https://runapi.ai/providers/elevenlabs.md
+catalog: https://runapi.ai/models.md
+metadata:
+  openclaw:
+    homepage: https://runapi.ai/models/elevenlabs
+    requires:
+      bins:
+      - runapi
+    install:
+    - kind: brew
+      formula: runapi-ai/tap/runapi
+      bins:
+      - runapi
+    envVars:
+    - name: RUNAPI_API_KEY
+      required: false
+      description: Optional RunAPI API key; agents should prefer environment auth or saved CLI config. Browser login is interactive fallback only.
 ---
 
-# @runapi.ai/elevenlabs — RunAPI.ai Elevenlabs audio generation
+# ElevenLabs on RunAPI
 
-Build Node / TypeScript integrations that generate speech, text-to-dialogue, text-to-sound, speech-to-text, and isolated audio through RunAPI.ai.
+Generate speech, dialogue, and sound with ElevenLabs through RunAPI. The default path for one-off agent tasks is the `runapi` CLI; SDKs are for application integration.
 
-## Setup
+## Routing decision
 
-Requires **Node 18+** (global `fetch`).
+- One-off generation, editing, or transformation for the user → use the **CLI path** with the `runapi` binary.
+- Building an app, backend, worker, library, or production codebase → use the **SDK integration path**.
 
-```bash
-npm install @runapi.ai/elevenlabs
-```
-
-Set your API key in the environment:
-
-```dotenv
-# .env
-RUNAPI_API_KEY=runapi_xxx   # get one at https://runapi.ai/settings/api_keys
-```
-
-```ts
-import { ElevenlabsClient } from '@runapi.ai/elevenlabs';
-
-// The SDK reads RUNAPI_API_KEY from the environment automatically.
-const client = new ElevenlabsClient();
-```
-
-Pass `{ apiKey }` explicitly if you manage secrets differently. `baseUrl` defaults to `https://runapi.ai`; override only for local development.
+## CLI path
 
-## Core recipe — text to speech
+The `runapi` binary is the runtime dependency. Run `runapi auth status` first. For agents and headless runs, prefer `RUNAPI_API_KEY` or import it into saved config with `printf '%s' "$RUNAPI_API_KEY" | runapi auth import-token --token -`. Use `runapi login` only when the user explicitly wants interactive browser auth.
 
-```ts
-const result = await client.textToSpeech.run({
-  model: 'text-to-speech-turbo-2-5',
-  text: 'Hello from RunAPI.',
-  voice: 'Rachel',
-});
+Inspect the available actions and request fields with CLI help:
 
-const audioUrl = result.audios[0].url;
+```shell
+runapi elevenlabs --help
+runapi elevenlabs text-to-speech --help
 ```
 
-`run()` creates the task, auto-polls, and resolves only when the task completes — `audios[0].url` is guaranteed on the resolved value (for speech-to-text, `text` is guaranteed). On failure it throws `TaskFailedError`; on polling timeout it throws `TaskTimeoutError`. Use `run()` for scripts and short-lived processes. For request handlers, split it:
+Run a one-off task (synchronous — polls until the task completes):
 
-```ts
-const { id } = await client.textToSpeech.create({ model: 'text-to-speech-turbo-2-5', text: '...', voice: 'Rachel' });
-// return 202 immediately; fetch later:
-const status = await client.textToSpeech.get(id);
-if (status.status === 'completed') { /* ... */ }
+```shell
+runapi elevenlabs text-to-speech --input-file request.json
 ```
 
-Do not hold a web worker open waiting on `run()`. Split + webhook is the production pattern.
-
-`run()` polls every 2 s for up to 15 min by default. Tune when needed:
+Submit asynchronously and poll separately:
 
-```ts
-await client.textToSpeech.run(params, { maxWaitMs: 2 * 60_000, pollIntervalMs: 1_000 });
+```shell
+runapi elevenlabs text-to-speech --async --input-file request.json
+runapi wait <task-id> --service elevenlabs --action text-to-speech
 ```
 
-If `TaskTimeoutError` fires, the task is still running server-side — resume with `<resource>.get(id)` or finish via webhook.
+Available actions: `text-to-speech`, `text-to-dialogue`, `text-to-sound`, `speech-to-text`, `isolate-audio`.
 
-## Multi-voice dialogue
+## SDK integration path
 
-Sequence lines with per-line `voice`:
-
-```ts
-const dialogue = await client.textToDialogue.run({
-  dialogue: [
-    { voice: 'Rachel', text: 'So what did you think?' },
-    { voice: 'Adam',   text: 'Honestly, it was incredible.' },
-  ],
-  stability: 0.5,
-  language_code: 'en',
-});
-
-console.log(dialogue.audios[0].url);
-```
-
-## Sound effects
-
-```ts
-const fx = await client.textToSound.run({
-  text: 'Thunderclap followed by rain on a tin roof',
-  duration_seconds: 6,
-  loop: false,
-  output_format: 'mp3_44100_128',
-});
-```
-
-## Speech to Text (audio in → text out)
-
-```ts
-const t = await client.speechToText.run({
-  audio_url: 'https://cdn.example.com/meeting.mp3',
-  diarize: true,
-  tag_audio_events: true,
-  language_code: 'en',
-});
-
-console.log(t.text);
-```
-
-## Audio isolation (remove background noise)
-
-```ts
-const isolated = await client.isolateAudio.run({
-  audio_url: 'https://cdn.example.com/noisy.mp3',
-});
-
-console.log(isolated.audios[0].url);
-```
+When integrating ElevenLabs into an app, backend, worker, or library — not for one-off tasks — use a RunAPI SDK package:
 
-## Models
+- JavaScript / TypeScript: `@runapi.ai/elevenlabs`
+- Ruby: `runapi-elevenlabs`
+- Go: `github.com/runapi-ai/elevenlabs-sdk/go`
 
-| Resource | `model` values |
-|---|---|
-| `textToSpeech` | `text-to-speech-turbo-2-5`, `text-to-speech-multilingual-v2` |
-| `textToDialogue` | — (no `model` field; server picks the engine) |
-| `textToSound` | — |
-| `speechToText` | — |
-| `isolateAudio` | — |
-
-Pick the turbo model for the lowest latency; pick multilingual v2 for non-English voices. `voice` accepts Elevenlabs voice IDs or named voices (e.g. `'Rachel'`, `'Adam'`).
-
-Exact credit costs are shown at https://runapi.ai/pricing and in the dashboard — do not hardcode prices in application code.
-
-## Callbacks (webhooks)
-
-Pass `callback_url` on `create()` (or any `run()` call) and RunAPI will POST the final payload to you:
-
-```ts
-await client.textToSpeech.create({
-  model: 'text-to-speech-turbo-2-5',
-  text: '...',
-  voice: 'Rachel',
-  callback_url: 'https://your.app/webhooks/runapi/elevenlabs',
-});
-```
-
-Payload shape (audio resources):
-
-```ts
-{ id: string; status: 'completed' | 'failed'; audios?: { url: string }[]; error?: string }
-```
-
-SpeechToText return `text: string` instead of `audios`.
-
-**Always verify the signature before trusting the body.** RunAPI signs every callback with your account's Callback Secret (rotate at `/accounts/callback_secret`). Headers:
-
-- `X-Callback-Id` — UUID, store to make handler idempotent
-- `X-Callback-Timestamp` — unix seconds, reject if `|now - ts| > 300`
-- `X-Callback-Signature` — base64 HMAC-SHA256 over `` `${id}.${ts}.${rawBody}` `` using the base64-decoded secret
-
-```ts
-import crypto from 'node:crypto';
-
-function verify(raw: string, id: string, ts: string, sig: string, secret: string) {
-  const key = Buffer.from(secret, 'base64');
-  const mac = crypto.createHmac('sha256', key)
-    .update(`${id}.${ts}.${raw}`)
-    .digest('base64');
-  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(sig));
-}
-```
-
-Reply `2xx` within 10s; any non-2xx triggers retries.
-
-## Errors
-
-All errors are re-exported from `@runapi.ai/core`. Always `instanceof` — never string-match messages.
-
-| Error | Status | Action |
-|---|---|---|
-| `AuthenticationError` | 401 | abort; surface "reconnect your API key" |
-| `InsufficientCreditsError` | 402 | prompt user to top up at runapi.ai/billing |
-| `ValidationError` | 400 / 422 | fix params; do not retry |
-| `RateLimitError` | 429 | sleep `err.retryAfterMs`, then retry |
-| `ServiceUnavailableError` | 503 / 455 | retry with backoff; transient service issue |
-| `TaskFailedError` | — | show `err.details` to user; do not auto-retry |
-| `TaskTimeoutError` | — | re-poll with `<resource>.get(id)` |
-
-```ts
-import { InsufficientCreditsError, TaskFailedError } from '@runapi.ai/elevenlabs';
-
-try {
-  await client.textToSpeech.run({ model: 'text-to-speech-turbo-2-5', text: '...', voice: 'Rachel' });
-} catch (err) {
-  if (err instanceof InsufficientCreditsError) { /* surface top-up CTA */ }
-  else if (err instanceof TaskFailedError)       { /* show err.details */ }
-  else throw err;
-}
-```
+## References
 
-## Gotchas
+- Model overview, pricing, and rate limits: https://runapi.ai/models/elevenlabs.md
+- Provider comparison: https://runapi.ai/providers/elevenlabs.md
+- Full model catalog: https://runapi.ai/models.md
 
-- `textToSpeech` requires `model`; `textToDialogue`, `textToSound`, `speechToText`, and `isolateAudio` do not take a `model` field.
-- `textToDialogue` is an array of `{ voice, text }` lines — voice is per-line, not per-request.
-- `text-to-dialogue.stability` is a fixed enum: `0`, `0.5`, or `1`.
-- `speechToText.run()` returns `{ text }`, not `{ audios }` — the response shape is different from the other resources.
-- `output_format` on `textToSound` covers a wide codec/bitrate matrix (`mp3_*`, `pcm_*`, `ulaw_8000`, `alaw_8000`, `opus_*`) — pick one from the type union, do not invent strings.
-- `callback_url` must be reachable from the public internet. `localhost` / `127.0.0.1` URLs will never fire — use a tunnel (cloudflared, ngrok, tailscale funnel) when developing locally.
+## Variants
 
-## Dig deeper
+- [Turbo v2.5 text to speech](https://runapi.ai/models/elevenlabs/text-to-speech-turbo-v2.5.md)
+- [Multilingual v2 text to speech](https://runapi.ai/models/elevenlabs/text-to-speech-multilingual-v2.md)
+- [Dialogue v3](https://runapi.ai/models/elevenlabs/text-to-dialogue-v3.md)
+- [Sound effects v2](https://runapi.ai/models/elevenlabs/sound-effect-v2.md)
+- [Speech to text](https://runapi.ai/models/elevenlabs/speech-to-text.md)
+- [Audio isolation](https://runapi.ai/models/elevenlabs/audio-isolation.md)
 
-Package README (full API surface, all params): `node_modules/@runapi.ai/elevenlabs/README.md`. Types: `@runapi.ai/elevenlabs/dist/types.d.ts`. Product docs: https://runapi.ai/docs.