Node.js・TypeScriptでAivis Cloud APIを使う方法｜型定義・ストリーミング・エラー処理まで解説！

mkdir aivis-cloud-api-sample
cd aivis-cloud-api-sample
npm init -y
npm pkg set type=module
npm install express
npm install --save-dev typescript tsx @types/node @types/express
mkdir src public

export AIVIS_API_KEY="your-api-key"
export AIVIS_MODEL_UUID="your-model-uuid"

$env:AIVIS_API_KEY="your-api-key"
$env:AIVIS_MODEL_UUID="your-model-uuid"

// src/aivis.ts
export type SamplingRate =
  | 8000
  | 11025
  | 12000
  | 16000
  | 22050
  | 24000
  | 44100
  | 48000;

type StyleSelector =
  | { style_id?: never; style_name?: never }
  | { style_id: number; style_name?: never }
  | { style_id?: never; style_name: string };

type CompressedOutput = {
  output_format?: "mp3" | "aac" | "opus";
  output_bitrate?: number;
};

type LosslessOutput = {
  output_format: "wav" | "flac";
  output_bitrate?: never;
};

export type SynthesizeRequest = {
  model_uuid: string;
  text: string;
  speaker_uuid?: string;
  user_dictionary_uuid?: string;
  use_ssml?: boolean;
  use_volume_normalizer?: boolean;
  language?: "ja";
  speaking_rate?: number;
  emotional_intensity?: number;
  tempo_dynamics?: number;
  pitch?: number;
  volume?: number;
  leading_silence_seconds?: number;
  trailing_silence_seconds?: number;
  line_break_silence_seconds?: number;
  output_sampling_rate?: SamplingRate;
  output_audio_channels?: "mono" | "stereo";
} & StyleSelector & (CompressedOutput | LosslessOutput);

const invalidRequest: SynthesizeRequest = {
  model_uuid: "モデルUUID",
  text: "こんにちは。",
  style_id: 1,
  style_name: "Happy", // エラー: style_idと同時に指定できない
};

npx openapi-typescript \
  https://api.aivis-project.com/v1/openapi.json \
  --output src/aivis-api.d.ts

import type { components } from "./aivis-api.js";

type SynthesizeRequest = components["schemas"]["TTSRequest"];

import { setTimeout as delay } from "node:timers/promises";

const ENDPOINT = "https://api.aivis-project.com/v1/tts/synthesize";

const API_KEY = process.env.AIVIS_API_KEY;
if (!API_KEY) {
  throw new Error("環境変数 AIVIS_API_KEY が設定されていません");
}

export class AivisApiError extends Error {
  constructor(
    public readonly status: number,
    public readonly responseBody: string,
  ) {
    super(`Aivis Cloud API returned HTTP ${status}`);
    this.name = "AivisApiError";
  }
}

type RequestOptions = {
  signal?: AbortSignal;
  maxRetries?: number;
};

function retryDelayMs(response: Response, attempt: number): number {
  const resetHeader = response.headers.get(
    "X-Aivis-RateLimit-Requests-Reset",
  );
  const resetSeconds = resetHeader === null ? Number.NaN : Number(resetHeader);

  if (response.status === 429 && Number.isFinite(resetSeconds)) {
    return Math.max(0, resetSeconds * 1000);
  }

  const exponentialBackoff = 1000 * 2 ** attempt;
  const jitter = Math.floor(Math.random() * 250);
  return exponentialBackoff + jitter;
}

export async function requestSynthesis(
  body: SynthesizeRequest,
  options: RequestOptions = {},
): Promise<Response> {
  const maxRetries = options.maxRetries ?? 2;
  const timeoutSignal = AbortSignal.timeout(120_000);
  const signal = options.signal
    ? AbortSignal.any([options.signal, timeoutSignal])
    : timeoutSignal;

  for (let attempt = 0; ; attempt++) {
    const response = await fetch(ENDPOINT, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
      signal,
    });

    if (response.ok && response.body) {
      return response;
    }

    const responseBody = await response.text().catch(() => "");
    const error = new AivisApiError(response.status, responseBody);
    const retryable = response.status === 429 || response.status >= 500;

    if (!retryable || attempt >= maxRetries) {
      throw error;
    }

    await delay(retryDelayMs(response, attempt), undefined, { signal });
  }
}

// src/save.ts
import { writeFile } from "node:fs/promises";
import { requestSynthesis, type SynthesizeRequest } from "./aivis.js";

const modelUuid = process.env.AIVIS_MODEL_UUID;
if (!modelUuid) {
  throw new Error("環境変数 AIVIS_MODEL_UUID が設定されていません");
}

const request = {
  model_uuid: modelUuid,
  text: "こんにちは。Aivis Cloud APIをNode.jsから呼び出しています。",
  output_format: "mp3",
  speaking_rate: 1.0,
} satisfies SynthesizeRequest;

const response = await requestSynthesis(request);
const audio = Buffer.from(await response.arrayBuffer());

