Create embeddable audio players for web content. Audio Native enables you to add text-to-speech audio to articles, blogs, and web pages with customizable player widgets.

Quick Reference

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });
// Access this API via: client.audioNative

Capabilities

Create Audio Native Project

Create an Audio Native enabled project with embeddable player.

/**
 * @param request - Project content and configuration
 * @param requestOptions - Optional request configuration
 * @returns Created project with player settings
 * @throws UnprocessableEntityError if request fails
 */
client.audioNative.create(
  request: BodyCreatesAudioNativeEnabledProjectV1AudioNativePost,
  requestOptions?: RequestOptions
): HttpResponsePromise<AudioNativeCreateProjectResponseModel>;

interface BodyCreatesAudioNativeEnabledProjectV1AudioNativePost {
  /** Project name */
  name: string;
  /** HTML or plain text content */
  html?: string;
  /** Plain text content (alternative to HTML) */
  text?: string;
  /** Voice ID to use */
  voice_id?: string;
  /** Model ID */
  model_id?: string;
  /** Auto-convert content to audio */
  auto_convert?: boolean;
  /** Player settings */
  player_settings?: AudioNativePlayerSettings;
  /** Apply text normalization */
  apply_text_normalization?: ApplyTextNormalizationEnum;
}

interface AudioNativePlayerSettings {
  /** Enable player controls */
  controls?: boolean;
  /** Auto-play audio */
  autoplay?: boolean;
  /** Background color */
  background_color?: string;
  /** Primary color */
  primary_color?: string;
  /** Text color */
  text_color?: string;
}

interface AudioNativeCreateProjectResponseModel {
  /** Project ID */
  project_id: string;
  /** Project name */
  name: string;
  /** Embed code for player */
  embed_code: string;
  /** Audio URL */
  audio_url?: string;
  /** Conversion status */
  status: "queued" | "converting" | "completed" | "failed";
}

enum ApplyTextNormalizationEnum {
  Auto = "auto",
  On = "on",
  Off = "off",
}

Get Player Settings

Retrieve player configuration for a project.

/**
 * @param project_id - Audio Native project ID
 * @param requestOptions - Optional request configuration
 * @returns Player settings
 * @throws UnprocessableEntityError if request fails
 */
client.audioNative.getSettings(
  project_id: string,
  requestOptions?: RequestOptions
): HttpResponsePromise<GetAudioNativeProjectSettingsResponseModel>;

interface GetAudioNativeProjectSettingsResponseModel {
  project_id: string;
  player_settings: AudioNativePlayerSettings;
  voice_id: string;
  model_id: string;
}

Update Project Content

Update content and settings of an Audio Native project.

/**
 * @param project_id - Audio Native project ID
 * @param request - Updated content and settings
 * @param requestOptions - Optional request configuration
 * @returns Updated project info
 * @throws UnprocessableEntityError if request fails
 */
client.audioNative.update(
  project_id: string,
  request: BodyUpdateAudioNativeProjectContentV1AudioNativeProjectIdContentPost,
  requestOptions?: RequestOptions
): HttpResponsePromise<AudioNativeEditContentResponseModel>;

interface BodyUpdateAudioNativeProjectContentV1AudioNativeProjectIdContentPost {
  /** Updated HTML content */
  html?: string;
  /** Updated text content */
  text?: string;
  /** Updated voice ID */
  voice_id?: string;
  /** Auto-convert after update */
  auto_convert?: boolean;
}

interface AudioNativeEditContentResponseModel {
  project_id: string;
  status: string;
  audio_url?: string;
}

Usage Examples

Create Basic Player

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });

// Create Audio Native project
const project = await client.audioNative.create({
  name: "Blog Post Audio",
  text: "This is the content of my blog post that will be converted to audio.",
  voice_id: "narrator-voice-id",
  auto_convert: true,
});

console.log("Project ID:", project.project_id);
console.log("Embed code:", project.embed_code);

Create from HTML

// Create player from HTML content
const htmlContent = `
  <article>
    <h1>Article Title</h1>
    <p>This is the first paragraph of the article.</p>
    <p>This is the second paragraph with more content.</p>
  </article>
`;

const project = await client.audioNative.create({
  name: "Article Player",
  html: htmlContent,
  voice_id: "voice-id",
  model_id: "eleven_multilingual_v2",
  auto_convert: true,
});

Customize Player Appearance

// Create player with custom styling
const project = await client.audioNative.create({
  name: "Styled Player",
  text: "Content with custom player styling.",
  voice_id: "voice-id",
  auto_convert: true,
  player_settings: {
    controls: true,
    autoplay: false,
    background_color: "#ffffff",
    primary_color: "#0066cc",
    text_color: "#333333",
  },
});

Update Project Content

// Update content of existing project
const updated = await client.audioNative.update(
  project.project_id,
  {
    text: "Updated content for the audio player.",
    auto_convert: true,
  }
);

console.log("Updated status:", updated.status);
console.log("Audio URL:", updated.audio_url);

Get Player Settings

// Retrieve player configuration
const settings = await client.audioNative.getSettings(project.project_id);

console.log("Voice ID:", settings.voice_id);
console.log("Model ID:", settings.model_id);
console.log("Player Settings:", settings.player_settings);

Embed in Website

// Create project and get embed code
const project = await client.audioNative.create({
  name: "Website Audio",
  text: "Welcome to our website!",
  voice_id: "voice-id",
  auto_convert: true,
});

