@kaana.ai/contracts 4.4.0 → 5.0.0

package/dist/internal/catalogue.d.ts

@@ -112,6 +112,50 @@ export declare const catalogueModelSchema: z.ZodObject<{
                     g711_alaw: "g711_alaw";
                 }>>;
             }, z.core.$strict>>;
+            parameters: z.ZodOptional<z.ZodObject<{
+                turnDetection: z.ZodArray<z.ZodObject<{
+                    type: z.ZodEnum<{
+                        none: "none";
+                        server_vad: "server_vad";
+                        semantic_vad: "semantic_vad";
+                    }>;
+                    fixedResponses: z.ZodBoolean;
+                    threshold: z.ZodOptional<z.ZodObject<{
+                        min: z.ZodNumber;
+                        max: z.ZodNumber;
+                    }, z.core.$strict>>;
+                    meteredUnits: z.ZodArray<z.ZodEnum<{
+                        input_tokens: "input_tokens";
+                        cached_input_tokens: "cached_input_tokens";
+                        output_tokens: "output_tokens";
+                        reasoning_tokens: "reasoning_tokens";
+                        requests: "requests";
+                        images: "images";
+                        audio_input_milliseconds: "audio_input_milliseconds";
+                        audio_output_milliseconds: "audio_output_milliseconds";
+                        video_milliseconds: "video_milliseconds";
+                        characters: "characters";
+                        embeddings: "embeddings";
+                        audio_input_tokens: "audio_input_tokens";
+                        cached_audio_input_tokens: "cached_audio_input_tokens";
+                        audio_output_tokens: "audio_output_tokens";
+                        session_milliseconds: "session_milliseconds";
+                        input_transcription_milliseconds: "input_transcription_milliseconds";
+                    }>>;
+                }, z.core.$strict>>;
+                outputModalities: z.ZodArray<z.ZodArray<z.ZodEnum<{
+                    text: "text";
+                    audio: "audio";
+                }>>>;
+                toolChoice: z.ZodArray<z.ZodEnum<{
+                    function: "function";
+                    none: "none";
+                    auto: "auto";
+                    required: "required";
+                }>>;
+                maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+                inputTranscriptionPrompt: z.ZodBoolean;
+            }, z.core.$strict>>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
     license: z.ZodObject<{
@@ -465,6 +509,50 @@ export declare const modelCatalogueEntrySchema: z.ZodObject<{
                     g711_alaw: "g711_alaw";
                 }>>;
             }, z.core.$strict>>;
+            parameters: z.ZodOptional<z.ZodObject<{
+                turnDetection: z.ZodArray<z.ZodObject<{
+                    type: z.ZodEnum<{
+                        none: "none";
+                        server_vad: "server_vad";
+                        semantic_vad: "semantic_vad";
+                    }>;
+                    fixedResponses: z.ZodBoolean;
+                    threshold: z.ZodOptional<z.ZodObject<{
+                        min: z.ZodNumber;
+                        max: z.ZodNumber;
+                    }, z.core.$strict>>;
+                    meteredUnits: z.ZodArray<z.ZodEnum<{
+                        input_tokens: "input_tokens";
+                        cached_input_tokens: "cached_input_tokens";
+                        output_tokens: "output_tokens";
+                        reasoning_tokens: "reasoning_tokens";
+                        requests: "requests";
+                        images: "images";
+                        audio_input_milliseconds: "audio_input_milliseconds";
+                        audio_output_milliseconds: "audio_output_milliseconds";
+                        video_milliseconds: "video_milliseconds";
+                        characters: "characters";
+                        embeddings: "embeddings";
+                        audio_input_tokens: "audio_input_tokens";
+                        cached_audio_input_tokens: "cached_audio_input_tokens";
+                        audio_output_tokens: "audio_output_tokens";
+                        session_milliseconds: "session_milliseconds";
+                        input_transcription_milliseconds: "input_transcription_milliseconds";
+                    }>>;
+                }, z.core.$strict>>;
+                outputModalities: z.ZodArray<z.ZodArray<z.ZodEnum<{
+                    text: "text";
+                    audio: "audio";
+                }>>>;
+                toolChoice: z.ZodArray<z.ZodEnum<{
+                    function: "function";
+                    none: "none";
+                    auto: "auto";
+                    required: "required";
+                }>>;
+                maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+                inputTranscriptionPrompt: z.ZodBoolean;
+            }, z.core.$strict>>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
     license: z.ZodObject<{
@@ -617,6 +705,8 @@ export declare const declaredModelSchema: z.ZodObject<{
             }>>;
         }, z.core.$strict>>;
         languages: z.ZodArray<z.ZodString>;
