@tokenlabai/mcp-server 0.6.25 → 0.6.27

package/contract/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "TokenLab AI Gateway",
-    "description": "Organization balance, API key management, and key-level usage/billing via management token",
+    "description": "TokenLab public AI API: model discovery, generation, files, cached content, asynchronous tasks, and management-token account reporting.",
     "version": "1.0.0",
     "termsOfService": "https://tokenlab.sh/tos",
     "contact": {
@@ -75,6 +75,10 @@
     {
       "name": "Webhooks",
       "description": "Workspace webhook management with Management Tokens (mt-...). Inference API keys do not grant management access."
+    },
+    {
+      "name": "Gemini Resources",
+      "description": "Workspace-owned Gemini files, uploads, and cached content"
     }
   ],
   "security": [
@@ -128,34 +132,6 @@
                     "stream": true
                   }
                 },
-                "live_translation": {
-                  "summary": "Stream audio translation",
-                  "value": {
-                    "model": "qwen3-livetranslate-flash",
-                    "messages": [
-                      {
-                        "role": "user",
-                        "content": [
-                          {
-                            "type": "input_audio",
-                            "input_audio": {
-                              "data": "https://example.com/sample.wav",
-                              "format": "wav"
-                            }
-                          }
-                        ]
-                      }
-                    ],
-                    "translation_options": {
-                      "source_lang": "zh",
-                      "target_lang": "en"
-                    },
-                    "modalities": [
-                      "text"
-                    ],
-                    "stream": true
-                  }
-                },
                 "function_calling": {
                   "summary": "Function calling",
                   "value": {
@@ -331,7 +307,7 @@
                 "text": {
                   "summary": "Text input",
                   "value": {
-                    "model": "jina-embeddings-v4",
+                    "model": "qwen3-vl-embedding",
                     "input": {
                       "text": "Describe this product for semantic search."
                     }
@@ -531,6 +507,9 @@
                     },
                     "error_details": {
                       "$ref": "#/components/schemas/AsyncTaskErrorDetails"
+                    },
+                    "media_retention": {
+                      "$ref": "#/components/schemas/MediaRetention"
                     }
                   }
                 }
@@ -588,18 +567,18 @@
                 "basic": {
                   "summary": "Basic TTS",
                   "value": {
-                    "model": "tts-1",
+                    "model": "grok-tts",
                     "input": "Hello, welcome to TokenLab!",
-                    "voice": "alloy"
+                    "voice": "eve"
                   }
                 },
-                "hd": {
-                  "summary": "HD quality TTS",
+                "voice_and_speed": {
+                  "summary": "Voice and speed",
                   "value": {
-                    "model": "tts-1-hd",
-                    "input": "This is high quality speech synthesis.",
-                    "voice": "nova",
-                    "response_format": "mp3",
+                    "model": "qwen3-tts-flash",
+                    "input": "This is a speech synthesis example.",
+                    "voice": "Cherry",
+                    "response_format": "wav",
                     "speed": 1
                   }
                 }
@@ -757,7 +736,7 @@
                 "image_to_video": {
                   "summary": "Image-to-Video",
                   "value": {
-                    "model": "hailuo-2.3-standard",
+                    "model": "hailuo-2.3",
                     "prompt": "Make this image come alive with gentle movement",
                     "operation": "image-to-video",
                     "image_url": "https://example.com/image.jpg",
@@ -1776,7 +1755,7 @@
           "Anthropic"
         ],
         "summary": "Count message tokens (Anthropic-compatible)",
-        "description": "Counts input tokens for an Anthropic-compatible messages request without creating a model response. Authentication is required; the operation is not billed.",
+        "description": "Counts input tokens for an Anthropic-compatible messages request without creating a model response. Authentication is required; the operation is not billed. Verified upstream counting is preferred. Upstream availability failures return a local estimate marked by X-TokenLab-Count-Tokens-Source: local_estimate. Platform authentication, permission and input errors remain errors. Bound files unreadable locally require upstream counting.",
         "operationId": "countAnthropicMessageTokens",
         "requestBody": {
           "required": true,
@@ -2731,7 +2710,7 @@
                       "string",
                       "null"
                     ],
-                    "description": "Service tier hint where supported by the model."
+                    "description": "TokenLab serves this request at the standard service tier. auto and default are forwarded. Other values, such as flex, priority, fast and ultrafast, are ignored and billed at the standard price."
                   },
                   "truncation": {
                     "type": "string",
@@ -3232,9 +3211,6 @@
             "application/json": {
               "schema": {
                 "type": "object",
-                "required": [
-                  "prompt"
-                ],
                 "properties": {
                   "model": {
                     "type": "string",
@@ -3242,7 +3218,7 @@
                   },
                   "prompt": {
                     "type": "string",
-                    "description": "3D model description"
+                    "description": "3D model description. Required for every model that takes a prompt; an image-to-3D model whose contract lists no prompt is called without one."
                   },
                   "image": {
                     "type": "string",
@@ -4535,7 +4511,8 @@
               "schema": {
                 "type": "object",
                 "required": [
-                  "file"
+                  "file",
+                  "model"
                 ],
                 "properties": {
                   "file": {
@@ -4543,8 +4520,7 @@
                     "format": "binary"
                   },
                   "model": {
-                    "type": "string",
-                    "default": "whisper-1"
+                    "type": "string"
                   },
                   "prompt": {
                     "type": "string"
@@ -4613,7 +4589,7 @@
             "schema": {
               "type": "string"
             },
-            "example": "gpt-realtime"
+            "example": "grok-voice-latest"
           }
         ],
         "responses": {
@@ -5775,6 +5751,9 @@
                     },
                     "error_details": {
                       "$ref": "#/components/schemas/AsyncTaskErrorDetails"
+                    },
+                    "media_retention": {
+                      "$ref": "#/components/schemas/MediaRetention"
                     }
                   },
                   "additionalProperties": true
@@ -8271,147 +8250,1417 @@
           }
         ]
       }
-    }
-  },
-  "components": {
-    "securitySchemes": {
-      "BearerAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "bearerFormat": "API Key",
-        "description": "API Key authentication. Create or manage API keys in [Dashboard > API > API Keys](https://tokenlab.sh/dashboard/api?tab=keys)."
-      },
-      "ManagementTokenAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "bearerFormat": "Management Token",
-        "description": "Management token authentication. Create or manage Management Tokens in [Dashboard > API > Management Tokens](https://tokenlab.sh/dashboard/api?tab=tokens)."
-      }
     },
-    "schemas": {
-      "ChatCompletionRequest": {
-        "type": "object",
-        "required": [
-          "model",
-          "messages"
+    "/v1beta/files:register": {
+      "post": {
+        "tags": [
+          "Gemini Resources"
         ],
-        "properties": {
-          "model": {
-            "type": "string",
-            "description": "ID of the model to use (e.g., gpt-5.4, claude-sonnet-4-6)",
-            "example": "gpt-4o"
+        "operationId": "geminiRegisterFiles",
+        "summary": "Register Gemini files",
+        "description": "Registers files from a supported source using Gemini JSON. The service validates the source and request fields. Resources can only be read, referenced, changed, or deleted in their owning Workspace. Missing, expired, or inaccessible resources return a Gemini-format error.",
+        "security": [
+          {
+            "BearerAuth": []
           },
-          "messages": {
-            "type": "array",
-            "description": "A list of messages comprising the conversation",
-            "items": {
-              "$ref": "#/components/schemas/ChatMessage"
+          {
+            "GeminiApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "key",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
             },
-            "minItems": 1
-          },
-          "temperature": {
-            "type": "number",
-            "minimum": 0,
-            "maximum": 2,
-            "default": 1,
-            "description": "Sampling temperature (0-2)"
+            "description": "API key alternative to Bearer or x-goog-api-key."
           },
-          "top_p": {
-            "type": "number",
-            "minimum": 0,
-            "maximum": 1,
-            "default": 1,
-            "description": "Nucleus sampling probability"
+          {
+            "name": "Idempotency-Key",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Reuse the same key and request body when recovering a create response. A different body with the same key returns a conflict."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "anyOf": [
+                    {
+                      "$ref": "#/components/schemas/GeminiFileResource"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "file": {
+                          "$ref": "#/components/schemas/GeminiFileResource"
+                        },
+                        "files": {
+                          "type": "array",
+                          "items": {
+                            "$ref": "#/components/schemas/GeminiFileResource"
+                          }
+                        }
+                      },
+                      "additionalProperties": true
+                    }
+                  ]
+                }
+              }
+            }
           },
-          "n": {
-            "type": "integer",
-            "minimum": 1,
-            "maximum": 128,
-            "default": 1,
-            "description": "Number of completions to generate"
+          "400": {
+            "$ref": "#/components/responses/GeminiResourceError"
           },
-          "stream": {
-            "type": "boolean",
-            "default": false,
-            "description": "If true, returns a stream of events"
+          "401": {
+            "$ref": "#/components/responses/GeminiResourceError"
           },
-          "stop": {
-            "oneOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "array",
-                "items": {
-                  "type": "string"
-                },
-                "maxItems": 4
-              }
-            ],
-            "description": "Stop sequences"
+          "403": {
+            "$ref": "#/components/responses/GeminiResourceError"
           },
-          "max_tokens": {
-            "type": "integer",
-            "minimum": 1,
-            "description": "Maximum number of tokens to generate"
+          "404": {
+            "$ref": "#/components/responses/GeminiResourceError"
           },
-          "max_completion_tokens": {
-            "type": "integer",
-            "minimum": 1,
-            "description": "Maximum completion tokens for newer reasoning-enabled model families"
+          "409": {
+            "$ref": "#/components/responses/GeminiResourceError"
           },
-          "presence_penalty": {
-            "type": "number",
-            "minimum": -2,
-            "maximum": 2,
-            "default": 0,
-            "description": "Presence penalty (-2 to 2)"
+          "429": {
+            "$ref": "#/components/responses/GeminiResourceError"
           },
-          "frequency_penalty": {
-            "type": "number",
-            "minimum": -2,
-            "maximum": 2,
-            "default": 0,
-            "description": "Frequency penalty (-2 to 2)"
+          "502": {
+            "$ref": "#/components/responses/GeminiResourceError"
           },
-          "tools": {
-            "type": "array",
-            "description": "List of tools the model may call",
-            "items": {
-              "$ref": "#/components/schemas/Tool"
+          "503": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GeminiFileRegisterRequest"
+              }
             }
+          }
+        }
+      }
+    },
+    "/v1beta/files": {
+      "post": {
+        "tags": [
+          "Gemini Resources"
+        ],
+        "operationId": "geminiCreateFile",
+        "summary": "Create Gemini file metadata",
+        "description": "Creates a Gemini file resource from JSON metadata. Upload file bytes through /upload/v1beta/files. Resources can only be read, referenced, changed, or deleted in their owning Workspace. Missing, expired, or inaccessible resources return a Gemini-format error.",
+        "security": [
+          {
+            "BearerAuth": []
           },
-          "functions": {
-            "type": "array",
-            "description": "Deprecated function definitions retained by the official Chat Completions contract.",
-            "items": {
-              "type": "object",
-              "additionalProperties": true
-            }
+          {
+            "GeminiApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "key",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "API key alternative to Bearer or x-goog-api-key."
           },
-          "function_call": {
-            "oneOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "object",
-                "additionalProperties": true
+          {
+            "name": "Idempotency-Key",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Reuse the same key and request body when recovering a create response. A different body with the same key returns a conflict."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "anyOf": [
+                    {
+                      "$ref": "#/components/schemas/GeminiFileResource"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "file": {
+                          "$ref": "#/components/schemas/GeminiFileResource"
+                        },
+                        "files": {
+                          "type": "array",
+                          "items": {
+                            "$ref": "#/components/schemas/GeminiFileResource"
+                          }
+                        }
+                      },
+                      "additionalProperties": true
+                    }
+                  ]
+                }
               }
-            ],
-            "description": "Deprecated function-call selection retained by the official Chat Completions contract."
+            }
           },
-          "tool_choice": {
-            "oneOf": [
-              {
-                "type": "string",
-                "enum": [
-                  "none",
-                  "auto",
-                  "required"
-                ]
-              },
-              {
+          "400": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "401": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "403": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "404": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "409": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "429": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "502": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "503": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GeminiFileCreateRequest"
+              }
+            }
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "Gemini Resources"
+        ],
+        "operationId": "geminiListFiles",
+        "summary": "List Gemini files",
+        "description": "Lists files belonging to the current Workspace. Use nextPageToken to continue. Resources can only be read, referenced, changed, or deleted in their owning Workspace. Missing, expired, or inaccessible resources return a Gemini-format error.",
+        "security": [
+          {
+            "BearerAuth": []
+          },
+          {
+            "GeminiApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "key",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "API key alternative to Bearer or x-goog-api-key."
+          },
+          {
+            "name": "pageSize",
+            "in": "query",
+            "schema": {
+              "type": "integer"
+            },
+            "description": "Requested page size; page_size is also accepted."
+          },
+          {
+            "name": "pageToken",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Opaque nextPageToken from the previous response. page_token is also accepted."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "files": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/GeminiFileResource"
+                      }
+                    },
+                    "nextPageToken": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "files"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "401": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "403": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "404": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "409": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "429": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "502": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "503": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          }
+        }
+      }
+    },
+    "/v1beta/files/{fileId}": {
+      "get": {
+        "tags": [
+          "Gemini Resources"
+        ],
+        "operationId": "geminiGetFile",
+        "summary": "Get Gemini file",
+        "description": "Reads metadata for a Gemini file. Resources can only be read, referenced, changed, or deleted in their owning Workspace. Missing, expired, or inaccessible resources return a Gemini-format error.",
+        "security": [
+          {
+            "BearerAuth": []
+          },
+          {
+            "GeminiApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "fileId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Suffix of the returned files/{fileId} name."
+          },
+          {
+            "name": "key",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "API key alternative to Bearer or x-goog-api-key."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GeminiFileResource"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "401": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "403": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "404": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "409": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "429": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "502": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "503": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Gemini Resources"
+        ],
+        "operationId": "geminiDeleteFile",
+        "summary": "Delete Gemini file",
+        "description": "Deletes a Gemini file. Save anything needed before deletion. Resources can only be read, referenced, changed, or deleted in their owning Workspace. Missing, expired, or inaccessible resources return a Gemini-format error.",
+        "security": [
+          {
+            "BearerAuth": []
+          },
+          {
+            "GeminiApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "fileId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "key",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "API key alternative to Bearer or x-goog-api-key."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "401": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "403": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "404": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "409": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "429": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "502": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "503": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          }
+        }
+      }
+    },
+    "/v1beta/cachedContents": {
+      "post": {
+        "tags": [
+          "Gemini Resources"
+        ],
+        "operationId": "geminiCreateCachedContent",
+        "summary": "Create Gemini cached content",
+        "description": "Creates cached content for a current TokenLab Gemini model. Supported fields, resource references, and lifetime depend on the service and model; lowerCamelCase and the corresponding proto snake_case names are accepted. Resources can only be read, referenced, changed, or deleted in their owning Workspace. Missing, expired, or inaccessible resources return a Gemini-format error.",
+        "security": [
+          {
+            "BearerAuth": []
+          },
+          {
+            "GeminiApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "key",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "API key alternative to Bearer or x-goog-api-key."
+          },
+          {
+            "name": "Idempotency-Key",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Reuse the same key and request body when recovering a create response. A different body with the same key returns a conflict."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GeminiCachedContentResource"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "401": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "403": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "404": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "409": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "429": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "502": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "503": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GeminiCachedContentRequest"
+              }
+            }
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "Gemini Resources"
+        ],
+        "operationId": "geminiListCachedContents",
+        "summary": "List Gemini cached content",
+        "description": "Lists cached content belonging to the current Workspace. Use nextPageToken to continue. Resources can only be read, referenced, changed, or deleted in their owning Workspace. Missing, expired, or inaccessible resources return a Gemini-format error.",
+        "security": [
+          {
+            "BearerAuth": []
+          },
+          {
+            "GeminiApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "key",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "API key alternative to Bearer or x-goog-api-key."
+          },
+          {
+            "name": "pageSize",
+            "in": "query",
+            "schema": {
+              "type": "integer"
+            },
+            "description": "Requested page size; page_size is also accepted."
+          },
+          {
+            "name": "pageToken",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Opaque nextPageToken from the previous response. page_token is also accepted."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "cachedContents"
+                  ],
+                  "properties": {
+                    "cachedContents": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/GeminiCachedContentResource"
+                      }
+                    },
+                    "nextPageToken": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "401": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "403": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "404": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "409": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "429": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "502": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "503": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          }
+        }
+      }
+    },
+    "/v1beta/cachedContents/{cacheId}": {
+      "get": {
+        "tags": [
+          "Gemini Resources"
+        ],
+        "operationId": "geminiGetCachedContent",
+        "summary": "Get Gemini cached content",
+        "description": "Reads cached content metadata. Resources can only be read, referenced, changed, or deleted in their owning Workspace. Missing, expired, or inaccessible resources return a Gemini-format error.",
+        "security": [
+          {
+            "BearerAuth": []
+          },
+          {
+            "GeminiApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "cacheId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Suffix of the returned cachedContents/{cacheId} name."
+          },
+          {
+            "name": "key",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "API key alternative to Bearer or x-goog-api-key."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GeminiCachedContentResource"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "401": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "403": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "404": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "409": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "429": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "502": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "503": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          }
+        }
+      },
+      "patch": {
+        "tags": [
+          "Gemini Resources"
+        ],
+        "operationId": "geminiUpdateCachedContent",
+        "summary": "Update Gemini cached content",
+        "description": "Updates the cache lifetime. Invalid lifetime or unsupported fields return a Gemini-format error. Resources can only be read, referenced, changed, or deleted in their owning Workspace. Missing, expired, or inaccessible resources return a Gemini-format error.",
+        "security": [
+          {
+            "BearerAuth": []
+          },
+          {
+            "GeminiApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "cacheId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "key",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "API key alternative to Bearer or x-goog-api-key."
+          },
+          {
+            "name": "updateMask",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Gemini field mask when required by the service."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GeminiCachedContentResource"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "401": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "403": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "404": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "409": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "429": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "502": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "503": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GeminiCachedContentUpdateRequest"
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Gemini Resources"
+        ],
+        "operationId": "geminiDeleteCachedContent",
+        "summary": "Delete Gemini cached content",
+        "description": "Deletes cached content. It cannot be used by subsequent generation after deletion. Resources can only be read, referenced, changed, or deleted in their owning Workspace. Missing, expired, or inaccessible resources return a Gemini-format error.",
+        "security": [
+          {
+            "BearerAuth": []
+          },
+          {
+            "GeminiApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "cacheId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "key",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "API key alternative to Bearer or x-goog-api-key."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "401": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "403": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "404": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "409": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "429": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "502": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "503": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          }
+        }
+      }
+    },
+    "/upload/v1beta/files": {
+      "post": {
+        "tags": [
+          "Gemini Resources"
+        ],
+        "operationId": "geminiUploadFile",
+        "summary": "Upload Gemini file",
+        "description": "Uploads bytes or starts a resumable upload. For resumable start, send metadata and read X-Goog-Upload-URL. Continue only at that returned URL. The upload URL grants access to that upload, expires after one hour, and must be kept private. Resources can only be read, referenced, changed, or deleted in their owning Workspace. Missing, expired, or inaccessible resources return a Gemini-format error.",
+        "security": [
+          {
+            "BearerAuth": []
+          },
+          {
+            "GeminiApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "key",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "API key alternative to Bearer or x-goog-api-key."
+          },
+          {
+            "name": "Idempotency-Key",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Reuse the same key and request body when recovering a create response. A different body with the same key returns a conflict."
+          },
+          {
+            "name": "X-Goog-Upload-Protocol",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Upload protocol such as resumable."
+          },
+          {
+            "name": "X-Goog-Upload-Command",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Upload command such as start or upload, finalize."
+          },
+          {
+            "name": "X-Goog-Upload-Header-Content-Length",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Expected file byte length when starting a resumable upload."
+          },
+          {
+            "name": "X-Goog-Upload-Header-Content-Type",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "File MIME type when starting a resumable upload."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "file": {
+                      "$ref": "#/components/schemas/GeminiFileResource"
+                    }
+                  },
+                  "additionalProperties": true
+                }
+              }
+            },
+            "headers": {
+              "X-Goog-Upload-URL": {
+                "description": "Private resumable upload URL; returned for resumable start. Use it as supplied.",
+                "schema": {
+                  "type": "string",
+                  "format": "uri"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "401": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "403": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "404": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "409": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "429": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "502": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "503": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          }
+        },
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GeminiFileCreateRequest"
+              }
+            },
+            "application/octet-stream": {
+              "schema": {
+                "type": "string",
+                "format": "binary"
+              }
+            },
+            "*/*": {
+              "schema": {
+                "type": "string",
+                "format": "binary"
+              }
+            }
+          }
+        },
+        "x-mint": {
+          "metadata": {
+            "playground": "none"
+          }
+        }
+      }
+    },
+    "/upload/v1beta/files/session/{sessionId}": {
+      "post": {
+        "tags": [
+          "Gemini Resources"
+        ],
+        "operationId": "geminiContinueFileUpload",
+        "summary": "Continue Gemini file upload",
+        "description": "Sends bytes or commands to the exact URL returned by resumable start. The session in the URL authorizes this upload; an API key is not required. Keep the URL private. A missing or expired session returns 404; a session that can no longer be continued returns 410. A nonterminal chunk can return 308, so do not treat that response as a page redirect.",
+        "security": [],
+        "parameters": [
+          {
+            "name": "sessionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "X-Goog-Upload-Command",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Upload command such as upload, finalize."
+          },
+          {
+            "name": "X-Goog-Upload-Offset",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Zero-based byte offset of the chunk."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "file": {
+                      "$ref": "#/components/schemas/GeminiFileResource"
+                    }
+                  },
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "308": {
+            "description": "Upload chunk accepted; more data or finalization is needed."
+          },
+          "400": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "401": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "403": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "404": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "409": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "410": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "429": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "502": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          },
+          "503": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          }
+        },
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/octet-stream": {
+              "schema": {
+                "type": "string",
+                "format": "binary"
+              }
+            },
+            "*/*": {
+              "schema": {
+                "type": "string",
+                "format": "binary"
+              }
+            }
+          }
+        },
+        "x-mint": {
+          "metadata": {
+            "playground": "none"
+          }
+        }
+      }
+    },
+    "/v1/media-results/{id}": {
+      "get": {
+        "tags": [
+          "Media Results"
+        ],
+        "summary": "Get a media result",
+        "description": "Returns a generated image, video, audio or downloadable 3D result. Result URLs have this form and stay valid for 30 days from when the result is first recorded. Use the URL exactly as you received it: its token grants access, and no API key is needed.",
+        "operationId": "getMediaResult",
+        "security": [],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "Result ID, followed by the file extension, for example `.png`, `.mp4`, `.mp3` or `.glb`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "token",
+            "in": "query",
+            "required": true,
+            "description": "Access token from the URL you received.",
+            "schema": {
+              "type": "string",
+              "pattern": "^[a-f0-9]{64}$"
+            }
+          },
+          {
+            "name": "metadata",
+            "in": "query",
+            "required": false,
+            "description": "Return the saving status as JSON instead of the file.",
+            "schema": {
+              "type": "boolean"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The file, or the saving status when `metadata=true`.",
+            "content": {
+              "application/octet-stream": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "status",
+                    "expires_at",
+                    "kind"
+                  ],
+                  "properties": {
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "saving",
+                        "saved",
+                        "failed",
+                        "expired"
+                      ]
+                    },
+                    "expires_at": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "content_type": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
+                    },
+                    "kind": {
+                      "type": "string",
+                      "enum": [
+                        "image",
+                        "video",
+                        "audio",
+                        "3d"
+                      ]
+                    }
+                  }
+                },
+                "example": {
+                  "status": "saved",
+                  "expires_at": "2026-11-06T08:00:00.000Z",
+                  "content_type": "video/mp4",
+                  "kind": "video"
+                }
+              }
+            }
+          },
+          "302": {
+            "description": "Redirect to a short-lived download URL for a saved image, video or audio file. The download URL lasts at most five minutes."
+          },
+          "404": {
+            "description": "`media_not_found`: the token or file extension does not match the result.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "410": {
+            "description": "`media_expired`: the 30-day period has ended, or saving failed more than 24 hours ago.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "502": {
+            "description": "`media_unavailable`: the result is not available now. Retry after the `Retry-After` delay.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "`media_unavailable`: the result is not available now. Retry after the `Retry-After` delay.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "BearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "API Key",
+        "description": "API Key authentication. Create or manage API keys in [Dashboard > API > API Keys](https://tokenlab.sh/dashboard/api?tab=keys)."
+      },
+      "ManagementTokenAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "Management Token",
+        "description": "Management token authentication. Create or manage Management Tokens in [Dashboard > API > Management Tokens](https://tokenlab.sh/dashboard/api?tab=tokens)."
+      },
+      "GeminiApiKey": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "x-goog-api-key",
+        "description": "TokenLab API key for Gemini requests."
+      }
+    },
+    "schemas": {
+      "ChatCompletionRequest": {
+        "type": "object",
+        "required": [
+          "model",
+          "messages"
+        ],
+        "properties": {
+          "model": {
+            "type": "string",
+            "description": "ID of the model to use (e.g., gpt-5.4, claude-sonnet-4-6)",
+            "example": "gpt-4o"
+          },
+          "messages": {
+            "type": "array",
+            "description": "A list of messages comprising the conversation",
+            "items": {
+              "$ref": "#/components/schemas/ChatMessage"
+            },
+            "minItems": 1
+          },
+          "temperature": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 2,
+            "default": 1,
+            "description": "Sampling temperature (0-2)"
+          },
+          "top_p": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "default": 1,
+            "description": "Nucleus sampling probability"
+          },
+          "n": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 128,
+            "default": 1,
+            "description": "Number of completions to generate"
+          },
+          "stream": {
+            "type": "boolean",
+            "default": false,
+            "description": "If true, returns a stream of events"
+          },
+          "stop": {
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "maxItems": 4
+              }
+            ],
+            "description": "Stop sequences"
+          },
+          "max_tokens": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Maximum number of tokens to generate"
+          },
+          "max_completion_tokens": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Maximum completion tokens for newer reasoning-enabled model families"
+          },
+          "presence_penalty": {
+            "type": "number",
+            "minimum": -2,
+            "maximum": 2,
+            "default": 0,
+            "description": "Presence penalty (-2 to 2)"
+          },
+          "frequency_penalty": {
+            "type": "number",
+            "minimum": -2,
+            "maximum": 2,
+            "default": 0,
+            "description": "Frequency penalty (-2 to 2)"
+          },
+          "tools": {
+            "type": "array",
+            "description": "List of tools the model may call",
+            "items": {
+              "$ref": "#/components/schemas/Tool"
+            }
+          },
+          "functions": {
+            "type": "array",
+            "description": "Deprecated function definitions retained by the official Chat Completions contract.",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          },
+          "function_call": {
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "object",
+                "additionalProperties": true
+              }
+            ],
+            "description": "Deprecated function-call selection retained by the official Chat Completions contract."
+          },
+          "tool_choice": {
+            "oneOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "none",
+                  "auto",
+                  "required"
+                ]
+              },
+              {
                 "type": "object",
                 "properties": {
                   "type": {
@@ -8530,7 +9779,45 @@
               "string",
               "null"
             ],
-            "description": "Service tier hint where supported by the model."
+            "description": "TokenLab serves this request at the standard service tier. auto and default are forwarded. Other values, such as flex, priority, fast and ultrafast, are ignored and billed at the standard price."
+          },
+          "anthropic_options": {
+            "type": "object",
+            "description": "Options for Claude models.",
+            "properties": {
+              "prompt_caching": {
+                "type": "boolean",
+                "description": "Set true to cache the start of the prompt on Claude models. TokenLab marks the end of the system prompt and the latest user message as cache points, unless a message already has cache_control."
+              },
+              "prompt_caching_ttl": {
+                "type": "string",
+                "enum": [
+                  "5m",
+                  "1h"
+                ],
+                "description": "Cache lifetime. Defaults to 5m. If the serving route does not support 1h, the 5-minute cache is used and the request is not rejected."
+              }
+            },
+            "additionalProperties": true
+          },
+          "extra": {
+            "type": "object",
+            "description": "Extension options. extra.prompt_caching and extra.prompt_caching_ttl are the same as the anthropic_options fields.",
+            "properties": {
+              "prompt_caching": {
+                "type": "boolean",
+                "description": "Set true to cache the start of the prompt on Claude models. TokenLab marks the end of the system prompt and the latest user message as cache points, unless a message already has cache_control."
+              },
+              "prompt_caching_ttl": {
+                "type": "string",
+                "enum": [
+                  "5m",
+                  "1h"
+                ],
+                "description": "Cache lifetime. Defaults to 5m. If the serving route does not support 1h, the 5-minute cache is used and the request is not rejected."
+              }
+            },
+            "additionalProperties": true
           }
         },
         "additionalProperties": true
