ElevenLabs TTSを既存コードに30分で組み込む方法［GraphAI例付き］

はじめに

AI技術の発展により、テキスト読み上げ（TTS）の品質が飛躍的に向上しています。その中でも、ElevenLabsのTTSモデル「Eleven v3」は感情表現の豊かさと自然な音声生成で注目を集めています。

この記事では、ElevenLabs TTSを既存のプロジェクトに素早く組み込む方法を、GraphAIフレームワークを使った実例とともに解説します。30分で実装できる具体的なステップバイステップガイドを提供し、AI駆動の音声合成アプリケーションを構築するための実践的な知識をお届けします。

ElevenLabs TTSとは

ElevenLabsの概要

ElevenLabsは、元Googleの機械学習エンジニアPiotr Dabkowskiと、元Palantirのデプロイメントストラテジスト Mati Staniszewskiによって2022年に設立されました。同社は、1200種類以上の音声と29の言語（日本語を含む）をサポートしており、クリエイターやコンテンツ制作者、教育者、マーケティング担当者など幅広いユーザーに利用されています。

Eleven v3の革新的機能

最新のEleven v3(alpha)では、70以上の言語に対応し世界の人口カバー率は60％から90％に拡大。対話モードでは会話の中で自然な話者切り替えが可能になり、音声タグのサポートにより「ささやき声」「笑い声」「皮肉な声調」等のトーンの指示や、「群衆の歓声」「ドアのきしむ音」といった効果音の指示を盛り込むことができます。

音声品質の特徴

ElevenLabsの音声クオリティは現在のAI音声合成技術の中でもトップクラスとされており、特に「自然さ」の面で他のサービスより優れており、独立した評価では他のTTSプロバイダーと比較して最も高いスコアを獲得しています。

GraphAIフレームワークとの相性

GraphAIとは

GraphAIとは、TypeScriptで書かれた単機能のAgentと呼ばれるプログラムを、YAMLやJSONファイルに書かれたデータフローグラフの法則に従って順次非同期に実行するプログラムのエンジンです。

GraphAIの主な特徴

GraphAIはDifyやLangGraphで出来るようなことは一通り出来ますが、それに加えて Graph 構造で定義されたワークフロー(GraphData)と Agent の実装(TypeScript)が分離されているため、各 Agent はAgent単位で任意の環境（ローカル / ブラウザ / サーバー）で実行可能となります。

GraphAIではエージェントは極力小さく作ることにより、各エージェントはシンプルに保ち、それらの入出力を組み合わせや実行順の制御をGraphAIに任せることより、簡単なプログラムの組み合わせで複雑なアプリケーションを作ることを可能にします。

30分で実装！ステップバイステップガイド

Step 1: 環境構築（5分）

まず、必要なパッケージをインストールします。

# プロジェクトディレクトリの作成
mkdir elevenlabs-graphai-project
cd elevenlabs-graphai-project

# package.jsonの初期化
npm init -y

# 必要なパッケージのインストール
npm install graphai @graphai/vanilla @elevenlabs/elevenlabs-js dotenv

Step 2: ElevenLabs APIキーの設定（3分）

ElevenLabsのサイト左下のメニューからAPI keyという箇所をクリックしてAPIキーを取得します。

.envファイルを作成し、APIキーを設定します：

ELEVENLABS_API_KEY=your_api_key_here

Step 3: 基本的なElevenLabs TTS実装（10分）

まず、基本的なTTS機能を実装します。ElevenLabsの公式JavaScript SDKを使用します：

// elevenlabs-basic.js
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import dotenv from 'dotenv';
import fs from 'fs';

dotenv.config();

const client = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY
});

async function textToSpeech(text, voiceId = "21m00Tcm4TlvDq8ikWAM") {
  try {
    const audio = await client.textToSpeech.convert(voiceId, {
      text: text,
      modelId: "eleven_multilingual_v2",
      voiceSettings: {
        stability: 0.5,
        similarityBoost: 0.5
      }
    });

    // 音声データをファイルに保存
    const audioBuffer = Buffer.from(await audio.arrayBuffer());
    const filename = `output_${Date.now()}.mp3`;
    fs.writeFileSync(filename, audioBuffer);
    
    console.log(`音声ファイルが生成されました: ${filename}`);
    return filename;
  } catch (error) {
    console.error('TTS変換エラー:', error);
    throw error;
  }
}