+        detectsLanguage: z.ZodOptional<z.ZodBoolean>;
+        transcriptionPrompt: z.ZodOptional<z.ZodBoolean>;
         audioFormats: z.ZodObject<{
             input: z.ZodArray<z.ZodEnum<{
                 "audio/mpeg": "audio/mpeg";
@@ -713,6 +803,50 @@ export declare const declaredModelSchema: z.ZodObject<{
                     g711_alaw: "g711_alaw";
                 }>>;
             }, z.core.$strict>>;
+            parameters: z.ZodOptional<z.ZodObject<{
+                turnDetection: z.ZodArray<z.ZodObject<{
+                    type: z.ZodEnum<{
+                        none: "none";
+                        server_vad: "server_vad";
+                        semantic_vad: "semantic_vad";
+                    }>;
+                    fixedResponses: z.ZodBoolean;
+                    threshold: z.ZodOptional<z.ZodObject<{
+                        min: z.ZodNumber;
+                        max: z.ZodNumber;
+                    }, z.core.$strict>>;
+                    meteredUnits: z.ZodArray<z.ZodEnum<{
+                        input_tokens: "input_tokens";
+                        cached_input_tokens: "cached_input_tokens";
+                        output_tokens: "output_tokens";
+                        reasoning_tokens: "reasoning_tokens";
+                        requests: "requests";
+                        images: "images";
+                        audio_input_milliseconds: "audio_input_milliseconds";
+                        audio_output_milliseconds: "audio_output_milliseconds";
+                        video_milliseconds: "video_milliseconds";
+                        characters: "characters";
+                        embeddings: "embeddings";
+                        audio_input_tokens: "audio_input_tokens";
+                        cached_audio_input_tokens: "cached_audio_input_tokens";
+                        audio_output_tokens: "audio_output_tokens";
+                        session_milliseconds: "session_milliseconds";
+                        input_transcription_milliseconds: "input_transcription_milliseconds";
+                    }>>;
+                }, z.core.$strict>>;
+                outputModalities: z.ZodArray<z.ZodArray<z.ZodEnum<{
+                    text: "text";
+                    audio: "audio";
+                }>>>;
+                toolChoice: z.ZodArray<z.ZodEnum<{
+                    function: "function";
+                    none: "none";
+                    auto: "auto";
+                    required: "required";
+                }>>;
+                maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+                inputTranscriptionPrompt: z.ZodBoolean;
+            }, z.core.$strict>>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
     license: z.ZodObject<{
@@ -841,6 +975,8 @@ export declare const declaredCatalogueSchema: z.ZodObject<{
                 }>>;
             }, z.core.$strict>>;
             languages: z.ZodArray<z.ZodString>;
+            detectsLanguage: z.ZodOptional<z.ZodBoolean>;
+            transcriptionPrompt: z.ZodOptional<z.ZodBoolean>;
             audioFormats: z.ZodObject<{
                 input: z.ZodArray<z.ZodEnum<{
                     "audio/mpeg": "audio/mpeg";
@@ -937,6 +1073,50 @@ export declare const declaredCatalogueSchema: z.ZodObject<{
                         g711_alaw: "g711_alaw";
                     }>>;
                 }, z.core.$strict>>;
+                parameters: z.ZodOptional<z.ZodObject<{
+                    turnDetection: z.ZodArray<z.ZodObject<{
+                        type: z.ZodEnum<{
+                            none: "none";
+                            server_vad: "server_vad";
+                            semantic_vad: "semantic_vad";
+                        }>;
+                        fixedResponses: z.ZodBoolean;
+                        threshold: z.ZodOptional<z.ZodObject<{
+                            min: z.ZodNumber;
+                            max: z.ZodNumber;
+                        }, z.core.$strict>>;
+                        meteredUnits: z.ZodArray<z.ZodEnum<{
+                            input_tokens: "input_tokens";
+                            cached_input_tokens: "cached_input_tokens";
+                            output_tokens: "output_tokens";
+                            reasoning_tokens: "reasoning_tokens";
+                            requests: "requests";
+                            images: "images";
+                            audio_input_milliseconds: "audio_input_milliseconds";
+                            audio_output_milliseconds: "audio_output_milliseconds";
+                            video_milliseconds: "video_milliseconds";
+                            characters: "characters";
+                            embeddings: "embeddings";
+                            audio_input_tokens: "audio_input_tokens";
+                            cached_audio_input_tokens: "cached_audio_input_tokens";
+                            audio_output_tokens: "audio_output_tokens";
+                            session_milliseconds: "session_milliseconds";
+                            input_transcription_milliseconds: "input_transcription_milliseconds";
+                        }>>;
+                    }, z.core.$strict>>;
+                    outputModalities: z.ZodArray<z.ZodArray<z.ZodEnum<{
+                        text: "text";
+                        audio: "audio";
+                    }>>>;
+                    toolChoice: z.ZodArray<z.ZodEnum<{
+                        function: "function";
+                        none: "none";
+                        auto: "auto";
+                        required: "required";
+                    }>>;
+                    maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+                    inputTranscriptionPrompt: z.ZodBoolean;
+                }, z.core.$strict>>;
             }, z.core.$strict>>;
         }, z.core.$strict>;
         license: z.ZodObject<{

package/dist/internal/realtime.d.ts

@@ -102,19 +102,17 @@ export declare const realtimeSessionRequestSchema: z.ZodObject<{
         tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
             parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-            strict: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
         toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-            auto: "auto";
             none: "none";
+            auto: "auto";
             required: "required";
         }>, z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
         }, z.core.$strict>]>>;
