@tokenlabai/mcp-server 0.6.24 → 0.6.26

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": [
@@ -89,7 +93,7 @@
           "Chat"
         ],
         "summary": "Create chat completion",
-        "description": "Creates a model response from a Chat Completions request. Chat-native upstreams receive the request shape unchanged apart from routing and authentication fields; unknown fields are forwarded on a best-effort basis. Portable Chat requests may be compiled one-way to another protocol when a compatible physical endpoint is selected.",
+        "description": "Creates a model response from a Chat Completions request. Supported request formats are listed in each model’s details. Unknown fields are accepted on a best-effort basis; model-specific support is not guaranteed.",
         "operationId": "createChatCompletion",
         "requestBody": {
           "required": true,
@@ -528,6 +532,9 @@
                           "additionalProperties": true
                         }
                       ]
+                    },
+                    "error_details": {
+                      "$ref": "#/components/schemas/AsyncTaskErrorDetails"
                     }
                   }
                 }
@@ -1448,7 +1455,7 @@
             }
           },
           "400": {
-            "description": "Task type, provider, or model does not support cancellation",
+            "description": "This task does not support cancellation",
             "content": {
               "application/json": {
                 "schema": {
@@ -2000,7 +2007,7 @@
           "Anthropic"
         ],
         "summary": "Delete message batch (Anthropic-compatible)",
-        "description": "Deletes a native Anthropic Message Batch when the provider supports deletion.",
+        "description": "Deletes an Anthropic Message Batch when deletion is supported for that batch.",
         "operationId": "deleteAnthropicMessageBatch",
         "parameters": [
           {
@@ -2109,7 +2116,7 @@
           "Anthropic"
         ],
         "summary": "Cancel message batch (Anthropic-compatible)",
-        "description": "Cancels a native Anthropic Message Batch when the provider still allows cancellation.",
+        "description": "Cancels an Anthropic Message Batch when cancellation is still available for that batch.",
         "operationId": "cancelAnthropicMessageBatch",
         "parameters": [
           {
@@ -2160,7 +2167,7 @@
           "Gemini"
         ],
         "summary": "Generate content (Gemini-compatible)",
-        "description": "Generates content using the native Gemini GenerateContent shape. This route is exposed only when the model details advertise Gemini requests and a same-protocol route is currently available. ProtoJSON lowerCamelCase and original proto snake_case field names are preserved. Unknown fields are forwarded best-effort and support is determined by the selected provider.\n\n**Authentication:** Use `?key=` query parameter, `x-goog-api-key` header, or `Authorization: Bearer` header.",
+        "description": "Generates content using the Gemini GenerateContent request shape. The model details must advertise Gemini requests and the model must be available. ProtoJSON lowerCamelCase and original proto snake_case field names are preserved. Unknown fields are accepted on a best-effort basis; model-specific support is not guaranteed.\n\n**Authentication:** Use `?key=` query parameter, `x-goog-api-key` header, or `Authorization: Bearer` header.",
         "operationId": "geminiGenerateContent",
         "parameters": [
           {
@@ -2642,7 +2649,7 @@
           "Responses"
         ],
         "summary": "Create response (OpenAI Responses API)",
-        "description": "Creates a response using the native OpenAI Responses API shape. The model details must advertise the Responses request format and a same-protocol route must be currently available; model names and providers do not imply availability. Unknown request fields are forwarded on a best-effort basis and remain subject to the selected provider's support.",
+        "description": "Creates a response using the OpenAI Responses API request shape. The model details must advertise the Responses request format and the model must be available. Unknown fields are accepted on a best-effort basis; model-specific support is not guaranteed.",
         "operationId": "createResponse",
         "requestBody": {
           "required": true,
@@ -2710,7 +2717,7 @@
                     "properties": {
                       "include_obfuscation": {
                         "type": "boolean",
-                        "description": "When true, request obfuscated tokens in Responses stream events from compatible upstreams."
+                        "description": "When true, request obfuscated tokens in Responses stream events where supported."
                       }
                     },
                     "additionalProperties": true,
@@ -2728,7 +2735,7 @@
                       "string",
                       "null"
                     ],
-                    "description": "Service tier hint for compatible providers."
+                    "description": "Service tier hint where supported by the model."
                   },
                   "truncation": {
                     "type": "string",
@@ -3271,7 +3278,7 @@
                   },
                   "seed": {
                     "type": "integer",
-                    "description": "Seed for deterministic-compatible providers."
+                    "description": "Seed for repeatable generation where supported by the model."
                   },
                   "user": {
                     "type": "string",
@@ -3666,7 +3673,7 @@
           "Management"
         ],
         "summary": "Get API key usage",
-        "description": "Returns paginated key-level usage details without exposing provider-specific execution details.",
+        "description": "Returns paginated usage details for this API key.",
         "operationId": "getManagementApiKeyUsage",
         "security": [
           {
@@ -3796,7 +3803,7 @@
           "Management"
         ],
         "summary": "Get API key billing",
-        "description": "Returns aggregated key-level billing breakdowns without exposing provider-specific execution details.",
+        "description": "Returns aggregated billing breakdowns for this API key.",
         "operationId": "getManagementApiKeyBilling",
         "security": [
           {
@@ -5665,6 +5672,12 @@
                     "cost": {
                       "type": "object",
                       "additionalProperties": true
+                    },
+                    "error": {
+                      "$ref": "#/components/schemas/AsyncTaskError"
+                    },
+                    "error_details": {
+                      "$ref": "#/components/schemas/AsyncTaskErrorDetails"
                     }
                   },
                   "additionalProperties": true
@@ -5762,7 +5775,10 @@
                       "additionalProperties": true
                     },
                     "error": {
-                      "type": "string"
+                      "$ref": "#/components/schemas/AsyncTaskError"
+                    },
+                    "error_details": {
+                      "$ref": "#/components/schemas/AsyncTaskErrorDetails"
                     }
                   },
                   "additionalProperties": true
@@ -8259,195 +8275,1322 @@
           }
         ]
       }
-    }
-  },
-  "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)"
-          },
-          "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"
+            "description": "API key alternative to Bearer or x-goog-api-key."
           },