// 使用例
textToSpeech("こんにちは！ElevenLabsのTTSテストです。");

Step 4: GraphAIエージェントの作成（7分）

GraphAI用のカスタムエージェントを作成します：

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

export const elevenLabsAgent = async ({ inputs, params }) => {
  const client = new ElevenLabsClient({
    apiKey: process.env.ELEVENLABS_API_KEY
  });

  const text = inputs[0] || params.text;
  const voiceId = params.voiceId || "21m00Tcm4TlvDq8ikWAM";
  const modelId = params.modelId || "eleven_multilingual_v2";

  try {
    const audio = await client.textToSpeech.convert(voiceId, {
      text: text,
      modelId: modelId,
      voiceSettings: {
        stability: params.stability || 0.5,
        similarityBoost: params.similarityBoost || 0.5
      }
    });

    const audioBuffer = Buffer.from(await audio.arrayBuffer());
    const filename = `tts_${Date.now()}.mp3`;
    
    // ファイルシステムへの保存（実際のプロジェクトでは適切なストレージを使用）
    require('fs').writeFileSync(filename, audioBuffer);
    
    return {
      audioFile: filename,
      text: text,
      voiceId: voiceId,
      success: true
    };
  } catch (error) {
    return {
      error: error.message,
      success: false
    };
  }
};

// エージェント情報の定義
elevenLabsAgent.samples = [
  {
    inputs: ["こんにちは、世界！"],
    params: {},
    result: {
      audioFile: "tts_example.mp3",
      text: "こんにちは、世界！",
      success: true
    }
  }
];

elevenLabsAgent.description = "ElevenLabs TTSを使用してテキストを音声に変換するエージェント";
elevenLabsAgent.category = ["audio", "tts"];

Step 5: GraphAIワークフローの定義（5分）

GraphAIのGraphファイルの必須項目はversionとnodesです。YAMLファイルでワークフローを定義します：

# tts-workflow.yaml
version: 0.5
nodes:
  # 入力テキストの定義
  inputText:
    value: "こんにちは！GraphAIとElevenLabsの統合テストです。日本語の音声合成がうまく動作するかテストしています。"
  
  # テキスト前処理（オプション）
  textProcessor:
    agent: stringTemplateAgent
    params:
      template: "【音声テスト】{{text}}"
    inputs:
      text: :inputText
  
  # ElevenLabs TTS変換
  ttsConverter:
    agent: elevenLabsAgent
    params:
      voiceId: "9BWtsMINqrJLrRacOk9x"  # Aria voice
      modelId: "eleven_multilingual_v2"
      stability: 0.7
      similarityBoost: 0.8
    inputs:
      - :textProcessor
  
  # 結果の表示
  output:
    agent: echoAgent
    inputs:
      - :ttsConverter
    isResult: true

Step 6: 実行スクリプトの作成と動作確認（残り時間）

最終的な実行スクリプトを作成します：

// run-graphai-tts.js
import { GraphAI } from "graphai";
import * as vanilla from "@graphai/vanilla";
import { elevenLabsAgent } from "./elevenlabs-agent.js";
import fs from 'fs';
import yaml from 'js-yaml';
import dotenv from 'dotenv';

dotenv.config();

// カスタムエージェントとバニラエージェントを結合
const agents = {
  ...vanilla,
  elevenLabsAgent
};

async function runTTSWorkflow() {
  try {
    // YAMLファイルからワークフロー定義を読み込み
    const yamlContent = fs.readFileSync('./tts-workflow.yaml', 'utf8');
    const graphData = yaml.load(yamlContent);
    
    // GraphAIインスタンスを作成
    const graph = new GraphAI(graphData, agents);
    
    console.log("TTSワークフローを開始します...");
    
    // ワークフローを実行
    const result = await graph.run();
    
    console.log("ワークフロー完了:", result);
    
    // 生成された音声ファイルの情報を表示
    if (result.success) {
      console.log(`音声ファイルが生成されました: ${result.audioFile}`);
      console.log(`変換されたテキスト: ${result.text}`);
    }
    
  } catch (error) {
    console.error("ワークフロー実行エラー:", error);
  }
}