-        temperature: z.ZodOptional<z.ZodNumber>;
         maxOutputTokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
     limits: z.ZodObject<{
@@ -244,19 +242,17 @@ export declare const realtimeSessionCreatedEventSchema: z.ZodObject<{
         tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
             parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-            strict: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
         toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-            auto: "auto";
             none: "none";
+            auto: "auto";
             required: "required";
         }>, z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
         }, z.core.$strict>]>>;
-        temperature: z.ZodOptional<z.ZodNumber>;
         maxOutputTokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
     limits: z.ZodObject<{
@@ -503,19 +499,17 @@ export declare const realtimeServerEventSchema: z.ZodDiscriminatedUnion<[z.ZodOb
         tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
             parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-            strict: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
         toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-            auto: "auto";
             none: "none";
+            auto: "auto";
             required: "required";
         }>, z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
         }, z.core.$strict>]>>;
-        temperature: z.ZodOptional<z.ZodNumber>;
         maxOutputTokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
     limits: z.ZodObject<{
@@ -581,19 +575,17 @@ export declare const realtimeServerEventSchema: z.ZodDiscriminatedUnion<[z.ZodOb
         tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
             parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-            strict: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
         toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-            auto: "auto";
             none: "none";
+            auto: "auto";
             required: "required";
         }>, z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
         }, z.core.$strict>]>>;
-        temperature: z.ZodOptional<z.ZodNumber>;
         maxOutputTokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
     schemaVersion: z.ZodLiteral<1>;

package/dist/internal/request.d.ts

@@ -344,6 +344,10 @@ export declare const inferenceRequestSchema: z.ZodObject<{
         }>;
         speed: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