-          "stop": {
-            "oneOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "array",
-                "items": {
-                  "type": "string"
-                },
-                "maxItems": 4
+          {
+            "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": "Stop sequences"
+            }
           },
-          "max_tokens": {
-            "type": "integer",
-            "minimum": 1,
-            "description": "Maximum number of tokens to generate"
+          "400": {
+            "$ref": "#/components/responses/GeminiResourceError"
           },
-          "max_completion_tokens": {
-            "type": "integer",
-            "minimum": 1,
-            "description": "Maximum completion tokens for newer reasoning-enabled model families"
+          "401": {
+            "$ref": "#/components/responses/GeminiResourceError"
           },
-          "presence_penalty": {
-            "type": "number",
-            "minimum": -2,
-            "maximum": 2,
-            "default": 0,
-            "description": "Presence penalty (-2 to 2)"
+          "403": {
+            "$ref": "#/components/responses/GeminiResourceError"
           },
-          "frequency_penalty": {
-            "type": "number",
-            "minimum": -2,
-            "maximum": 2,
-            "default": 0,
-            "description": "Frequency penalty (-2 to 2)"
+          "404": {
+            "$ref": "#/components/responses/GeminiResourceError"
           },
-          "tools": {
-            "type": "array",
-            "description": "List of tools the model may call",
-            "items": {
-              "$ref": "#/components/schemas/Tool"
-            }
+          "409": {
+            "$ref": "#/components/responses/GeminiResourceError"
           },
-          "functions": {
-            "type": "array",
-            "description": "Deprecated function definitions retained by the official Chat Completions contract.",
-            "items": {
-              "type": "object",
-              "additionalProperties": true
-            }
+          "429": {
+            "$ref": "#/components/responses/GeminiResourceError"
           },
-          "function_call": {
-            "oneOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "object",
-                "additionalProperties": true
-              }
-            ],
-            "description": "Deprecated function-call selection retained by the official Chat Completions contract."
+          "502": {
+            "$ref": "#/components/responses/GeminiResourceError"
           },
-          "tool_choice": {
-            "oneOf": [
-              {
-                "type": "string",
-                "enum": [
-                  "none",
-                  "auto",
-                  "required"
-                ]
-              },
-              {
-                "type": "object",
-                "properties": {
-                  "type": {
-                    "type": "string",
-                    "enum": [
-                      "function"
-                    ]
-                  },
-                  "function": {
-                    "type": "object",
-                    "properties": {
-                      "name": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "name"
-                    ]
-                  }
-                },
-                "required": [
-                  "type",
-                  "function"
-                ]
+          "503": {
+            "$ref": "#/components/responses/GeminiResourceError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GeminiFileRegisterRequest"
               }
-            ],
-            "description": "Controls which function is called"
+            }
+          }
+        }
+      }
+    },
+    "/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": []
           },
-          "response_format": {
-            "type": "object",
-            "properties": {
-              "type": {
-                "type": "string",
-                "enum": [
-                  "text",
-                  "json_object"
-                ]
-              }
+          {
+            "GeminiApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "key",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
             },
-            "description": "Response format specification"
-          },
-          "seed": {
-            "type": "integer",
-            "description": "Seed for deterministic generation"
+            "description": "API key alternative to Bearer or x-goog-api-key."
           },
-          "user": {
-            "type": "string",
-            "description": "End-user identifier for abuse detection"
+          {
+            "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
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "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"
+          }
+        }
+      }
+    }
+  },
+  "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": {
+                    "type": "string",
+                    "enum": [
+                      "function"
+                    ]
+                  },
+                  "function": {
+                    "type": "object",
+                    "properties": {
+                      "name": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "name"
+                    ]
+                  }
+                },
+                "required": [
+                  "type",
+                  "function"
+                ]
+              }
+            ],
+            "description": "Controls which function is called"
+          },
+          "response_format": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "text",
+                  "json_object"
+                ]
+              }
+            },
+            "description": "Response format specification"
+          },
+          "seed": {
+            "type": "integer",
+            "description": "Seed for deterministic generation"
+          },
+          "user": {
+            "type": "string",
+            "description": "End-user identifier for abuse detection"
           },
           "stream_options": {
             "type": "object",
@@ -8511,14 +9654,14 @@
           "prediction": {
             "type": "object",
             "additionalProperties": true,
-            "description": "Prediction hints for providers that support draft or speculative decoding."
+            "description": "Prediction hints for models that support draft or speculative decoding."
           },
           "service_tier": {
             "type": [
               "string",
               "null"
             ],
-            "description": "Service tier hint for compatible providers."
+            "description": "Service tier hint where supported by the model."
           }
         },
         "additionalProperties": true
