@ai-sdk/hume 0.0.0-1c33ba03-20260114162300 → 0.0.0-4115c213-20260122152721

package/CHANGELOG.md

@@ -1,11 +1,40 @@
 # @ai-sdk/hume
 
-## 0.0.0-1c33ba03-20260114162300
+## 0.0.0-4115c213-20260122152721
 
 ### Patch Changes
 
-- Updated dependencies [261c011]
-  - @ai-sdk/provider-utils@0.0.0-1c33ba03-20260114162300
+- 4caafb2: chore: excluded tests from src folder in npm package
+- Updated dependencies [4caafb2]
+  - @ai-sdk/provider@0.0.0-4115c213-20260122152721
+  - @ai-sdk/provider-utils@0.0.0-4115c213-20260122152721
+
+## 2.0.10
+
+### Patch Changes
+
+- 2b8369d: chore: add docs to package dist
+
+## 2.0.9
+
+### Patch Changes
+
+- 8dc54db: chore: add src folders to package bundle
+
+## 2.0.8
+
+### Patch Changes
+
+- Updated dependencies [5c090e7]
+  - @ai-sdk/provider@3.0.4
+  - @ai-sdk/provider-utils@4.0.8
+
+## 2.0.7
+
+### Patch Changes
+
+- Updated dependencies [46f46e4]
+  - @ai-sdk/provider-utils@4.0.7
 
 ## 2.0.6
 

package/dist/index.js

@@ -236,7 +236,7 @@ var HumeSpeechModel = class {
 };
 
 // src/version.ts
-var VERSION = true ? "0.0.0-1c33ba03-20260114162300" : "0.0.0-test";
+var VERSION = true ? "0.0.0-4115c213-20260122152721" : "0.0.0-test";
 
 // src/hume-provider.ts
 function createHume(options = {}) {

package/dist/index.mjs

@@ -216,7 +216,7 @@ var HumeSpeechModel = class {
 };
 
 // src/version.ts
-var VERSION = true ? "0.0.0-1c33ba03-20260114162300" : "0.0.0-test";
+var VERSION = true ? "0.0.0-4115c213-20260122152721" : "0.0.0-test";
 
 // src/hume-provider.ts
 function createHume(options = {}) {

package/docs/150-hume.mdx

@@ -0,0 +1,103 @@
+---
+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', 'bun']}>
+  <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>
+
+  <Tab>
+    <Snippet text="bun 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} /> |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/hume",
-  "version": "0.0.0-1c33ba03-20260114162300",
+  "version": "0.0.0-4115c213-20260122152721",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -8,9 +8,18 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist/**/*",
+    "docs/**/*",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "!src/**/__snapshots__",
+    "!src/**/__fixtures__",
     "CHANGELOG.md",
     "README.md"
   ],
+  "directories": {
+    "doc": "./docs"
+  },
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -20,16 +29,16 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "3.0.3",
-    "@ai-sdk/provider-utils": "0.0.0-1c33ba03-20260114162300"
+    "@ai-sdk/provider": "0.0.0-4115c213-20260122152721",
+    "@ai-sdk/provider-utils": "0.0.0-4115c213-20260122152721"
   },
   "devDependencies": {
     "@types/node": "20.17.24",
     "tsup": "^8",
     "typescript": "5.6.3",
     "zod": "3.25.76",
-    "@vercel/ai-tsconfig": "0.0.0",
-    "@ai-sdk/test-server": "1.0.1"
+    "@ai-sdk/test-server": "0.0.0-4115c213-20260122152721",
+    "@vercel/ai-tsconfig": "0.0.0"
   },
   "peerDependencies": {
     "zod": "^3.25.76 || ^4.1.8"
@@ -54,7 +63,7 @@
   "scripts": {
     "build": "tsup --tsconfig tsconfig.build.json",
     "build:watch": "tsup --tsconfig tsconfig.build.json --watch",
-    "clean": "del-cli dist",
+    "clean": "del-cli dist docs",
     "lint": "eslint \"./**/*.ts*\"",
     "type-check": "tsc --noEmit",
     "prettier-check": "prettier --check \"./**/*.ts*\"",

package/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';
+  };
+};

package/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;
+};

package/src/hume-error.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod/v4';
+import { createJsonErrorResponseHandler } from '@ai-sdk/provider-utils';
+
+export const humeErrorDataSchema = z.object({
+  error: z.object({
+    message: z.string(),
+    code: z.number(),
+  }),
+});
+
+export type HumeErrorData = z.infer<typeof humeErrorDataSchema>;
+
+export const humeFailedResponseHandler = createJsonErrorResponseHandler({
+  errorSchema: humeErrorDataSchema,
+  errorToMessage: data => data.error.message,
+});