await writeFile("output.mp3", audio);

console.log("output.mp3を保存しました");
console.log(
  "文字数:",
  response.headers.get("X-Aivis-Character-Count") ?? "不明",
);

npx tsx src/save.ts

const text = [
  "今日は、Aivis Cloud APIのストリーミングについてご紹介します。",
  "音声は、生成できた部分から順にブラウザへ届けられます。",
  "そのため、長い文章でも完成を待たずに再生を始められます。",
].join("\n");

// src/server.ts
import express from "express";
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";
import {
  AivisApiError,
  requestSynthesis,
  type SynthesizeRequest,
} from "./aivis.js";

const modelUuid = process.env.AIVIS_MODEL_UUID;
if (!modelUuid) {
  throw new Error("環境変数 AIVIS_MODEL_UUID が設定されていません");
}

const app = express();
app.use(express.json({ limit: "32kb" }));
app.use(express.static("public"));

app.post("/api/tts", async (req, res) => {
  const text = req.body?.text;
  const characterCount =
    typeof text === "string" ? Array.from(text).length : 0;

  if (characterCount < 1 || characterCount > 3000) {
    res.status(400).json({
      message: "textは1文字以上3,000文字以下で指定してください",
    });
    return;
  }

  const controller = new AbortController();
  res.on("close", () => {
    if (!res.writableEnded) controller.abort();
  });

  const body = {
    model_uuid: modelUuid,
    text,
    output_format: "mp3",
    leading_silence_seconds: 0,
    use_volume_normalizer: true,
  } satisfies SynthesizeRequest;

  try {
    const upstream = await requestSynthesis(body, {
      signal: controller.signal,
    });

    res.status(200);
    res.setHeader(
      "Content-Type",
      upstream.headers.get("Content-Type") ?? "audio/mpeg",
    );
    res.setHeader("Cache-Control", "no-store");
    res.setHeader("X-Accel-Buffering", "no");

    await pipeline(Readable.fromWeb(upstream.body!), res);
  } catch (error) {
    if (controller.signal.aborted) return;

    if (error instanceof AivisApiError && !res.headersSent) {
      res.status(error.status).json({
        message: "音声を生成できませんでした",
      });
      return;
    }

    if (!res.headersSent) {
      res.status(500).json({ message: "サーバー内でエラーが発生しました" });
    } else {
      res.destroy();
    }
  }
});

app.listen(3000, () => {
  console.log("http://localhost:3000 で起動しました");
});

<!doctype html>
<html lang="ja">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Aivis Cloud API Streaming Sample</title>
  </head>
  <body>
    <textarea id="text" rows="6" cols="60">今日は、Aivis Cloud APIのストリーミング再生を試します。
音声は、生成できた部分から順に再生されます。</textarea>
    <button id="play">音声を生成して再生</button>
    <audio id="audio" controls></audio>

    <script type="module">
      const button = document.querySelector("#play");
      const textarea = document.querySelector("#text");
      const audio = document.querySelector("#audio");

      const waitForUpdateEnd = (sourceBuffer) =>
        sourceBuffer.updating
          ? new Promise((resolve) =>
              sourceBuffer.addEventListener("updateend", resolve, {
                once: true,
              }),
            )
          : Promise.resolve();

      button.addEventListener("click", async () => {
        button.disabled = true;

        try {
          const MediaSourceClass =
            globalThis.MediaSource ?? globalThis.ManagedMediaSource;

          if (!MediaSourceClass?.isTypeSupported("audio/mpeg")) {
            throw new Error("このブラウザはMP3の逐次再生に対応していません");
          }

          const mediaSource = new MediaSourceClass();
          const objectUrl = URL.createObjectURL(mediaSource);
          audio.src = objectUrl;
          audio.disableRemotePlayback = true;
          audio.addEventListener(
            "ended",
            () => URL.revokeObjectURL(objectUrl),
            { once: true },
          );

          // クリック操作中に再生を予約し、自動再生制限を避ける
          const playPromise = audio.play();

          await new Promise((resolve) =>
            mediaSource.addEventListener("sourceopen", resolve, { once: true }),
          );

          const response = await fetch("/api/tts", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ text: textarea.value }),
          });

          if (!response.ok || !response.body) {
            throw new Error(`音声を生成できませんでした: HTTP ${response.status}`);
          }

          const sourceBuffer = mediaSource.addSourceBuffer("audio/mpeg");
          const reader = response.body.getReader();

          for (;;) {
            const { value, done } = await reader.read();
            if (done) break;

            await waitForUpdateEnd(sourceBuffer);
            sourceBuffer.appendBuffer(value);
          }

          await waitForUpdateEnd(sourceBuffer);
          mediaSource.endOfStream();
          await playPromise;
        } catch (error) {
          console.error(error);
          alert(error instanceof Error ? error.message : "再生に失敗しました");
        } finally {
          button.disabled = false;
        }
      });
    </script>
  </body>
</html>

npx tsx src/server.ts