@@ -9098,7 +10241,7 @@
           },
           "quality": {
             "type": "string",
-            "description": "Image quality. Defaults and accepted values are model-specific. For gpt-image-2, omit this field or use auto for automatic quality, or send low, medium, or high. Other image families may use provider-specific values."
+            "description": "Image quality. Defaults and accepted values are model-specific. For gpt-image-2, omit this field or use auto for automatic quality, or send low, medium, or high. Other models may accept different values; check the model details."
           },
           "style": {
             "type": "string",
@@ -9112,6 +10255,10 @@
             "type": "boolean",
             "description": "Ask compatible models to expand or enhance the prompt."
           },
+          "prompt_extend": {
+            "type": "boolean",
+            "description": "For z-image-turbo, enable prompt expansion. Defaults to false. Enabling it uses the model's prompt-expansion price."
+          },
           "negative_prompt": {
             "type": "string",
             "description": "Content to avoid for compatible image models."
@@ -9242,6 +10389,10 @@
           "expand_prompt": {
             "type": "boolean"
           },
+          "prompt_extend": {
+            "type": "boolean",
+            "description": "For z-image-turbo, enable prompt expansion. Defaults to false. Enabling it uses the model's prompt-expansion price."
+          },
           "negative_prompt": {
             "type": "string"
           },
@@ -9338,6 +10489,24 @@
                 }
               }
             }
+          },
+          "task_id": {
+            "type": "string",
+            "description": "Task ID when the request runs as a task."
+          },
+          "status": {
+            "type": "string",
+            "description": "Task status when the request runs as a task."
+          },
+          "poll_url": {
+            "type": "string",
+            "description": "URL to poll for the task result."
+          },
+          "error": {
+            "$ref": "#/components/schemas/AsyncTaskError"
+          },
+          "error_details": {
+            "$ref": "#/components/schemas/AsyncTaskErrorDetails"
           }
         },
         "required": [
@@ -9380,11 +10549,11 @@
                 "additionalProperties": false
               }
             ],
-            "description": "Voice selector for OpenAI-compatible, Gemini, xAI, and MiniMax-compatible routes. Some MiniMax routes also accept voice_id."
+            "description": "Voice selector for OpenAI-compatible, Gemini, xAI, and MiniMax-compatible speech models. Some MiniMax models also accept voice_id."
           },
           "voice_id": {
             "type": "string",
-            "description": "Provider-native voice selector for MiniMax-compatible speech models."
+            "description": "Voice selector for MiniMax-compatible speech models."
           },
           "instructions": {
             "type": "string",
@@ -9398,7 +10567,7 @@
           },
           "language_code": {
             "type": "string",
-            "description": "Optional language code for Gemini, xAI, and compatible TTS routes.",
+            "description": "Optional language code for Gemini, xAI, and compatible TTS models.",
             "example": "en-US"
           },
           "response_format": {
@@ -9425,7 +10594,7 @@
             "type": "number",
             "minimum": 0,
             "maximum": 2,
-            "description": "Sampling temperature for Gemini-compatible TTS routes."
+            "description": "Sampling temperature for Gemini-compatible TTS models."
           }
         },
         "additionalProperties": false
