@tanstack/ai-byteplus 0.0.0

package/dist/esm/adapters/tts.js

@@ -0,0 +1,307 @@
+import { bytePlusVoiceError, bytePlusVoiceHeaders, getBytePlusVoiceApiKeyFromEnv, readJsonBody, withBytePlusVoiceDefaults } from "../utils/client.js";
+import { BaseTTSAdapter } from "@tanstack/ai/adapters";
+import { toRunErrorPayload } from "@tanstack/ai/adapter-internals";
+import { generateId } from "@tanstack/ai-utils";
+//#region src/adapters/tts.ts
+/** Path of the synchronous Seed Speech synthesis endpoint. */
+var TTS_CREATE_PATH = "/api/v3/tts/create";
+/**
+* Name of the request field carrying the text to speak.
+*
+* **`text_prompt` is correct — do not "fix" this to `text`.** The endpoint
+* schema (docs.byteplus.com/en/docs/byteplusvoice/seedaudio-01) lists this
+* body as exactly `model`, `text_prompt`, `references`, `audio_config`,
+* `watermark`; there is no request-side `text`. The `text` spelling belongs
+* to the *other* endpoint, `/tts/unidirectional` (TTS 2.0), where it sits
+* under `req_params.text`. The name stays isolated here so the two spellings
+* never get conflated.
+*/
+var TTS_TEXT_FIELD = "text_prompt";
+/**
+* Sample rate used when the caller doesn't pick one. The endpoint documents a
+* default of 40000, which is not among the rates it accepts — so the adapter
+* never relies on the server default and always sends this instead.
+*/
+var DEFAULT_SAMPLE_RATE = 24e3;
+/**
+* True when a Seed Speech envelope's `code` means success.
+*
+* Seed Speech uses `0` for success and a flat numeric code otherwise
+* (`45000010 Invalid X-Api-Key`). The success envelope has not been confirmed
+* against a live key, so `code` is accepted as a number, its string form, or
+* absent — an envelope that omits `code` entirely is treated as success, which
+* is what the HTTP status already told us.
+*/
+function isZeroCode(code) {
+	if (code === void 0) return true;
+	return Number(code) === 0;
+}
+/**
+* Voice used when neither `TTSOptions.voice` nor `modelOptions.speaker` is
+* set — the English female "Stokie" voice from the TTS 2.0 generation.
+*/
+var BYTEPLUS_DEFAULT_TTS_SPEAKER = "en_female_stokie_uranus_bigtts";
+/**
+* Hard cap on a single Seed Speech synthesis, in seconds. Longer scripts must
+* be split across calls and stitched client-side.
+*
+* The cap applies to the *pre-rate* length the service bills on — the
+* `original_duration` it returns. The delivered clip can run longer than this
+* when `speech_rate` slows it down.
+*/
+var BYTEPLUS_TTS_MAX_OUTPUT_SECONDS = 120;
+/**
+* BytePlus Seed Speech text-to-speech adapter.
+*
+* Talks to `POST {baseURL}/api/v3/tts/create` on the Seed Speech voice host.
+* Two things differ from the Ark-hosted adapters in this package:
+*
+* - **Separate API key.** Seed Speech authenticates with `X-Api-Key` and its
+*   own key (`BYTEPLUS_VOICE_API_KEY`). An `ARK_API_KEY` sent here is
+*   rejected with `45000010 Invalid X-Api-Key`.
+* - **120 s output cap.** A single call synthesises at most
+*   {@link BYTEPLUS_TTS_MAX_OUTPUT_SECONDS} seconds of audio; longer scripts
+*   have to be split and stitched client-side. The cap is measured before
+*   `speech_rate` is applied, so a slowed clip can play for longer than that
+*   — `result.duration` is the delivered length and `result.originalDuration`
+*   is the metered one.
+*
+* Streaming synthesis (`tts/unidirectional` and the WebSocket API) is not
+* covered by this adapter — note that endpoint spells the text field `text`,
+* while this one uses `text_prompt`.
+*
+* @example
+* ```ts
+* const adapter = byteplusSpeech('seed-audio-1.0')
+* const result = await generateSpeech({
+*   adapter,
+*   text: 'welcome to the guitar store',
+*   voice: 'en_female_stokie_uranus_bigtts',
+*   format: 'mp3',
+* })
+* ```
+*/
+var BytePlusTTSAdapter = class extends BaseTTSAdapter {
+	name = "byteplus";
+	apiKey;
+	baseURL;
+	defaultHeaders;
+	fetchImpl;
+	constructor(model, config) {
+		super(model, config);
+		const resolved = withBytePlusVoiceDefaults(config);
+		this.apiKey = resolved.apiKey;
+		this.baseURL = resolved.baseURL ?? "https://voice.ap-southeast-1.bytepluses.com";
+		this.defaultHeaders = resolved.defaultHeaders ?? {};
+		this.fetchImpl = resolved.fetch ?? globalThis.fetch.bind(globalThis);
+	}
+	async generateSpeech(options) {
+		const { logger, model, text, voice, format, speed, modelOptions } = options;
+		logger.request(`activity=generateSpeech provider=byteplus model=${model}`, {
+			provider: "byteplus",
+			model
+		});
+		const { body, audioFormat, sampleRate } = buildTTSRequestBody({
+			model,
+			text,
+			voice,
+			format,
+			speed,
+			modelOptions,
+			logger
+		});
+		try {
+			const response = await this.fetchImpl(`${this.baseURL}${TTS_CREATE_PATH}`, {
+				method: "POST",
+				headers: bytePlusVoiceHeaders(this.apiKey, {
+					...this.defaultHeaders,
+					"X-Api-Request-Id": newRequestId()
+				}),
+				body: JSON.stringify(body)
+			});
+			const payload = await readJsonBody(response);
+			if (!response.ok) throw bytePlusVoiceError(response.status, payload, "text-to-speech");
+			const data = payload;
+			if (!isZeroCode(data.code)) throw bytePlusVoiceError(response.status, payload, "text-to-speech");
+			if (typeof data.audio !== "string" || data.audio.length === 0) throw new Error(`BytePlus Seed Speech text-to-speech returned a success response with no audio (model ${model}).`);
+			const duration = toDurationSeconds(data.duration);
+			const originalDuration = toDurationSeconds(data.original_duration);
+			return {
+				id: generateId(this.name),
+				model,
+				audio: data.audio,
+				format: audioFormat,
+				contentType: getContentType(audioFormat, sampleRate),
+				...duration !== void 0 && { duration },
+				...originalDuration !== void 0 && { originalDuration },
+				...data.subtitle !== void 0 && { subtitle: data.subtitle },
+				...data.url !== void 0 && { url: data.url }
+			};
+		} catch (error) {
+			logger.errors("byteplus.generateSpeech fatal", {
+				error: toRunErrorPayload(error, "byteplus.generateSpeech failed"),
+				source: "byteplus.generateSpeech"
+			});
+			throw error;
+		}
+	}
+};
+/**
+* Build the JSON body for `POST /api/v3/tts/create`, resolving the voice,
+* output format and rate fields in one place.
+*
+* Returns the request `body`, the resolved `audioFormat` and the
+* `sampleRate`, which the caller reports on the result and turns into a
+* `contentType`.
+*/
+function buildTTSRequestBody(options) {
+	const { model, text, voice, format, speed, modelOptions, logger } = options;
+	const audioFormat = pickAudioFormat(modelOptions?.format, format, logger);
+	const sampleRate = modelOptions?.sample_rate ?? DEFAULT_SAMPLE_RATE;
+	const audioConfig = {
+		format: audioFormat,
+		sample_rate: sampleRate
+	};
+	if (modelOptions?.pitch_rate !== void 0) audioConfig.pitch_rate = modelOptions.pitch_rate;
+	if (modelOptions?.loudness_rate !== void 0) audioConfig.loudness_rate = modelOptions.loudness_rate;
+	if (modelOptions?.enable_subtitle !== void 0) audioConfig.enable_subtitle = modelOptions.enable_subtitle;
+	const speechRate = modelOptions?.speech_rate ?? (speed !== void 0 ? toSpeechRate(speed, logger) : void 0);
+	if (speechRate !== void 0) audioConfig.speech_rate = speechRate;
+	const body = {
+		model,
+		[TTS_TEXT_FIELD]: text,
+		references: modelOptions?.references ?? [{ speaker: modelOptions?.speaker ?? voice ?? "en_female_stokie_uranus_bigtts" }],
+		audio_config: audioConfig
+	};
+	if (modelOptions?.watermark !== void 0) body.watermark = modelOptions.watermark;
+	return {
+		body,
+		audioFormat,
+		sampleRate
+	};
+}
+/**
+* Convert the cross-provider `TTSOptions.speed` multiplier into Seed Speech's
+* `speech_rate` percentage.
+*
+* ```
+* speech_rate = clamp(round((speed - 1) * 100), -50, 100)
+* ```
+*
+* so `0.5 → -50`, `1.0 → 0`, `1.5 → 50`, `2.0 → 100`.
+*
+* The range `-50`..`100` and both multiplier anchors (`-50` = 0.5×,
+* `100` = 2×) are documented, and hold on both the `/tts/create` and
+* `/tts/unidirectional` endpoints.
+*
+* `TTSOptions.speed` spans a wider 0.25×–4× than the endpoint supports, so
+* anything outside 0.5×–2× clamps (and warns) rather than erroring.
+*/
+function toSpeechRate(speed, logger) {
+	const rate = Math.round((speed - 1) * 100);
+	const clamped = Math.min(100, Math.max(-50, rate));
+	if (clamped !== rate) logger?.warn(`Speed ${speed}× is outside the range BytePlus Seed Speech documents (0.5×–2×) — clamping speech_rate from ${rate} to ${clamped}.`, {
+		provider: "byteplus",
+		requestedSpeed: speed,
+		speechRate: clamped
+	});
+	return clamped;
+}
+/**
+* Map the cross-provider `TTSOptions.format` onto a Seed Speech output
+* format. An explicit `modelOptions.format` always wins.
+*
+* Seed Speech produces `wav`, `mp3`, `pcm` and `ogg_opus`. The generic
+* `opus` maps onto `ogg_opus`; `aac` and `flac` have no equivalent and fall
+* back to `mp3` (matching how the other non-OpenAI TTS adapters in this repo
+* handle unsupported codecs). The fallback is logged so it isn't silent.
+*/
+function pickAudioFormat(override, format, logger) {
+	if (override) return override;
+	if (!format) return "mp3";
+	switch (format) {
+		case "mp3":
+		case "wav":
+		case "pcm": return format;
+		case "opus": return "ogg_opus";
+		case "aac":
+		case "flac":
+			logger.warn(`BytePlus Seed Speech does not support ${format} output — falling back to mp3. Set modelOptions.format to choose between wav, mp3, pcm and ogg_opus.`, {
+				provider: "byteplus",
+				requestedFormat: format
+			});
+			return "mp3";
+	}
+}
+/**
+* Build a per-request id for the `X-Api-Request-Id` header. Falls back to the
+* package's own id generator on runtimes without `crypto.randomUUID`.
+*/
+function newRequestId() {
+	return globalThis.crypto?.randomUUID?.() ?? generateId("byteplus-tts");
+}
+/**
+* MIME type for a Seed Speech output format.
+*
+* `pcm` is raw little-endian 16-bit samples, so its media type has to carry
+* the sample rate (RFC 3551/3555). The adapter always resolves a rate, so one
+* is always available here.
+*/
+function getContentType(format, sampleRate) {
+	switch (format) {
+		case "mp3": return "audio/mpeg";
+		case "wav": return "audio/wav";
+		case "ogg_opus": return "audio/ogg;codecs=opus";
+		case "pcm": return `audio/L16;rate=${sampleRate ?? 24e3}`;
+	}
+}
+/**
+* Coerce a `duration` / `original_duration` field to a usable number of
+* seconds.
+*
+* Both are documented as float **seconds**, so this only parses the string
+* form and drops values that can't be a length (zero, negative, non-numeric).
+* Note that `duration` may legitimately exceed
+* {@link BYTEPLUS_TTS_MAX_OUTPUT_SECONDS} — a clip synthesised at
+* `speech_rate: -50` runs at half speed, so up to 120 s of billed audio can
+* be delivered as up to 240 s of playback. Do not "correct" a large value
+* here; the cap applies to `original_duration`.
+*
+* The subtitle timings are the mixed-unit exception: those are milliseconds
+* and are passed through untouched on {@link BytePlusTTSResult.subtitle}.
+*/
+function toDurationSeconds(raw) {
+	const value = typeof raw === "string" ? Number(raw) : raw;
+	if (value === void 0 || !Number.isFinite(value) || value <= 0) return;
+	return value;
+}
+/**
+* Creates a BytePlus Seed Speech TTS adapter with an explicit API key.
+*
+* The key is the **Seed Speech** key, not the Ark key used by the chat, image
+* and video adapters.
+*
+* @example
+* ```ts
+* const adapter = createBytePlusSpeech('seed-audio-1.0', process.env.BYTEPLUS_VOICE_API_KEY!)
+* ```
+*/
+function createBytePlusSpeech(model, apiKey, config) {
+	return new BytePlusTTSAdapter(model, {
+		...config,
+		apiKey
+	});
+}
+/**
+* Creates a BytePlus Seed Speech TTS adapter, reading the API key from
+* `BYTEPLUS_VOICE_API_KEY`.
+*
+* @throws Error if `BYTEPLUS_VOICE_API_KEY` is not set.
+*/
+function byteplusSpeech(model, config) {
+	return createBytePlusSpeech(model, getBytePlusVoiceApiKeyFromEnv(), config);
+}
+//#endregion
+export { BYTEPLUS_DEFAULT_TTS_SPEAKER, BYTEPLUS_TTS_MAX_OUTPUT_SECONDS, BytePlusTTSAdapter, buildTTSRequestBody, byteplusSpeech, createBytePlusSpeech, getContentType, toDurationSeconds, toSpeechRate };
+
+//# sourceMappingURL=tts.js.map