@@ -8693,6 +9980,14 @@
           "tool_call_id": {
             "type": "string",
             "description": "ID of the tool call being responded to"
+          },
+          "reasoning_details": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            },
+            "description": "Assistant messages only: the reasoning_details returned in an earlier response, sent back unchanged."
           }
         }
       },
@@ -8849,6 +10144,18 @@
                   "string",
                   "null"
                 ]
+              },
+              "reasoning_content": {
+                "type": "string",
+                "description": "Thinking text, when the model thinks. Some models return only a summary, or no text."
+              },
+              "reasoning_details": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": true
+                },
+                "description": "Thinking blocks with their signatures. To continue a conversation with thinking, send them back unchanged in the assistant message."
               }
             }
           },
@@ -9045,14 +10352,13 @@
       "ImageGenerationRequest": {
         "type": "object",
         "required": [
-          "model",
-          "prompt"
+          "model"
         ],
         "properties": {
           "prompt": {
             "type": "string",
             "maxLength": 4000,
-            "description": "Image description"
+            "description": "Image description. Required for every model that takes a prompt; a tool whose contract lists no prompt (background removal, upscaling, vectorizing) is called without one."
           },
           "model": {
             "type": "string",
@@ -9106,7 +10412,7 @@
           },
           "size": {
             "type": "string",
-            "description": "Image size. Defaults are model-specific. For gpt-image-2, omit this field or use auto for automatic sizing, or send WIDTHxHEIGHT; custom dimensions must both be multiples of 16, longest edge <= 3840px, long/short ratio <= 3:1, and total pixels between 655,360 and 8,294,400."
+            "description": "Image size. Defaults are model-specific. For gpt-image-2, omit this field or use auto for automatic sizing, or send WIDTHxHEIGHT; custom dimensions must both be multiples of 16, longest edge <= 3840px, long/short ratio <= 3:1, and total pixels between 655,360 and 8,294,400. For Google image models with resolution tiers (gemini-3.1-flash-image, gemini-3-pro-image, gemini-3.1-flash-lite-image, gemini-nano-banana-2.1, nano-banana-2, nano-banana-2.1, nano-banana-pro), send an output size from the model's size table or a resolution tier: 1K, 2K, or 4K. TokenLab sends a tier as resolution. A tier that the model does not support, or a tier that is different from resolution, returns 400 invalid_image_size_contract. The recommended form for these models is aspect_ratio with resolution."
           },
           "quality": {
             "type": "string",
@@ -9142,8 +10448,7 @@
               "url",
               "b64_json"
             ],
-            "default": "url",
-            "description": "Response format"
+            "description": "How the images are returned. Omitted: when the model returns image bytes, each image is in data[].b64_json, and also in data[].url when TokenLab stored it; when the model returns a link, each image is in data[].url. url: only data[].url. b64_json: only data[].b64_json. Links are TokenLab media-result URLs that stay valid for 30 days."
           },
           "async": {
             "type": "boolean",
@@ -9208,8 +10513,7 @@
       "ImageGenerationMultipartRequest": {
         "type": "object",
         "required": [
-          "model",
-          "prompt"
+          "model"
         ],
         "properties": {
           "model": {
@@ -9219,7 +10523,7 @@
           "prompt": {
             "type": "string",
             "maxLength": 4000,
-            "description": "Image description"
+            "description": "Image description. Required for every model that takes a prompt; a tool whose contract lists no prompt (background removal, upscaling, vectorizing) is called without one."
           },
           "operation": {
             "type": "string",
@@ -9376,6 +10680,9 @@
           },
           "error_details": {
             "$ref": "#/components/schemas/AsyncTaskErrorDetails"
+          },
+          "media_retention": {
+            "$ref": "#/components/schemas/MediaRetention"
           }
         },
         "required": [
@@ -9386,14 +10693,14 @@
       "AudioSpeechRequest": {
         "type": "object",
         "required": [
+          "model",
           "input"
         ],
         "properties": {
           "model": {
             "type": "string",
-            "default": "tts-1",
-            "description": "TTS model. Query GET /v1/models?recommended_for=tts for the current shortlist.",
-            "example": "tts-1"
+            "description": "TTS model. There is no default model. Query GET /v1/models?recommended_for=tts for the current shortlist.",
+            "example": "grok-tts"
           },
           "input": {
             "type": "string",
@@ -9451,7 +10758,7 @@
               "sse"
             ],
             "default": "audio",
-            "description": "TokenLab delivery format. stream_format=sse is not supported for tts-1 or tts-1-hd."
+            "description": "TokenLab delivery format."
           },
           "speed": {
             "type": "number",
@@ -9482,8 +10789,8 @@
           },
           "model": {
             "type": "string",
-            "description": "Model to use (whisper-1)",
-            "example": "whisper-1"
+            "description": "Transcription model ID. There is no default model.",
+            "example": "whisper-large-v3"
           },
           "language": {
             "type": "string",
@@ -10014,6 +11321,9 @@
           "draft_task_id": {
             "type": "string",
             "description": "Seedance draft task identifier when returned by the adapter."
+          },
+          "media_retention": {
+            "$ref": "#/components/schemas/MediaRetention"
           }
         },
         "required": [
@@ -10143,6 +11453,9 @@
           },
           "fbx_url": {
             "type": "string"
+          },
+          "media_retention": {
+            "$ref": "#/components/schemas/MediaRetention"
           }
         }
       },
@@ -10472,21 +11785,44 @@
                 ]
               },
               "input_per_1m": {
-                "type": "string"
+                "type": "string",
+                "description": "TokenLab Verified price per 1M input tokens. Omitted when the model has no Verified supply (`deliveryAvailability.verified` is false)."
               },
               "output_per_1m": {
-                "type": "string"
+                "type": "string",
+                "description": "TokenLab Verified price per 1M output tokens. Omitted when the model has no Verified supply (`deliveryAvailability.verified` is false)."
               },
               "per_request": {
-                "type": "string"
+                "type": "string",
+                "description": "TokenLab Verified price per request. Omitted when the model has no Verified supply (`deliveryAvailability.verified` is false)."
               },
               "min_price": {
                 "type": "string",
-                "description": "Minimum TokenLab price for a structured pricing model."
+                "description": "Lowest TokenLab Verified price for a model with structured pricing. Omitted when the model has no Verified supply (`deliveryAvailability.verified` is false)."
               },
               "max_price": {
                 "type": "string",
-                "description": "Maximum TokenLab price for a structured pricing model."
+                "description": "Highest TokenLab Verified price for a model with structured pricing. Omitted when the model has no Verified supply (`deliveryAvailability.verified` is false)."
+              },
+              "official_input_per_1m": {
+                "type": "string",
+                "description": "Official price per 1M input tokens. Requests that Official delivers are billed at this price."
+              },
+              "official_output_per_1m": {
+                "type": "string",
+                "description": "Official price per 1M output tokens. Requests that Official delivers are billed at this price."
+              },
+              "official_per_request": {
+                "type": "string",
+                "description": "Official price per request. Requests that Official delivers are billed at this price."
+              },
+              "official_min_price": {
+                "type": "string",
+                "description": "Lowest Official price for a model with structured pricing."
+              },
+              "official_max_price": {
+                "type": "string",
+                "description": "Highest Official price for a model with structured pricing."
               },
               "has_complex_pricing": {
                 "type": "boolean"
@@ -10643,7 +11979,7 @@
               },
               "code": {
                 "type": "string",
-                "description": "Error code"
+                "description": "Error code. Branch on this value, not on `message`. 400 codes include `invalid_request_error`, `missing_required_parameter`, `invalid_value`, `invalid_image_url`, `unsupported_model_capability` and `unpriceable_selection`."
               },
               "param": {
                 "type": "string",
@@ -12144,6 +13480,44 @@
           "model": {
             "type": "string"
           },
+          "deliveryAvailability": {
+            "type": "object",
+            "description": "Current model availability by delivery tier; omitted when the source projection is unavailable.",
+            "properties": {
+              "verified": {
+                "type": "boolean",
+                "description": "Whether this model has eligible TokenLab Verified delivery supply."
+              },
+              "official": {
+                "type": "boolean",
+                "description": "Whether this model has eligible Official delivery supply."
+              },
+              "operations": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "object",
+                  "properties": {
+                    "verified": {
+                      "type": "boolean"
+                    },
+                    "official": {
+                      "type": "boolean"
+                    }
+                  },
+                  "required": [
+                    "verified",
+                    "official"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            },
+            "required": [
+              "verified",
+              "official"
+            ],
+            "additionalProperties": false
+          },
           "pricing_unit": {
             "type": "string"
           },
@@ -12178,8 +13552,12 @@
             "additionalProperties": true
           },
           "scalar_pricing": {
-            "type": "object",
-            "additionalProperties": true
+            "$ref": "#/components/schemas/ScalarPricing",
+            "description": "TokenLab Verified price. The price fields are null when the model has no Verified supply (`deliveryAvailability.verified` is false)."
+          },
+          "official_scalar_pricing": {
+            "$ref": "#/components/schemas/ScalarPricing",
+            "description": "Official price. Requests that Official delivers are billed at this price."
           }
         },
         "additionalProperties": true
@@ -12654,6 +14032,44 @@
           "provider": {
             "type": "string"
           },
+          "deliveryAvailability": {
+            "type": "object",
+            "description": "Current model availability by delivery tier; omitted when the source projection is unavailable.",
+            "properties": {
+              "verified": {
+                "type": "boolean",
+                "description": "Whether this model has eligible TokenLab Verified delivery supply."
+              },
+              "official": {
+                "type": "boolean",
+                "description": "Whether this model has eligible Official delivery supply."
+              },
+              "operations": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "object",
+                  "properties": {
+                    "verified": {
+                      "type": "boolean"
+                    },
+                    "official": {
+                      "type": "boolean"
+                    }
+                  },
+                  "required": [
+                    "verified",
+                    "official"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            },
+            "required": [
+              "verified",
+              "official"
+            ],
+            "additionalProperties": false
+          },
           "is_lock_price": {
             "type": "boolean"
           },
@@ -12673,19 +14089,43 @@
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "TokenLab Verified price per 1M input tokens. Omitted when the model has no Verified supply (`deliveryAvailability.verified` is false)."
           },
           "output_per_1m_tokens": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "TokenLab Verified price per 1M output tokens. Omitted when the model has no Verified supply (`deliveryAvailability.verified` is false)."
           },
           "lock_price_per_request": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "TokenLab Verified price per request. Omitted when the model has no Verified supply (`deliveryAvailability.verified` is false)."
+          },
+          "official_input_per_1m_tokens": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Official price per 1M input tokens. Requests that Official delivers are billed at this price."
+          },
+          "official_output_per_1m_tokens": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Official price per 1M output tokens. Requests that Official delivers are billed at this price."
+          },
+          "official_lock_price_per_request": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Official price per request. Requests that Official delivers are billed at this price."
           },
           "has_complex_pricing": {
             "type": "boolean"
@@ -13195,7 +14635,7 @@
           "model": {
             "type": "string",
             "description": "Model to use for multimodal embeddings",
-            "example": "jina-embeddings-v4"
+            "example": "qwen3-vl-embedding"
           },
           "input": {
             "oneOf": [
@@ -13371,8 +14811,12 @@
             "additionalProperties": false
           },
           "pricing": {
-            "type": "object",
-            "additionalProperties": true
+            "$ref": "#/components/schemas/ScalarPricing",
+            "description": "TokenLab Verified price. The price fields are null when the model has no Verified supply (`deliveryAvailability.verified` is false)."
+          },
+          "official_pricing": {
+            "$ref": "#/components/schemas/ScalarPricing",
+            "description": "Official price. Requests that Official delivers are billed at this price."
           },
           "capabilities": {
             "type": "array",
@@ -13404,12 +14848,21 @@
           "pricing_unit": {
             "type": "string"
           },
-          "cache_pricing": {
+          "cache_pricing": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "additionalProperties": true,
+            "description": "TokenLab Verified prompt-cache prices. Null or omitted when the model has no Verified supply (`deliveryAvailability.verified` is false)."
+          },
+          "official_cache_pricing": {
             "type": [
               "object",
               "null"
             ],
-            "additionalProperties": true
+            "additionalProperties": true,
+            "description": "Official prompt-cache prices. Null or omitted when none are published."
           },
           "has_complex_pricing": {
             "type": "boolean"
@@ -13623,6 +15076,7 @@
         "required": [
           "aliases",
           "pricing",
+          "official_pricing",
           "capabilities",
           "max_input_tokens",
           "max_output_tokens",
@@ -13684,8 +15138,12 @@
             "additionalProperties": false
           },
           "pricing": {
-            "type": "object",
-            "additionalProperties": true
+            "$ref": "#/components/schemas/ScalarPricing",
+            "description": "TokenLab Verified price. The price fields are null when the model has no Verified supply (`deliveryAvailability.verified` is false)."
+          },
+          "official_pricing": {
+            "$ref": "#/components/schemas/ScalarPricing",
+            "description": "Official price. Requests that Official delivers are billed at this price."
           },
           "capabilities": {
             "type": "array",
@@ -13722,7 +15180,16 @@
               "object",
               "null"
             ],
-            "additionalProperties": true
+            "additionalProperties": true,
+            "description": "TokenLab Verified prompt-cache prices. Null or omitted when the model has no Verified supply (`deliveryAvailability.verified` is false)."
+          },
+          "official_cache_pricing": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "additionalProperties": true,
+            "description": "Official prompt-cache prices. Null or omitted when none are published."
           },
           "has_complex_pricing": {
             "type": "boolean"
@@ -15553,6 +17020,18 @@
                   "null"
                 ]
               },
+              "webSearch": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "groundedPrompt": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
               "structured": {
                 "anyOf": [
                   {
@@ -16269,6 +17748,262 @@
             "additionalProperties": false
           }
         ]
+      },
+      "GeminiFileResource": {
+        "type": "object",
+        "description": "A Gemini file in the current Workspace. Fields are returned when available.",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "File resource name such as files/{fileId}."
+          },
+          "displayName": {
+            "type": "string",
+            "description": "Human-readable file name."
+          },
+          "mimeType": {
+            "type": "string",
+            "description": "Media MIME type."
+          },
+          "sizeBytes": {
+            "type": "string",
+            "description": "File byte size as a decimal string."
+          },
+          "uri": {
+            "type": "string",
+            "description": "File URI to use in Gemini content parts."
+          },
+          "state": {
+            "type": "string",
+            "description": "Processing state reported by the service. Wait until the file is ready before generation."
+          },
+          "createTime": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updateTime": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "expirationTime": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "error": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        },
+        "additionalProperties": true
+      },
+      "GeminiFileCreateRequest": {
+        "type": "object",
+        "description": "Gemini file metadata request. Supported fields and values are validated by the service. File bytes are uploaded through /upload/v1beta/files.",
+        "properties": {
+          "file": {
+            "$ref": "#/components/schemas/GeminiFileResource"
+          }
+        },
+        "additionalProperties": true
+      },
+      "GeminiFileRegisterRequest": {
+        "type": "object",
+        "description": "Gemini file registration request. Use only sources and fields accepted by the service; registration does not upload local bytes.",
+        "additionalProperties": true
+      },
+      "GeminiCachedContentRequest": {
+        "type": "object",
+        "required": [
+          "model"
+        ],
+        "properties": {
+          "model": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Current TokenLab model ID that supports Gemini cached content."
+          },
+          "displayName": {
+            "type": "string",
+            "description": "Human-readable cache name."
+          },
+          "ttl": {
+            "type": "string",
+            "description": "Positive duration such as 3600s. Supported lifetime is validated by the service."
+          },
+          "expireTime": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Requested expiration time; use ttl or expireTime as supported by the service."
+          },
+          "contents": {
+            "$ref": "#/components/schemas/GeminiRequest/properties/contents"
+          },
+          "systemInstruction": {
+            "$ref": "#/components/schemas/GeminiRequest/properties/systemInstruction"
+          },
+          "tools": {
+            "$ref": "#/components/schemas/GeminiRequest/properties/tools"
+          },
+          "toolConfig": {
+            "$ref": "#/components/schemas/GeminiRequest/properties/toolConfig"
+          }
+        },
+        "additionalProperties": true
+      },
+      "GeminiCachedContentResource": {
+        "type": "object",
+        "description": "Cached content belonging to the current Workspace. Use the returned name as cachedContent in Gemini generation.",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Resource name such as cachedContents/{cacheId}."
+          },
+          "model": {
+            "type": "string",
+            "description": "TokenLab model ID associated with the cached content."
+          },
+          "displayName": {
+            "type": "string",
+            "description": "Human-readable cache name."
+          },
+          "createTime": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updateTime": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "expireTime": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "usageMetadata": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        },
+        "additionalProperties": true
+      },
+      "GeminiCachedContentUpdateRequest": {
+        "type": "object",
+        "description": "Update cached content lifetime using the fields accepted by the service.",
+        "properties": {
+          "ttl": {
+            "type": "string",
+            "description": "Positive duration such as 3600s."
+          },
+          "expireTime": {
+            "type": "string",
+            "format": "date-time"
+          }
+        },
+        "additionalProperties": true
+      },
+      "MediaRetention": {
+        "type": "object",
+        "description": "Saving status of the media results in this response. Present when the status is known within the response time limit; when it is absent, the media URLs still work.",
+        "required": [
+          "days",
+          "items"
+        ],
+        "properties": {
+          "days": {
+            "type": "integer",
+            "description": "Days a media-result URL stays valid after the result is first recorded.",
+            "example": 30
+          },
+          "items": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "url",
+                "kind",
+                "status",
+                "expires_at"
+              ],
+              "properties": {
+                "url": {
+                  "type": "string",
+                  "format": "uri"
+                },
+                "kind": {
+                  "type": "string",
+                  "enum": [
+                    "image",
+                    "video",
+                    "audio",
+                    "3d"
+                  ]
+                },
+                "content_type": {
+                  "type": "string"
+                },
+                "status": {
+                  "type": "string",
+                  "enum": [
+                    "saving",
+                    "saved",
+                    "failed",
+                    "expired"
+                  ]
+                },
+                "expires_at": {
+                  "type": "string",
+                  "format": "date-time"
+                }
+              },
+              "additionalProperties": false
+            }
+          }
+        },
+        "additionalProperties": false
+      },
+      "ScalarPricing": {
+        "type": "object",
+        "description": "One scalar price layer in USD. Token prices are per 1M tokens.",
+        "properties": {
+          "input_per_1m": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Price per 1M input tokens. Null for per-request pricing."
+          },
+          "output_per_1m": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Price per 1M output tokens. Null for per-request pricing."
+          },
+          "per_request": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Price per request. Null for per-token pricing."
+          },
+          "is_lock_price": {
+            "type": "boolean",
+            "description": "Whether the model is priced per request."
+          },
+          "currency": {
+            "type": "string",
+            "enum": [
+              "USD"
+            ]
+          }
+        },
+        "required": [
+          "input_per_1m",
+          "output_per_1m",
+          "per_request",
+          "is_lock_price",
+          "currency"
+        ],
+        "additionalProperties": true
       }
     },
     "responses": {
@@ -16279,18 +18014,77 @@
             "schema": {
               "$ref": "#/components/schemas/ValidationError"
             },
-            "example": {
-              "error": {
-                "message": "model: Model is required",
-                "type": "invalid_request_error",
-                "param": "model"
+            "examples": {
+              "validation": {
+                "summary": "Invalid field",
+                "value": {
+                  "error": {
+                    "message": "model: Model is required",
+                    "type": "invalid_request_error",
+                    "param": "model"
+                  },
+                  "validation_errors": [
+                    {
+                      "field": "model",
+                      "message": "Model is required"
+                    }
+                  ]
+                }
+              },
+              "missingRequiredParameter": {
+                "summary": "Required field is missing",
+                "value": {
+                  "error": {
+                    "message": "model is required",
+                    "type": "invalid_request_error",
+                    "code": "missing_required_parameter",
+                    "param": "model"
+                  }
+                }
               },
-              "validation_errors": [
-                {
-                  "field": "model",
-                  "message": "Model is required"
+              "invalidValue": {
+                "summary": "Value the model does not accept",
+                "value": {
+                  "error": {
+                    "message": "reasoning_effort \"max\" is not supported for this model. Supported values: low, medium, high.",
+                    "type": "invalid_request_error",
+                    "code": "invalid_value",
+                    "param": "reasoning_effort"
+                  }
                 }
-              ]
+              },
+              "invalidImageUrl": {
+                "summary": "Image URL cannot be used",
+                "value": {
+                  "error": {
+                    "message": "image_url could not be downloaded from the image URL: the connection to the image host timed out. The URL must be publicly reachable from the internet (hosts that serve only mainland China networks can be unreachable). Use a different image URL or send the image as a base64 data URL.",
+                    "type": "invalid_request_error",
+                    "code": "invalid_image_url",
+                    "param": "image_url"
+                  }
+                }
+              },
+              "unsupportedModelCapability": {
+                "summary": "No route of the Delivery tier supports a parameter",
+                "value": {
+                  "error": {
+                    "message": "Model gpt-4.1-mini cannot serve this request for operation 'chat' on the routes this request can use: web_search_options is not supported. Change these parameters, or choose another model or Delivery tier.",
+                    "type": "invalid_request_error",
+                    "code": "unsupported_model_capability"
+                  }
+                }
+              },
+              "unpriceableSelection": {
+                "summary": "Video request cannot be priced",
+                "value": {
+                  "error": {
+                    "message": "This image-to-video request cannot be priced without resolution. Set resolution explicitly if the operation accepts it.",
+                    "type": "invalid_request_error",
+                    "code": "unpriceable_selection",
+                    "param": "resolution"
+                  }
+                }
+              }
             }
           }
         }
@@ -16490,10 +18284,32 @@
                     "request_id": "req_01JEXAMPLE"
                   }
                 }
+              },
+              "pricingUnavailable": {
+                "summary": "TokenLab cannot price this request",
+                "value": {
+                  "error": {
+                    "message": "TokenLab cannot serve model gpt-image-2 with operation 'image-edit' right now because it cannot price this request on the routes this request can use. The request was not charged.",
+                    "type": "all_channels_failed",
+                    "code": "model_pricing_unavailable",
+                    "retryable": false,
+                    "request_id": "req_01JEXAMPLE"
+                  }
+                }
               }
             }
           }
         }
+      },
+      "GeminiResourceError": {
+        "description": "Gemini-format resource error",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/GeminiErrorResponse"
+            }
+          }
+        }
       }
     },
     "parameters": {