// The embed_code can be inserted into HTML
console.log("Add this to your HTML:");
console.log(project.embed_code);

// Example HTML usage:
// <div id="audio-player">
//   <!-- Insert embed_code here -->
// </div>

Blog Integration

// Automatically add audio to blog posts
interface BlogPost {
  title: string;
  content: string;
  author: string;
}

async function addAudioToBlogPost(
  post: BlogPost,
  voiceId: string
): Promise<string> {
  const fullContent = `${post.title}. By ${post.author}. ${post.content}`;

  const project = await client.audioNative.create({
    name: `Audio: ${post.title}`,
    text: fullContent,
    voice_id: voiceId,
    auto_convert: true,
    player_settings: {
      controls: true,
      autoplay: false,
    },
  });

  return project.embed_code;
}

const post = {
  title: "Introduction to AI",
  content: "Artificial intelligence is transforming...",
  author: "John Doe",
};

const embedCode = await addAudioToBlogPost(post, "narrator-voice-id");

Multi-Language Content

// Create audio players for multiple languages
const languages = [
  { code: "en", text: "Hello, welcome to our website!", voice: "en-voice-id" },
  { code: "es", text: "¡Hola, bienvenido a nuestro sitio web!", voice: "es-voice-id" },
  { code: "fr", text: "Bonjour, bienvenue sur notre site!", voice: "fr-voice-id" },
];

for (const lang of languages) {
  const project = await client.audioNative.create({
    name: `Welcome Message (${lang.code})`,
    text: lang.text,
    voice_id: lang.voice,
    model_id: "eleven_multilingual_v2",
    auto_convert: true,
  });

  console.log(`${lang.code} player:`, project.project_id);
}

Auto-play Player

// Create player with auto-play enabled
const project = await client.audioNative.create({
  name: "Auto-play Audio",
  text: "This audio will play automatically when the page loads.",
  voice_id: "voice-id",
  auto_convert: true,
  player_settings: {
    autoplay: true,
    controls: true,
  },
});

Update Voice

// Change voice for existing project
await client.audioNative.update(project.project_id, {
  voice_id: "new-voice-id",
  auto_convert: true, // Regenerate audio with new voice
});

Batch Creation

// Create multiple Audio Native projects
interface ContentItem {
  title: string;
  content: string;
}

const content: ContentItem[] = [
  { title: "Chapter 1", content: "Introduction to the topic..." },
  { title: "Chapter 2", content: "Deep dive into details..." },
  { title: "Chapter 3", content: "Conclusions and summary..." },
];

async function createAudioSeries(
  items: ContentItem[],
  voiceId: string
): Promise<void> {
  for (const item of items) {
    const project = await client.audioNative.create({
      name: item.title,
      text: `${item.title}. ${item.content}`,
      voice_id: voiceId,
      auto_convert: true,
    });

    console.log(`Created ${item.title}:`, project.project_id);
  }
}

await createAudioSeries(content, "voice-id");

Branded Player

// Create player matching brand colors
const brandColors = {
  primary: "#ff6b35",
  background: "#f7f7f7",
  text: "#2d3142",
};

const project = await client.audioNative.create({
  name: "Branded Player",
  text: "Listen to this content with our branded audio player.",
  voice_id: "voice-id",
  auto_convert: true,
  player_settings: {
    controls: true,
    background_color: brandColors.background,
    primary_color: brandColors.primary,
    text_color: brandColors.text,
  },
});

News Article Audio

// Convert news article to audio
async function createNewsAudio(
  headline: string,
  byline: string,
  articleText: string
): Promise<string> {
  const fullText = `${headline}. ${byline}. ${articleText}`;

  const project = await client.audioNative.create({
    name: `News: ${headline}`,
    text: fullText,
    voice_id: "news-voice-id",
    model_id: "eleven_turbo_v2_5",
    auto_convert: true,
    player_settings: {
      controls: true,
      autoplay: false,
      primary_color: "#cc0000",
    },
  });

  return project.embed_code;
}

const embedCode = await createNewsAudio(
  "Breaking News: Major Development",
  "By Jane Smith, Senior Reporter",
  "In a surprising turn of events today..."
);

Wait for Conversion

// Wait for audio conversion to complete
async function waitForConversion(projectId: string): Promise<string> {
  while (true) {
    const settings = await client.audioNative.getSettings(projectId);

    // Check project status
    const project = await client.audioNative.update(projectId, {});

    if (project.status === "completed") {
      return project.audio_url!;
    } else if (project.status === "failed") {
      throw new Error("Audio conversion failed");
    }

    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

const audioUrl = await waitForConversion(project.project_id);
console.log("Audio ready:", audioUrl);

Minimal Player

// Create minimal player without controls
const project = await client.audioNative.create({
  name: "Minimal Audio",
  text: "Simple audio with minimal interface.",
  voice_id: "voice-id",
  auto_convert: true,
  player_settings: {
    controls: false,
    autoplay: true,
  },
});

Version

Tile

Files

audio-native.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/content/

Audio Native

Quick Reference

Capabilities

Create Audio Native Project

Get Player Settings

Update Project Content

Usage Examples

Create Basic Player

Create from HTML

Customize Player Appearance

Update Project Content

Get Player Settings

Embed in Website

Blog Integration

Multi-Language Content

Auto-play Player

Update Voice

Batch Creation

Branded Player

News Article Audio

Wait for Conversion

Minimal Player

audio-native.mddocs/content/