@tanstack/ai-byteplus 0.3.4 → 0.3.7

package/dist/esm/adapters/tts.js

@@ -173,7 +173,7 @@ function buildTTSRequestBody(options) {
 		references: modelOptions?.references ?? [{ speaker: modelOptions?.speaker ?? voice ?? "en_female_stokie_uranus_bigtts" }],
 		audio_config: audioConfig
 	};
-	if (modelOptions?.watermark !== void 0) body.watermark = modelOptions.watermark;
+	if (modelOptions?.watermark !== void 0) body.watermark = typeof modelOptions.watermark === "boolean" ? { aigc_watermark: modelOptions.watermark } : modelOptions.watermark;
 	return {
 		body,
 		audioFormat,

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

@@ -1 +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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"}
+{"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.\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    // The endpoint wants an object. `true` means the audible marker, which is\n    // what a caller passing a boolean is asking for.\n    body.watermark =\n      typeof modelOptions.watermark === 'boolean'\n        ? { aigc_watermark: modelOptions.watermark }\n        : 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/audio/tts-provider-options.d.ts

@@ -1,4 +1,4 @@
-import { BytePlusTTSAudioFormat, BytePlusTTSReference, BytePlusTTSSampleRate, BytePlusTTSSubtitle } from './wire-types.js';
+import { BytePlusTTSAudioFormat, BytePlusTTSReference, BytePlusTTSSampleRate, BytePlusTTSSubtitle, BytePlusTTSWatermark } from './wire-types.js';
 import { TTSResult } from '@tanstack/ai';
 /**
  * Seed Speech voice identifier (`speaker` on the wire).
@@ -72,10 +72,13 @@ export interface BytePlusTTSProviderOptions {
      */
     enable_subtitle?: boolean;
     /**
-     * Watermark the generated audio. The field name is confirmed against the
-     * endpoint schema; the boolean type is assumed and unprobed.
+     * Watermark the generated audio.
+     *
+     * Seed Audio takes an object with two independent markers — an audible
+     * `aigc_watermark` appended to the clip and an `aigc_metadata` block written
+     * into the audio header. `true` is shorthand for `{ aigc_watermark: true }`.
      */
-    watermark?: boolean;
+    watermark?: boolean | BytePlusTTSWatermark;
 }
 /**
  * BytePlus-specific extension of `TTSResult`.

package/dist/esm/audio/wire-types.d.ts

@@ -46,15 +46,16 @@ export type BytePlusTTSSampleRate = (typeof BYTEPLUS_TTS_SAMPLE_RATES)[number];
  * audio references (30 s / 10 MB each) and 1 image reference (10 MB), and
  * image references are mutually exclusive with audio ones.
  *
- * **Member object shape is unresolved — must live-probe when the Seed Speech
- * key lands.** The docs list the member fields flat (`speaker | audio_data |
- * audio_url | image_data | image_url`) without a worked example, so whether
- * the server wants a flat `{ speaker }` or a discriminated `{ type, ... }`
- * could not be settled. The adapter sends the flat reading — see
- * `buildTTSRequestBody` in `../adapters/tts`.
+ * The member fields are flat (`speaker | audio_data | audio_url | image_data |
+ * image_url`), confirmed against
+ * docs.byteplus.com/en/docs/byteplusvoice/seedaudio-01.
  */
 export interface BytePlusTTSReference {
-    /** Stock voice id, e.g. `en_female_stokie_uranus_bigtts`. */
+    /**
+     * Voice id, e.g. `en_female_stokie_uranus_bigtts`. Either a stock TTS 2.0
+     * voice or the id of a voice you cloned through Voice Replication — this
+     * field is the join between replication and synthesis.
+     */
     speaker?: string;
     /** URL of a reference clip to clone (≤30 s, ≤10 MB). */
     audio_url?: string;
@@ -88,6 +89,36 @@ export interface BytePlusTTSAudioConfig {
     /** Emit sentence and word timings in the response. Defaults to `false`. */
     enable_subtitle?: boolean;
 }
+/**
+ * `watermark` block of a TTS request.
+ *
+ * Two independent markers, both off by default:
+ *
+ * - `aigc_watermark` — **explicit**: appends an audible rhythm marker to the
+ *   end of the clip.
+ * - `aigc_metadata` — **implicit**: writes provenance metadata into the audio
+ *   header. Nothing is written unless `enable` is `true`.
+ *
+ * This is an object, not a boolean — unlike Seedream images and Seedance
+ * video, where `watermark` genuinely is a boolean.
+ */
+export interface BytePlusTTSWatermark {
+    /** Append an audible rhythm marker to the end of the audio. Default `false`. */
+    aigc_watermark?: boolean;
+    /** Provenance metadata written into the audio header. */
+    aigc_metadata?: {
+        /** Write the metadata. Default `false` — the rest is ignored without it. */
+        enable?: boolean;
+        /** Name or code of the synthesis provider. */
+        content_producer?: string;
+        /** Content production id. */
+        produce_id?: string;
+        /** Name or code of the distribution provider. */
+        content_propagator?: string;
+        /** Content distribution id. */
+        propagate_id?: string;
+    };
+}
 /** Request body for `POST /api/v3/tts/create` — exactly five fields. */
 export interface BytePlusTTSCreateRequest {
     /** Seed Speech synthesis model, e.g. `seed-audio-1.0`. */
@@ -109,11 +140,8 @@ export interface BytePlusTTSCreateRequest {
     /** Voice selection and cloning references. See {@link BytePlusTTSReference}. */
     references?: Array<BytePlusTTSReference>;
     audio_config?: BytePlusTTSAudioConfig;
-    /**
-     * Watermark the generated audio. The field name is confirmed; the boolean
-     * type is assumed by analogy with Seedream's `watermark` and unprobed.
-     */
-    watermark?: boolean;
+    /** Watermark the generated audio. See {@link BytePlusTTSWatermark}. */
+    watermark?: BytePlusTTSWatermark;
 }
 /**
  * One timed entry of a TTS subtitle track.

package/dist/esm/audio/wire-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"wire-types.js","names":[],"sources":["../../../src/audio/wire-types.ts"],"sourcesContent":["/**\n * Minimal wire types for the BytePlus **Seed Speech** HTTP API (TTS + ASR).\n *\n * Seed Speech is a separate product from Ark: it lives on\n * `voice.ap-southeast-1.bytepluses.com`, authenticates with `X-Api-Key`\n * (a different key from `ARK_API_KEY`), and returns a flat numeric error\n * envelope instead of Ark's OpenAI-shaped one.\n *\n * Only the fields the adapters read or write are modelled here — this is a\n * hand-written subset, not a generated schema.\n *\n * Provenance:\n * - Endpoints, auth header, format/rate ranges and the 120 s TTS output cap:\n *   BytePlus Seed Speech docs (`docs.byteplus.com/en/docs/byteplusvoice`),\n *   captured in the Phase 0 research notes.\n * - Error envelope `{code, message}`: verified live — an Ark key sent as\n *   `X-Api-Key` returns HTTP 401 `{\"code\":45000010,\"message\":\"Invalid X-Api-Key\"}`.\n * - ASR request/response shape (`user`/`audio`/`request` in, `audio_info` +\n *   `result.utterances` out, all timings in **milliseconds**): the Volcengine\n *   flash-recognition reference the BytePlus endpoint is derived from\n *   (`docs.volcengine.com/docs/6561/1631584`).\n *\n * No Seed Speech API key was available when these were written, so the TTS\n * response fields are documented-but-unverified; the adapters parse them\n * defensively rather than assuming they are always present.\n */\n\n// ============================================================================\n// TTS — POST /api/v3/tts/create\n// ============================================================================\n\n/** Output container/codec accepted by `audio_config.format`. */\nexport type BytePlusTTSAudioFormat = 'wav' | 'mp3' | 'pcm' | 'ogg_opus'\n\n/**\n * Sample rates `audio_config.sample_rate` accepts.\n *\n * The docs also state a *default* of 40000, which is not one of the valid\n * values — a documentation bug. The adapter therefore always sends an\n * explicit rate rather than relying on the server default.\n */\nexport const BYTEPLUS_TTS_SAMPLE_RATES = [\n  8000, 16000, 24000, 32000, 44100, 48000,\n] as const\n\n/** A sample rate `audio_config.sample_rate` accepts. */\nexport type BytePlusTTSSampleRate = (typeof BYTEPLUS_TTS_SAMPLE_RATES)[number]\n\n/**\n * One entry of the request's `references` array.\n *\n * This is where the voice lives: `speaker` names a stock voice, while\n * `audio_url` / `audio_data` supply reference clips to clone (the `@Audio1`..\n * `@Audio3` markers in `text_prompt` address them positionally). Exactly one\n * of `speaker`, `audio_url` or `audio_data` may be set per entry; at most 3\n * audio references (30 s / 10 MB each) and 1 image reference (10 MB), and\n * image references are mutually exclusive with audio ones.\n *\n * **Member object shape is unresolved — must live-probe when the Seed Speech\n * key lands.** The docs list the member fields flat (`speaker | audio_data |\n * audio_url | image_data | image_url`) without a worked example, so whether\n * the server wants a flat `{ speaker }` or a discriminated `{ type, ... }`\n * could not be settled. The adapter sends the flat reading — see\n * `buildTTSRequestBody` in `../adapters/tts`.\n */\nexport interface BytePlusTTSReference {\n  /** Stock voice id, e.g. `en_female_stokie_uranus_bigtts`. */\n  speaker?: string\n  /** URL of a reference clip to clone (≤30 s, ≤10 MB). */\n  audio_url?: string\n  /** Base64 reference clip to clone (≤30 s, ≤10 MB). */\n  audio_data?: string\n  /** URL of a reference image (≤10 MB). Mutually exclusive with audio refs. */\n  image_url?: string\n  /** Base64 reference image (≤10 MB). Mutually exclusive with audio refs. */\n  image_data?: string\n}\n\n/**\n * `audio_config` block of a TTS request — exactly six fields.\n *\n * The three `*_rate` fields are integer percentages relative to the voice's\n * neutral delivery, not multipliers.\n */\nexport interface BytePlusTTSAudioConfig {\n  /** Output format. Defaults to `wav` server-side. */\n  format?: BytePlusTTSAudioFormat\n  /**\n   * Output sample rate in Hz. See {@link BYTEPLUS_TTS_SAMPLE_RATES} for the\n   * valid values and for why the adapter always sends one.\n   */\n  sample_rate?: number\n  /** Speaking rate, `-50`..`100`. `-50` = 0.5×, `0` = 1×, `100` = 2×. */\n  speech_rate?: number\n  /** Loudness adjustment, `-50`..`100`. `0` is the voice's natural level. */\n  loudness_rate?: number\n  /** Pitch adjustment, `-12`..`12`. `0` is the voice's natural pitch. */\n  pitch_rate?: number\n  /** Emit sentence and word timings in the response. Defaults to `false`. */\n  enable_subtitle?: boolean\n}\n\n/** Request body for `POST /api/v3/tts/create` — exactly five fields. */\nexport interface BytePlusTTSCreateRequest {\n  /** Seed Speech synthesis model, e.g. `seed-audio-1.0`. */\n  model: string\n  /**\n   * The text to speak (≤3000 chars). Dual-purpose: either literal text or a\n   * natural-language description of the delivery, and the place the\n   * `@Audio1`..`@Audio3` reference markers go.\n   *\n   * **`text_prompt` is correct — do not \"fix\" this to `text`.** This endpoint\n   * has no request-side `text` field. The `text` spelling belongs to the\n   * *other* endpoint, `/tts/unidirectional` (TTS 2.0), where it sits under\n   * `req_params.text`. Confirmed against\n   * docs.byteplus.com/en/docs/byteplusvoice/seedaudio-01, which lists this\n   * body as exactly `model`, `text_prompt`, `references`, `audio_config`,\n   * `watermark`.\n   */\n  text_prompt: string\n  /** Voice selection and cloning references. See {@link BytePlusTTSReference}. */\n  references?: Array<BytePlusTTSReference>\n  audio_config?: BytePlusTTSAudioConfig\n  /**\n   * Watermark the generated audio. The field name is confirmed; the boolean\n   * type is assumed by analogy with Seedream's `watermark` and unprobed.\n   */\n  watermark?: boolean\n}\n\n/**\n * One timed entry of a TTS subtitle track.\n *\n * **Times are milliseconds** — unlike the response's `duration` fields, which\n * are seconds. The endpoint genuinely mixes units.\n */\nexport interface BytePlusTTSSubtitleEntry {\n  text?: string\n  start_time?: number\n  end_time?: number\n}\n\n/** Sentence- and word-level timings returned when `enable_subtitle` is set. */\nexport interface BytePlusTTSSubtitle {\n  sentences?: Array<BytePlusTTSSubtitleEntry>\n  words?: Array<BytePlusTTSSubtitleEntry>\n}\n\n/** Response body for `POST /api/v3/tts/create`. */\nexport interface BytePlusTTSCreateResponse {\n  /**\n   * Status code — `0` on success, a flat error code otherwise.\n   *\n   * Typed as `number | string` because only the *error* envelope was verified\n   * live (HTTP 401 `{\"code\":45000010,…}`); the success envelope's shape is\n   * docs-derived and no voice key was available to confirm it. Treating a\n   * string code as \"not a failure\" would return a failed 200 as success, so\n   * the adapter coerces before comparing — see `isZeroCode` in\n   * `adapters/tts.ts`.\n   */\n  code?: number | string\n  message?: string\n  /** Base64-encoded audio in the requested `audio_config.format`. */\n  audio?: string\n  /**\n   * Length of the delivered audio in **seconds** (float), after `speech_rate`\n   * is applied. This can legitimately exceed 120 when the clip is slowed\n   * down — the 120 s cap applies to {@link BytePlusTTSCreateResponse.original_duration}.\n   */\n  duration?: number | string\n  /**\n   * Length in **seconds** (float) before rate adjustment. This is the billing\n   * basis and is capped at 120.\n   */\n  original_duration?: number | string\n  /** Temporary download URL for the same audio. Expires after ~2 hours. */\n  url?: string\n  /** Sentence and word timings, present when `enable_subtitle` was set. */\n  subtitle?: BytePlusTTSSubtitle\n}\n\n// ============================================================================\n// ASR — POST /api/v3/auc/bigmodel/recognize/flash\n// ============================================================================\n\n/**\n * Value of the `X-Api-Resource-Id` header that selects the Seed ASR turbo\n * model. The flash endpoint takes no `model` field in its body — the model is\n * chosen entirely by this header.\n */\nexport const BYTEPLUS_ASR_RESOURCE_ID = 'volc.seedasr.auc_turbo'\n\n/** Header name carrying {@link BYTEPLUS_ASR_RESOURCE_ID}. */\nexport const BYTEPLUS_ASR_RESOURCE_HEADER = 'X-Api-Resource-Id'\n\n/**\n * Audio input. Exactly one of `url` or `data` is sent — the endpoint accepts\n * files up to 2 hours long / 100 MB.\n */\nexport interface BytePlusASRAudio {\n  /** Publicly reachable URL of the audio file. */\n  url?: string\n  /** Base64-encoded audio bytes. */\n  data?: string\n  /** Container hint, e.g. `mp3`, `wav`, `ogg`. */\n  format?: string\n}\n\n/** `request` block of a recognition call. */\nexport interface BytePlusASRRequestOptions {\n  /** Recognition model family. Defaults to `bigmodel`. */\n  model_name?: string\n  /** Inverse text normalisation (spoken numbers → digits). */\n  enable_itn?: boolean\n  /** Insert punctuation. */\n  enable_punc?: boolean\n  /** Disfluency removal (\"um\", repeated words). */\n  enable_ddc?: boolean\n  /** Attach per-utterance speaker labels. */\n  enable_speaker_info?: boolean\n  /** Return the `utterances` breakdown as well as the flat transcript. */\n  show_utterances?: boolean\n  /** Spoken language hint, e.g. `en-US`. */\n  language?: string\n}\n\n/** Request body for `POST /api/v3/auc/bigmodel/recognize/flash`. */\nexport interface BytePlusASRRecognizeRequest {\n  user?: { uid?: string }\n  audio: BytePlusASRAudio\n  request?: BytePlusASRRequestOptions\n}\n\n/** One recognised word. `start_time` / `end_time` are milliseconds. */\nexport interface BytePlusASRWord {\n  text?: string\n  start_time?: number\n  end_time?: number\n  confidence?: number\n}\n\n/** One recognised utterance. `start_time` / `end_time` are milliseconds. */\nexport interface BytePlusASRUtterance {\n  text?: string\n  start_time?: number\n  end_time?: number\n  words?: Array<BytePlusASRWord>\n  /**\n   * Extra per-utterance annotations. Speaker labels arrive here when\n   * `enable_speaker_info` is set; the exact key is read defensively because it\n   * could not be confirmed against a live response.\n   */\n  additions?: Record<string, string>\n}\n\nexport interface BytePlusASRResult {\n  text?: string\n  utterances?: Array<BytePlusASRUtterance>\n}\n\n/**\n * Response body for `POST /api/v3/auc/bigmodel/recognize/flash`.\n *\n * The Volcengine-lineage wire shape nests everything under `result`; BytePlus'\n * prose docs describe the same payload as \"transcript + utterances\", so the\n * flat spelling is tolerated as a fallback.\n */\nexport interface BytePlusASRRecognizeResponse {\n  /** `duration` is the audio length in **milliseconds**. */\n  audio_info?: { duration?: number }\n  result?: BytePlusASRResult\n  /** Flat alias for `result.text`. */\n  transcript?: string\n  /** Flat alias for `result.utterances`. */\n  utterances?: Array<BytePlusASRUtterance>\n}\n\n// ============================================================================\n// Errors\n// ============================================================================\n\n/**\n * Seed Speech error envelope: a flat numeric `code` plus a `message`, e.g.\n * `{\"code\": 45000010, \"message\": \"Invalid X-Api-Key\"}` (verified live on a\n * 401). Format it with `bytePlusVoiceError` from `../utils/client`.\n */\nexport interface BytePlusVoiceErrorBody {\n  code?: number\n  message?: string\n}\n"],"mappings":";;;;;;;;AAyCA,IAAa,4BAA4B;CACvC;CAAM;CAAO;CAAO;CAAO;CAAO;AACpC;;;;;;AAmJA,IAAa,2BAA2B;;AAGxC,IAAa,+BAA+B"}
+{"version":3,"file":"wire-types.js","names":[],"sources":["../../../src/audio/wire-types.ts"],"sourcesContent":["/**\n * Minimal wire types for the BytePlus **Seed Speech** HTTP API (TTS + ASR).\n *\n * Seed Speech is a separate product from Ark: it lives on\n * `voice.ap-southeast-1.bytepluses.com`, authenticates with `X-Api-Key`\n * (a different key from `ARK_API_KEY`), and returns a flat numeric error\n * envelope instead of Ark's OpenAI-shaped one.\n *\n * Only the fields the adapters read or write are modelled here — this is a\n * hand-written subset, not a generated schema.\n *\n * Provenance:\n * - Endpoints, auth header, format/rate ranges and the 120 s TTS output cap:\n *   BytePlus Seed Speech docs (`docs.byteplus.com/en/docs/byteplusvoice`),\n *   captured in the Phase 0 research notes.\n * - Error envelope `{code, message}`: verified live — an Ark key sent as\n *   `X-Api-Key` returns HTTP 401 `{\"code\":45000010,\"message\":\"Invalid X-Api-Key\"}`.\n * - ASR request/response shape (`user`/`audio`/`request` in, `audio_info` +\n *   `result.utterances` out, all timings in **milliseconds**): the Volcengine\n *   flash-recognition reference the BytePlus endpoint is derived from\n *   (`docs.volcengine.com/docs/6561/1631584`).\n *\n * No Seed Speech API key was available when these were written, so the TTS\n * response fields are documented-but-unverified; the adapters parse them\n * defensively rather than assuming they are always present.\n */\n\n// ============================================================================\n// TTS — POST /api/v3/tts/create\n// ============================================================================\n\n/** Output container/codec accepted by `audio_config.format`. */\nexport type BytePlusTTSAudioFormat = 'wav' | 'mp3' | 'pcm' | 'ogg_opus'\n\n/**\n * Sample rates `audio_config.sample_rate` accepts.\n *\n * The docs also state a *default* of 40000, which is not one of the valid\n * values — a documentation bug. The adapter therefore always sends an\n * explicit rate rather than relying on the server default.\n */\nexport const BYTEPLUS_TTS_SAMPLE_RATES = [\n  8000, 16000, 24000, 32000, 44100, 48000,\n] as const\n\n/** A sample rate `audio_config.sample_rate` accepts. */\nexport type BytePlusTTSSampleRate = (typeof BYTEPLUS_TTS_SAMPLE_RATES)[number]\n\n/**\n * One entry of the request's `references` array.\n *\n * This is where the voice lives: `speaker` names a stock voice, while\n * `audio_url` / `audio_data` supply reference clips to clone (the `@Audio1`..\n * `@Audio3` markers in `text_prompt` address them positionally). Exactly one\n * of `speaker`, `audio_url` or `audio_data` may be set per entry; at most 3\n * audio references (30 s / 10 MB each) and 1 image reference (10 MB), and\n * image references are mutually exclusive with audio ones.\n *\n * The member fields are flat (`speaker | audio_data | audio_url | image_data |\n * image_url`), confirmed against\n * docs.byteplus.com/en/docs/byteplusvoice/seedaudio-01.\n */\nexport interface BytePlusTTSReference {\n  /**\n   * Voice id, e.g. `en_female_stokie_uranus_bigtts`. Either a stock TTS 2.0\n   * voice or the id of a voice you cloned through Voice Replication — this\n   * field is the join between replication and synthesis.\n   */\n  speaker?: string\n  /** URL of a reference clip to clone (≤30 s, ≤10 MB). */\n  audio_url?: string\n  /** Base64 reference clip to clone (≤30 s, ≤10 MB). */\n  audio_data?: string\n  /** URL of a reference image (≤10 MB). Mutually exclusive with audio refs. */\n  image_url?: string\n  /** Base64 reference image (≤10 MB). Mutually exclusive with audio refs. */\n  image_data?: string\n}\n\n/**\n * `audio_config` block of a TTS request — exactly six fields.\n *\n * The three `*_rate` fields are integer percentages relative to the voice's\n * neutral delivery, not multipliers.\n */\nexport interface BytePlusTTSAudioConfig {\n  /** Output format. Defaults to `wav` server-side. */\n  format?: BytePlusTTSAudioFormat\n  /**\n   * Output sample rate in Hz. See {@link BYTEPLUS_TTS_SAMPLE_RATES} for the\n   * valid values and for why the adapter always sends one.\n   */\n  sample_rate?: number\n  /** Speaking rate, `-50`..`100`. `-50` = 0.5×, `0` = 1×, `100` = 2×. */\n  speech_rate?: number\n  /** Loudness adjustment, `-50`..`100`. `0` is the voice's natural level. */\n  loudness_rate?: number\n  /** Pitch adjustment, `-12`..`12`. `0` is the voice's natural pitch. */\n  pitch_rate?: number\n  /** Emit sentence and word timings in the response. Defaults to `false`. */\n  enable_subtitle?: boolean\n}\n\n/**\n * `watermark` block of a TTS request.\n *\n * Two independent markers, both off by default:\n *\n * - `aigc_watermark` — **explicit**: appends an audible rhythm marker to the\n *   end of the clip.\n * - `aigc_metadata` — **implicit**: writes provenance metadata into the audio\n *   header. Nothing is written unless `enable` is `true`.\n *\n * This is an object, not a boolean — unlike Seedream images and Seedance\n * video, where `watermark` genuinely is a boolean.\n */\nexport interface BytePlusTTSWatermark {\n  /** Append an audible rhythm marker to the end of the audio. Default `false`. */\n  aigc_watermark?: boolean\n  /** Provenance metadata written into the audio header. */\n  aigc_metadata?: {\n    /** Write the metadata. Default `false` — the rest is ignored without it. */\n    enable?: boolean\n    /** Name or code of the synthesis provider. */\n    content_producer?: string\n    /** Content production id. */\n    produce_id?: string\n    /** Name or code of the distribution provider. */\n    content_propagator?: string\n    /** Content distribution id. */\n    propagate_id?: string\n  }\n}\n\n/** Request body for `POST /api/v3/tts/create` — exactly five fields. */\nexport interface BytePlusTTSCreateRequest {\n  /** Seed Speech synthesis model, e.g. `seed-audio-1.0`. */\n  model: string\n  /**\n   * The text to speak (≤3000 chars). Dual-purpose: either literal text or a\n   * natural-language description of the delivery, and the place the\n   * `@Audio1`..`@Audio3` reference markers go.\n   *\n   * **`text_prompt` is correct — do not \"fix\" this to `text`.** This endpoint\n   * has no request-side `text` field. The `text` spelling belongs to the\n   * *other* endpoint, `/tts/unidirectional` (TTS 2.0), where it sits under\n   * `req_params.text`. Confirmed against\n   * docs.byteplus.com/en/docs/byteplusvoice/seedaudio-01, which lists this\n   * body as exactly `model`, `text_prompt`, `references`, `audio_config`,\n   * `watermark`.\n   */\n  text_prompt: string\n  /** Voice selection and cloning references. See {@link BytePlusTTSReference}. */\n  references?: Array<BytePlusTTSReference>\n  audio_config?: BytePlusTTSAudioConfig\n  /** Watermark the generated audio. See {@link BytePlusTTSWatermark}. */\n  watermark?: BytePlusTTSWatermark\n}\n\n/**\n * One timed entry of a TTS subtitle track.\n *\n * **Times are milliseconds** — unlike the response's `duration` fields, which\n * are seconds. The endpoint genuinely mixes units.\n */\nexport interface BytePlusTTSSubtitleEntry {\n  text?: string\n  start_time?: number\n  end_time?: number\n}\n\n/** Sentence- and word-level timings returned when `enable_subtitle` is set. */\nexport interface BytePlusTTSSubtitle {\n  sentences?: Array<BytePlusTTSSubtitleEntry>\n  words?: Array<BytePlusTTSSubtitleEntry>\n}\n\n/** Response body for `POST /api/v3/tts/create`. */\nexport interface BytePlusTTSCreateResponse {\n  /**\n   * Status code — `0` on success, a flat error code otherwise.\n   *\n   * Typed as `number | string` because only the *error* envelope was verified\n   * live (HTTP 401 `{\"code\":45000010,…}`); the success envelope's shape is\n   * docs-derived and no voice key was available to confirm it. Treating a\n   * string code as \"not a failure\" would return a failed 200 as success, so\n   * the adapter coerces before comparing — see `isZeroCode` in\n   * `adapters/tts.ts`.\n   */\n  code?: number | string\n  message?: string\n  /** Base64-encoded audio in the requested `audio_config.format`. */\n  audio?: string\n  /**\n   * Length of the delivered audio in **seconds** (float), after `speech_rate`\n   * is applied. This can legitimately exceed 120 when the clip is slowed\n   * down — the 120 s cap applies to {@link BytePlusTTSCreateResponse.original_duration}.\n   */\n  duration?: number | string\n  /**\n   * Length in **seconds** (float) before rate adjustment. This is the billing\n   * basis and is capped at 120.\n   */\n  original_duration?: number | string\n  /** Temporary download URL for the same audio. Expires after ~2 hours. */\n  url?: string\n  /** Sentence and word timings, present when `enable_subtitle` was set. */\n  subtitle?: BytePlusTTSSubtitle\n}\n\n// ============================================================================\n// ASR — POST /api/v3/auc/bigmodel/recognize/flash\n// ============================================================================\n\n/**\n * Value of the `X-Api-Resource-Id` header that selects the Seed ASR turbo\n * model. The flash endpoint takes no `model` field in its body — the model is\n * chosen entirely by this header.\n */\nexport const BYTEPLUS_ASR_RESOURCE_ID = 'volc.seedasr.auc_turbo'\n\n/** Header name carrying {@link BYTEPLUS_ASR_RESOURCE_ID}. */\nexport const BYTEPLUS_ASR_RESOURCE_HEADER = 'X-Api-Resource-Id'\n\n/**\n * Audio input. Exactly one of `url` or `data` is sent — the endpoint accepts\n * files up to 2 hours long / 100 MB.\n */\nexport interface BytePlusASRAudio {\n  /** Publicly reachable URL of the audio file. */\n  url?: string\n  /** Base64-encoded audio bytes. */\n  data?: string\n  /** Container hint, e.g. `mp3`, `wav`, `ogg`. */\n  format?: string\n}\n\n/** `request` block of a recognition call. */\nexport interface BytePlusASRRequestOptions {\n  /** Recognition model family. Defaults to `bigmodel`. */\n  model_name?: string\n  /** Inverse text normalisation (spoken numbers → digits). */\n  enable_itn?: boolean\n  /** Insert punctuation. */\n  enable_punc?: boolean\n  /** Disfluency removal (\"um\", repeated words). */\n  enable_ddc?: boolean\n  /** Attach per-utterance speaker labels. */\n  enable_speaker_info?: boolean\n  /** Return the `utterances` breakdown as well as the flat transcript. */\n  show_utterances?: boolean\n  /** Spoken language hint, e.g. `en-US`. */\n  language?: string\n}\n\n/** Request body for `POST /api/v3/auc/bigmodel/recognize/flash`. */\nexport interface BytePlusASRRecognizeRequest {\n  user?: { uid?: string }\n  audio: BytePlusASRAudio\n  request?: BytePlusASRRequestOptions\n}\n\n/** One recognised word. `start_time` / `end_time` are milliseconds. */\nexport interface BytePlusASRWord {\n  text?: string\n  start_time?: number\n  end_time?: number\n  confidence?: number\n}\n\n/** One recognised utterance. `start_time` / `end_time` are milliseconds. */\nexport interface BytePlusASRUtterance {\n  text?: string\n  start_time?: number\n  end_time?: number\n  words?: Array<BytePlusASRWord>\n  /**\n   * Extra per-utterance annotations. Speaker labels arrive here when\n   * `enable_speaker_info` is set; the exact key is read defensively because it\n   * could not be confirmed against a live response.\n   */\n  additions?: Record<string, string>\n}\n\nexport interface BytePlusASRResult {\n  text?: string\n  utterances?: Array<BytePlusASRUtterance>\n}\n\n/**\n * Response body for `POST /api/v3/auc/bigmodel/recognize/flash`.\n *\n * The Volcengine-lineage wire shape nests everything under `result`; BytePlus'\n * prose docs describe the same payload as \"transcript + utterances\", so the\n * flat spelling is tolerated as a fallback.\n */\nexport interface BytePlusASRRecognizeResponse {\n  /** `duration` is the audio length in **milliseconds**. */\n  audio_info?: { duration?: number }\n  result?: BytePlusASRResult\n  /** Flat alias for `result.text`. */\n  transcript?: string\n  /** Flat alias for `result.utterances`. */\n  utterances?: Array<BytePlusASRUtterance>\n}\n\n// ============================================================================\n// Errors\n// ============================================================================\n\n/**\n * Seed Speech error envelope: a flat numeric `code` plus a `message`, e.g.\n * `{\"code\": 45000010, \"message\": \"Invalid X-Api-Key\"}` (verified live on a\n * 401). Format it with `bytePlusVoiceError` from `../utils/client`.\n */\nexport interface BytePlusVoiceErrorBody {\n  code?: number\n  message?: string\n}\n"],"mappings":";;;;;;;;AAyCA,IAAa,4BAA4B;CACvC;CAAM;CAAO;CAAO;CAAO;CAAO;AACpC;;;;;;AAgLA,IAAa,2BAA2B;;AAGxC,IAAa,+BAA+B"}

package/dist/esm/index.d.ts

@@ -9,7 +9,7 @@ export { BytePlusTranscriptionAdapter, byteplusTranscription, createBytePlusTran
 export type { BytePlusTranscriptionWord } from './adapters/transcription.js';
 export type { BytePlusTranscriptionProviderOptions } from './audio/transcription-provider-options.js';
 export { BYTEPLUS_ASR_RESOURCE_HEADER, BYTEPLUS_ASR_RESOURCE_ID, BYTEPLUS_TTS_SAMPLE_RATES, } from './audio/wire-types.js';
-export type { BytePlusASRAudio, BytePlusASRRecognizeRequest, BytePlusASRRecognizeResponse, BytePlusASRResult, BytePlusASRUtterance, BytePlusASRWord, BytePlusTTSAudioConfig, BytePlusTTSAudioFormat, BytePlusTTSCreateRequest, BytePlusTTSCreateResponse, BytePlusTTSReference, BytePlusTTSSampleRate, BytePlusTTSSubtitle, BytePlusTTSSubtitleEntry, BytePlusVoiceErrorBody, } from './audio/wire-types.js';
+export type { BytePlusASRAudio, BytePlusASRRecognizeRequest, BytePlusASRRecognizeResponse, BytePlusASRResult, BytePlusASRUtterance, BytePlusASRWord, BytePlusTTSAudioConfig, BytePlusTTSAudioFormat, BytePlusTTSCreateRequest, BytePlusTTSCreateResponse, BytePlusTTSReference, BytePlusTTSSampleRate, BytePlusTTSSubtitle, BytePlusTTSSubtitleEntry, BytePlusTTSWatermark, BytePlusVoiceErrorBody, } from './audio/wire-types.js';
 export { BytePlusImageAdapter, byteplusImage, createBytePlusImage, } from './adapters/image.js';
 export type { BytePlusImageConfig } from './adapters/image.js';
 export { BYTEPLUS_IMAGE_MAX_PROMPT_WORDS, BYTEPLUS_IMAGE_MAX_SEQUENTIAL_IMAGES, BYTEPLUS_OUTPUT_FORMAT_IMAGE_MODELS, parseBytePlusImageSize, } from './image/image-provider-options.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-byteplus",
-  "version": "0.3.4",
+  "version": "0.3.7",
   "description": "BytePlus ModelArk adapter for TanStack AI: Seed LLM chat, Seedance video, Seedream image, and Seed Speech TTS/ASR.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -54,15 +54,15 @@
   "devDependencies": {
     "@vitest/coverage-v8": "4.1.10",
     "vite": "^8.2.1",
-    "@tanstack/ai": "0.53.0"
+    "@tanstack/ai": "0.55.0"
   },
   "peerDependencies": {
-    "@tanstack/ai": "^0.53.0"
+    "@tanstack/ai": "^0.55.0"
   },
   "dependencies": {
     "openai": "^6.41.0",
     "@tanstack/ai-utils": "^0.4.0",
-    "@tanstack/openai-base": "^0.10.10"
+    "@tanstack/openai-base": "^0.10.12"
   },
   "scripts": {
     "build": "vite build",

package/src/adapters/tts.ts

@@ -275,9 +275,7 @@ export function buildTTSRequestBody(options: {
     model,
     [TTS_TEXT_FIELD]: text,
     // The voice belongs inside `references`, not at the top level — a
-    // top-level `speaker` is silently ignored by the server. The flat member
-    // shape here is the best-supported reading of the docs; see
-    // `BytePlusTTSReference` for the unresolved part and the live-probe flag.
+    // top-level `speaker` is silently ignored by the server.
     references: modelOptions?.references ?? [
       {
         speaker: modelOptions?.speaker ?? voice ?? BYTEPLUS_DEFAULT_TTS_SPEAKER,
@@ -286,7 +284,12 @@ export function buildTTSRequestBody(options: {
     audio_config: audioConfig,
   }
   if (modelOptions?.watermark !== undefined) {
-    body.watermark = modelOptions.watermark
+    // The endpoint wants an object. `true` means the audible marker, which is
+    // what a caller passing a boolean is asking for.
+    body.watermark =
+      typeof modelOptions.watermark === 'boolean'
+        ? { aigc_watermark: modelOptions.watermark }
+        : modelOptions.watermark
   }
 
   return { body, audioFormat, sampleRate }

package/src/audio/tts-provider-options.ts

@@ -3,6 +3,7 @@ import type {
   BytePlusTTSReference,
   BytePlusTTSSampleRate,
   BytePlusTTSSubtitle,
+  BytePlusTTSWatermark,
 } from './wire-types'
 import type { TTSResult } from '@tanstack/ai'
 
@@ -79,10 +80,13 @@ export interface BytePlusTTSProviderOptions {
    */
   enable_subtitle?: boolean
   /**
-   * Watermark the generated audio. The field name is confirmed against the
-   * endpoint schema; the boolean type is assumed and unprobed.
+   * Watermark the generated audio.
+   *
+   * Seed Audio takes an object with two independent markers — an audible
+   * `aigc_watermark` appended to the clip and an `aigc_metadata` block written
+   * into the audio header. `true` is shorthand for `{ aigc_watermark: true }`.
    */
-  watermark?: boolean
+  watermark?: boolean | BytePlusTTSWatermark
 }
 
 /**

package/src/audio/wire-types.ts

@@ -56,15 +56,16 @@ export type BytePlusTTSSampleRate = (typeof BYTEPLUS_TTS_SAMPLE_RATES)[number]
  * audio references (30 s / 10 MB each) and 1 image reference (10 MB), and
  * image references are mutually exclusive with audio ones.
  *
- * **Member object shape is unresolved — must live-probe when the Seed Speech
- * key lands.** The docs list the member fields flat (`speaker | audio_data |
- * audio_url | image_data | image_url`) without a worked example, so whether
- * the server wants a flat `{ speaker }` or a discriminated `{ type, ... }`
- * could not be settled. The adapter sends the flat reading — see
- * `buildTTSRequestBody` in `../adapters/tts`.
+ * The member fields are flat (`speaker | audio_data | audio_url | image_data |
+ * image_url`), confirmed against
+ * docs.byteplus.com/en/docs/byteplusvoice/seedaudio-01.
  */
 export interface BytePlusTTSReference {
-  /** Stock voice id, e.g. `en_female_stokie_uranus_bigtts`. */
+  /**
+   * Voice id, e.g. `en_female_stokie_uranus_bigtts`. Either a stock TTS 2.0
+   * voice or the id of a voice you cloned through Voice Replication — this
+   * field is the join between replication and synthesis.
+   */
   speaker?: string
   /** URL of a reference clip to clone (≤30 s, ≤10 MB). */
   audio_url?: string
@@ -100,6 +101,37 @@ export interface BytePlusTTSAudioConfig {
   enable_subtitle?: boolean
 }
 
+/**
+ * `watermark` block of a TTS request.
+ *
+ * Two independent markers, both off by default:
+ *
+ * - `aigc_watermark` — **explicit**: appends an audible rhythm marker to the
+ *   end of the clip.
+ * - `aigc_metadata` — **implicit**: writes provenance metadata into the audio
+ *   header. Nothing is written unless `enable` is `true`.
+ *
+ * This is an object, not a boolean — unlike Seedream images and Seedance
+ * video, where `watermark` genuinely is a boolean.
+ */
+export interface BytePlusTTSWatermark {
+  /** Append an audible rhythm marker to the end of the audio. Default `false`. */
+  aigc_watermark?: boolean
+  /** Provenance metadata written into the audio header. */
+  aigc_metadata?: {
+    /** Write the metadata. Default `false` — the rest is ignored without it. */
+    enable?: boolean
+    /** Name or code of the synthesis provider. */
+    content_producer?: string
+    /** Content production id. */
+    produce_id?: string
+    /** Name or code of the distribution provider. */
+    content_propagator?: string
+    /** Content distribution id. */
+    propagate_id?: string
+  }
+}
+
 /** Request body for `POST /api/v3/tts/create` — exactly five fields. */
 export interface BytePlusTTSCreateRequest {
   /** Seed Speech synthesis model, e.g. `seed-audio-1.0`. */
@@ -121,11 +153,8 @@ export interface BytePlusTTSCreateRequest {
   /** Voice selection and cloning references. See {@link BytePlusTTSReference}. */
   references?: Array<BytePlusTTSReference>
   audio_config?: BytePlusTTSAudioConfig
-  /**
-   * Watermark the generated audio. The field name is confirmed; the boolean
-   * type is assumed by analogy with Seedream's `watermark` and unprobed.
-   */
-  watermark?: boolean
+  /** Watermark the generated audio. See {@link BytePlusTTSWatermark}. */
+  watermark?: BytePlusTTSWatermark
 }
 
 /**

package/src/index.ts

@@ -84,6 +84,7 @@ export type {
   BytePlusTTSSampleRate,
   BytePlusTTSSubtitle,
   BytePlusTTSSubtitleEntry,
+  BytePlusTTSWatermark,
   BytePlusVoiceErrorBody,
 } from './audio/wire-types'
 export {