feat(providers/hume): add speech (#5727)

.changeset/selfish-wasps-applaud.md

@@ -0,0 +1,5 @@
+---
+'@ai-sdk/hume': patch
+---
+
+feat(providers/hume): add speech

content/docs/02-foundations/02-providers-and-models.mdx

@@ -41,6 +41,7 @@ The AI SDK comes with a wide range of providers that you can use to interact wit
 - [Groq Provider](/providers/ai-sdk-providers/groq) (`@ai-sdk/groq`)
 - [Perplexity Provider](/providers/ai-sdk-providers/perplexity) (`@ai-sdk/perplexity`)
 - [ElevenLabs Provider](/providers/ai-sdk-providers/elevenlabs) (`@ai-sdk/elevenlabs`)
+- [Hume Provider](/providers/ai-sdk-providers/hume) (`@ai-sdk/hume`)
 - [Rev.ai Provider](/providers/ai-sdk-providers/revai) (`@ai-sdk/revai`)
 
 You can also use the [OpenAI Compatible provider](/providers/openai-compatible-providers) with OpenAI-compatible APIs:

content/docs/03-ai-sdk-core/37-speech.mdx

@@ -145,5 +145,6 @@ try {
 | [OpenAI](/providers/ai-sdk-providers/openai#speech-models) | `tts-1`           |
 | [OpenAI](/providers/ai-sdk-providers/openai#speech-models) | `tts-1-hd`        |
 | [OpenAI](/providers/ai-sdk-providers/openai#speech-models) | `gpt-4o-mini-tts` |
+| [Hume](/providers/ai-sdk-providers/hume#speech-models)     | `default`         |
 
 Above are a small subset of the speech models supported by the AI SDK providers. For more, see the respective provider documentation.

content/providers/01-ai-sdk-providers/150-hume.mdx

@@ -0,0 +1,99 @@
+---
+title: Hume
+description: Learn how to use the Hume provider for the AI SDK.
+---
+
+# Hume Provider
+
+The [Hume](https://hume.ai/) provider contains language model support for the Hume transcription API.
+
+## Setup
+
+The Hume provider is available in the `@ai-sdk/hume` module. You can install it with
+
+<Tabs items={['pnpm', 'npm', 'yarn']}>
+  <Tab>
+    <Snippet text="pnpm add @ai-sdk/hume" dark />
+  </Tab>
+  <Tab>
+    <Snippet text="npm install @ai-sdk/hume" dark />
+  </Tab>
+  <Tab>
+    <Snippet text="yarn add @ai-sdk/hume" dark />
+  </Tab>
+</Tabs>
+
+## Provider Instance
+
+You can import the default provider instance `hume` from `@ai-sdk/hume`:
+
+```ts
+import { hume } from '@ai-sdk/hume';
+```
+
+If you need a customized setup, you can import `createHume` from `@ai-sdk/hume` and create a provider instance with your settings:
+
+```ts
+import { createHume } from '@ai-sdk/hume';
+
+const hume = createHume({
+  // custom settings, e.g.
+  fetch: customFetch,
+});
+```
+
+You can use the following optional settings to customize the Hume provider instance:
+
+- **apiKey** _string_
+
+  API key that is being sent using the `Authorization` header.
+  It defaults to the `HUME_API_KEY` environment variable.
+
+- **headers** _Record&lt;string,string&gt;_
+
+  Custom headers to include in the requests.
+
+- **fetch** _(input: RequestInfo, init?: RequestInit) => Promise&lt;Response&gt;_
+
+  Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation.
+  Defaults to the global `fetch` function.
+  You can use it as a middleware to intercept requests,
+  or to provide a custom fetch implementation for e.g. testing.
+
+## Speech Models
+
+You can create models that call the [Hume speech API](https://dev.hume.ai/docs/text-to-speech-tts/overview)
+using the `.speech()` factory method.
+
+```ts
+const model = hume.speech();
+```
+
+You can also pass additional provider-specific options using the `providerOptions` argument. For example, supplying a voice to use for the generated audio.
+
+```ts highlight="6"
+import { experimental_generateSpeech as generateSpeech } from 'ai';
+import { hume } from '@ai-sdk/hume';
+
+const result = await generateSpeech({
+  model: hume.speech(),
+  text: 'Hello, world!',
+  voice: 'd8ab67c6-953d-4bd8-9370-8fa53a0f1453',
+  providerOptions: { hume: {} },
+});
+```
+
+The following provider options are available:
+
+- **context** _object_
+
+  Either:
+
+  - `{ generationId: string }` - A generation ID to use for context.
+  - `{ utterances: HumeUtterance[] }` - An array of utterance objects for context.
+
+### Model Capabilities
+
+| Model     | Instructions        |
+| --------- | ------------------- |
+| `default` | <Check size={18} /> |

examples/ai-core/package.json

@@ -17,6 +17,7 @@
     "@ai-sdk/google-vertex": "3.0.0-canary.9",
     "@ai-sdk/groq": "2.0.0-canary.9",
     "@ai-sdk/luma": "1.0.0-canary.8",
+    "@ai-sdk/hume": "1.0.0-canary.0",
     "@ai-sdk/mistral": "2.0.0-canary.8",
     "@ai-sdk/openai": "2.0.0-canary.8",
     "@ai-sdk/openai-compatible": "1.0.0-canary.8",

examples/ai-core/src/generate-speech/hume-instructions.ts

@@ -0,0 +1,21 @@
+import { hume } from '@ai-sdk/hume';
+import { experimental_generateSpeech as generateSpeech } from 'ai';
+import 'dotenv/config';
+import { saveAudioFile } from '../lib/save-audio';
+
+async function main() {
+  const result = await generateSpeech({
+    model: hume.speech(),
+    text: 'Hello from the AI SDK!',
+    instructions: 'Speak in a slow and steady tone',
+  });
+
+  console.log('Audio:', result.audio);
+  console.log('Warnings:', result.warnings);
+  console.log('Responses:', result.responses);
+  console.log('Provider Metadata:', result.providerMetadata);
+
+  await saveAudioFile(result.audio);
+}
+
+main().catch(console.error);

examples/ai-core/src/generate-speech/hume-speed.ts

@@ -0,0 +1,21 @@
+import { hume } from '@ai-sdk/hume';
+import { experimental_generateSpeech as generateSpeech } from 'ai';
+import 'dotenv/config';
+import { saveAudioFile } from '../lib/save-audio';
+
+async function main() {
+  const result = await generateSpeech({
+    model: hume.speech(),
+    text: 'Hello from the AI SDK!',
+    speed: 1.5,
+  });
+
+  console.log('Audio:', result.audio);
+  console.log('Warnings:', result.warnings);
+  console.log('Responses:', result.responses);
+  console.log('Provider Metadata:', result.providerMetadata);
+
+  await saveAudioFile(result.audio);
+}
+
+main().catch(console.error);

examples/ai-core/src/generate-speech/hume-voice.ts

@@ -0,0 +1,21 @@
+import { hume } from '@ai-sdk/hume';
+import { experimental_generateSpeech as generateSpeech } from 'ai';
+import 'dotenv/config';
+import { saveAudioFile } from '../lib/save-audio';
+
+async function main() {
+  const result = await generateSpeech({
+    model: hume.speech(),
+    text: 'Hello from the AI SDK!',
+    voice: 'nova',
+  });
+
+  console.log('Audio:', result.audio);
+  console.log('Warnings:', result.warnings);
+  console.log('Responses:', result.responses);
+  console.log('Provider Metadata:', result.providerMetadata);
+
+  await saveAudioFile(result.audio);
+}
+
+main().catch(console.error);

examples/ai-core/src/generate-speech/hume.ts

@@ -0,0 +1,20 @@
+import { hume } from '@ai-sdk/hume';
+import { experimental_generateSpeech as generateSpeech } from 'ai';
+import 'dotenv/config';
+import { saveAudioFile } from '../lib/save-audio';
+
+async function main() {
+  const result = await generateSpeech({
+    model: hume.speech(),
+    text: 'Hello from the AI SDK!',
+  });
+
+  console.log('Audio:', result.audio);
+  console.log('Warnings:', result.warnings);
+  console.log('Responses:', result.responses);
+  console.log('Provider Metadata:', result.providerMetadata);
+
+  await saveAudioFile(result.audio);
+}
+
+main().catch(console.error);

examples/ai-core/tsconfig.json

@@ -52,6 +52,9 @@
     {
       "path": "../../packages/deepseek"
     },
+    {
+      "path": "../../packages/hume"
+    },
     {
       "path": "../../packages/fal"
     },

packages/hume/README.md

@@ -0,0 +1,36 @@
+# AI SDK - Hume Provider
+
+The **[Hume provider](https://sdk.vercel.ai/providers/ai-sdk-providers/hume)** for the [AI SDK](https://sdk.vercel.ai/docs)
+contains support for the Hume API.
+
+## Setup
+
+The Hume provider is available in the `@ai-sdk/hume` module. You can install it with
+
+```bash
+npm i @ai-sdk/hume
+```
+
+## Provider Instance
+
+You can import the default provider instance `lmnt` from `@ai-sdk/lmnt`:
+
+```ts
+import { hume } from '@ai-sdk/hume';
+```
+
+## Example
+
+```ts
+import { hume } from '@ai-sdk/hume';
+import { experimental_generateSpeech as generateSpeech } from 'ai';
+
+const result = await generateSpeech({
+  model: hume.speech('aurora'),
+  text: 'Hello, world!',
+});
+```
+
+## Documentation
+
+Please check out the **[Hume provider documentation](https://sdk.vercel.ai/providers/ai-sdk-providers/hume)** for more information.

packages/hume/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@ai-sdk/hume",
+  "version": "1.0.0-canary.0",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup --tsconfig tsconfig.build.json",
+    "build:watch": "tsup --tsconfig tsconfig.build.json --watch",
+    "clean": "rm -rf dist",
+    "lint": "eslint \"./**/*.ts*\"",
+    "type-check": "tsc --noEmit",
+    "prettier-check": "prettier --check \"./**/*.ts*\"",
+    "test": "pnpm test:node && pnpm test:edge",
+    "test:edge": "vitest --config vitest.edge.config.js --run",
+    "test:node": "vitest --config vitest.node.config.js --run",
+    "test:node:watch": "vitest --config vitest.node.config.js --watch"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@ai-sdk/provider": "2.0.0-canary.7",
+    "@ai-sdk/provider-utils": "3.0.0-canary.8"
+  },
+  "devDependencies": {
+    "@types/node": "20.17.24",
+    "@vercel/ai-tsconfig": "workspace:*",
+    "tsup": "^8",
+    "typescript": "5.6.3",
+    "zod": "3.23.8"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://sdk.vercel.ai/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel/ai.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vercel/ai/issues"
+  },
+  "keywords": [
+    "ai"
+  ]
+}

packages/hume/src/hume-api-types.ts

@@ -0,0 +1,29 @@
+type HumeSpeechAPIUtterances = Array<{
+  text: string;
+  description?: string;
+  speed?: number;
+  trailing_silence?: number;
+  voice?:
+    | {
+        id: string;
+        provider?: 'HUME_AI' | 'CUSTOM_VOICE';
+      }
+    | {
+        name: string;
+        provider?: 'HUME_AI' | 'CUSTOM_VOICE';
+      };
+}>;
+
+export type HumeSpeechAPITypes = {
+  utterances: HumeSpeechAPIUtterances;
+  context?:
+    | {
+        generation_id: string;
+      }
+    | {
+        utterances: HumeSpeechAPIUtterances;
+      };
+  format: {
+    type: 'mp3' | 'pcm' | 'wav';
+  };
+};

packages/hume/src/hume-config.ts

@@ -0,0 +1,9 @@
+import { FetchFunction } from '@ai-sdk/provider-utils';
+
+export type HumeConfig = {
+  provider: string;
+  url: (options: { modelId: string; path: string }) => string;
+  headers: () => Record<string, string | undefined>;
+  fetch?: FetchFunction;
+  generateId?: () => string;
+};