@tanstack/ai-byteplus 0.0.0

package/dist/esm/audio/tts-provider-options.d.ts

@@ -0,0 +1,114 @@
+import { BytePlusTTSAudioFormat, BytePlusTTSReference, BytePlusTTSSampleRate, BytePlusTTSSubtitle } from './wire-types.js';
+import { TTSResult } from '@tanstack/ai';
+/**
+ * Seed Speech voice identifier (`speaker` on the wire).
+ *
+ * Voice ids encode language, gender, character name and model generation:
+ * `en_female_stokie_uranus_bigtts` is the English female "Stokie" voice on
+ * TTS 2.0. The generation suffix matters when picking one:
+ *
+ * - `_uranus_bigtts` — TTS 2.0 voices (the current generation).
+ * - `_mars_bigtts` / `_moon_bigtts` — TTS 1.0 voices.
+ * - `*_emo_v2_*` — TTS 1.0 voices that additionally accept emotion tags.
+ *
+ * The full roster lives at
+ * https://docs.byteplus.com/en/docs/byteplusvoice/voicelist and changes far
+ * more often than this package ships, so the union stays open: any string is
+ * accepted, and the one listed id is the adapter's default.
+ */
+export type BytePlusTTSVoice = 'en_female_stokie_uranus_bigtts' | (string & {});
+/**
+ * Provider-specific options for BytePlus Seed Speech TTS
+ * (`POST /api/v3/tts/create`).
+ *
+ * These map 1:1 onto the wire fields so the BytePlus documentation stays
+ * useful; where a cross-provider `TTSOptions` field covers the same ground
+ * (`voice`, `format`, `speed`), the option here wins.
+ */
+export interface BytePlusTTSProviderOptions {
+    /**
+     * Voice id. Overrides `TTSOptions.voice` when both are set. It is sent as
+     * the `speaker` of a single `references` entry.
+     */
+    speaker?: BytePlusTTSVoice;
+    /**
+     * Full `references` array, for voice cloning or image-referenced delivery.
+     * When set this replaces the entry the adapter would otherwise build from
+     * `speaker` / `TTSOptions.voice`, so include a `speaker` entry yourself if
+     * you still want a stock voice. Address audio references from the text with
+     * `@Audio1`..`@Audio3`.
+     */
+    references?: Array<BytePlusTTSReference>;
+    /**
+     * Output format. Overrides the mapping applied to `TTSOptions.format`,
+     * which is useful for `ogg_opus` and for pinning `pcm` explicitly.
+     */
+    format?: BytePlusTTSAudioFormat;
+    /**
+     * Output sample rate in Hz. Defaults to 24000 — the adapter always sends an
+     * explicit rate because the documented server default (40000) is not one of
+     * the values the endpoint accepts. For `pcm` output this is also what the
+     * returned `contentType` (`audio/L16;rate=…`) reports.
+     */
+    sample_rate?: BytePlusTTSSampleRate;
+    /**
+     * Pitch adjustment in the range `-12`..`12`, where `0` is the voice's
+     * natural pitch.
+     */
+    pitch_rate?: number;
+    /**
+     * Speaking rate in the range `-50`..`100` (`-50` = 0.5×, `0` = 1×,
+     * `100` = 2×). Overrides the value derived from `TTSOptions.speed`.
+     */
+    speech_rate?: number;
+    /**
+     * Loudness adjustment in the range `-50`..`100`, where `0` is the voice's
+     * natural level.
+     */
+    loudness_rate?: number;
+    /**
+     * Ask for sentence- and word-level timings alongside the audio. They are
+     * surfaced on {@link BytePlusTTSResult.subtitle}.
+     */
+    enable_subtitle?: boolean;
+    /**
+     * Watermark the generated audio. The field name is confirmed against the
+     * endpoint schema; the boolean type is assumed and unprobed.
+     */
+    watermark?: boolean;
+}
+/**
+ * BytePlus-specific extension of `TTSResult`.
+ *
+ * The cross-provider `TTSResult` has nowhere to put the subtitle timings or
+ * the temporary download URL, so callers who want them narrow the result:
+ *
+ * ```ts
+ * const result: BytePlusTTSResult = await generateSpeech({ adapter, text })
+ * for (const sentence of result.subtitle?.sentences ?? []) {
+ *   console.log(sentence.text, sentence.start_time)
+ * }
+ * ```
+ */
+export interface BytePlusTTSResult extends TTSResult {
+    /**
+     * Sentence and word timings, present only when
+     * `modelOptions.enable_subtitle` was set. Their `start_time` / `end_time`
+     * are **milliseconds**, even though `duration` and
+     * {@link BytePlusTTSResult.originalDuration} are seconds.
+     */
+    subtitle?: BytePlusTTSSubtitle;
+    /**
+     * Length of the audio in seconds *before* `speech_rate` was applied. This
+     * is what BytePlus bills on and what the 120 s cap applies to, so it is the
+     * number to meter against — `duration` reflects the delivered clip and can
+     * exceed 120 s when the speech is slowed down.
+     */
+    originalDuration?: number;
+    /**
+     * Temporary download URL for the same audio that `audio` carries as base64.
+     * **Expires roughly 2 hours after generation** — persist the bytes, not the
+     * link.
+     */
+    url?: string;
+}

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

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

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