@@ -9619,7 +10788,7 @@
           },
           "output_audio": {
             "type": "boolean",
-            "description": "Canonical model-dependent audio output toggle. Veo 3 and Seedance requests default to true when omitted. Kling 3.0 Video accepts this selector for non-element-reference requests and maps it to the compatible sound control; omitted Kling requests default to silent output. Do not combine output_audio=true with kling_elements. The aliases outputAudio and generate_audio are accepted for compatibility and must match when provided together."
+            "description": "Audio-output selector for operations that declare it. Omission follows the model default; `false` requests silent output only when allowed. See the audio behavior above and the selected model detail."
           },
           "fps": {
             "type": "integer",
@@ -9742,7 +10911,7 @@
           "audio_url": {
             "type": "string",
             "format": "uri",
-            "description": "Publicly reachable audio URL for model-specific audio-conditioned video flows."
+            "description": "Public audio URL for an audio-driven or reference-audio operation supported by the selected model."
           },
           "task_id": {
             "type": "string",
@@ -9777,7 +10946,7 @@
           },
           "video_urls": {
             "type": "array",
-            "description": "Compatibility array for video-conditioned flows when multiple input videos are supported by the routed model family. Seedance 2.5 accepts up to 10 aggregate video inputs; other video models retain the shared limit of 3 references unless the model details specify a lower limit.",
+            "description": "Compatibility array for video-conditioned flows when multiple input videos are supported by the selected model. Seedance 2.5 accepts up to 10 aggregate video inputs; other video models retain the shared limit of 3 references unless the model details specify a lower limit.",
             "minItems": 1,
             "maxItems": 10,
             "items": {
@@ -9787,7 +10956,7 @@
           },
           "audio_urls": {
             "type": "array",
-            "description": "Compatibility array for audio-conditioned flows when multiple audio references are supported by the routed model family. Seedance 2.5 accepts up to 10 aggregate audio inputs and permits pure-audio reference requests without a prompt; other video models retain the shared limit of 3 references unless the model details specify a lower limit.",
+            "description": "Compatibility array for audio-conditioned flows when multiple audio references are supported by the selected model. Seedance 2.5 accepts up to 10 aggregate audio inputs and permits pure-audio reference requests without a prompt; other video models retain the shared limit of 3 references unless the model details specify a lower limit.",
             "minItems": 1,
             "maxItems": 10,
             "items": {
@@ -9860,11 +11029,27 @@
           "draft": {
             "type": "boolean",
             "default": false,
-            "description": "Seedance 1.5 Pro draft workflow flag. Only supported by draft-capable Seedance routes; draft=true creates a low-cost draft task."
+            "description": "Seedance 1.5 Pro draft workflow flag. Only supported by Seedance models supporting drafts; draft=true creates a low-cost draft task."
           },
           "draft_task_id": {
             "type": "string",
             "description": "Seedance 1.5 Pro draft promotion task ID. Provide this instead of draft=true to create the final video from a previous draft task."
+          },
+          "audio": {
+            "type": "boolean",
+            "description": "Audio-output selector for operations that declare it. Omission follows the model default; `false` requests silent output only when allowed. See the audio behavior above and the selected model detail."
+          },
+          "bgm": {
+            "type": "boolean",
+            "description": "Optional audio control. Accepted only when declared by the selected model and operation; availability may differ by operation."
+          },
+          "audio_type": {
+            "type": "string",
+            "description": "Optional audio control. Accepted only when declared by the selected model and operation; availability may differ by operation."
+          },
+          "voice_id": {
+            "type": "string",
+            "description": "Optional audio control. Accepted only when declared by the selected model and operation; availability may differ by operation."
           }
         }
       },
@@ -9910,15 +11095,10 @@
             }
           },
           "error": {
-            "type": "object",
-            "properties": {
-              "code": {
-                "type": "string"
-              },
-              "message": {
-                "type": "string"
-              }
-            }
+            "$ref": "#/components/schemas/AsyncTaskError"
+          },
+          "error_details": {
+            "$ref": "#/components/schemas/AsyncTaskErrorDetails"
           },
           "task_id": {
             "type": "string",
@@ -10037,6 +11217,9 @@
               }
             ]
           },