// ワークフローを実行
runTTSWorkflow();

高度な活用例

ストリーミングTTSの実装

リアルタイムでの音声生成が必要な場合は、ストリーミング機能を使用できます：

// streaming-tts-agent.js
export const streamingTTSAgent = async ({ inputs, params }) => {
  const client = new ElevenLabsClient({
    apiKey: process.env.ELEVENLABS_API_KEY
  });

  const text = inputs[0] || params.text;
  
  try {
    const audioStream = await client.textToSpeech.stream(
      params.voiceId || "21m00Tcm4TlvDq8ikWAM",
      {
        text: text,
        modelId: "eleven_multilingual_v2"
      }
    );

    // ストリーミングデータの処理
    return {
      stream: audioStream,
      text: text,
      streaming: true
    };
  } catch (error) {
    return { 
      error: error.message,
      streaming: false 
    };
  }
};

複数言語対応ワークフロー

Eleven v3は70以上の言語に対応しているため、多言語対応のワークフローも構築できます：

# multilingual-tts.yaml
version: 0.5
nodes:
  inputTexts:
    value:
      japanese: "こんにちは、今日はいい天気ですね。"
      english: "Hello, it's a beautiful day today."
      spanish: "Hola, hace un hermoso día hoy."
  
  japaneseAudio:
    agent: elevenLabsAgent
    params:
      voiceId: "9BWtsMINqrJLrRacOk9x"
      modelId: "eleven_multilingual_v2"
    inputs:
      - :inputTexts.japanese
  
  englishAudio:
    agent: elevenLabsAgent  
    params:
      voiceId: "21m00Tcm4TlvDq8ikWAM"
      modelId: "eleven_multilingual_v2"
    inputs:
      - :inputTexts.english
      
  spanishAudio:
    agent: elevenLabsAgent
    params:
      voiceId: "ThT5KcBeYPX3keUQqHPh"
      modelId: "eleven_multilingual_v2" 
    inputs:
      - :inputTexts.spanish
  
  result:
    agent: arrayFlatAgent
    inputs:
      - :japaneseAudio
      - :englishAudio
      - :spanishAudio
    isResult: true

エラーハンドリングとベストプラクティス

レート制限への対応

ElevenLabsのSDKは指数バックオフによる自動リトライ機能を備えています。追加の制御が必要な場合：

export const robustTTSAgent = async ({ inputs, params }) => {
  const maxRetries = params.maxRetries || 3;
  let attempt = 0;

  while (attempt < maxRetries) {
    try {
      const client = new ElevenLabsClient({
        apiKey: process.env.ELEVENLABS_API_KEY
      });

      const result = await client.textToSpeech.convert(
        params.voiceId || "21m00Tcm4TlvDq8ikWAM",
        {
          text: inputs[0] || params.text,
          modelId: params.modelId || "eleven_multilingual_v2"
        }
      );

      return { 
        success: true, 
        audio: result,
        attempt: attempt + 1 
      };
      
    } catch (error) {
      attempt++;
      if (attempt >= maxRetries) {
        return { 
          success: false, 
          error: error.message,
          finalAttempt: attempt 
        };
      }
      
      // 指数バックオフ
      await new Promise(resolve => 
        setTimeout(resolve, Math.pow(2, attempt) * 1000)
      );
    }
  }
};

テキスト前処理の重要性

TTSは長い文章をスピーチ化すると、イントネーションがおかしくなったり破綻が多くなります。破綻が多い場合はテキストを分割し、漢字の読み間違いがある場合は平仮名にします。

export const textPreprocessAgent = async ({ inputs, params }) => {
  let text = inputs[0] || params.text;
  
  // 長い文章を分割
  const maxLength = params.maxLength || 500;
  if (text.length > maxLength) {
    // 句読点で分割
    text = text.substring(0, maxLength).split(/[。！？]/).slice(0, -1).join('。') + '。';
  }
  
  // 特殊文字の処理
  text = text.replace(/[""]/g, '"');
  text = text.replace(/['']/g, "'");
  
  // 数字の読み方調整（オプション）
  if (params.convertNumbers) {
    text = text.replace(/(\d+)/g, (match) => {
      // 数字を漢数字に変換するロジック
      return convertToKanji(match);
    });
  }
  
  return {
    processedText: text,
    originalLength: inputs[0].length,
    processedLength: text.length
  };
};