@@ -0,0 +1,28 @@
+//#region src/audio/wire-types.ts
+/**
+* Sample rates `audio_config.sample_rate` accepts.
+*
+* The docs also state a *default* of 40000, which is not one of the valid
+* values — a documentation bug. The adapter therefore always sends an
+* explicit rate rather than relying on the server default.
+*/
+var BYTEPLUS_TTS_SAMPLE_RATES = [
+	8e3,
+	16e3,
+	24e3,
+	32e3,
+	44100,
+	48e3
+];
+/**
+* Value of the `X-Api-Resource-Id` header that selects the Seed ASR turbo
+* model. The flash endpoint takes no `model` field in its body — the model is
+* chosen entirely by this header.
+*/
+var BYTEPLUS_ASR_RESOURCE_ID = "volc.seedasr.auc_turbo";
+/** Header name carrying {@link BYTEPLUS_ASR_RESOURCE_ID}. */
+var BYTEPLUS_ASR_RESOURCE_HEADER = "X-Api-Resource-Id";
+//#endregion
+export { BYTEPLUS_ASR_RESOURCE_HEADER, BYTEPLUS_ASR_RESOURCE_ID, BYTEPLUS_TTS_SAMPLE_RATES };
+
+//# sourceMappingURL=wire-types.js.map

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

@@ -0,0 +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"}

package/dist/esm/image/image-provider-options.d.ts