+          "error_details": {
+            "$ref": "#/components/schemas/AsyncTaskErrorDetails"
+          },
           "task_id": {
             "type": "string"
           },
@@ -10918,7 +12101,7 @@
           },
           "service_tier": {
             "type": "string",
-            "description": "Service tier hint for compatible providers."
+            "description": "Service tier hint where supported by the model."
           }
         }
       },
@@ -11244,7 +12427,7 @@
               },
               "responseModalities": {
                 "type": "array",
-                "description": "Requested output modalities for compatible native Gemini routes.",
+                "description": "Requested output modalities for supported Gemini models.",
                 "items": {
                   "type": "string"
                 }
@@ -12188,7 +13371,7 @@
             "example": 1741425600
           }
         },
-        "description": "File metadata. Batch files include status; image/reference files may omit status depending on the upstream file provider."
+        "description": "File metadata. Batch files include status; image/reference files may omit status depending on the file purpose."
       },
       "FileListResponse": {
         "type": "object",
@@ -13006,7 +14189,7 @@
       },
       "AnthropicMessageBatch": {
         "type": "object",
-        "description": "Anthropic-compatible message batch object relayed from the provider.",
+        "description": "Anthropic-compatible message batch object.",
         "required": [
           "id",
           "type",
@@ -13039,7 +14222,7 @@
           "request_counts": {
             "type": "object",
             "additionalProperties": true,
-            "description": "Upstream request count summary for the batch"
+            "description": "Request count summary for the batch"
           },
           "ended_at": {
             "type": [
@@ -13075,7 +14258,7 @@
               "string",
               "null"
             ],
-            "description": "Upstream results URL, when available"
+            "description": "Results URL, when available"
           }
         },
         "additionalProperties": true
@@ -13272,7 +14455,7 @@
       },
       "ModelListTokenLabExtension": {
         "type": "object",
-        "description": "TokenLab discovery fields for the list route. Detail-only metadata such as capability flags, pricing provenance, full model details, and empty recommendation snapshots are omitted.",
+        "description": "TokenLab model discovery fields. Use the model details endpoint for the full supported request and pricing contract.",
         "properties": {
           "aliases": {
             "type": "array",
@@ -13396,14 +14579,14 @@
                   "deprecated",
                   "retired"
                 ],
-                "description": "Provider lifecycle stage for public discovery and display."
+                "description": "Model lifecycle stage for public discovery and display."
               },
               "reason": {
                 "type": [
                   "string",
                   "null"
                 ],
-                "description": "Short lifecycle reason or provider note."
+                "description": "Short model lifecycle explanation."
               },
               "replacement_model": {
                 "type": [
@@ -13718,14 +14901,14 @@
                   "deprecated",
                   "retired"
                 ],
-                "description": "Provider lifecycle stage for public discovery and display."
+                "description": "Model lifecycle stage for public discovery and display."
               },
               "reason": {
                 "type": [
                   "string",
                   "null"
                 ],
-                "description": "Short lifecycle reason or provider note."
+                "description": "Short model lifecycle explanation."
               },
               "replacement_model": {
                 "type": [
@@ -14253,6 +15436,61 @@
             "items": {
               "type": "string"
             }
+          },
+          "parameter_options": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "array",
+              "items": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              }
+            }
+          },
+          "parameter_value_constraints": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "properties": {
+                "enum": {
+                  "type": "array",
+                  "items": {
+                    "type": [
+                      "string",
+                      "boolean"
+                    ]
+                  }
+                },
+                "enumCaseInsensitive": {
+                  "type": "boolean"
+                },
+                "maxItems": {
+                  "type": "integer"
+                },
+                "maxInteger": {
+                  "type": "integer"
+                },
+                "when": {
+                  "type": "object",
+                  "properties": {
+                    "parameter": {
+                      "type": "string"
+                    },
+                    "equals": {
+                      "type": [
+                        "string",
+                        "boolean"
+                      ]
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              },
+              "additionalProperties": false
+            }
           }
         },
         "additionalProperties": false
@@ -14675,7 +15913,7 @@
             "minimum": -1,
             "maximum": 4294967295,
             "default": -1,
-            "description": "Random seed. -1 lets the model choose a seed. Forwarded on a best-effort basis for routes that accept it."
+            "description": "Random seed. -1 lets the model choose a seed. Accepted on a best-effort basis where supported by the model."
           },
           "execution_expires_after": {
             "type": "integer",
@@ -15859,126 +17097,460 @@
               "additionalProperties": false
             }
           },