料金とコスト最適化

ElevenLabsの料金体系

ElevenLabsの無料プランは月に合計2万文字まで生成可能で、生成1回ごとの最大文字数は2500文字です。ただし、商用利用は不可で帰属表示が必要となります。有料プランは月額5ドル(約720円)のスタータープラン、月額22ドル(約3000円)のクリエイタープラン、月額99ドル(約1万4000円)のプロプランがあります。

コスト効率化のテクニック

export const costOptimizedTTSAgent = async ({ inputs, params }) => {
  const text = inputs[0] || params.text;
  
  // キャッシュチェック（同じテキストの再生成を避ける）
  const cacheKey = `tts_${hashText(text)}_${params.voiceId}`;
  const cachedResult = await getFromCache(cacheKey);
  
  if (cachedResult && !params.forceRegenerate) {
    return {
      ...cachedResult,
      fromCache: true
    };
  }
  
  // 文字数に基づいてモデルを選択
  const modelId = text.length > 1000 
    ? "eleven_turbo_v2_5"  // 長文用高速モデル
    : "eleven_multilingual_v2";  // 高品質モデル
  
  const client = new ElevenLabsClient({
    apiKey: process.env.ELEVENLABS_API_KEY
  });
  
  try {
    const audio = await client.textToSpeech.convert(
      params.voiceId || "21m00Tcm4TlvDq8ikWAM",
      {
        text: text,
        modelId: modelId,
        voiceSettings: {
          stability: params.stability || 0.5,
          similarityBoost: params.similarityBoost || 0.5
        }
      }
    );
    
    const result = {
      audio: audio,
      text: text,
      modelUsed: modelId,
      characterCount: text.length,
      estimatedCost: calculateCost(text.length)
    };
    
    // 結果をキャッシュ
    await saveToCache(cacheKey, result);
    
    return result;
    
  } catch (error) {
    return { 
      success: false, 
      error: error.message 
    };
  }
};

パフォーマンス最適化

並列処理による高速化

複数のテキストを同時に処理する場合：

# parallel-tts.yaml
version: 0.5
nodes:
  inputTexts:
    value:
      - "最初のテキストです。"
      - "2番目のテキストです。"
      - "3番目のテキストです。"
  
  # 並列でTTS処理
  tts1:
    agent: elevenLabsAgent
    inputs:
      - :inputTexts.0
    
  tts2:
    agent: elevenLabsAgent
    inputs:
      - :inputTexts.1
      
  tts3:
    agent: elevenLabsAgent
    inputs:
      - :inputTexts.2
  
  # 結果をまとめる
  allResults:
    agent: arrayFlatAgent
    inputs:
      - :tts1
      - :tts2
      - :tts3
    isResult: true

Flash v2.5モデルの活用

Flash v2は英語専用、Flash v2.5は32言語に対応で、圧倒的に低い遅延を実現しています。リアルタイム性が重要な場合：

export const fastTTSAgent = async ({ inputs, params }) => {
  const client = new ElevenLabsClient({
    apiKey: process.env.ELEVENLABS_API_KEY
  });

  const startTime = performance.now();
  
  try {
    const audio = await client.textToSpeech.convert(
      params.voiceId || "21m00Tcm4TlvDq8ikWAM",
      {
        text: inputs[0] || params.text,
        modelId: "eleven_flash_v2_5",  // 高速モデル
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.5
        }
      }
    );
    
    const endTime = performance.now();
    
    return {
      audio: audio,
      processingTime: endTime - startTime,
      model: "eleven_flash_v2_5",
      success: true
    };
    
  } catch (error) {
    return {
      error: error.message,
      processingTime: performance.now() - startTime,
      success: false
    };
  }
};

実用的な応用例

ポッドキャスト自動生成システム