package/dist/esm/adapters/tts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts.js","names":[],"sources":["../../../src/adapters/tts.ts"],"sourcesContent":["import { BaseTTSAdapter } from '@tanstack/ai/adapters'\nimport { generateId } from '@tanstack/ai-utils'\nimport { toRunErrorPayload } from '@tanstack/ai/adapter-internals'\nimport {\n  BYTEPLUS_VOICE_BASE_URL,\n  bytePlusVoiceError,\n  bytePlusVoiceHeaders,\n  getBytePlusVoiceApiKeyFromEnv,\n  readJsonBody,\n  withBytePlusVoiceDefaults,\n} from '../utils/client'\nimport type { TTSOptions } from '@tanstack/ai'\nimport type { InternalLogger } from '@tanstack/ai/adapter-internals'\nimport type { BytePlusVoiceConfig } from '../utils/client'\nimport type { BytePlusTTSModel } from '../model-meta'\nimport type {\n  BytePlusTTSAudioConfig,\n  BytePlusTTSAudioFormat,\n  BytePlusTTSCreateRequest,\n  BytePlusTTSCreateResponse,\n} from '../audio/wire-types'\nimport type {\n  BytePlusTTSProviderOptions,\n  BytePlusTTSResult,\n} from '../audio/tts-provider-options'\n\n/** Path of the synchronous Seed Speech synthesis endpoint. */\nconst TTS_CREATE_PATH = '/api/v3/tts/create'\n\n/**\n * Name of the request field carrying the text to speak.\n *\n * **`text_prompt` is correct — do not \"fix\" this to `text`.** The endpoint\n * schema (docs.byteplus.com/en/docs/byteplusvoice/seedaudio-01) lists this\n * body as exactly `model`, `text_prompt`, `references`, `audio_config`,\n * `watermark`; there is no request-side `text`. The `text` spelling belongs\n * to the *other* endpoint, `/tts/unidirectional` (TTS 2.0), where it sits\n * under `req_params.text`. The name stays isolated here so the two spellings\n * never get conflated.\n */\nconst TTS_TEXT_FIELD = 'text_prompt' satisfies keyof BytePlusTTSCreateRequest\n\n/**\n * Sample rate used when the caller doesn't pick one. The endpoint documents a\n * default of 40000, which is not among the rates it accepts — so the adapter\n * never relies on the server default and always sends this instead.\n */\nconst DEFAULT_SAMPLE_RATE = 24000\n\n/**\n * True when a Seed Speech envelope's `code` means success.\n *\n * Seed Speech uses `0` for success and a flat numeric code otherwise\n * (`45000010 Invalid X-Api-Key`). The success envelope has not been confirmed\n * against a live key, so `code` is accepted as a number, its string form, or\n * absent — an envelope that omits `code` entirely is treated as success, which\n * is what the HTTP status already told us.\n */\nfunction isZeroCode(code: number | string | undefined): boolean {\n  if (code === undefined) return true\n  return Number(code) === 0\n}\n\n/**\n * Voice used when neither `TTSOptions.voice` nor `modelOptions.speaker` is\n * set — the English female \"Stokie\" voice from the TTS 2.0 generation.\n */\nexport const BYTEPLUS_DEFAULT_TTS_SPEAKER = 'en_female_stokie_uranus_bigtts'\n\n/**\n * Hard cap on a single Seed Speech synthesis, in seconds. Longer scripts must\n * be split across calls and stitched client-side.\n *\n * The cap applies to the *pre-rate* length the service bills on — the\n * `original_duration` it returns. The delivered clip can run longer than this\n * when `speech_rate` slows it down.\n */\nexport const BYTEPLUS_TTS_MAX_OUTPUT_SECONDS = 120\n\n/**\n * BytePlus Seed Speech text-to-speech adapter.\n *\n * Talks to `POST {baseURL}/api/v3/tts/create` on the Seed Speech voice host.\n * Two things differ from the Ark-hosted adapters in this package:\n *\n * - **Separate API key.** Seed Speech authenticates with `X-Api-Key` and its\n *   own key (`BYTEPLUS_VOICE_API_KEY`). An `ARK_API_KEY` sent here is\n *   rejected with `45000010 Invalid X-Api-Key`.\n * - **120 s output cap.** A single call synthesises at most\n *   {@link BYTEPLUS_TTS_MAX_OUTPUT_SECONDS} seconds of audio; longer scripts\n *   have to be split and stitched client-side. The cap is measured before\n *   `speech_rate` is applied, so a slowed clip can play for longer than that\n *   — `result.duration` is the delivered length and `result.originalDuration`\n *   is the metered one.\n *\n * Streaming synthesis (`tts/unidirectional` and the WebSocket API) is not\n * covered by this adapter — note that endpoint spells the text field `text`,\n * while this one uses `text_prompt`.\n *\n * @example\n * ```ts\n * const adapter = byteplusSpeech('seed-audio-1.0')\n * const result = await generateSpeech({\n *   adapter,\n *   text: 'welcome to the guitar store',\n *   voice: 'en_female_stokie_uranus_bigtts',\n *   format: 'mp3',\n * })\n * ```\n */\nexport class BytePlusTTSAdapter<\n  TModel extends BytePlusTTSModel = BytePlusTTSModel,\n> extends BaseTTSAdapter<TModel, BytePlusTTSProviderOptions> {\n  readonly name = 'byteplus' as const\n\n  private readonly apiKey: string\n  private readonly baseURL: string\n  private readonly defaultHeaders: Record<string, string>\n  private readonly fetchImpl: typeof fetch\n\n  constructor(model: TModel, config: BytePlusVoiceConfig) {\n    super(model, config)\n    const resolved = withBytePlusVoiceDefaults(config)\n    this.apiKey = resolved.apiKey\n    this.baseURL = resolved.baseURL ?? BYTEPLUS_VOICE_BASE_URL\n    this.defaultHeaders = resolved.defaultHeaders ?? {}\n    this.fetchImpl = resolved.fetch ?? globalThis.fetch.bind(globalThis)\n  }\n\n  async generateSpeech(\n    options: TTSOptions<BytePlusTTSProviderOptions>,\n  ): Promise<BytePlusTTSResult> {\n    const { logger, model, text, voice, format, speed, modelOptions } = options\n\n    logger.request(`activity=generateSpeech provider=byteplus model=${model}`, {\n      provider: 'byteplus',\n      model,\n    })\n\n    const { body, audioFormat, sampleRate } = buildTTSRequestBody({\n      model,\n      text,\n      voice,\n      format,\n      speed,\n      modelOptions,\n      logger,\n    })\n\n    try {\n      const response = await this.fetchImpl(\n        `${this.baseURL}${TTS_CREATE_PATH}`,\n        {\n          method: 'POST',\n          headers: bytePlusVoiceHeaders(this.apiKey, {\n            ...this.defaultHeaders,\n            // Client-generated per-request id. BytePlus echoes it in their\n            // request logs, which is what support asks for when diagnosing a\n            // synthesis failure.\n            'X-Api-Request-Id': newRequestId(),\n          }),\n          body: JSON.stringify(body),\n        },\n      )\n\n      const payload = await readJsonBody(response)\n\n      if (!response.ok) {\n        throw bytePlusVoiceError(response.status, payload, 'text-to-speech')\n      }\n\n      const data = payload as BytePlusTTSCreateResponse\n\n      // Seed Speech reports status in the body, not only in the HTTP status:\n      // a 200 can carry a non-zero `code`. Check it before looking at `audio`,\n      // because a failed call may still return a partial or placeholder\n      // payload that would otherwise be handed back as if it were valid.\n      //\n      // `code` is accepted as a number *or* a string. The success envelope was\n      // never confirmed against a live key (no voice key yet — see\n      // `audio/wire-types.ts`), and `readStringField` already tolerates both\n      // forms when rendering the error, so requiring a number here would let\n      // `{\"code\": \"45000010\"}` through both this gate and the one below.\n      if (!isZeroCode(data.code)) {\n        throw bytePlusVoiceError(response.status, payload, 'text-to-speech')\n      }\n\n      // Belt and braces for a 200 that reports success but carries nothing to\n      // play. Say that the adapter rejected it, rather than reusing the\n      // envelope-error phrasing — a bare \"failed (200)\" gives no hint that the\n      // response was well-formed and simply empty.\n      if (typeof data.audio !== 'string' || data.audio.length === 0) {\n        throw new Error(\n          `BytePlus Seed Speech text-to-speech returned a success response ` +\n            `with no audio (model ${model}).`,\n        )\n      }\n\n      const duration = toDurationSeconds(data.duration)\n      const originalDuration = toDurationSeconds(data.original_duration)\n\n      return {\n        id: generateId(this.name),\n        model,\n        audio: data.audio,\n        format: audioFormat,\n        contentType: getContentType(audioFormat, sampleRate),\n        ...(duration !== undefined && { duration }),\n        ...(originalDuration !== undefined && { originalDuration }),\n        ...(data.subtitle !== undefined && { subtitle: data.subtitle }),\n        ...(data.url !== undefined && { url: data.url }),\n      }\n    } catch (error) {\n      logger.errors('byteplus.generateSpeech fatal', {\n        error: toRunErrorPayload(error, 'byteplus.generateSpeech failed'),\n        source: 'byteplus.generateSpeech',\n      })\n      throw error\n    }\n  }\n}\n\n/**\n * Build the JSON body for `POST /api/v3/tts/create`, resolving the voice,\n * output format and rate fields in one place.\n *\n * Returns the request `body`, the resolved `audioFormat` and the\n * `sampleRate`, which the caller reports on the result and turns into a\n * `contentType`.\n */\nexport function buildTTSRequestBody(options: {\n  model: string\n  text: string\n  voice: string | undefined\n  format: TTSOptions['format'] | undefined\n  speed: number | undefined\n  modelOptions: BytePlusTTSProviderOptions | undefined\n  logger: InternalLogger\n}): {\n  body: BytePlusTTSCreateRequest\n  audioFormat: BytePlusTTSAudioFormat\n  sampleRate: number\n} {\n  const { model, text, voice, format, speed, modelOptions, logger } = options\n\n  const audioFormat = pickAudioFormat(modelOptions?.format, format, logger)\n  // Always explicit: the documented server default (40000) is not one of the\n  // rates the endpoint accepts, so relying on it is a coin flip.\n  const sampleRate = modelOptions?.sample_rate ?? DEFAULT_SAMPLE_RATE\n\n  const audioConfig: BytePlusTTSAudioConfig = {\n    format: audioFormat,\n    sample_rate: sampleRate,\n  }\n  if (modelOptions?.pitch_rate !== undefined) {\n    audioConfig.pitch_rate = modelOptions.pitch_rate\n  }\n  if (modelOptions?.loudness_rate !== undefined) {\n    audioConfig.loudness_rate = modelOptions.loudness_rate\n  }\n  if (modelOptions?.enable_subtitle !== undefined) {\n    audioConfig.enable_subtitle = modelOptions.enable_subtitle\n  }\n\n  // An explicit `speech_rate` always wins over the derived one — it is the\n  // native unit and the only way to reach the extremes precisely.\n  const speechRate =\n    modelOptions?.speech_rate ??\n    (speed !== undefined ? toSpeechRate(speed, logger) : undefined)\n  if (speechRate !== undefined) {\n    audioConfig.speech_rate = speechRate\n  }\n\n  const body: BytePlusTTSCreateRequest = {\n    model,\n    [TTS_TEXT_FIELD]: text,\n    // The voice belongs inside `references`, not at the top level — a\n    // top-level `speaker` is silently ignored by the server. The flat member\n    // shape here is the best-supported reading of the docs; see\n    // `BytePlusTTSReference` for the unresolved part and the live-probe flag.\n    references: modelOptions?.references ?? [\n      {\n        speaker: modelOptions?.speaker ?? voice ?? BYTEPLUS_DEFAULT_TTS_SPEAKER,\n      },\n    ],\n    audio_config: audioConfig,\n  }\n  if (modelOptions?.watermark !== undefined) {\n    body.watermark = modelOptions.watermark\n  }\n\n  return { body, audioFormat, sampleRate }\n}\n\n/**\n * Convert the cross-provider `TTSOptions.speed` multiplier into Seed Speech's\n * `speech_rate` percentage.\n *\n * ```\n * speech_rate = clamp(round((speed - 1) * 100), -50, 100)\n * ```\n *\n * so `0.5 → -50`, `1.0 → 0`, `1.5 → 50`, `2.0 → 100`.\n *\n * The range `-50`..`100` and both multiplier anchors (`-50` = 0.5×,\n * `100` = 2×) are documented, and hold on both the `/tts/create` and\n * `/tts/unidirectional` endpoints.\n *\n * `TTSOptions.speed` spans a wider 0.25×–4× than the endpoint supports, so\n * anything outside 0.5×–2× clamps (and warns) rather than erroring.\n */\nexport function toSpeechRate(speed: number, logger?: InternalLogger): number {\n  const rate = Math.round((speed - 1) * 100)\n  const clamped = Math.min(100, Math.max(-50, rate))\n  if (clamped !== rate) {\n    logger?.warn(\n      `Speed ${speed}× is outside the range BytePlus Seed Speech documents (0.5×–2×) — clamping speech_rate from ${rate} to ${clamped}.`,\n      { provider: 'byteplus', requestedSpeed: speed, speechRate: clamped },\n    )\n  }\n  return clamped\n}\n\n/**\n * Map the cross-provider `TTSOptions.format` onto a Seed Speech output\n * format. An explicit `modelOptions.format` always wins.\n *\n * Seed Speech produces `wav`, `mp3`, `pcm` and `ogg_opus`. The generic\n * `opus` maps onto `ogg_opus`; `aac` and `flac` have no equivalent and fall\n * back to `mp3` (matching how the other non-OpenAI TTS adapters in this repo\n * handle unsupported codecs). The fallback is logged so it isn't silent.\n */\nfunction pickAudioFormat(\n  override: BytePlusTTSAudioFormat | undefined,\n  format: TTSOptions['format'] | undefined,\n  logger: InternalLogger,\n): BytePlusTTSAudioFormat {\n  if (override) return override\n  if (!format) return 'mp3'\n  switch (format) {\n    case 'mp3':\n    case 'wav':\n    case 'pcm':\n      return format\n    case 'opus':\n      return 'ogg_opus'\n    case 'aac':\n    case 'flac':\n      logger.warn(\n        `BytePlus Seed Speech does not support ${format} output — falling back to mp3. Set modelOptions.format to choose between wav, mp3, pcm and ogg_opus.`,\n        { provider: 'byteplus', requestedFormat: format },\n      )\n      return 'mp3'\n  }\n}\n\n/**\n * Build a per-request id for the `X-Api-Request-Id` header. Falls back to the\n * package's own id generator on runtimes without `crypto.randomUUID`.\n */\nfunction newRequestId(): string {\n  return globalThis.crypto?.randomUUID?.() ?? generateId('byteplus-tts')\n}\n\n/**\n * MIME type for a Seed Speech output format.\n *\n * `pcm` is raw little-endian 16-bit samples, so its media type has to carry\n * the sample rate (RFC 3551/3555). The adapter always resolves a rate, so one\n * is always available here.\n */\nexport function getContentType(\n  format: BytePlusTTSAudioFormat,\n  sampleRate?: number,\n): string {\n  switch (format) {\n    case 'mp3':\n      return 'audio/mpeg'\n    case 'wav':\n      return 'audio/wav'\n    case 'ogg_opus':\n      return 'audio/ogg;codecs=opus'\n    case 'pcm':\n      return `audio/L16;rate=${sampleRate ?? 24000}`\n  }\n}\n\n/**\n * Coerce a `duration` / `original_duration` field to a usable number of\n * seconds.\n *\n * Both are documented as float **seconds**, so this only parses the string\n * form and drops values that can't be a length (zero, negative, non-numeric).\n * Note that `duration` may legitimately exceed\n * {@link BYTEPLUS_TTS_MAX_OUTPUT_SECONDS} — a clip synthesised at\n * `speech_rate: -50` runs at half speed, so up to 120 s of billed audio can\n * be delivered as up to 240 s of playback. Do not \"correct\" a large value\n * here; the cap applies to `original_duration`.\n *\n * The subtitle timings are the mixed-unit exception: those are milliseconds\n * and are passed through untouched on {@link BytePlusTTSResult.subtitle}.\n */\nexport function toDurationSeconds(\n  raw: number | string | undefined,\n): number | undefined {\n  const value = typeof raw === 'string' ? Number(raw) : raw\n  if (value === undefined || !Number.isFinite(value) || value <= 0) {\n    return undefined\n  }\n  return value\n}\n\n/**\n * Creates a BytePlus Seed Speech TTS adapter with an explicit API key.\n *\n * The key is the **Seed Speech** key, not the Ark key used by the chat, image\n * and video adapters.\n *\n * @example\n * ```ts\n * const adapter = createBytePlusSpeech('seed-audio-1.0', process.env.BYTEPLUS_VOICE_API_KEY!)\n * ```\n */\nexport function createBytePlusSpeech<\n  TModel extends BytePlusTTSModel = BytePlusTTSModel,\n>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<BytePlusVoiceConfig, 'apiKey'>,\n): BytePlusTTSAdapter<TModel> {\n  return new BytePlusTTSAdapter(model, { ...config, apiKey })\n}\n\n/**\n * Creates a BytePlus Seed Speech TTS adapter, reading the API key from\n * `BYTEPLUS_VOICE_API_KEY`.\n *\n * @throws Error if `BYTEPLUS_VOICE_API_KEY` is not set.\n */\nexport function byteplusSpeech<\n  TModel extends BytePlusTTSModel = BytePlusTTSModel,\n>(\n  model: TModel,\n  config?: Omit<BytePlusVoiceConfig, 'apiKey'>,\n): BytePlusTTSAdapter<TModel> {\n  return createBytePlusSpeech(model, getBytePlusVoiceApiKeyFromEnv(), config)\n}\n"],"mappings":"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"}

package/dist/esm/adapters/video.d.ts

@@ -0,0 +1,182 @@
+import { BaseVideoAdapter, DurationOptions } from '@tanstack/ai/adapters';
+import { VideoGenerationOptions, VideoJobResult, VideoStatusResult, VideoUrlResult } from '@tanstack/ai';
+import { BytePlusVideoTaskStatus } from '../video/wire-types.js';
+import { BytePlusVideoProviderOptions } from '../video/video-provider-options.js';
+import { BytePlusVideoModelOrString, ResolveBytePlusVideoInputModalities, ResolveBytePlusVideoSize } from '../model-meta.js';
+import { BytePlusArkConfig } from '../utils/client.js';
+/**
+ * Configuration for the BytePlus Seedance video adapter.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export interface BytePlusVideoConfig extends BytePlusArkConfig {
+}
+/**
+ * BytePlus Seedance video generation adapter.
+ *
+ * Drives Ark's asynchronous task API — `POST /contents/generations/tasks` to
+ * submit, `GET /contents/generations/tasks/{id}` to poll and to read the
+ * finished video URL. Core owns the polling loop; this adapter implements the
+ * three primitives plus the duration metadata.
+ *
+ * Prompt parts map onto Seedance's `content[]` roles, which the API sorts into
+ * mutually exclusive task types:
+ *
+ * - `'start_frame'` (or a single un-roled image) → `first_frame` — the frame
+ *   the video opens on (`i2v`).
+ * - `'end_frame'` → `last_frame` — the frame it closes on (`flf2v`); Seedance
+ *   requires a `first_frame` alongside it, and
+ *   `seedance-1-0-pro-fast-251015` does not support it at all.
+ * - `'reference'` / `'character'` → `reference_image`, video parts →
+ *   `reference_video`, audio parts → `reference_audio` — subject and style
+ *   references the model draws on (`r2v`, Seedance 2.0 family only).
+ *
+ * Frame roles and reference roles cannot be combined in one request, so the
+ * adapter rejects a mix up front rather than surfacing a raw 400.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ *
+ * @example
+ * ```typescript
+ * const adapter = byteplusVideo('seedance-1-0-pro-fast-251015')
+ *
+ * const { jobId } = await generateVideo({
+ *   adapter,
+ *   prompt: 'a guitar being played in a store',
+ *   size: '16:9_720p',
+ *   duration: 4,
+ *   modelOptions: { service_tier: 'flex' },
+ * })
+ * ```
+ */
+export declare class BytePlusVideoAdapter<TModel extends BytePlusVideoModelOrString> extends BaseVideoAdapter<TModel, BytePlusVideoProviderOptions, Record<TModel, BytePlusVideoProviderOptions>, Record<TModel, ResolveBytePlusVideoSize<TModel>>, Record<TModel, ResolveBytePlusVideoInputModalities<TModel>>, Record<TModel, number>> {
+    readonly name: "byteplus";
+    /** Config with the Ark base URL resolved and its trailing slashes trimmed. */
+    private readonly clientConfig;
+    constructor(config: BytePlusVideoConfig, model: TModel);
+    private request;
+    /**
+     * Builds the `content[]` array from the resolved prompt, enforcing
+     * Seedance's role vocabulary and mode exclusivity.
+     */
+    private buildContent;
+    createVideoJob(options: VideoGenerationOptions<BytePlusVideoProviderOptions, ResolveBytePlusVideoSize<TModel>, number>): Promise<VideoJobResult>;
+    /**
+     * Fetches a task, tagging the thrown error with the HTTP status.
+     *
+     * The 200 body is validated rather than cast. `readJsonBody` returns
+     * `undefined` for an empty body and the raw text for a non-JSON one — both
+     * documented failure modes of these hosts (an HTML error page from a proxy
+     * in front of the API). Casting either to `BytePlusVideoTask` yields a task
+     * whose `status` is `undefined`, which {@link mapStatus} would have to
+     * interpret; the honest answer is that the response was not a task at all,
+     * so say so while the body is still in hand.
+     */
+    private retrieveTask;
+    getVideoStatus(jobId: string): Promise<VideoStatusResult>;
+    getVideoUrl(jobId: string): Promise<VideoUrlResult>;
+    /**
+     * Maps Seedance task states onto the generic video status set. `expired`
+     * (the task outlived `execution_expires_after`) and `cancelled` are
+     * terminal non-successes, so both report as failed.
+     *
+     * An unrecognized state throws rather than defaulting to `processing`.
+     * Core's poll loop treats `processing` as "keep waiting", so mapping an
+     * unknown state — a missing `status`, or a terminal one Ark adds later such
+     * as `rejected` — onto it means polling until `maxDuration` and then
+     * reporting a generic timeout, with the state Ark actually sent never
+     * reaching the caller. Failing here names it.
+     */
+    protected mapStatus(apiStatus: BytePlusVideoTaskStatus | string | undefined): VideoStatusResult['status'];
+    /**
+     * Seedance accepts any whole second inside a per-model range: 4–15s on the
+     * 2.0 family, 4–12s on 1.5-pro, 2–12s on the 1.0 models. An unknown model
+     * reports the union of those ranges as a UI hint — see
+     * `BYTEPLUS_VIDEO_FALLBACK_DURATIONS`, which `createVideoJob` does not snap
+     * against.
+     */
+    availableDurations(): DurationOptions<number>;
+    /**
+     * Coerce a raw seconds value to the closest duration this model accepts
+     * (clamped to its range and rounded to whole seconds).
+     */
+    snapDuration(seconds: number): number | undefined;
+}
+/**
+ * Creates a BytePlus Seedance video adapter with an explicit API key.
+ * Type resolution happens here at the call site.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ *
+ * @param model - The model name (e.g., 'seedance-1-0-pro-fast-251015')
+ * @param apiKey - Your BytePlus Ark API key
+ * @param config - Optional additional configuration
+ * @returns Configured BytePlus video adapter instance with resolved types
+ *
+ * @example
+ * ```typescript
+ * const adapter = createBytePlusVideo('seedance-1-5-pro-251215', 'ark-...')
+ *
+ * const { jobId } = await generateVideo({
+ *   adapter,
+ *   prompt: 'a guitar being played in a store',
+ *   size: '16:9_1080p',
+ *   duration: 5,
+ * })
+ * ```
+ */
+export declare function createBytePlusVideo<TModel extends BytePlusVideoModelOrString>(model: TModel, apiKey: string, config?: Omit<BytePlusVideoConfig, 'apiKey'>): BytePlusVideoAdapter<TModel>;
+/**
+ * Creates a BytePlus Seedance video adapter, reading `ARK_API_KEY` from the
+ * environment. Type resolution happens here at the call site.
+ *
+ * Note that Ark keys are region-isolated and Seedance is only served from the
+ * Asia-Pacific endpoint — an EU key will not work here.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ *
+ * @param model - The model name (e.g., 'dreamina-seedance-2-0-260128')
+ * @param config - Optional configuration (excluding apiKey, auto-detected)
+ * @returns Configured BytePlus video adapter instance with resolved types
+ * @throws Error if ARK_API_KEY is not found in environment
+ *
+ * @example
+ * ```typescript
+ * const adapter = byteplusVideo('dreamina-seedance-2-0-260128')
+ *
+ * // Image-to-video: an un-roled image is the opening frame.
+ * const { jobId } = await generateVideo({
+ *   adapter,
+ *   prompt: [
+ *     { type: 'text', content: 'the guitarist starts playing' },
+ *     { type: 'image', source: { type: 'url', value: 'https://example.com/shop.jpg' } },
+ *   ],
+ * })
+ *
+ * const status = await getVideoJobStatus({ adapter, jobId })
+ * ```
+ *
+ * ## Models this package does not know yet
+ *
+ * `model` also accepts any string, so a Seedance id BytePlus publishes after
+ * this release works without upgrading. **Seedance 2.5 is the case this exists
+ * for**: `dreamina-seedance-2-5-260628` is real and reachable, but its
+ * capability cells could not be probed from this repo's account (Ark answers
+ * 404 `ModelNotOpen` until the model is activated in the Ark Console), so it
+ * is deliberately absent from the narrowed model tables. Passing it here works
+ * for an account that has activated it.
+ *
+ * An unknown id relaxes both halves of the adapter: the `size` type widens to
+ * any string, provider options are ungated, and the runtime guards that encode
+ * per-model capabilities — resolution tiers, closing-frame and reference-media
+ * support, frame cardinality and mode exclusivity, duration snapping — stand
+ * down so Ark decides. Known ids are unaffected. See
+ * {@link BytePlusVideoModelOrString} for how to discover and probe an id.
+ *
+ * @example
+ * ```typescript
+ * // Seedance 2.5, before this package ships probe-verified metadata for it:
+ * const adapter = byteplusVideo('dreamina-seedance-2-5-260628')
+ * ```
+ */
+export declare function byteplusVideo<TModel extends BytePlusVideoModelOrString>(model: TModel, config?: Omit<BytePlusVideoConfig, 'apiKey'>): BytePlusVideoAdapter<TModel>;