-          "pagination": {
+          "pagination": {
+            "type": "object",
+            "required": [
+              "page",
+              "limit",
+              "total",
+              "total_pages"
+            ],
+            "properties": {
+              "page": {
+                "type": "integer"
+              },
+              "limit": {
+                "type": "integer"
+              },
+              "total": {
+                "type": "integer"
+              },
+              "total_pages": {
+                "type": "integer"
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "additionalProperties": false
+      },
+      "DeletedWebhookEndpoint": {
+        "type": "object",
+        "required": [
+          "id",
+          "object",
+          "deleted"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "object": {
+            "type": "string",
+            "enum": [
+              "webhook_endpoint"
+            ]
+          },
+          "deleted": {
+            "type": "boolean",
+            "const": true
+          }
+        },
+        "additionalProperties": false
+      },
+      "CreateWebhookEndpointRequest": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "url",
+          "events"
+        ],
+        "properties": {
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "Public HTTPS receiver URL. Credentials, query strings, fragments, private or reserved network targets and redirects are rejected."
+          },
+          "events": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 10,
+            "items": {
+              "type": "string",
+              "enum": [
+                "task.completed",
+                "task.failed",
+                "task.timeout"
+              ]
+            },
+            "description": "Supported event subscriptions; duplicates are removed."
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 200
+          }
+        }
+      },
+      "UpdateWebhookEndpointRequest": {
+        "type": "object",
+        "additionalProperties": false,
+        "minProperties": 1,
+        "properties": {
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "Public HTTPS receiver URL. Credentials, query strings, fragments, private or reserved network targets and redirects are rejected."
+          },
+          "events": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 10,
+            "items": {
+              "type": "string",
+              "enum": [
+                "task.completed",
+                "task.failed",
+                "task.timeout"
+              ]
+            },
+            "description": "Supported event subscriptions; duplicates are removed."
+          },
+          "description": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "maxLength": 200
+          },
+          "is_active": {
+            "type": "boolean",
+            "description": "Resume or pause delivery. Resuming resets the consecutive failure count."
+          }
+        }
+      },
+      "TaskTimeoutWebhook": {
+        "type": "object",
+        "required": [
+          "id",
+          "type",
+          "created",
+          "data"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Stable event ID for deduplication at the receiving endpoint."
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "task.timeout"
+            ]
+          },
+          "created": {
+            "type": "integer",
+            "description": "Event creation time in Unix seconds."
+          },
+          "data": {
+            "type": "object",
+            "required": [
+              "taskType",
+              "taskId",
+              "expectedTimeoutMs",
+              "actualWaitMs"
+            ],
+            "properties": {
+              "taskType": {
+                "type": "string",
+                "enum": [
+                  "video",
+                  "music",
+                  "3d",
+                  "world",
+                  "image",
+                  "audio"
+                ]
+              },
+              "taskId": {
+                "type": "string"
+              },
+              "expectedTimeoutMs": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Expected timeout threshold in milliseconds."
+              },
+              "actualWaitMs": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Actual elapsed wait in milliseconds."
+              },
+              "refundIssued": {
+                "type": "boolean",
+                "description": "True if the refund succeeded or had already been issued. False does not rule out a later refund."
+              },
+              "resolutionSource": {
+                "type": "string",
+                "enum": [
+                  "callback",
+                  "status_query",
+                  "background_poller",
+                  "timeout_detector",
+                  "create_response"
+                ]
+              },
+              "refundOutcome": {
+                "type": "string",
+                "enum": [
+                  "success",
+                  "already_refunded",
+                  "not_applicable",
+                  "failed_persisted",
+                  "failed_unrecoverable"
+                ],
+                "description": "Refund processing result at event creation."
+              }
+            },
+            "description": "Timeout event data. This event does not contain durationMs."
+          }
+        }
+      },
+      "AsyncTaskUpstreamError": {
+        "type": "object",
+        "description": "The upstream service's own error, present only for a task that ran on an Official route. Its `code` values are defined by the upstream service and may change; branch on `error_details.code` and `error_details.type`.",
+        "required": [
+          "message"
+        ],
+        "properties": {
+          "source": {
+            "type": "string",
+            "description": "Upstream service name, when known."
+          },
+          "code": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "param": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      },
+      "AsyncTaskErrorDetails": {
+        "type": "object",
+        "description": "Why a task failed. A status read returns HTTP 200 even for a failed task; `status` here is the status of the failure itself.",
+        "required": [
+          "status",
+          "message",
+          "type",
+          "code",
+          "retryable"
+        ],
+        "properties": {
+          "projection_version": {
+            "type": "integer",
+            "description": "`2` means `message` is the final reason for the failure."
+          },
+          "status": {
+            "type": "integer",
+            "minimum": 400,
+            "maximum": 599
+          },
+          "message": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          },
+          "code": {
+            "type": "string"
+          },
+          "param": {
+            "type": "string",
+            "description": "The request field at fault, omitted when no specific field is known."
+          },
+          "retryable": {
+            "type": "boolean"
+          },
+          "upstream": {
+            "$ref": "#/components/schemas/AsyncTaskUpstreamError"
+          }
+        },
+        "additionalProperties": false
+      },
+      "AsyncTaskError": {
+        "description": "Why the task failed: a string, or an object with `message` and, when known, `type`, `code`, `param` and `retryable`.",
+        "oneOf": [
+          {
+            "type": "string"
+          },
+          {
             "type": "object",
             "required": [
-              "page",
-              "limit",
-              "total",
-              "total_pages"
+              "message"
             ],
             "properties": {
-              "page": {
-                "type": "integer"
+              "message": {
+                "type": "string"
               },
-              "limit": {
-                "type": "integer"
+              "type": {
+                "type": "string"
               },
-              "total": {
-                "type": "integer"
+              "code": {
+                "type": "string"
               },
-              "total_pages": {
-                "type": "integer"
+              "param": {
+                "type": "string"
+              },
+              "retryable": {
+                "type": "boolean"
               }
             },
             "additionalProperties": false
           }
-        },
-        "additionalProperties": false
+        ]
       },
-      "DeletedWebhookEndpoint": {
+      "GeminiFileResource": {
         "type": "object",
-        "required": [
-          "id",
-          "object",
-          "deleted"
-        ],
+        "description": "A Gemini file in the current Workspace. Fields are returned when available.",
         "properties": {
-          "id": {
-            "type": "string"
+          "name": {
+            "type": "string",
+            "description": "File resource name such as files/{fileId}."
           },
-          "object": {
+          "displayName": {
             "type": "string",
-            "enum": [
-              "webhook_endpoint"
-            ]
+            "description": "Human-readable file name."
           },
-          "deleted": {
-            "type": "boolean",
-            "const": true
+          "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": false
+        "additionalProperties": true
       },
-      "CreateWebhookEndpointRequest": {
+      "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",
-        "additionalProperties": false,
         "required": [
-          "url",
-          "events"
+          "model"
         ],
         "properties": {
-          "url": {
+          "model": {
             "type": "string",
-            "format": "uri",
-            "description": "Public HTTPS receiver URL. Credentials, query strings, fragments, private or reserved network targets and redirects are rejected."
+            "minLength": 1,
+            "description": "Current TokenLab model ID that supports Gemini cached content."
           },
-          "events": {
-            "type": "array",
-            "minItems": 1,
-            "maxItems": 10,
-            "items": {
-              "type": "string",
-              "enum": [
-                "task.completed",
-                "task.failed",
-                "task.timeout"
-              ]
-            },
-            "description": "Supported event subscriptions; duplicates are removed."
+          "displayName": {
+            "type": "string",
+            "description": "Human-readable cache name."
           },
-          "description": {
+          "ttl": {
             "type": "string",
-            "maxLength": 200
+            "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
       },
-      "UpdateWebhookEndpointRequest": {
+      "GeminiCachedContentResource": {
         "type": "object",
-        "additionalProperties": false,
-        "minProperties": 1,
+        "description": "Cached content belonging to the current Workspace. Use the returned name as cachedContent in Gemini generation.",
         "properties": {
-          "url": {
+          "name": {
             "type": "string",
-            "format": "uri",
-            "description": "Public HTTPS receiver URL. Credentials, query strings, fragments, private or reserved network targets and redirects are rejected."
+            "description": "Resource name such as cachedContents/{cacheId}."
           },
-          "events": {
-            "type": "array",
-            "minItems": 1,
-            "maxItems": 10,
-            "items": {
-              "type": "string",
-              "enum": [
-                "task.completed",
-                "task.failed",
-                "task.timeout"
-              ]
-            },
-            "description": "Supported event subscriptions; duplicates are removed."
+          "model": {
+            "type": "string",
+            "description": "TokenLab model ID associated with the cached content."
           },
-          "description": {
-            "type": [
-              "string",
-              "null"
-            ],
-            "maxLength": 200
+          "displayName": {
+            "type": "string",
+            "description": "Human-readable cache name."
           },
-          "is_active": {
-            "type": "boolean",
-            "description": "Resume or pause delivery. Resuming resets the consecutive failure count."
+          "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
       }
     },
     "responses": {
@@ -16090,7 +17662,7 @@
         }
       },
       "UpstreamError": {
-        "description": "Upstream Provider Error",
+        "description": "Service Error",
         "content": {
           "application/json": {
             "schema": {
@@ -16098,7 +17670,7 @@
             },
             "example": {
               "error": {
-                "message": "Upstream provider returned an error",
+                "message": "The service could not complete the request",
                 "type": "upstream_error"
               }
             }
@@ -16106,7 +17678,7 @@
         }
       },
       "AllChannelsFailed": {
-        "description": "All Channels Failed",
+        "description": "Service Unavailable",
         "content": {
           "application/json": {
             "schema": {
@@ -16114,7 +17686,7 @@
             },
             "example": {
               "error": {
-                "message": "All available channels failed to process the request",
+                "message": "The service is temporarily unable to process this request",
                 "type": "all_channels_failed"
               }
             }
@@ -16171,7 +17743,7 @@
         }
       },
       "DeliveryUnavailable": {
-        "description": "No eligible Delivery route is currently available, or all eligible routes failed.",
+        "description": "The requested Delivery tier is temporarily unavailable.",
         "content": {
           "application/json": {
             "schema": {
@@ -16179,7 +17751,7 @@
             },
             "examples": {
               "requestedTierUnavailable": {
-                "summary": "The requested Delivery tier has no eligible route",
+                "summary": "The requested Delivery tier is unavailable",
                 "value": {
                   "error": {
                     "message": "The requested Delivery tier is temporarily unavailable for model gpt-5.4.",
@@ -16191,7 +17763,7 @@
                 }
               },
               "eligibleRoutesFailed": {
-                "summary": "All eligible Delivery routes failed",
+                "summary": "The requested Delivery tier could not complete this request",
                 "value": {
                   "error": {
                     "message": "All available routes failed to process the request.",
@@ -16204,6 +17776,16 @@
             }
           }
         }
+      },
+      "GeminiResourceError": {
+        "description": "Gemini-format resource error",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/GeminiErrorResponse"
+            }
+          }
+        }
       }
     },
     "parameters": {
@@ -16211,7 +17793,7 @@
         "name": "X-TokenLab-Delivery-Policy",
         "in": "header",
         "required": false,
-        "description": "Per-request Delivery policy. Overrides the API key and Workspace defaults. Auto tries TokenLab Verified first and may switch once to Official only before output, upstream acceptance, or persistent resource creation.",
+        "description": "Per-request Delivery policy. Overrides the API key and Workspace defaults. Auto tries TokenLab Verified first and may switch once to Official only before output, request acceptance, or persistent resource creation.",
         "schema": {
           "type": "string",
           "enum": [
@@ -16222,5 +17804,78 @@
         }
       }
     }
+  },
+  "webhooks": {
+    "taskTimeout": {
+      "post": {
+        "tags": [
+          "Webhooks"
+        ],
+        "summary": "Task timeout notification",
+        "description": "Sent to a configured webhook endpoint subscribed to task.timeout. Verify the HMAC-SHA256 signature over the timestamp, a period, and the raw request body using the signing secret. Return 2xx promptly and deduplicate by event ID. See https://tokenlab.sh/docs/en/guides/webhooks for signature verification and delivery recovery.",
+        "operationId": "receiveTaskTimeoutWebhook",
+        "security": [],
+        "parameters": [
+          {
+            "in": "header",
+            "name": "X-Webhook-ID",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Matches the event id in the request body."
+          },
+          {
+            "in": "header",
+            "name": "X-Webhook-Timestamp",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "pattern": "^[0-9]+$"
+            },
+            "description": "Delivery attempt timestamp in Unix seconds."
+          },
+          {
+            "in": "header",
+            "name": "X-Webhook-Signature",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "pattern": "^sha256=[a-f0-9]{64}$"
+            },
+            "description": "HMAC-SHA256 signature using the complete whsec_ signing secret."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TaskTimeoutWebhook"
+              },
+              "example": {
+                "id": "event-unique-id",
+                "type": "task.timeout",
+                "created": 1790000000,
+                "data": {
+                  "taskType": "image",
+                  "taskId": "ldtask_0123456789abcdef0123456789abcdef",
+                  "expectedTimeoutMs": 1800000,
+                  "actualWaitMs": 1801000,
+                  "refundIssued": true,
+                  "resolutionSource": "timeout_detector",
+                  "refundOutcome": "success"
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "2XX": {
+            "description": "Notification accepted by the receiving endpoint."
+          }
+        }
+      }
+    }
   }
 }