# podcast-generator.yaml
version: 0.5
nodes:
  scriptData:
    value:
      title: "AI技術の最新動向"
      segments:
        - speaker: "ホスト"
          text: "こんにちは、AI技術ポッドキャストへようこそ。"
        - speaker: "ゲスト"
          text: "本日はお招きいただき、ありがとうございます。"
  
  hostAudio:
    agent: elevenLabsAgent
    params:
      voiceId: "9BWtsMINqrJLrRacOk9x"  # ホスト用音声
      modelId: "eleven_multilingual_v2"
    inputs:
      - :scriptData.segments.0.text
  
  guestAudio:
    agent: elevenLabsAgent
    params:
      voiceId: "21m00Tcm4TlvDq8ikWAM"  # ゲスト用音声  
      modelId: "eleven_multilingual_v2"
    inputs:
      - :scriptData.segments.1.text
      
  podcastData:
    agent: arrayFlatAgent
    inputs:
      - :hostAudio
      - :guestAudio
    isResult: true

多言語学習アプリ

export const languageLearningAgent = async ({ inputs, params }) => {
  const { word, targetLanguage } = params;
  const client = new ElevenLabsClient({
    apiKey: process.env.ELEVENLABS_API_KEY
  });

  // 言語ごとの音声IDマッピング
  const voiceMap = {
    'ja': '9BWtsMINqrJLrRacOk9x',  // 日本語
    'en': '21m00Tcm4TlvDq8ikWAM', // 英語
    'es': 'ThT5KcBeYPX3keUQqHPh'  // スペイン語
  };

  try {
    const pronunciationAudio = await client.textToSpeech.convert(
      voiceMap[targetLanguage],
      {
        text: word,
        modelId: "eleven_multilingual_v2"
      }
    );

    return {
      word: word,
      language: targetLanguage,
      audio: pronunciationAudio,
      learningMode: true
    };
  } catch (error) {
    return { error: error.message };
  }
};

トラブルシューティング

よくある問題と解決策

問題1: APIキーのエラー

// APIキーの検証
export const validateApiKeyAgent = async ({ params }) => {
  try {
    const client = new ElevenLabsClient({
      apiKey: process.env.ELEVENLABS_API_KEY
    });
    
    const voices = await client.voices.search({});
    return { 
      valid: true, 
      voiceCount: voices.length 
    };
  } catch (error) {
    return { 
      valid: false, 
      error: error.message 
    };
  }
};

問題2: 音声品質の調整

export const qualityTuningAgent = async ({ inputs, params }) => {
  const baseSettings = {
    stability: 0.5,
    similarityBoost: 0.5
  };
  
  // テキストの特性に基づいて設定を調整
  const text = inputs[0];
  let settings = { ...baseSettings };
  
  if (text.includes('!') || text.includes('？')) {
    // 感情表現が多い場合は不安定性を上げる
    settings.stability = 0.3;
    settings.similarityBoost = 0.7;
  } else if (text.length > 1000) {
    // 長文の場合は安定性を重視
    settings.stability = 0.8;
    settings.similarityBoost = 0.4;
  }
  
  return { optimizedSettings: settings };
};

まとめ

この記事では、ElevenLabs TTSをGraphAIフレームワークと組み合わせて、わずか30分で実用的な音声合成システムを構築する方法を解説しました。

主なポイント：

1. 環境構築の簡素化: npmパッケージを使った迅速なセットアップ
2. GraphAIの活用: YAMLベースの宣言的ワークフロー定義
3. 実践的な実装例: 基本的なTTSから高度な多言語対応まで
4. パフォーマンス最適化: キャッシュ、並列処理、モデル選択の戦略
5. コスト効率化: 適切なプラン選択と使用量管理

ElevenLabsの低レイテンシーテキスト読み上げ(TTS) APIの統合は簡単で、最小限のコーディング作業だけで、クリアで高品質な音声をアプリケーションに組み込むことができます。

GraphAIフレームワークとの組み合わせにより、複雑なワークフローも直感的に構築でき、AIエージェントの力を最大限に活用した音声アプリケーションの開発が可能になります。

今回紹介した実装方法を基に、ぜひあなた自身のプロジェクトでElevenLabs TTSの力を体験してください。音声技術の革新が、あなたのアプリケーションにどのような新しい価値をもたらすか、きっと驚かれることでしょう。