+    transcription: z.ZodOptional<z.ZodObject<{
+        language: z.ZodOptional<z.ZodString>;
+        prompt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
     audioOutput: z.ZodOptional<z.ZodObject<{
         voice: z.ZodString;
         format: z.ZodEnum<{
@@ -362,8 +366,8 @@ export declare const inferenceRequestSchema: z.ZodObject<{
         strict: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>>;
     toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-        auto: "auto";
         none: "none";
+        auto: "auto";
         required: "required";
     }>, z.ZodObject<{
         type: z.ZodLiteral<"function">;
@@ -619,6 +623,10 @@ export declare const scopedInferenceRequestSchema: z.ZodObject<{
         }>;
         speed: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
+    transcription: z.ZodOptional<z.ZodObject<{
+        language: z.ZodOptional<z.ZodString>;
+        prompt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
     audioOutput: z.ZodOptional<z.ZodObject<{
         voice: z.ZodString;
         format: z.ZodEnum<{
@@ -637,8 +645,8 @@ export declare const scopedInferenceRequestSchema: z.ZodObject<{
         strict: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>>;
     toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-        auto: "auto";
         none: "none";
+        auto: "auto";
         required: "required";
     }>, z.ZodObject<{
         type: z.ZodLiteral<"function">;
@@ -864,6 +872,19 @@ export declare const privateAutoInferenceRequestSchema: z.ZodObject<{
             high: "high";
         }>;
     }, z.core.$strict>>;
+    transcription: z.ZodOptional<z.ZodObject<{
+        language: z.ZodOptional<z.ZodString>;
+        prompt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        none: "none";
+        auto: "auto";
+        required: "required";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"function">;
+        name: z.ZodString;
+    }, z.core.$strict>]>>;
+    maxOutputTokens: z.ZodOptional<z.ZodNumber>;
     tools: z.ZodDefault<z.ZodArray<z.ZodObject<{
         type: z.ZodLiteral<"function">;
         name: z.ZodString;
@@ -871,7 +892,6 @@ export declare const privateAutoInferenceRequestSchema: z.ZodObject<{
         parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         strict: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>>;
-    maxOutputTokens: z.ZodOptional<z.ZodNumber>;
     stream: z.ZodBoolean;
     responseFormat: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"text">;
@@ -883,14 +903,6 @@ export declare const privateAutoInferenceRequestSchema: z.ZodObject<{
         schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         strict: z.ZodBoolean;
     }, z.core.$strict>], "type">>;
-    toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-        auto: "auto";
-        none: "none";
-        required: "required";
-    }>, z.ZodObject<{
-        type: z.ZodLiteral<"function">;
-        name: z.ZodString;
-    }, z.core.$strict>]>>;
     routingPolicy: z.ZodObject<{
         routingPolicyId: z.ZodString;
         policyVersion: z.ZodNumber;

package/dist/internal/request.js

@@ -7,7 +7,7 @@ import { z } from 'zod';
 import { inferenceApiFormatSchema, inferenceModalitySchema } from '../public/catalogue.js';
 import { decisionInputSchema } from '../public/decisions.js';
 import { idempotencyKeySchema, inferenceTimestampSchema } from '../public/identifiers.js';
-import { inferenceAudioOutputParametersSchema, inferenceMessageSchema, inferenceReasoningSchema, inferenceSpeechParametersSchema, responseFormatSchema, samplingParametersSchema, toolChoiceSchema, toolDefinitionSchema, } from '../public/messages.js';
+import { inferenceAudioOutputParametersSchema, inferenceMessageSchema, inferenceReasoningSchema, inferenceSpeechParametersSchema, inferenceTranscriptionParametersSchema, responseFormatSchema, samplingParametersSchema, toolChoiceSchema, toolDefinitionSchema, } from '../public/messages.js';
 import { routingPolicyReferenceSchema } from '../public/policy.js';
 import { inferenceAttributionSchema } from './attribution.js';
 import { PRIVATE_AUTO_REQUEST_ENVELOPE_VERSION, privateAutoExecutionSchema, privateAutoInputSchema, } from './privateAutoExecution.js';
@@ -96,6 +96,8 @@ const inferenceRequestObjectSchema = z.object({
     /** Absent means the route's own default reasoning behaviour. */
     reasoning: inferenceReasoningSchema.optional(),
     speech: inferenceSpeechParametersSchema.optional(),
+    /** File transcription parameters. Contract set 4.5.0. */
+    transcription: inferenceTranscriptionParametersSchema.optional(),
     /** Spoken output from a conversational model. Contract set 3.2.0. */
     audioOutput: inferenceAudioOutputParametersSchema.optional(),
     tools: z.array(toolDefinitionSchema).default([]),
@@ -164,6 +166,7 @@ export const inferenceRequestSchema = inferenceRequestObjectSchema.superRefine((
             request.responseFormat !== undefined ||
             request.reasoning !== undefined ||
             request.speech !== undefined ||
+            request.transcription !== undefined ||
             request.audioOutput !== undefined) {
             ctx.addIssue({
                 code: 'custom',
@@ -191,6 +194,16 @@ export const inferenceRequestSchema = inferenceRequestObjectSchema.superRefine((
             message: 'speech parameters require the audio_speech API format',
         });
     }
+    if (request.transcription !== undefined &&
+        (request.client.apiFormat !== 'audio_transcriptions' ||
+            request.modality !== 'audio' ||
+            request.input.format !== 'messages')) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['transcription'],
+            message: 'transcription parameters require the audio_transcriptions API format with audio messages input',
+        });
+    }
     if (request.audioOutput !== undefined) {
         if (request.client.apiFormat !== 'chat_completions') {
             ctx.addIssue({

package/dist/internal/settlement.d.ts

@@ -111,6 +111,21 @@ export declare const settlementAcknowledgementSchema: z.ZodObject<{
         settled: "settled";
     }>;
 }, z.core.$strict>;
+/**
+ * The signature domain of Oxy's reconciliation read, under the Oxy edge key
+ * (`KAANA_EDGE_PUBLIC_KEYS`). New in package 4.4.1; Kaana has verified under it
+ * since contract set 4.2.0.
+ */
+export declare const SETTLEMENT_READ_SIGNATURE_DOMAIN = "oxy-kaana-settlement-read:v1";
+/** Where Oxy reads the outbox, on `https://kaana.ai`. */
+export declare const SETTLEMENT_READ_PATH = "/internal/v1/settlements";
+/**
+ * The query string of a reconciliation read, without its `?`: both what Oxy
+ * sends and the exact bytes it signs. Kaana verifies the raw query and nothing
+ * else — the path is fixed by the domain — so signing `path?query`, or encoding
+ * the cursor differently from what is sent, is refused as unsigned.
+ */
+export declare function settlementReadQuery(cursor: string | null): string;
 /** `GET /internal/v1/settlements?cursor=`: what Oxy reconciles against. */
 export declare const settlementPageSchema: z.ZodObject<{
     data: z.ZodArray<z.ZodObject<{

package/dist/internal/settlement.js

@@ -61,6 +61,23 @@ export const settlementAcknowledgementSchema = z
     status: z.enum(['settled', 'duplicate']),
 })
     .strict();
+/**
+ * The signature domain of Oxy's reconciliation read, under the Oxy edge key
+ * (`KAANA_EDGE_PUBLIC_KEYS`). New in package 4.4.1; Kaana has verified under it
+ * since contract set 4.2.0.
+ */
+export const SETTLEMENT_READ_SIGNATURE_DOMAIN = 'oxy-kaana-settlement-read:v1';
+/** Where Oxy reads the outbox, on `https://kaana.ai`. */
+export const SETTLEMENT_READ_PATH = '/internal/v1/settlements';
+/**
+ * The query string of a reconciliation read, without its `?`: both what Oxy
+ * sends and the exact bytes it signs. Kaana verifies the raw query and nothing
+ * else — the path is fixed by the domain — so signing `path?query`, or encoding
+ * the cursor differently from what is sent, is refused as unsigned.
+ */
+export function settlementReadQuery(cursor) {
+    return cursor === null ? '' : `cursor=${encodeURIComponent(cursor)}`;
+}
 /** `GET /internal/v1/settlements?cursor=`: what Oxy reconciles against. */
 export const settlementPageSchema = z
     .object({

package/dist/public/audio.d.ts

@@ -8,6 +8,7 @@
  * (decision 9) and transcription are new in contract set 4.0.0.
  */
 import { z } from 'zod';
+import { type AudioInputMediaType } from './audioFormats.js';
 import type { ModelAudioCapabilities } from './catalogue.js';
 /** The longest text one speech request may carry, before any model's own limit. */
 export declare const MAX_SPEECH_INPUT_CHARACTERS = 100000;
@@ -248,11 +249,6 @@ export declare const transcriptionRequestSchema: z.ZodObject<{
     model: z.ZodString;
     language: z.ZodOptional<z.ZodString>;
     prompt: z.ZodOptional<z.ZodString>;
-    timestamps: z.ZodOptional<z.ZodEnum<{
-        none: "none";
-        segment: "segment";
-        word: "word";
-    }>>;
 }, z.core.$strict>;
 /**
  * The longest audio one transcription request may carry, when its container
@@ -277,11 +273,6 @@ export declare const transcriptionJsonRequestSchema: z.ZodObject<{
     model: z.ZodString;
     language: z.ZodOptional<z.ZodString>;
     prompt: z.ZodOptional<z.ZodString>;
-    timestamps: z.ZodOptional<z.ZodEnum<{
-        none: "none";
-        segment: "segment";
-        word: "word";
-    }>>;
     audio: z.ZodObject<{
         mediaType: z.ZodEnum<{
             "audio/mpeg": "audio/mpeg";
@@ -296,7 +287,7 @@ export declare const transcriptionJsonRequestSchema: z.ZodObject<{
         data: z.ZodString;
     }, z.core.$strict>;
 }, z.core.$strict>;
-/** The response. Segments or words are present only when the request asked for them. */
+/** The response. */
 export declare const transcriptionSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     requestId: z.ZodString;
@@ -304,16 +295,6 @@ export declare const transcriptionSchema: z.ZodObject<{
     text: z.ZodString;
     language: z.ZodOptional<z.ZodString>;
     durationMs: z.ZodOptional<z.ZodNumber>;
-    segments: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        text: z.ZodString;
-        startMs: z.ZodNumber;
-        endMs: z.ZodNumber;
-    }, z.core.$strict>>>;
-    words: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        word: z.ZodString;
-        startMs: z.ZodNumber;
-        endMs: z.ZodNumber;
-    }, z.core.$strict>>>;
     usage: z.ZodArray<z.ZodObject<{
         unit: z.ZodEnum<{
             input_tokens: "input_tokens";
@@ -336,6 +317,26 @@ export declare const transcriptionSchema: z.ZodObject<{
         quantity: z.ZodNumber;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+/** Why a transcription request cannot be served by a model, before anything is held. */
+export interface TranscriptionRequestIssue {
+    /** The request's field at fault, as `invalid_request.param` names it. */
+    readonly param: 'file' | 'language' | 'prompt';
+    readonly message: string;
+}
+/**
+ * Check a transcription request against the model's published `audio` — the
+ * transcription counterpart of {@link checkSpeechRequest}. Kaana refuses a
+ * request with `invalid_request` and the first issue's `param` BEFORE asking
+ * Oxy for a grant; a client may run the same check to choose a model, and
+ * omit `language` where `detectsLanguage` lets the model detect it.
+ *
+ * `mediaType` is the upload's (the multipart `file` part's content type, or
+ * `audio.mediaType` of the JSON form). Returns every issue, in field order.
+ */
+export declare function checkTranscriptionRequest(request: {
+    readonly language?: string;
+    readonly prompt?: string;
+}, mediaType: AudioInputMediaType, audio: ModelAudioCapabilities): TranscriptionRequestIssue[];
 export type SpeechStreamFormat = z.infer<typeof speechStreamFormatSchema>;
 export type SpeechRequest = z.infer<typeof speechRequestSchema>;
 export type SpeechAudioDeltaEvent = z.infer<typeof speechAudioDeltaEventSchema>;

package/dist/public/audio.js

@@ -160,12 +160,16 @@ export const MAX_TRANSCRIPTION_FILE_BYTES = 20 * 1024 * 1024;
 export const transcriptionRequestSchema = z
     .object({
     model: modelReferenceSchema,
-    /** The spoken language, when known; validated against the model's `audio.languages`. */
+    /**
+     * The spoken language, when known: one of the model's `audio.languages`.
+     * Absent lets a model that `detectsLanguage` detect it.
+     */
     language: languageTagSchema.optional(),
-    /** Vocabulary or context that helps the model; never an instruction. */
+    /**
+     * Vocabulary or context that helps the model; never an instruction. Only
+     * for a model whose `audio.transcriptionPrompt` is true.
+     */
     prompt: z.string().max(4096).optional(),
-    /** Absent means `none`. */
-    timestamps: z.enum(['none', 'segment', 'word']).optional(),
 })
     .strict();
 /**
@@ -201,11 +205,7 @@ export const transcriptionJsonRequestSchema = transcriptionRequestSchema
         .strict(),
 })
     .strict();
-const timedSpanFields = {
-    startMs: z.number().int().nonnegative().safe(),
-    endMs: z.number().int().nonnegative().safe(),
-};
-/** The response. Segments or words are present only when the request asked for them. */
+/** The response. */
 export const transcriptionSchema = z
     .object({
     schemaVersion: z.literal(1),
@@ -213,24 +213,37 @@ export const transcriptionSchema = z
     /** The revision that actually served the request. */
     model: modelReferenceSchema,
     text: z.string(),
-    /** The language the model heard, when it reports one. */
+    /** The language the model heard, when its provider reports it as a tag. */
     language: languageTagSchema.optional(),
+    /** The audio's duration, measured from its container before the grant. */
     durationMs: z.number().int().nonnegative().safe().optional(),
-    segments: z.array(z.object({ ...timedSpanFields, text: z.string() }).strict()).optional(),
-    words: z.array(z.object({ ...timedSpanFields, word: z.string() }).strict()).optional(),
     usage: usageSchema,
 })
-    .strict()
-    .superRefine((transcription, ctx) => {
-    for (const field of ['segments', 'words']) {
-        for (const [index, span] of (transcription[field] ?? []).entries()) {
-            if (span.endMs < span.startMs) {
-                ctx.addIssue({
-                    code: 'custom',
-                    path: [field, index, 'endMs'],
-                    message: 'a span cannot end before it starts',
-                });
-            }
-        }
+    .strict();
+/**
+ * Check a transcription request against the model's published `audio` — the
+ * transcription counterpart of {@link checkSpeechRequest}. Kaana refuses a
+ * request with `invalid_request` and the first issue's `param` BEFORE asking
+ * Oxy for a grant; a client may run the same check to choose a model, and
+ * omit `language` where `detectsLanguage` lets the model detect it.
+ *
+ * `mediaType` is the upload's (the multipart `file` part's content type, or
+ * `audio.mediaType` of the JSON form). Returns every issue, in field order.
+ */
+export function checkTranscriptionRequest(request, mediaType, audio) {
+    const issues = [];
+    if (!audio.audioFormats.input.includes(mediaType)) {
+        issues.push({ param: 'file', message: `this model does not take ${mediaType} audio` });
     }
-});
+    if (request.language !== undefined && !audio.languages.includes(request.language)) {
+        issues.push({
+            param: 'language',
+            message: `this model does not declare the language ${request.language}` +
+                (audio.detectsLanguage === true ? '; omit it to let the model detect the language' : ''),
+        });
+    }
+    if (request.prompt !== undefined && audio.transcriptionPrompt !== true) {
+        issues.push({ param: 'prompt', message: 'this model takes no prompt' });
+    }
+    return issues;
+}