@@ -0,0 +1,165 @@
+import { BytePlusImageOutputFormat, BytePlusImageResponseFormat, BytePlusOptimizePromptOptions, BytePlusSequentialImageGeneration, BytePlusSequentialImageGenerationOptions } from './wire-types.js';
+import { BytePlusImageModel, BytePlusImageSize } from '../model-meta.js';
+/**
+ * BytePlus documents a 600-word ceiling on the image prompt. Word-based, so
+ * it is only meaningful for space-separated scripts — the check below never
+ * fires for Chinese or Japanese text, which is the intended behaviour.
+ */
+export declare const BYTEPLUS_IMAGE_MAX_PROMPT_WORDS = 600;
+/**
+ * Upper bound of `sequential_image_generation_options.max_images`, i.e. the
+ * most images one request can return.
+ */
+export declare const BYTEPLUS_IMAGE_MAX_SEQUENTIAL_IMAGES = 15;
+/**
+ * Models that accept `output_format`.
+ *
+ * The Ark OpenAPI document's field note claims 5.0-lite only, but its own
+ * request demo sends `output_format` on `seedream-5-0-260128`, so the whole
+ * 5.0 family is treated as supporting it. The Seedream 4.x snapshots are
+ * documented as not reading it, so `output_format` is omitted from their
+ * provider-options type — but, as with `sequential_image_generation`, it is
+ * not gated at runtime: a value that reaches a model which does not read it
+ * comes back as an Ark error rather than a local rejection.
+ */
+export declare const BYTEPLUS_OUTPUT_FORMAT_IMAGE_MODELS: ReadonlyArray<BytePlusImageModel>;
+/**
+ * Base provider options shared by every Seedream model.
+ */
+export interface BytePlusImageBaseProviderOptions {
+    /**
+     * Return images as expiring links (`url`, valid 24 hours) or inline base64
+     * (`b64_json`).
+     *
+     * @default 'url'
+     */
+    response_format?: BytePlusImageResponseFormat;
+    /**
+     * Whether to stamp an "AI generated" watermark in the bottom-right corner.
+     *
+     * **BytePlus defaults this to `true`.** Pass `false` for a clean image.
+     */
+    watermark?: boolean;
+    /**
+     * Group-image mode. Set to `auto` to let the model return a set of related
+     * images (bounded by {@link BytePlusImageBaseProviderOptions.sequential_image_generation_options}).
+     * `generateImage()`'s `numberOfImages` sets this for you; an explicit value
+     * here wins.
+     *
+     * Documented on Seedream 5.0-lite, 4.5 and 4.0. It is sent as given on
+     * every model rather than gated locally — the shipped 5.0 ids post-date the
+     * published parameter table, and an unsupported combination comes back as a
+     * clear Ark error.
+     *
+     * @default 'disabled'
+     */
+    sequential_image_generation?: BytePlusSequentialImageGeneration;
+    /** Bounds for group-image mode. Only read when the mode is `auto`. */
+    sequential_image_generation_options?: BytePlusSequentialImageGenerationOptions;
+    /**
+     * Prompt-rewriting configuration. Documented on Seedream 5.0-lite, 4.5 and
+     * 4.0; `mode: 'fast'` is unsupported on 5.0-lite and 4.5.
+     */
+    optimize_prompt_options?: BytePlusOptimizePromptOptions;
+}
+/**
+ * Provider options for the Seedream 5.0 family, which additionally chooses the
+ * generated file format.
+ */
+export interface BytePlusSeedream5ImageProviderOptions extends BytePlusImageBaseProviderOptions {
+    /**
+     * File format of the generated image.
+     *
+     * @default 'jpeg'
+     */
+    output_format?: BytePlusImageOutputFormat;
+}
+/**
+ * Every Seedream provider option, used as the adapter's base option type.
+ * Call sites are narrowed per model by
+ * {@link BytePlusImageModelProviderOptionsByName}.
+ */
+export type BytePlusImageProviderOptions = BytePlusSeedream5ImageProviderOptions;
+/**
+ * Type-only map from image model name to its provider options.
+ */
+export type BytePlusImageModelProviderOptionsByName = {
+    'dola-seedream-5-0-pro-260628': BytePlusSeedream5ImageProviderOptions;
+    'seedream-5-0-260128': BytePlusSeedream5ImageProviderOptions;
+    'seedream-5-0-lite-260128': BytePlusSeedream5ImageProviderOptions;
+    'seedream-4-5-251128': BytePlusImageBaseProviderOptions;
+    'seedream-4-0-250828': BytePlusImageBaseProviderOptions;
+};
+/**
+ * Type-only map from image model name to the non-text prompt modalities it
+ * accepts. Every shipped Seedream model takes reference images for
+ * image-conditioned generation.
+ */
+export type BytePlusImageModelInputModalitiesByName = {
+    [K in BytePlusImageModel]: readonly ['image'];
+};
+/**
+ * A parsed `size` value: either the shorthand token form or explicit pixels.
+ */
+export type ParsedBytePlusImageSize = {
+    kind: 'token';
+    value: '1K' | '2K' | '4K';
+} | {
+    kind: 'pixels';
+    width: number;
+    height: number;
+};
+/**
+ * Parses a Seedream `size` string. Accepts a shorthand token (case-insensitive
+ * — `2k` normalizes to `2K`) or explicit `WIDTHxHEIGHT` pixels, and returns
+ * `undefined` for anything else, including mixtures such as `2K x 1024`.
+ */
+export declare function parseBytePlusImageSize(size: string): ParsedBytePlusImageSize | undefined;
+/**
+ * Validates the generic `size` option and returns the string to put on the
+ * wire (`2K`, `2048x2048`), or `undefined` when no size was requested.
+ *
+ * This checks the *form* only. Which pixel dimensions a given model actually
+ * accepts is not encoded here, so the message deliberately makes no per-model
+ * claim; an out-of-range size is left to the API to reject.
+ *
+ * @throws Error when the value is neither a size token nor `WIDTHxHEIGHT`.
+ */
+export declare function resolveBytePlusImageSize(size: BytePlusImageSize | string | undefined): string | undefined;
+/**
+ * Validates the prompt text against BytePlus's documented limits.
+ *
+ * @throws Error when the prompt is empty or exceeds
+ * {@link BYTEPLUS_IMAGE_MAX_PROMPT_WORDS} words.
+ */
+export declare function validateBytePlusImagePrompt(model: string, prompt: string): void;
+/**
+ * Validates the reference-image count against the model's editing limit.
+ *
+ * A model this package has no limit for is left to Ark, deliberately and
+ * explicitly. `model` is typed closed, but `wire-types.ts` documents that the
+ * endpoint also accepts preconfigured endpoint ids (`ep-…`), so a JS caller
+ * can reach an id that is not in the table. Reading `undefined` out of it and
+ * comparing `count > undefined` — always false — would disable the guard by
+ * accident and look identical to passing; the explicit early return says the
+ * skip is intended.
+ *
+ * @throws Error when more references are supplied than a *known* model accepts.
+ */
+export declare function validateBytePlusReferenceImages(model: BytePlusImageModel, count: number): void;
+/**
+ * Maps the generic `numberOfImages` option onto Seedream's group-image
+ * parameters.
+ *
+ * The endpoint has no `n`: more than one image per request is only reachable
+ * through `sequential_image_generation: 'auto'`, where `max_images` is an
+ * upper bound and the model decides how many images the prompt actually
+ * warrants. A request for N images can therefore come back with fewer — the
+ * one place BytePlus cannot honour `numberOfImages` exactly.
+ *
+ * @throws Error when the count is not an integer in `[1, 15]`.
+ */
+export declare function resolveBytePlusSequentialImages(model: string, numberOfImages: number | undefined): {
+    sequential_image_generation?: BytePlusSequentialImageGeneration;
+    sequential_image_generation_options?: BytePlusSequentialImageGenerationOptions;
+};