import { BaseReport } from "../contracts/result/base-report.type.mjs";
import { ExecuteResult } from "../contracts/result/execute-result.type.mjs";
import { FlowObserveOption } from "../observe/resolve-observers.mjs";
import { GeneratedAudio, SpeechModelContract } from "../contracts/speech-model.contract.mjs";

//#region ../ai/src/speech/speech.d.ts
/** Parameters for {@link speech}. `model` comes from `sdk.speech({ name })`. */
type SpeechParams = {
  /** The TTS model to synthesize with. */model: SpeechModelContract; /** The text to speak. */
  text: string; /** Voice id/name; overrides the model's default voice. */
  voice?: string; /** Output container (`"mp3"` / `"opus"` / `"aac"` / `"flac"` / `"wav"` / `"pcm"`). */
  format?: string; /** Playback speed multiplier. */
  speed?: number; /** Extra tone/delivery steering (model-dependent). */
  instructions?: string; /** Cancellation handle. */
  signal?: AbortSignal; /** Observability routing — same `observe` seam as agents. */
  observe?: FlowObserveOption; /** Groups this call into a session for flat cost/trace queries. */
  sessionId?: string; /** Report node name (defaults to `"speech"`). */
  name?: string; /** Provider-specific options forwarded verbatim to the adapter. */
  options?: Record<string, unknown>;
};
/** Success payload of a {@link speech} run. */
type SpeechData = {
  /** The synthesized audio, normalized to the discriminated shape. */audio: GeneratedAudio;
};
/** The report node a {@link speech} run produces (`type: "speech"`). */
type SpeechReport = BaseReport & {
  type: "speech"; /** Identity of the TTS model this run used. */
  model: {
    name: string;
    provider: string;
  }; /** Number of input characters synthesized (0 on failure). */
  characters: number;
};
/** Result envelope of {@link speech} — the uniform `{ data, error, usage, report }`. */
type SpeechResult = ExecuteResult<SpeechData> & {
  type: "speech";
  report: SpeechReport;
};
/**
 * Synthesize speech from text — the text-to-speech verb of the
 * output-modality track (Theme I), sibling to `ai.image()`. Wraps a
 * {@link SpeechModelContract} (from `openai.speech(...)`) in the
 * framework's uniform result contract:
 *
 * - **Never throws.** Provider failures surface as a typed `AIError` on
 *   `result.error`; `result.data` is then `undefined`.
 * - **Cost-truth.** `result.usage.cost` is filled per-character
 *   (`tts-1`) or per-token (`gpt-4o-mini-tts`), folding into the same
 *   `Usage.cost` rollup as text.
 * - **Observable.** The completed {@link SpeechReport} routes to any
 *   registered `Observer` (panoptic, OTel, …) via the `observe` seam.
 *
 * @example
 * const openai = new OpenAISDK({ apiKey });
 * const { data, error } = await ai.speech({
 *   model: openai.speech({ name: "tts-1", voice: "alloy" }),
 *   text: "Your order has shipped.",
 *   format: "mp3",
 * });
 * if (!error) await fs.writeFile("ship.mp3", Buffer.from(data.audio.base64, "base64"));
 */
declare function speech(params: SpeechParams): Promise<SpeechResult>;
//#endregion
export { SpeechData, SpeechParams, SpeechReport, SpeechResult, speech };
//# sourceMappingURL=speech.d.mts.map