package/src/hume-provider.ts

@@ -0,0 +1,79 @@
+import { SpeechModelV3, ProviderV3 } from '@ai-sdk/provider';
+import {
+  FetchFunction,
+  loadApiKey,
+  withUserAgentSuffix,
+} from '@ai-sdk/provider-utils';
+import { HumeSpeechModel } from './hume-speech-model';
+import { VERSION } from './version';
+
+export interface HumeProvider extends Pick<ProviderV3, 'speechModel'> {
+  (settings?: {}): {
+    speech: HumeSpeechModel;
+  };
+
+  /**
+Creates a model for speech synthesis.
+   */
+  speech(): SpeechModelV3;
+}
+
+export interface HumeProviderSettings {
+  /**
+API key for authenticating requests.
+     */
+  apiKey?: string;
+
+  /**
+Custom headers to include in the requests.
+     */
+  headers?: Record<string, string>;
+
+  /**
+Custom fetch implementation. You can use it as a middleware to intercept requests,
+or to provide a custom fetch implementation for e.g. testing.
+    */
+  fetch?: FetchFunction;
+}
+
+/**
+Create an Hume provider instance.
+ */
+export function createHume(options: HumeProviderSettings = {}): HumeProvider {
+  const getHeaders = () =>
+    withUserAgentSuffix(
+      {
+        'X-Hume-Api-Key': loadApiKey({
+          apiKey: options.apiKey,
+          environmentVariableName: 'HUME_API_KEY',
+          description: 'Hume',
+        }),
+        ...options.headers,
+      },
+      `ai-sdk/hume/${VERSION}`,
+    );
+
+  const createSpeechModel = () =>
+    new HumeSpeechModel('', {
+      provider: `hume.speech`,
+      url: ({ path }) => `https://api.hume.ai${path}`,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
+  const provider = function () {
+    return {
+      speech: createSpeechModel(),
+    };
+  };
+
+  provider.speech = createSpeechModel;
+  provider.speechModel = createSpeechModel;
+
+  return provider satisfies HumeProvider;
+}
+
+/**
+Default Hume provider instance.
+ */
+export const hume = createHume();

package/src/hume-speech-model.ts

@@ -0,0 +1,238 @@
+import { SpeechModelV3, SharedV3Warning } from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  createBinaryResponseHandler,
+  parseProviderOptions,
+  postJsonToApi,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { HumeConfig } from './hume-config';
+import { humeFailedResponseHandler } from './hume-error';
+import { HumeSpeechAPITypes } from './hume-api-types';
+
+// https://dev.hume.ai/reference/text-to-speech-tts/synthesize-file
+const humeSpeechCallOptionsSchema = z.object({
+  /**
+   * Context for the speech synthesis request.
+   * Can be either a generationId for retrieving a previous generation,
+   * or a list of utterances to synthesize.
+   */
+  context: z
+    .object({
+      /**
+       * ID of a previously generated speech synthesis to retrieve.
+       */
+      generationId: z.string(),
+    })
+    .or(
+      z.object({
+        /**
+         * List of utterances to synthesize into speech.
+         */
+        utterances: z.array(
+          z.object({
+            /**
+             * The text content to convert to speech.
+             */
+            text: z.string(),
+            /**
+             * Optional description or instructions for how the text should be spoken.
+             */
+            description: z.string().optional(),
+            /**
+             * Optional speech rate multiplier.
+             */
+            speed: z.number().optional(),
+            /**
+             * Optional duration of silence to add after the utterance in seconds.
+             */
+            trailingSilence: z.number().optional(),
+            /**
+             * Voice configuration for the utterance.
+             * Can be specified by ID or name.
+             */
+            voice: z
+              .object({
+                /**
+                 * ID of the voice to use.
+                 */
+                id: z.string(),
+                /**
+                 * Provider of the voice, either Hume's built-in voices or a custom voice.
+                 */
+                provider: z.enum(['HUME_AI', 'CUSTOM_VOICE']).optional(),
+              })
+              .or(
+                z.object({
+                  /**
+                   * Name of the voice to use.
+                   */
+                  name: z.string(),
+                  /**
+                   * Provider of the voice, either Hume's built-in voices or a custom voice.
+                   */
+                  provider: z.enum(['HUME_AI', 'CUSTOM_VOICE']).optional(),
+                }),
+              )
+              .optional(),
+          }),
+        ),
+      }),
+    )
+    .nullish(),
+});
+
+export type HumeSpeechCallOptions = z.infer<typeof humeSpeechCallOptionsSchema>;
+
+interface HumeSpeechModelConfig extends HumeConfig {
+  _internal?: {
+    currentDate?: () => Date;
+  };
+}
+
+export class HumeSpeechModel implements SpeechModelV3 {
+  readonly specificationVersion = 'v3';
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(
+    readonly modelId: '',
+    private readonly config: HumeSpeechModelConfig,
+  ) {}
+
+  private async getArgs({
+    text,
+    voice = 'd8ab67c6-953d-4bd8-9370-8fa53a0f1453',
+    outputFormat = 'mp3',
+    speed,
+    instructions,
+    language,
+    providerOptions,
+  }: Parameters<SpeechModelV3['doGenerate']>[0]) {
+    const warnings: SharedV3Warning[] = [];
+
+    // Parse provider options
+    const humeOptions = await parseProviderOptions({
+      provider: 'hume',
+      providerOptions,
+      schema: humeSpeechCallOptionsSchema,
+    });
+
+    // Create request body
+    const requestBody: HumeSpeechAPITypes = {
+      utterances: [
+        {
+          text,
+          speed,
+          description: instructions,
+          voice: {
+            id: voice,
+            provider: 'HUME_AI',
+          },
+        },
+      ],
+      format: { type: 'mp3' },
+    };
+
+    if (outputFormat) {
+      if (['mp3', 'pcm', 'wav'].includes(outputFormat)) {
+        requestBody.format = { type: outputFormat as 'mp3' | 'pcm' | 'wav' };
+      } else {
+        warnings.push({
+          type: 'unsupported',
+          feature: 'outputFormat',
+          details: `Unsupported output format: ${outputFormat}. Using mp3 instead.`,
+        });
+      }
+    }
+
+    // Add provider-specific options
+    if (humeOptions) {
+      const speechModelOptions: Omit<
+        HumeSpeechAPITypes,
+        'utterances' | 'format'
+      > = {};
+
+      if (humeOptions.context) {
+        if ('generationId' in humeOptions.context) {
+          speechModelOptions.context = {
+            generation_id: humeOptions.context.generationId,
+          };
+        } else {
+          speechModelOptions.context = {
+            utterances: humeOptions.context.utterances.map(utterance => ({
+              text: utterance.text,
+              description: utterance.description,
+              speed: utterance.speed,
+              trailing_silence: utterance.trailingSilence,
+              voice: utterance.voice,
+            })),
+          };
+        }
+      }
+
+      for (const key in speechModelOptions) {
+        const value =
+          speechModelOptions[
+            key as keyof Omit<HumeSpeechAPITypes, 'utterances' | 'format'>
+          ];
+        if (value !== undefined) {
+          (requestBody as Record<string, unknown>)[key] = value;
+        }
+      }
+    }
+
+    if (language) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'language',
+        details: `Hume speech models do not support language selection. Language parameter "${language}" was ignored.`,
+      });
+    }
+
+    return {
+      requestBody,
+      warnings,
+    };
+  }
+
+  async doGenerate(
+    options: Parameters<SpeechModelV3['doGenerate']>[0],
+  ): Promise<Awaited<ReturnType<SpeechModelV3['doGenerate']>>> {
+    const currentDate = this.config._internal?.currentDate?.() ?? new Date();
+    const { requestBody, warnings } = await this.getArgs(options);
+
+    const {
+      value: audio,
+      responseHeaders,
+      rawValue: rawResponse,
+    } = await postJsonToApi({
+      url: this.config.url({
+        path: '/v0/tts/file',
+        modelId: this.modelId,
+      }),
+      headers: combineHeaders(this.config.headers(), options.headers),
+      body: requestBody,
+      failedResponseHandler: humeFailedResponseHandler,
+      successfulResponseHandler: createBinaryResponseHandler(),
+      abortSignal: options.abortSignal,
+      fetch: this.config.fetch,
+    });
+
+    return {
+      audio,
+      warnings,
+      request: {
+        body: JSON.stringify(requestBody),
+      },
+      response: {
+        timestamp: currentDate,
+        modelId: this.modelId,
+        headers: responseHeaders,
+        body: rawResponse,
+      },
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { createHume, hume } from './hume-provider';
+export type { HumeProvider, HumeProviderSettings } from './hume-provider';
+export { VERSION } from './version';

package/src/version.ts

@@ -0,0 +1,6 @@
+// Version string of this package injected at build time.
+declare const __PACKAGE_VERSION__: string | undefined;
+export const VERSION: string =
+  typeof __PACKAGE_VERSION__ !== 'undefined'
+    ? __PACKAGE_VERSION__
+    : '0.0.0-test';