flexinference 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.1.0
+
+Adds the **Interactions** caller format (`client.interactions.create`), the third format
+alongside Responses and chat completions. It works for both OpenAI and Gemini models and
+posts to `/interactions`. `start_within` is required (same rule as the other formats) and
+`service_tier` is a compile-time error (the router owns the tier). New `interactionText(obj)`
+helper pulls the assistant text out of the `steps[]` shape, where `outputText` returns "".
+
+## 1.0.1
+
+Gemini now supports **image input** and **web search** (send a Responses `web_search`
+tool; the router maps it to Gemini's `google_search`), in addition to text, streaming,
+structured outputs, and function calling. No API or type changes - translation is
+handled server-side, so existing code keeps working.
+
 ## 1.0.0
 
 The stable v1 of the FlexInference TypeScript SDK. This release makes `start_within`

package/README.md

@@ -26,6 +26,17 @@ Responses come back as the **raw OpenAI JSON** (we never reshape the body), so t
 
 `start_within` is **required** on every request. It takes `"default"`, `"priority"`, `"auto"`, or a duration `"HHh-MMm-SSs"` (5s-10m). The duration races OpenAI's flex tier on a flex-capable model and falls back to standard if it can't start in time; `"default"`, `"priority"`, and `"auto"` map to those OpenAI service tiers and proxy any model. It is typed, so a missing value or a value outside the allowed shapes is a **compile-time** error; a duration that fits the shape but is malformed or out of range is caught at **runtime**, the same check plain-JavaScript callers get. See the [docs](https://flexinference.mintlify.app/deadline-routing).
 
+## Providers (OpenAI and Gemini)
+
+FlexInference routes to **OpenAI** and **Google Gemini**. Send the same OpenAI-shaped request and pass whichever model id you want - `gpt-5.5`, `o4-mini`, `gemini-3.5-flash`, and so on. We run Gemini through its Interactions API and translate it back to the OpenAI shape, so your code is identical for both.
+
+- **OpenAI:** `default` (standard tier), `priority`, `auto`, and the flex race (a duration) on flex-capable models.
+- **Gemini:** `default` maps to Gemini's **standard** tier, plus `priority` and the flex race on the Gemini flex models (`gemini-3.5-flash`, `gemini-3.1-flash-lite`, `gemini-3.1-pro-preview`, `gemini-3-flash-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite`). Gemini has no `auto` tier, so `start_within: "auto"` on a Gemini model returns `400`.
+
+Add the provider key you'll use (OpenAI and/or Gemini) in the [dashboard](https://www.flexinference.com/dashboard). Text, streaming, structured outputs, function calling, image input, and web search work on both providers (send a Responses `web_search` tool; we map it to Gemini's `google_search`).
+
+Don't send `service_tier` - the router controls the tier from `start_within` and rejects a caller-supplied `service_tier` with `400 service_tier_not_allowed`.
+
 ## Streaming
 
 ```ts

package/dist/index.d.ts

@@ -17,6 +17,11 @@ type RawChatRequest = Schemas["CreateChatCompletionRequest"];
 export type ChatCompletionCreateParams = WithStartWithin<Partial<RawChatRequest> & Required<Pick<RawChatRequest, "model" | "messages">>>;
 export type ChatCompletion = Schemas["CreateChatCompletionResponse"];
 export type ChatCompletionChunk = Schemas["CreateChatCompletionStreamResponse"];
+export type InteractionCreateParams = WithStartWithin<Schemas["InteractionCreateParams"]> & {
+    service_tier?: never;
+};
+export type InteractionObject = Schemas["InteractionObject"];
+export type InteractionStreamEvent = Schemas["InteractionStreamEvent"];
 /**
  * Concatenate the assistant's text from a non-streamed response. Works on a Responses
  * object (walks `output[].content[]` for `output_text` parts) and on a chat completion
@@ -27,6 +32,14 @@ export type ChatCompletionChunk = Schemas["CreateChatCompletionStreamResponse"];
  * their `output_text.delta` events instead.
  */
 export declare function outputText(response: ResponseObject | ChatCompletion): string;
+/**
+ * Concatenate the assistant's text from a non-streamed Interactions response. The text
+ * lives in `steps[]` of type `model_output`, each a `content[]` of `{type:"text",text}`
+ * parts (a different shape from Responses/chat, so `outputText` returns "" on it). Returns
+ * "" when there is no text (e.g. a function-call-only interaction). Read-only: nothing is
+ * reshaped. Streamed interactions are not objects; collect their `step.delta` text events.
+ */
+export declare function interactionText(interaction: InteractionObject): string;
 export interface FlexErrorBody {
     error: {
         message: string;
@@ -65,6 +78,7 @@ type Post = (path: string, body: unknown, signal: AbortSignal | undefined) => Pr
 export declare class FlexInference {
     readonly responses: Responses;
     readonly chat: Chat;
+    readonly interactions: Interactions;
     private readonly apiKey;
     private readonly baseURL;
     private readonly fetchImpl;
@@ -96,4 +110,14 @@ declare class ChatCompletions {
         stream: true;
     }, options?: RequestOptions): Promise<AsyncIterable<ChatCompletionChunk>>;
 }
+declare class Interactions {
+    private readonly post;
+    constructor(post: Post);
+    create(body: InteractionCreateParams & {
+        stream?: false | null;
+    }, options?: RequestOptions): Promise<InteractionObject>;
+    create(body: InteractionCreateParams & {
+        stream: true;
+    }, options?: RequestOptions): Promise<AsyncIterable<InteractionStreamEvent>>;
+}
 export {};

package/dist/index.js

@@ -36,6 +36,32 @@ export function outputText(response) {
     }
     return "";
 }
+/**
+ * Concatenate the assistant's text from a non-streamed Interactions response. The text
+ * lives in `steps[]` of type `model_output`, each a `content[]` of `{type:"text",text}`
+ * parts (a different shape from Responses/chat, so `outputText` returns "" on it). Returns
+ * "" when there is no text (e.g. a function-call-only interaction). Read-only: nothing is
+ * reshaped. Streamed interactions are not objects; collect their `step.delta` text events.
+ */
+export function interactionText(interaction) {
+    const obj = interaction;
+    if (!isRecord(obj))
+        return "";
+    const steps = obj.steps;
+    if (!Array.isArray(steps))
+        return "";
+    let text = "";
+    for (const step of steps) {
+        if (!isRecord(step) || step.type !== "model_output" || !Array.isArray(step.content))
+            continue;
+        for (const part of step.content) {
+            if (isRecord(part) && part.type === "text" && typeof part.text === "string") {
+                text += part.text;
+            }
+        }
+    }
+    return text;
+}
 export class FlexInferenceError extends Error {
     status;
     type;
@@ -87,6 +113,7 @@ function assertStartWithin(body) {
 export class FlexInference {
     responses;
     chat;
+    interactions;
     apiKey;
     baseURL;
     fetchImpl;
@@ -105,6 +132,7 @@ export class FlexInference {
         const post = (path, body, signal) => this.post(path, body, signal);
         this.responses = new Responses(post);
         this.chat = new Chat(post);
+        this.interactions = new Interactions(post);
     }
     async post(path, body, signal) {
         // One AbortController fed by three sources: the caller's signal, a 10s connect
@@ -214,6 +242,25 @@ class ChatCompletions {
         }
     }
 }
+class Interactions {
+    post;
+    constructor(post) {
+        this.post = post;
+    }
+    async create(body, options) {
+        assertStartWithin(body);
+        const { res, cleanup } = await this.post("/interactions", body, options?.signal);
+        if (body.stream) {
+            return streamSSE(res, cleanup);
+        }
+        try {
+            return (await res.json());
+        }
+        finally {
+            cleanup();
+        }
+    }
+}
 async function* streamSSE(res, cleanup) {
     if (!res.body) {
         cleanup();

package/dist/types.d.ts

@@ -64,6 +64,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/interactions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Create an interaction. The third FlexInference caller format; works for OpenAI and Gemini models via the canonical Responses path. Send start_within and do not send service_tier. */
+        post: operations["createInteraction"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -1105,7 +1122,7 @@ export interface components {
              */
             top_logprobs?: number;
             /**
-             * @description FlexInference deadline control. Required on every request. "default", "priority", and "auto" map to those OpenAI service tiers ("auto" lets OpenAI pick) and proxy any model. A duration "HHh-MMm-SSs" between 5 seconds and 10 minutes runs the flex tier on a flex-capable model and automatically falls back to standard if it has not started within the window. The retired value "standard" is no longer accepted (use "default").
+             * @description FlexInference deadline control. Required on every request. "default" maps to the provider's standard real-time tier (OpenAI "default", Gemini "standard"), "priority" to the provider's priority tier, and "auto" to OpenAI's auto tier (OpenAI only; Gemini has no auto tier). These proxy any model. A duration "HHh-MMm-SSs" between 5 seconds and 10 minutes runs the provider's flex tier (OpenAI or Gemini) on a flex-capable model and automatically falls back to standard if it has not started within the window. Do not send service_tier (the router controls the tier). The retired value "standard" is no longer accepted (use "default").
              * @example 00h-00m-30s
              */
             start_within?: string;
@@ -5366,6 +5383,298 @@ export interface components {
                 param?: string | null;
             };
         };
+        /** Interaction Text Part */
+        InteractionTextPart: {
+            /** @constant */
+            type: "text";
+            text: string;
+        };
+        /** Interaction Image Part */
+        InteractionImagePart: {
+            /** @constant */
+            type: "image";
+            mime_type: string;
+            /** @description Base64-encoded image bytes. */
+            data: string;
+        };
+        /** Interaction Document Part */
+        InteractionDocumentPart: {
+            /** @constant */
+            type: "document";
+            mime_type: string;
+            /** @description Base64-encoded document bytes. */
+            data: string;
+        };
+        /**
+         * Interaction Content Part
+         * @description A single piece of multimodal content in an Interactions request.
+         */
+        InteractionContentPart: components["schemas"]["InteractionTextPart"] | components["schemas"]["InteractionImagePart"] | components["schemas"]["InteractionDocumentPart"];
+        /** Interaction User Input Step */
+        InteractionUserInputStep: {
+            /** @constant */
+            type: "user_input";
+            content: components["schemas"]["InteractionContentPart"][];
+        };
+        /** Interaction Model Output Step */
+        InteractionModelOutputStep: {
+            /** @constant */
+            type: "model_output";
+            content: components["schemas"]["InteractionContentPart"][];
+        };
+        /** Interaction Function Call Step */
+        InteractionFunctionCallStep: {
+            /** @constant */
+            type: "function_call";
+            id?: string;
+            name: string;
+            /** @description Parsed function arguments object (not a JSON string). */
+            arguments: {
+                [key: string]: unknown;
+            };
+        };
+        /** Interaction Function Result Step */
+        InteractionFunctionResultStep: {
+            /** @constant */
+            type: "function_result";
+            name: string;
+            /** @description Tool result payload; any JSON value. */
+            result: unknown;
+        };
+        /**
+         * Interaction Step
+         * @description One turn in a multi-turn Interactions request (a step list).
+         */
+        InteractionStep: components["schemas"]["InteractionUserInputStep"] | components["schemas"]["InteractionModelOutputStep"] | components["schemas"]["InteractionFunctionCallStep"] | components["schemas"]["InteractionFunctionResultStep"];
+        /** Interaction Function Tool */
+        InteractionFunctionTool: {
+            /** @constant */
+            type: "function";
+            name: string;
+            description?: string;
+            /** @description JSON Schema for the function parameters. */
+            parameters?: {
+                [key: string]: unknown;
+            };
+        };
+        /** Interaction Google Search Tool */
+        InteractionGoogleSearchTool: {
+            /** @constant */
+            type: "google_search";
+        };
+        /** Interaction Tool */
+        InteractionTool: components["schemas"]["InteractionFunctionTool"] | components["schemas"]["InteractionGoogleSearchTool"];
+        /**
+         * Interaction Generation Config
+         * @description Generation controls. thinking_level maps to canonical reasoning.effort.
+         */
+        InteractionGenerationConfig: {
+            max_output_tokens?: number;
+            temperature?: number;
+            top_p?: number;
+            /** @enum {string} */
+            thinking_level?: "minimal" | "low" | "medium" | "high";
+            /** @description auto, none, or any. "any" maps to canonical tool_choice "required". */
+            tool_choice?: string;
+        };
+        /**
+         * Interaction Create Params
+         * @description Request body for POST /v1/interactions. Works for both OpenAI and Gemini models via the canonical Responses path. Does not accept service_tier (the router owns the tier). start_within is required at runtime but left optional here.
+         */
+        InteractionCreateParams: {
+            model: string;
+            /** @description A prompt string, a content-part array (one turn), or a step list (multi-turn). */
+            input?: string | components["schemas"]["InteractionContentPart"][] | components["schemas"]["InteractionStep"][];
+            /** @description System instruction as a string or a content-part array. */
+            system_instruction?: string | components["schemas"]["InteractionContentPart"][];
+            tools?: components["schemas"]["InteractionTool"][];
+            /** @description Inline JSON schema, mapped to canonical text.format.json_schema. */
+            response_format?: {
+                [key: string]: unknown;
+            };
+            generation_config?: components["schemas"]["InteractionGenerationConfig"];
+            previous_interaction_id?: string;
+            stream?: boolean;
+            background?: boolean;
+            store?: boolean;
+            /** @description FlexInference deadline control (see the Responses/Chat ops). Required on every request; enforced by the router at runtime, not by this schema. */
+            start_within?: string;
+        } & {
+            [key: string]: unknown;
+        };
+        /** Interaction Usage */
+        InteractionUsage: {
+            total_input_tokens?: number;
+            total_output_tokens?: number;
+            total_thought_tokens?: number;
+            total_cached_tokens?: number;
+            total_tokens?: number;
+            total_tool_use_tokens?: number;
+        };
+        /**
+         * Interaction Text Annotation
+         * @description An opaque annotation on emitted text (e.g. a web-search citation).
+         */
+        InteractionTextAnnotation: {
+            [key: string]: unknown;
+        };
+        /** Interaction Response Text Content */
+        InteractionResponseTextContent: {
+            /** @constant */
+            type: "text";
+            text: string;
+            annotations?: components["schemas"]["InteractionTextAnnotation"][];
+        };
+        /** Interaction Model Output Response Step */
+        InteractionModelOutputResponseStep: {
+            /** @constant */
+            type: "model_output";
+            content: components["schemas"]["InteractionResponseTextContent"][];
+        };
+        /** Interaction Function Call Response Step */
+        InteractionFunctionCallResponseStep: {
+            /** @constant */
+            type: "function_call";
+            id?: string;
+            name: string;
+            arguments: {
+                [key: string]: unknown;
+            };
+        };
+        /** Interaction Google Search Call Step */
+        InteractionGoogleSearchCallStep: {
+            /** @constant */
+            type: "google_search_call";
+            id: string;
+        };
+        /** Interaction Response Step */
+        InteractionResponseStep: components["schemas"]["InteractionModelOutputResponseStep"] | components["schemas"]["InteractionFunctionCallResponseStep"] | components["schemas"]["InteractionGoogleSearchCallStep"];
+        /**
+         * Interaction Object
+         * @description Non-stream response from POST /v1/interactions.
+         */
+        InteractionObject: {
+            id: string;
+            /** @constant */
+            object: "interaction";
+            /** @enum {string} */
+            status: "completed" | "requires_action" | "incomplete" | "failed";
+            model: string;
+            created?: number;
+            updated?: number;
+            service_tier?: string;
+            usage?: components["schemas"]["InteractionUsage"];
+            steps: components["schemas"]["InteractionResponseStep"][];
+        };
+        /**
+         * Interaction Stream Snapshot
+         * @description Interaction state carried by created and completed stream events.
+         */
+        InteractionStreamSnapshot: {
+            id: string;
+            status: string;
+            /** @constant */
+            object: "interaction";
+            model: string;
+            usage?: components["schemas"]["InteractionUsage"];
+        } & {
+            [key: string]: unknown;
+        };
+        /**
+         * Interaction Stream Step
+         * @description The step descriptor on a step.start event.
+         */
+        InteractionStreamStep: {
+            /** @enum {string} */
+            type: "model_output" | "function_call" | "google_search_call";
+            id?: string;
+            name?: string;
+        };
+        /**
+         * Interaction Stream Delta
+         * @description The incremental payload on a step.delta event.
+         */
+        InteractionStreamDelta: {
+            /** @enum {string} */
+            type?: "text" | "arguments_delta";
+            text?: string;
+            arguments?: string;
+            annotations?: components["schemas"]["InteractionTextAnnotation"][];
+        };
+        /** Interaction Created Event */
+        InteractionCreatedEvent: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event_type: "interaction.created";
+            interaction: components["schemas"]["InteractionStreamSnapshot"];
+        };
+        /** Interaction Status Update Event */
+        InteractionStatusUpdateEvent: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event_type: "interaction.status_update";
+            interaction_id: string;
+            status: string;
+        };
+        /** Interaction Completed Event */
+        InteractionCompletedEvent: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event_type: "interaction.completed";
+            interaction: components["schemas"]["InteractionStreamSnapshot"];
+        };
+        /** Interaction Step Start Event */
+        InteractionStepStartEvent: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event_type: "step.start";
+            index: number;
+            step: components["schemas"]["InteractionStreamStep"];
+        };
+        /** Interaction Step Delta Event */
+        InteractionStepDeltaEvent: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event_type: "step.delta";
+            index: number;
+            delta: components["schemas"]["InteractionStreamDelta"];
+        };
+        /** Interaction Step Stop Event */
+        InteractionStepStopEvent: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event_type: "step.stop";
+            index: number;
+        };
+        /** Interaction Error Event */
+        InteractionErrorEvent: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event_type: "error";
+            /** @description Error payload (mirrors the FlexError error object). */
+            error: {
+                [key: string]: unknown;
+            };
+        };
+        /**
+         * Interaction Stream Event
+         * @description One server-sent event frame on the Interactions stream.
+         */
+        InteractionStreamEvent: components["schemas"]["InteractionCreatedEvent"] | components["schemas"]["InteractionStatusUpdateEvent"] | components["schemas"]["InteractionCompletedEvent"] | components["schemas"]["InteractionStepStartEvent"] | components["schemas"]["InteractionStepDeltaEvent"] | components["schemas"]["InteractionStepStopEvent"] | components["schemas"]["InteractionErrorEvent"];
     };
     responses: never;
     parameters: never;
@@ -5398,7 +5707,7 @@ export interface operations {
                     "text/event-stream": components["schemas"]["CreateChatCompletionStreamResponse"];
                 };
             };
-            /** @description Bad request. A FlexInference-layer rejection (type flexinference_error, e.g. missing_start_within, invalid_start_within, model_not_flex_capable, no_byok_key) or an OpenAI rejection passed through unchanged. */
+            /** @description Bad request. A FlexInference-layer rejection (type flexinference_error, e.g. missing_start_within, invalid_start_within, model_not_flex_capable, no_byok_key, no_gemini_key, auto_unsupported_for_gemini, service_tier_not_allowed) or an OpenAI/Gemini rejection passed through unchanged. */
             400: {
                 headers: {
                     [name: string]: unknown;
@@ -5441,7 +5750,50 @@ export interface operations {
                     "text/event-stream": components["schemas"]["ResponseStreamEvent"];
                 };
             };
-            /** @description Bad request. A FlexInference-layer rejection (type flexinference_error, e.g. missing_start_within, invalid_start_within, model_not_flex_capable, no_byok_key) or an OpenAI rejection passed through unchanged. */
+            /** @description Bad request. A FlexInference-layer rejection (type flexinference_error, e.g. missing_start_within, invalid_start_within, model_not_flex_capable, no_byok_key, no_gemini_key, auto_unsupported_for_gemini, service_tier_not_allowed) or an OpenAI/Gemini rejection passed through unchanged. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FlexError"];
+                };
+            };
+            /** @description Invalid or missing FlexInference API key (type flexinference_error, code invalid_api_key). */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FlexError"];
+                };
+            };
+        };
+    };
+    createInteraction: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["InteractionCreateParams"];
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["InteractionObject"];
+                    "text/event-stream": components["schemas"]["InteractionStreamEvent"];
+                };
+            };
+            /** @description Bad request. A FlexInference-layer rejection (type flexinference_error, e.g. missing_start_within, invalid_start_within, model_not_flex_capable, auto_unsupported_for_gemini, service_tier_not_allowed) or an OpenAI/Gemini rejection passed through unchanged. */
             400: {
                 headers: {
                     [name: string]: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flexinference",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Official TypeScript SDK for FlexInference - a deadline-aware, OpenAI-compatible inference router.",
   "license": "MIT",
   "author": "Aditya Perswal <adityaperswal@gmail.com>",