{ "openapi": "3.1.0", "info": { "title": "TokenLab AI Gateway", "description": "Organization balance, API key management, and key-level usage/billing via management token", "version": "1.0.0", "termsOfService": "https://tokenlab.sh/tos", "contact": { "name": "Technical Support", "email": "support@tokenlab.sh" } }, "servers": [ { "url": "https://api.tokenlab.sh", "description": "Production server" } ], "tags": [ { "name": "Chat", "description": "Chat completions API (OpenAI-compatible)" }, { "name": "Responses", "description": "OpenAI Responses API-compatible native endpoints" }, { "name": "Embeddings", "description": "Text embeddings API" }, { "name": "Images", "description": "Image generation API" }, { "name": "Audio", "description": "Audio processing API (TTS & STT)" }, { "name": "Video", "description": "Video generation API" }, { "name": "Models", "description": "Available models listing" }, { "name": "Anthropic", "description": "Anthropic-compatible Messages API" }, { "name": "Gemini", "description": "Google Gemini-compatible API" }, { "name": "Management", "description": "Organization API key management and key-level usage/billing via management token" }, { "name": "Files", "description": "Batch file upload and retrieval" }, { "name": "Batches", "description": "OpenAI-compatible asynchronous batch jobs" }, { "name": "Seedance Volc Compatible", "description": "Seedance 2.0 Volc-style compatibility endpoints" }, { "name": "Decisions" }, { "name": "Webhooks", "description": "Workspace webhook management with Management Tokens (mt-...). Inference API keys do not grant management access." } ], "security": [ { "BearerAuth": [] } ], "paths": { "/v1/chat/completions": { "post": { "tags": [ "Chat" ], "summary": "Create chat completion", "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, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" }, "examples": { "basic": { "summary": "Basic chat completion", "value": { "model": "gpt-4o", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "Hello!" } ] } }, "streaming": { "summary": "Streaming response", "value": { "model": "gpt-4o", "messages": [ { "role": "user", "content": "Tell me a story" } ], "stream": true } }, "live_translation": { "summary": "Stream audio translation", "value": { "model": "qwen3-livetranslate-flash", "messages": [ { "role": "user", "content": [ { "type": "input_audio", "input_audio": { "data": "https://example.com/sample.wav", "format": "wav" } } ] } ], "translation_options": { "source_lang": "zh", "target_lang": "en" }, "modalities": [ "text" ], "stream": true } }, "function_calling": { "summary": "Function calling", "value": { "model": "gpt-4o", "messages": [ { "role": "user", "content": "What's the weather in Tokyo?" } ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "Get weather for a location", "parameters": { "type": "object", "properties": { "location": { "type": "string" } }, "required": [ "location" ] } } } ] } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events stream with JSON chunks" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] } }, "/v1/embeddings": { "post": { "tags": [ "Embeddings" ], "summary": "Create embeddings", "description": "Creates an embedding vector representing the input text.", "operationId": "createEmbedding", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingRequest" }, "examples": { "single": { "summary": "Single text embedding", "value": { "model": "text-embedding-3-small", "input": "The quick brown fox jumps over the lazy dog" } }, "batch": { "summary": "Batch embeddings", "value": { "model": "text-embedding-3-small", "input": [ "Hello world", "How are you?" ] } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] } }, "/v1/multimodal/embeddings": { "post": { "tags": [ "Embeddings" ], "summary": "Create multimodal embeddings", "description": "Creates embeddings for multimodal input items. Text input is generally available; image input may require feature enablement.", "operationId": "createMultimodalEmbedding", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultimodalEmbeddingRequest" }, "examples": { "text": { "summary": "Text input", "value": { "model": "jina-embeddings-v4", "input": { "text": "Describe this product for semantic search." } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultimodalEmbeddingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] } }, "/v1/images/generations": { "post": { "tags": [ "Images" ], "summary": "Create image", "description": "Creates an image given a prompt.", "operationId": "createImage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationRequest" }, "examples": { "basic": { "summary": "Basic image generation", "value": { "model": "gpt-image-2", "prompt": "A white cat sitting on a rainy windowsill", "size": "1024x1024", "quality": "auto" } }, "high_quality": { "summary": "High quality image", "value": { "model": "gpt-image-2", "prompt": "A cinematic product photo of matte black headphones on a glass desk", "size": "1536x1024", "quality": "high" } } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImageGenerationMultipartRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] } }, "/v1/images/{id}": { "get": { "tags": [ "Images" ], "summary": "Get image task status", "description": "Compatibility alias for polling public async image task IDs such as `ldtask_...`. Prefer the `poll_url` returned by create responses, or use `/v1/tasks/{id}` as the canonical fixed status endpoint. This route uses the same authorization, ownership checks, billing headers, terminal snapshots, and response shape as the image-specific status handler.", "operationId": "getImageTaskStatusAlias", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The public async image task ID returned by `id` / `task_id`, or embedded in `poll_url`.", "schema": { "type": "string", "pattern": "^ldtask_[0-9a-fA-F]{32}$" } } ], "responses": { "200": { "description": "Image task status", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "task_id": { "type": "string" }, "poll_url": { "type": "string" }, "created": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "error": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ] }, "error_details": { "$ref": "#/components/schemas/AsyncTaskErrorDetails" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Task not available to the current API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Task not found or no longer available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/audio/speech": { "post": { "tags": [ "Audio" ], "summary": "Create speech", "description": "Generates audio from the input text (Text-to-Speech).", "operationId": "createSpeech", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioSpeechRequest" }, "examples": { "basic": { "summary": "Basic TTS", "value": { "model": "tts-1", "input": "Hello, welcome to TokenLab!", "voice": "alloy" } }, "hd": { "summary": "HD quality TTS", "value": { "model": "tts-1-hd", "input": "This is high quality speech synthesis.", "voice": "nova", "response_format": "mp3", "speed": 1 } } } } } }, "responses": { "200": { "description": "Audio file", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/opus": { "schema": { "type": "string", "format": "binary" } }, "audio/aac": { "schema": { "type": "string", "format": "binary" } }, "audio/flac": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] } }, "/v1/audio/transcriptions": { "post": { "tags": [ "Audio" ], "summary": "Create transcription", "description": "Transcribes audio into text (Speech-to-Text).", "operationId": "createTranscription", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AudioTranscriptionRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioTranscriptionResponse" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] } }, "/v1/videos/generations": { "post": { "tags": [ "Video" ], "summary": "Create video generation task", "description": "Creates an asynchronous video generation task. The response returns a canonical task ID and usually a preferred `poll_url`; clients should poll `poll_url` first, or use `/v1/tasks/{id}` as the fixed status endpoint.", "operationId": "createVideo", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoGenerationRequest" }, "examples": { "text_to_video": { "summary": "Text-to-Video", "value": { "model": "veo3.1", "prompt": "A cinematic shot of a golden retriever running through a field of sunflowers", "duration": 5, "aspect_ratio": "16:9" } }, "image_to_video": { "summary": "Image-to-Video", "value": { "model": "hailuo-2.3-standard", "prompt": "Make this image come alive with gentle movement", "operation": "image-to-video", "image_url": "https://example.com/image.jpg", "duration": 6 } }, "reference_to_video": { "summary": "Reference-to-Video", "value": { "model": "veo3.1", "prompt": "Keep the same subject identity and palette while adding subtle motion", "operation": "reference-to-video", "reference_images": [ "https://example.com/ref-a.jpg" ], "duration": 8, "aspect_ratio": "9:16", "resolution": "720p" } } } } } }, "responses": { "200": { "description": "Task created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoGenerationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "409": { "description": "Seedance material is still preparing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "message": "Seedance material is still preparing. Please retry after it becomes ACTIVE.", "type": "invalid_request_error", "code": "seedance_material_preparing", "param": "material_asset_id", "auto_material_asset_ids": [ "asset-20260720123456-auto1" ] } } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] } }, "/v1/videos/generations/{id}": { "get": { "tags": [ "Video" ], "summary": "Get video task status", "description": "Retrieves the status and result of a video generation task. New clients should prefer the `poll_url` returned by create responses, or use `/v1/tasks/{id}` as the canonical fixed status endpoint. The `/v1/videos/generations/{id}` path remains for backward compatibility.", "operationId": "getVideoTask", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The async task ID returned by `id` / `task_id`, or embedded in `poll_url`", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoTaskResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/videos/assets": { "post": { "tags": [ "Video" ], "summary": "Create Seedance material asset", "description": "Uploads one Seedance material asset URL into a TokenLab material group. Image materials must use supported dimensions; an invalid source is rejected with 400 seedance_material_source_invalid instead of remaining in PROCESSING. Real-person assets require the group_id mapped from Result.GroupId returned by GetVisualValidateResult.", "operationId": "createSeedanceMaterialAsset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedanceMaterialAssetCreateRequest" }, "examples": { "virtual_avatar_asset": { "summary": "Create a virtual-avatar material asset", "value": { "asset_url": "https://example.com/reference.png", "asset_name": "Front view", "asset_type": "Image", "library_type": "aigc_avatar", "group_id": "group-20260720123456-vrt01" } }, "real_person_asset": { "summary": "Create a real-person material asset", "value": { "asset_url": "https://example.com/verified-person-closeup.jpg", "asset_name": "Creator A close-up", "asset_type": "Image", "library_type": "liveness_face", "group_id": "group-20260720123456-real1" } } } } } }, "responses": { "201": { "description": "Material asset created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedanceMaterialAsset" }, "examples": { "asset_created": { "summary": "Material asset accepted for processing", "value": { "id": "asset-20260720123456-qn7wr", "object": "seedance.material_asset", "group_id": "group-20260720123456-vrt01", "library_type": "aigc_avatar", "asset_name": "Front view", "asset_type": "Image", "status": "PROCESSING", "ready": false, "error_message": null, "metadata": null, "created_at": 1782998400000 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Material asset mapping conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MaterialLibraryUnavailable" } } }, "get": { "tags": [ "Video" ], "summary": "List Seedance material assets", "description": "Lists Seedance material assets owned by the authenticated organization. Use library_type, group_id, and status filters to find assets for a generation workflow.", "operationId": "listSeedanceMaterialAssets", "parameters": [ { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "page_token", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "group_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by TokenLab material asset group id." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PROCESSING", "ACTIVE", "FAILED", "DELETED" ] } }, { "name": "library_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "aigc_avatar", "liveness_face" ] }, "description": "Filter by material library class." }, { "name": "project_name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "default": "default" }, "description": "Project scope for the material resource." } ], "responses": { "200": { "description": "Material assets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedanceMaterialAssetList" }, "examples": { "assets": { "summary": "Material assets", "value": { "assets": [ { "id": "asset-20260720123456-qn7wr", "object": "seedance.material_asset", "group_id": "group-20260720123456-vrt01", "library_type": "aigc_avatar", "asset_name": "Front view", "asset_type": "Image", "status": "ACTIVE", "ready": true, "error_message": null, "metadata": null, "created_at": 1782998400000 } ], "next_page_token": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/videos/assets/{assetId}": { "get": { "tags": [ "Video" ], "summary": "Get Seedance material asset", "description": "Retrieves one TokenLab Seedance material asset and its asynchronous ingestion status.", "operationId": "getSeedanceMaterialAsset", "parameters": [ { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "asset-20260720123456-qn7wr" }, { "name": "project_name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "default": "default" }, "description": "Project scope for the material resource." } ], "responses": { "200": { "description": "Material asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedanceMaterialAsset" }, "examples": { "asset": { "summary": "Material asset", "value": { "id": "asset-20260720123456-qn7wr", "object": "seedance.material_asset", "group_id": "group-20260720123456-vrt01", "library_type": "aigc_avatar", "asset_name": "Front view", "asset_type": "Image", "status": "ACTIVE", "ready": true, "error_message": null, "metadata": null, "created_at": 1782998400000 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MaterialLibraryUnavailable" } } }, "put": { "tags": [ "Video" ], "operationId": "updateSeedanceMaterialAsset", "summary": "Update Seedance material asset", "description": "Updates a Seedance material asset owned by the authenticated organization.", "parameters": [ { "name": "assetId", "in": "path", "required": true, "description": "TokenLab material asset ID.", "schema": { "type": "string" }, "example": "asset-20260720123456-qn7wr" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedanceMaterialAssetUpdateRequest" }, "examples": { "update_asset": { "summary": "Update asset metadata", "value": { "asset_name": "Front view approved", "metadata": { "approved_by": "creative-team" } } } } } } }, "responses": { "200": { "description": "Material asset updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedanceMaterialAsset" }, "examples": { "asset_updated": { "summary": "Material asset updated", "value": { "id": "asset-20260720123456-qn7wr", "object": "seedance.material_asset", "group_id": "group-20260720123456-vrt01", "library_type": "aigc_avatar", "asset_name": "Front view approved", "asset_type": "Image", "status": "ACTIVE", "ready": true, "error_message": null, "metadata": { "approved_by": "creative-team" }, "created_at": 1782998400000 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Material asset is still processing or has failed without an active replica", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "The stored material source failed permanent validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "message": "Image width must be between 300px and 6000px.", "type": "invalid_request_error", "code": "seedance_material_source_invalid", "param": "asset_url" } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/MaterialLibraryUnavailable" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Video" ], "summary": "Delete Seedance material asset", "description": "Deletes a Seedance material asset owned by the authenticated organization.", "operationId": "deleteSeedanceMaterialAsset", "parameters": [ { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "asset-20260720123456-qn7wr" }, { "name": "project_name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "default": "default" }, "description": "Project scope for the material resource." } ], "responses": { "200": { "description": "Material asset deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedanceMaterialAssetDeleteResponse" }, "examples": { "asset_deleted": { "summary": "Material asset deleted", "value": { "deleted": true, "id": "asset-20260720123456-qn7wr" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MaterialLibraryUnavailable" } } } }, "/v1/tasks/{id}": { "get": { "tags": [ "Tasks" ], "summary": "Get async task status", "description": "Retrieves the status and result of an asynchronous generation task. Prefer the `poll_url` returned by the create response; `/v1/tasks/{id}` is the canonical fixed status endpoint for video, music, and 3D jobs.", "operationId": "getAsyncTask", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The async task ID returned by `id` / `task_id`, or embedded in `poll_url`", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task status (task-type specific fields may be present)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoTaskResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Task not available to the current API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Tasks" ], "summary": "Cancel async task", "description": "Cancels a queued asynchronous task when cancellation is supported for the selected task. Cancellation currently supports queued Seedance video tasks (`seedance-1.5-pro`, `seedance-2.0`, and `seedance-2.0-fast`) while they are still waiting to run. Tasks that are already processing, completed, failed, expired, or unsupported are not cancelled.", "operationId": "cancelAsyncTask", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The async task ID returned by `id` / `task_id`, or embedded in `poll_url`", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task cancelled. The task remains queryable and is represented as `failed` with `cancelled: true` for compatibility with existing async task status values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoTaskResponse" }, "example": { "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "status": "failed", "cancelled": true, "cancellation_status": "cancelled", "error": "Task cancelled before execution" } } } }, "400": { "description": "This task does not support cancellation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Task not available to the current API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Task is no longer cancellable, for example because it is already processing or terminal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/models": { "get": { "tags": [ "Models" ], "summary": "List models", "description": "Lists the currently available models. Use `view=compact` for model selection and `view=full` for the existing OpenAI-compatible discovery shape. Native API calls default to `full`; integrations may choose `compact` as their default. Non-chat recommendations are available through `recommended_for`.", "operationId": "listModels", "parameters": [ { "name": "provider", "in": "query", "required": false, "description": "Filter by public model provider, for example openai, anthropic, google, or minimax.", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "required": false, "description": "Filter by a public capability tag.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "Filter by model category.", "schema": { "type": "string", "enum": [ "chat", "embedding", "translation", "image", "video", "audio", "tts", "stt", "rerank", "3d", "music", "decision" ] } }, { "name": "recommended_for", "in": "query", "required": false, "description": "Sort supported non-chat models for a task category and include recommendation evidence.", "schema": { "type": "string", "enum": [ "image", "video", "music", "3d", "tts", "stt", "embedding", "rerank", "translation" ] } }, { "name": "view", "in": "query", "required": false, "description": "Choose compact model-selection fields or the full OpenAI-compatible list shape.", "schema": { "type": "string", "enum": [ "compact", "full" ], "default": "full" } } ], "responses": { "200": { "description": "List of models", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ModelsResponse" }, { "$ref": "#/components/schemas/CompactModelsResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/models/{model}": { "get": { "tags": [ "Models" ], "summary": "Get model", "description": "Retrieves current model details, including supported operations, request parameters, request endpoints, selector limits, and pricing when available. Non-chat integrations should read these current model-specific request details before creating a request.", "operationId": "getModel", "parameters": [ { "name": "model", "in": "path", "required": true, "description": "The model ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Model information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/messages": { "post": { "tags": [ "Anthropic" ], "summary": "Create message (Anthropic-compatible)", "description": "Creates a model response using Anthropic's native request format. Supports Claude models with vision and streaming.\n\n**Authentication:** Use `x-api-key` header or `Authorization: Bearer` header.", "operationId": "createAnthropicMessage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessagesRequest" }, "examples": { "basic": { "summary": "Basic message", "value": { "model": "claude-sonnet-4-6", "max_tokens": 1024, "messages": [ { "role": "user", "content": "Hello, Claude!" } ] } }, "with_system": { "summary": "With system prompt", "value": { "model": "claude-sonnet-4-6", "max_tokens": 1024, "system": "You are a helpful assistant.", "messages": [ { "role": "user", "content": "What is 2+2?" } ] } }, "streaming": { "summary": "Streaming response", "value": { "model": "claude-sonnet-4-6", "max_tokens": 1024, "stream": true, "messages": [ { "role": "user", "content": "Tell me a story" } ] } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessagesResponse" } }, "text/event-stream": { "schema": { "type": "string", "description": "Anthropic-style SSE stream with message_start, content_block_delta, message_stop events" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] } }, "/v1/messages/count_tokens": { "post": { "tags": [ "Anthropic" ], "summary": "Count message tokens (Anthropic-compatible)", "description": "Counts input tokens for an Anthropic-compatible messages request without creating a model response. Authentication is required; the operation is not billed.", "operationId": "countAnthropicMessageTokens", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicCountTokensRequest" } } } }, "responses": { "200": { "description": "Token count response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicCountTokensResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/v1/messages/batches": { "post": { "tags": [ "Anthropic" ], "summary": "Create message batch (Anthropic-compatible)", "description": "Creates a native Anthropic Message Batch. Requests use the same Anthropic message parameters as /v1/messages.", "operationId": "createAnthropicMessageBatch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageBatchCreateRequest" } } } }, "responses": { "200": { "description": "Created message batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageBatch" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] }, "get": { "tags": [ "Anthropic" ], "summary": "List message batches (Anthropic-compatible)", "description": "Lists native Anthropic Message Batches for the authenticated organization.", "operationId": "listAnthropicMessageBatches", "parameters": [ { "name": "before_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return batches before this batch id" }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return batches after this batch id" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 20 }, "description": "Maximum number of batches to return" } ], "responses": { "200": { "description": "Message batch list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageBatchListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/v1/messages/batches/{message_batch_id}": { "get": { "tags": [ "Anthropic" ], "summary": "Retrieve message batch (Anthropic-compatible)", "description": "Retrieves the status and metadata for a native Anthropic Message Batch.", "operationId": "retrieveAnthropicMessageBatch", "parameters": [ { "name": "message_batch_id", "in": "path", "required": true, "description": "Anthropic message batch identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Message batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageBatch" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } }, "delete": { "tags": [ "Anthropic" ], "summary": "Delete message batch (Anthropic-compatible)", "description": "Deletes an Anthropic Message Batch when deletion is supported for that batch.", "operationId": "deleteAnthropicMessageBatch", "parameters": [ { "name": "message_batch_id", "in": "path", "required": true, "description": "Anthropic message batch identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted message batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicDeletedMessageBatch" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/v1/messages/batches/{message_batch_id}/results": { "get": { "tags": [ "Anthropic" ], "summary": "Retrieve message batch results (Anthropic-compatible)", "description": "Downloads JSONL results for a completed native Anthropic Message Batch.", "operationId": "retrieveAnthropicMessageBatchResults", "parameters": [ { "name": "message_batch_id", "in": "path", "required": true, "description": "Anthropic message batch identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Message batch results in JSONL format", "content": { "application/x-jsonl": { "schema": { "type": "string", "description": "Newline-delimited JSON result records" } }, "text/plain": { "schema": { "type": "string", "description": "Newline-delimited JSON result records" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/v1/messages/batches/{message_batch_id}/cancel": { "post": { "tags": [ "Anthropic" ], "summary": "Cancel message batch (Anthropic-compatible)", "description": "Cancels an Anthropic Message Batch when cancellation is still available for that batch.", "operationId": "cancelAnthropicMessageBatch", "parameters": [ { "name": "message_batch_id", "in": "path", "required": true, "description": "Anthropic message batch identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancelled message batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageBatch" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/v1beta/models/{model}:generateContent": { "post": { "tags": [ "Gemini" ], "summary": "Generate content (Gemini-compatible)", "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": [ { "$ref": "#/components/parameters/DeliveryPolicy" }, { "name": "model", "in": "path", "required": true, "description": "Model name (e.g., gemini-2.5-pro)", "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": false, "description": "API key (alternative to header auth)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiRequest" }, "examples": { "basic": { "summary": "Basic text generation", "value": { "contents": [ { "parts": [ { "text": "Hello, Gemini!" } ] } ] } }, "with_config": { "summary": "With generation config", "value": { "contents": [ { "parts": [ { "text": "Explain quantum computing" } ] } ], "generationConfig": { "temperature": 0.7, "maxOutputTokens": 1024 } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiResponse" } } } }, "400": { "description": "Gemini-native invalid request error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiErrorResponse" } } } }, "401": { "description": "Gemini-native authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiErrorResponse" } } } }, "402": { "description": "Gemini-native payment error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiErrorResponse" } } } }, "500": { "description": "Gemini-native server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiErrorResponse" } } } }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } } } }, "/v1beta/models/{model}:streamGenerateContent": { "post": { "tags": [ "Gemini" ], "summary": "Stream generate content (Gemini-compatible)", "description": "Streams native Gemini GenerateContent Server-Sent Events without adding Chat Completions terminators. Metadata-only chunks, intermediate chunks without finishReason, and natural EOF are valid.\n\n**Authentication:** Use `?key=` query parameter, `x-goog-api-key` header, or `Authorization: Bearer` header.", "operationId": "geminiStreamGenerateContent", "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" }, { "name": "model", "in": "path", "required": true, "description": "Model name (e.g., gemini-2.5-pro)", "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": false, "description": "API key (alternative to header auth)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiRequest" } } } }, "responses": { "200": { "description": "Streaming response", "content": { "text/event-stream": { "schema": { "type": "string", "description": "SSE stream with Gemini response chunks" } } } }, "400": { "description": "Gemini-native invalid request error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiErrorResponse" } } } }, "401": { "description": "Gemini-native authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiErrorResponse" } } } }, "402": { "description": "Gemini-native payment error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiErrorResponse" } } } }, "500": { "description": "Gemini-native server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiErrorResponse" } } } }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } } } }, "/v1beta/models/{model}:countTokens": { "post": { "tags": [ "Gemini" ], "summary": "Count tokens (Gemini-compatible)", "description": "Counts tokens using the native Gemini CountTokens contract. Unknown fields and either official ProtoJSON field-name spelling are forwarded best-effort.", "operationId": "geminiCountTokens", "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contents": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "generateContentRequest": { "type": "object", "additionalProperties": true }, "generate_content_request": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Gemini-native token count response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Gemini-native error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiErrorResponse" } } } } } } }, "/v1beta/models/{model}:embedContent": { "post": { "tags": [ "Gemini" ], "summary": "Embed content (Gemini-compatible)", "description": "Creates an embedding using the native Gemini EmbedContent contract.", "operationId": "geminiEmbedContent", "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" }, { "name": "model", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "object", "additionalProperties": true }, "taskType": { "type": "string" }, "task_type": { "type": "string" }, "title": { "type": "string" }, "outputDimensionality": { "type": "integer" }, "output_dimensionality": { "type": "integer" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Gemini-native embedding response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Gemini-native error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiErrorResponse" } } } }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } } } }, "/v1beta/models/{model}:batchEmbedContents": { "post": { "tags": [ "Gemini" ], "summary": "Batch embed contents (Gemini-compatible)", "description": "Creates multiple embeddings using the native Gemini BatchEmbedContents contract.", "operationId": "geminiBatchEmbedContents", "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" }, { "name": "model", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "requests" ], "properties": { "requests": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Gemini-native batch embedding response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Gemini-native error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiErrorResponse" } } } }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } } } }, "/v1/responses": { "post": { "tags": [ "Responses" ], "summary": "Create response (OpenAI Responses API)", "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, "content": { "application/json": { "schema": { "type": "object", "required": [ "model" ], "properties": { "model": { "type": "string", "description": "Model to use" }, "input": { "oneOf": [ { "type": "string", "description": "Single string input." }, { "type": "array", "description": "Structured input items for the conversation." } ], "description": "Input content as a string or structured item array." }, "instructions": { "type": "string", "description": "System instructions" }, "max_output_tokens": { "type": "integer", "description": "Maximum output tokens" }, "temperature": { "type": "number" }, "stream": { "type": "boolean" }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Tools available to the model. Tool types and combinations are validated by the selected service." }, "tool_choice": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ], "description": "Tool choice policy or explicit tool selection." }, "stream_options": { "type": "object", "properties": { "include_obfuscation": { "type": "boolean", "description": "When true, request obfuscated tokens in Responses stream events where supported." } }, "additionalProperties": true, "description": "Responses streaming options." }, "include": { "type": "array", "items": { "type": "string" }, "description": "Additional response sections to include when supported." }, "service_tier": { "type": [ "string", "null" ], "description": "Service tier hint where supported by the model." }, "truncation": { "type": "string", "description": "Truncation strategy for long conversations." }, "background": { "type": "boolean", "description": "Whether to run the response asynchronously." }, "previous_response_id": { "type": "string", "description": "ID of a previous response to continue." }, "prompt": { "type": "object", "additionalProperties": true, "description": "Reference to a reusable prompt template and variables." }, "store": { "type": "boolean", "description": "Whether the response is stored for later retrieval." }, "reasoning": { "type": "object", "additionalProperties": true, "description": "Reasoning configuration." }, "top_p": { "type": "number", "description": "Nucleus sampling probability." }, "parallel_tool_calls": { "type": "boolean", "description": "Whether the model may issue parallel tool calls." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Request metadata." }, "text": { "type": "object", "additionalProperties": true, "description": "Text formatting options." } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] } }, "/v1/responses/{id}": { "get": { "tags": [ "Responses" ], "summary": "Retrieve response", "description": "Retrieves a stored Responses API response by TokenLab response id. Ownership checks return 404 when the response is missing or unavailable to the current API key.", "operationId": "retrieveResponse", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Response id returned by POST /v1/responses." }, { "name": "include", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Additional response fields to include." }, { "name": "include_obfuscation", "in": "query", "schema": { "type": "boolean" }, "description": "Whether streamed events include obfuscation fields." }, { "name": "stream", "in": "query", "schema": { "type": "boolean" }, "description": "Whether to retrieve the response as an event stream." }, { "name": "starting_after", "in": "query", "schema": { "type": "integer" }, "description": "Sequence number after which streaming events are returned." } ], "responses": { "200": { "description": "Stored response" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Responses" ], "summary": "Delete response", "description": "Deletes a stored Responses API response. This operation is deletion, not cancellation of an in-progress response.", "operationId": "deleteResponse", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Response id returned by POST /v1/responses." } ], "responses": { "200": { "description": "Deleted response" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/responses/compact": { "post": { "tags": [ "Responses" ], "summary": "Compact response context (OpenAI Responses API)", "description": "Compacts Responses input and returns the native `response.compaction` contract. The request model must be available on a same-protocol Responses path.", "operationId": "compactResponse", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "Model to use for compaction. Codex CLI sends the current session model." }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "description": "Responses input items to compact." } ], "description": "Conversation input to compact." }, "max_output_tokens": { "type": "integer", "description": "Maximum output tokens." }, "stream": { "type": "boolean", "description": "Streaming is not supported for compaction." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Request metadata." } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful compaction response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] } }, "/v1/rerank": { "post": { "tags": [ "Embeddings" ], "summary": "Rerank documents", "description": "Reranks documents by relevance to a query using semantic similarity.", "operationId": "rerankDocuments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "query", "documents" ], "properties": { "model": { "type": "string", "description": "Reranker model to use" }, "query": { "type": "string", "description": "Query to rank against" }, "documents": { "type": "array", "items": { "type": "string" }, "description": "Documents to rerank" }, "top_n": { "type": "integer", "description": "Number of results to return" }, "return_documents": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Ranked results", "content": { "application/json": { "schema": { "type": "object", "required": [ "results", "model" ], "properties": { "id": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "model": { "type": "string" }, "usage": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] } }, "/v1/music/generations": { "post": { "tags": [ "Audio" ], "summary": "Create music generation task", "description": "Creates a music generation task using Suno. Returns a task ID for polling.", "operationId": "createMusic", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "default": "suno_music" }, "prompt": { "type": "string", "description": "Music description. Required for music, lyrics, upload-cover, and upload-extend requests; omit for add-instrumental." }, "title": { "type": "string" }, "tags": { "type": "string" }, "negative_tags": { "type": "string", "description": "Styles to avoid. Required when audio_operation is add-instrumental." }, "action": { "type": "string", "enum": [ "MUSIC", "LYRICS" ] }, "mv": { "type": "string", "enum": [ "chirp-v3-5", "chirp-v4", "chirp-v4-5", "chirp-v4.5", "chirp-v4-5plus", "chirp-v4.5plus", "chirp-v4-5all", "chirp-v4.5all", "chirp-v5", "chirp-v5-5", "chirp-v5.5" ], "description": "Official Suno model version. Required when creating music (action omitted or MUSIC); omit for lyrics-only requests." }, "make_instrumental": { "type": "boolean", "description": "Generate instrumental output without vocals." }, "audio_url": { "type": "string", "format": "uri", "description": "Publicly reachable reference or uploaded audio URL. Defaults to upload-cover when audio_operation is omitted." }, "audio_operation": { "type": "string", "enum": [ "upload-cover", "upload-extend", "add-instrumental" ], "description": "Uploaded-audio mode. upload-extend requires continue_at; add-instrumental requires audio_url, title, tags, and negative_tags." }, "continue_clip_id": { "type": "string", "description": "Clip ID to continue when extending an existing generation." }, "continue_at": { "type": "number", "description": "Timestamp in seconds for continuation flows. Required when audio_operation is upload-extend." } } } } } }, "responses": { "200": { "description": "Task created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] } }, "/v1/music/generations/{id}": { "get": { "tags": [ "Audio" ], "summary": "Get music task status", "description": "Retrieves the status and result of a music generation task.", "operationId": "getMusicTask", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task status" }, "404": { "description": "Task not found" } } } }, "/v1/3d/generations": { "post": { "tags": [ "Video" ], "summary": "Create 3D model generation task", "description": "Creates a 3D model generation task using Tripo3D. Returns a task ID for polling.", "operationId": "create3D", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "model": { "type": "string", "default": "tripo-h3.1" }, "prompt": { "type": "string", "description": "3D model description" }, "image": { "type": "string", "description": "Base64 image for image-to-3D" }, "image_url": { "type": "string" }, "format": { "type": "string", "enum": [ "glb", "fbx", "obj", "usdz" ] }, "quality": { "type": "string", "enum": [ "draft", "standard", "high" ] }, "style": { "type": "string", "description": "Style hint for compatible 3D model families." }, "seed": { "type": "integer", "description": "Seed for repeatable generation where supported by the model." }, "user": { "type": "string", "description": "End-user identifier." } } } } } }, "responses": { "200": { "description": "Task created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] } }, "/v1/3d/generations/{id}": { "get": { "tags": [ "Video" ], "summary": "Get 3D task status", "description": "Retrieves the status and result of a 3D generation task.", "operationId": "get3DTask", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task status" }, "404": { "description": "Task not found" } } } }, "/v1/management/balance": { "get": { "tags": [ "Management" ], "summary": "Get organization balance", "description": "Returns the current organization balance totals for the authenticated management token.", "operationId": "getManagementBalance", "security": [ { "ManagementTokenAuth": [] } ], "responses": { "200": { "description": "Organization balance totals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementBalanceResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/v1/management/api-keys": { "get": { "tags": [ "Management" ], "summary": "List organization API keys", "description": "Lists user-managed API keys for the current organization management token.", "operationId": "listManagementApiKeys", "security": [ { "ManagementTokenAuth": [] } ], "responses": { "200": { "description": "List of API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementApiKeyListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-mint": { "metadata": { "playground": "simple" } } }, "post": { "tags": [ "Management" ], "summary": "Create organization API key", "description": "Creates a new user API key for the current organization management token.", "operationId": "createManagementApiKey", "security": [ { "ManagementTokenAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "default": "Default Key", "description": "Display name for the user API key. Trimmed server-side. Length must be 1-50 characters." }, "limitAmount": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1000000, "description": "Spending limit input in USD. `null` or omitted means unlimited usage, and `0` means zero quota." }, "limitCurrency": { "type": "string", "enum": [ "USD" ], "default": "USD", "description": "Currency for `limitAmount`. USD is the only active currency. Sending `CNY` returns 400 `currency_retired`." }, "models": { "type": "array", "default": [], "description": "Optional model allowlist. Empty array means no per-key model restriction beyond organization policy.", "items": { "type": "string" } }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Optional RFC3339 timestamp. null means no expiry." }, "deliveryPolicy": { "type": [ "string", "null" ], "enum": [ "auto", "verified", "official", null ], "description": "Per-key Delivery policy. null inherits the Workspace default." } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementCreatedApiKey" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/v1/management/api-keys/{keyId}": { "patch": { "tags": [ "Management" ], "summary": "Update organization API key", "description": "Updates a user-managed API key for the current organization management token.", "operationId": "updateManagementApiKey", "security": [ { "ManagementTokenAuth": [] } ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "inactive", "suspended", "revoked" ], "description": "Lifecycle status for the user API key." }, "name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Updated display name. Length must be 1-50 characters after trimming." }, "limitAmount": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1000000, "description": "Updated spending limit input in USD. `null` means unlimited and `0` means zero quota." }, "limitCurrency": { "type": "string", "enum": [ "USD" ], "description": "Currency for `limitAmount`. USD is the only active currency. Sending `CNY` returns 400 `currency_retired`.", "default": "USD" }, "models": { "type": "array", "description": "Updated model allowlist.", "items": { "type": "string" } }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Updated RFC3339 expiry timestamp. null clears the expiry." }, "deliveryPolicy": { "type": [ "string", "null" ], "enum": [ "auto", "verified", "official", null ], "description": "Per-key Delivery policy. null inherits the Workspace default." } }, "description": "At least one field must be provided.", "minProperties": 1 } } } }, "responses": { "200": { "description": "Updated API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementApiKey" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "A revoked API key cannot be reactivated. Create a new key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "message": "A revoked API key cannot be reactivated. Create a new key.", "type": "invalid_request_error", "code": "api_key_revoked" } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/v1/management/api-keys/{keyId}/usage": { "get": { "tags": [ "Management" ], "summary": "Get API key usage", "description": "Returns paginated usage details for this API key.", "operationId": "getManagementApiKeyUsage", "security": [ { "ManagementTokenAuth": [] } ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "1-based page number. Default is 1." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Page size. Default is 50 and the maximum is 100." }, { "name": "model", "in": "query", "schema": { "type": "string", "maxLength": 100 }, "description": "Filter by requested model name. Maximum length 100." }, { "name": "modelVendor", "in": "query", "schema": { "type": "string", "maxLength": 100 }, "description": "Filter by public model vendor. Maximum length 100." }, { "name": "scene", "in": "query", "schema": { "type": "string", "enum": [ "chat", "image", "audio", "video", "embedding", "rerank", "translation", "music", "3d", "realtime", "systemone" ] }, "description": "Filter by public request scene." }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "description": "Inclusive date filter. Accepts either RFC3339 with timezone (for example 2026-03-28T00:00:00+08:00) or YYYY-MM-DD." }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "description": "Inclusive date filter. Accepts either RFC3339 with timezone (for example 2026-03-28T00:00:00+08:00) or YYYY-MM-DD." } ], "responses": { "200": { "description": "API key usage details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementUsageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/v1/management/api-keys/{keyId}/billing": { "get": { "tags": [ "Management" ], "summary": "Get API key billing", "description": "Returns aggregated billing breakdowns for this API key.", "operationId": "getManagementApiKeyBilling", "security": [ { "ManagementTokenAuth": [] } ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "model", "in": "query", "schema": { "type": "string", "maxLength": 100 }, "description": "Filter by requested model name. Maximum length 100." }, { "name": "modelVendor", "in": "query", "schema": { "type": "string", "maxLength": 100 }, "description": "Filter by public model vendor. Maximum length 100." }, { "name": "scene", "in": "query", "schema": { "type": "string", "enum": [ "chat", "image", "audio", "video", "embedding", "rerank", "translation", "music", "3d", "realtime", "systemone" ] }, "description": "Filter by public request scene." }, { "name": "startDate", "in": "query", "schema": { "type": "string" } }, { "name": "endDate", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key billing breakdowns", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementBillingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/v1/models/{model}/pricing": { "get": { "tags": [ "Models" ], "summary": "Get model pricing", "description": "Retrieves pricing-only detail for one model. Use this endpoint for price explanation, not for non-chat request construction.", "operationId": "getModelPricing", "parameters": [ { "name": "model", "in": "path", "required": true, "description": "The model ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Model pricing information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPricingResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/files": { "post": { "tags": [ "Files" ], "summary": "Upload file", "description": "Uploads a TokenLab/OpenAI-compatible batch or image file. With anthropic-beta: files-api-2025-04-14, uploads an Anthropic Files resource without a purpose field and returns Anthropic file metadata.", "operationId": "uploadFile", "parameters": [ { "name": "anthropic-beta", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Include files-api-2025-04-14 to use Anthropic Files API mode." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "purpose": { "type": "string", "enum": [ "batch", "user_data", "vision" ], "description": "Required in TokenLab/OpenAI-compatible mode: use batch for Batch API JSONL files, or user_data/vision for image edits. Omit in Anthropic Files mode." }, "model": { "type": "string", "description": "Optional TokenLab extension for image file uploads. Defaults to gpt-image-2 and binds the returned file_id to the selected image-edit configuration." } } } } } }, "responses": { "200": { "description": "Uploaded", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FileObject" }, { "$ref": "#/components/schemas/AnthropicFileObject" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/BadRequest" } } }, "get": { "tags": [ "Files" ], "summary": "List files", "operationId": "listFiles", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string" } }, { "name": "after_id", "in": "query", "schema": { "type": "string" }, "description": "Anthropic Files cursor. Return files after this public file id. Requires the Anthropic Files beta header and cannot be combined with before_id." }, { "name": "before_id", "in": "query", "schema": { "type": "string" }, "description": "Anthropic Files cursor. Return files before this public file id. Requires the Anthropic Files beta header and cannot be combined with after_id." }, { "name": "scope_id", "in": "query", "schema": { "type": "string" }, "description": "Reserved Anthropic Files scope cursor. TokenLab currently returns an explicit unsupported error rather than silently ignoring this value." }, { "name": "purpose", "in": "query", "schema": { "type": "string", "enum": [ "batch", "batch_output", "user_data", "vision" ] }, "description": "Optional file purpose filter. batch and batch_output cover Batch API files; user_data and vision cover TokenLab image/reference file bindings. Anthropic Files API mode is selected by Anthropic headers rather than this query parameter." }, { "name": "anthropic-beta", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Include files-api-2025-04-14 to use Anthropic Files API mode." } ], "responses": { "200": { "description": "List of files", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FileListResponse" }, { "$ref": "#/components/schemas/AnthropicFileListResponse" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/files/{file_id}": { "get": { "tags": [ "Files" ], "summary": "Retrieve file", "operationId": "retrieveFile", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "anthropic-beta", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Include files-api-2025-04-14 to use Anthropic Files API mode." } ], "responses": { "200": { "description": "File metadata", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FileObject" }, { "$ref": "#/components/schemas/AnthropicFileObject" } ] } } } }, "404": { "$ref": "#/components/responses/BadRequest" } } }, "delete": { "tags": [ "Files" ], "summary": "Delete file", "description": "Deletes a batch file or a bound image/reference file. When the request includes anthropic-beta: files-api-2025-04-14, the route uses Anthropic Files API mode for the bound workspace.", "operationId": "deleteFile", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "File ID returned by the Files API." }, { "name": "anthropic-beta", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Include files-api-2025-04-14 to use Anthropic Files API mode." } ], "responses": { "200": { "description": "File deleted", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FileDeletedObject" }, { "$ref": "#/components/schemas/AnthropicDeletedFile" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/files/{file_id}/content": { "get": { "tags": [ "Files" ], "summary": "Retrieve file content", "operationId": "retrieveFileContent", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File content", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/batches": { "post": { "tags": [ "Batches" ], "summary": "Create batch", "description": "Creates an OpenAI-compatible batch job.", "operationId": "createBatch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateRequest" } } } }, "responses": { "200": { "description": "Batch created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchObject" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] }, "get": { "tags": [ "Batches" ], "summary": "List batches", "operationId": "listBatches", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of batches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/batches/{batch_id}": { "get": { "tags": [ "Batches" ], "summary": "Retrieve batch", "operationId": "retrieveBatch", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Batch object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchObject" } } } }, "404": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/batches/{batch_id}/cancel": { "post": { "tags": [ "Batches" ], "summary": "Cancel batch", "operationId": "cancelBatch", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancelled batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchObject" } } } }, "404": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/pricing": { "get": { "tags": [ "Models" ], "summary": "List model pricing", "description": "Returns the public pricing surface for active models, with optional provider and tag filters.", "operationId": "getPricing", "parameters": [ { "name": "provider", "in": "query", "description": "Filter by provider ID.", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "description": "Filter by model tag.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pricing information for matching models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/translations": { "post": { "tags": [ "Text" ], "summary": "Translate text", "description": "Translates text into a target language using the current translation request format.", "operationId": "createTranslation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationRequest" } } } }, "responses": { "200": { "description": "Translated text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] } }, "/v1/audio/translations": { "post": { "tags": [ "Audio" ], "summary": "Translate audio", "description": "Transcribes audio and translates the result to English.", "operationId": "createAudioTranslation", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "model": { "type": "string", "default": "whisper-1" }, "prompt": { "type": "string" }, "response_format": { "type": "string" }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 } } } } } }, "responses": { "200": { "description": "Translated transcript", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioTranscriptionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] } }, "/v1/realtime": { "get": { "tags": [ "Realtime" ], "summary": "Connect to realtime WebSocket", "description": "Returns realtime endpoint metadata for normal HTTP GET requests. WebSocket clients use the same path with `?model={model}` and Bearer API key authentication to open realtime speech or multimodal sessions. This public surface is a TokenLab WebSocket subset of OpenAI Realtime; it does not expose its REST helper endpoints such as client secrets, translation client secrets, Calls, or legacy beta session creation.", "operationId": "connectRealtime", "parameters": [ { "name": "model", "in": "query", "required": false, "description": "Realtime model ID to route the WebSocket session. Required for WebSocket upgrade requests; optional for plain HTTP metadata checks.", "schema": { "type": "string" }, "example": "gpt-realtime" } ], "responses": { "101": { "description": "WebSocket connection established" }, "200": { "description": "Realtime endpoint metadata returned for non-WebSocket GET requests", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "websocket_url", "protocol" ], "properties": { "object": { "type": "string", "example": "realtime.endpoint" }, "websocket_url": { "type": "string", "example": "/v1/realtime?model={model}" }, "protocol": { "type": "string", "example": "tokenlab_realtime_proxy" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/images/edits": { "post": { "tags": [ "Images" ], "summary": "Edit image", "description": "Edits an image using multipart image uploads, JSON image URLs, or the official JSON images array for supported GPT Image models.", "operationId": "editImage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "Model to use for image edits. Send this explicitly." }, "prompt": { "type": "string" }, "image_url": { "type": "string", "format": "uri", "description": "Single source image URL. Kept for TokenLab compatibility; use images for the official JSON shape." }, "n": { "type": "integer", "minimum": 1 }, "quality": { "type": "string" }, "size": { "type": "string" }, "aspect_ratio": { "type": "string" }, "resolution": { "type": "string" }, "response_format": { "type": "string" }, "background": { "type": "string", "enum": [ "transparent", "opaque", "auto" ] }, "output_format": { "type": "string", "enum": [ "png", "jpeg", "webp" ] }, "output_compression": { "type": "integer", "minimum": 0, "maximum": 100 }, "compression": { "type": "integer", "minimum": 0, "maximum": 100 }, "moderation": { "type": "string", "enum": [ "auto", "low" ] }, "async": { "type": "boolean", "description": "Return a task before the edited image is ready for models that support public async execution." }, "stream": { "type": "boolean", "description": "Reserved image streaming flag. The public edit route currently rejects true." }, "user": { "type": "string" }, "image_urls": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "string", "format": "uri" }, "description": "Multiple source image URLs. GPT Image edits accept up to 16 source images; xAI Grok Imagine edit models accept at most 3 source images." }, "images": { "type": "array", "minItems": 1, "maxItems": 16, "description": "Official JSON image references for image edits. Provide exactly one of image_url or file_id for each item. GPT Image edits accept up to 16 source images; xAI Grok Imagine edit models accept at most 3 source images.", "items": { "type": "object", "oneOf": [ { "required": [ "image_url" ] }, { "required": [ "file_id" ] } ], "properties": { "image_url": { "type": "string", "format": "uri" }, "file_id": { "type": "string", "description": "A file id returned by TokenLab /v1/files and bound to the same image-edit configuration." } }, "additionalProperties": false } }, "mask": { "type": "object", "oneOf": [ { "required": [ "image_url" ] }, { "required": [ "file_id" ] } ], "properties": { "image_url": { "type": "string", "format": "uri", "description": "Source mask image URL. Public http/https URLs and compatible data URLs are supported by the runtime validation path." }, "file_id": { "type": "string", "description": "A file id returned by TokenLab /v1/files and bound to the same image-edit configuration." } }, "additionalProperties": false, "description": "Optional JSON mask reference for image edits. Provide exactly one of image_url or file_id. Multipart requests can also send mask as a file part." } }, "additionalProperties": true, "anyOf": [ { "required": [ "image_url" ] }, { "required": [ "image_urls" ] }, { "required": [ "images" ] } ] } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "model", "prompt" ], "properties": { "image": { "oneOf": [ { "type": "string", "format": "binary" }, { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "string", "format": "binary" } } ], "description": "Source image file(s). Repeat image for multiple source images. GPT Image edits accept up to 16 images; xAI Grok Imagine edit models accept at most 3 source images." }, "mask": { "type": "string", "format": "binary" }, "model": { "type": "string", "description": "Model to use for image edits. Send this explicitly, for example gpt-image-2." }, "prompt": { "type": "string" }, "n": { "type": "integer", "minimum": 1 }, "quality": { "type": "string" }, "size": { "type": "string" }, "aspect_ratio": { "type": "string" }, "resolution": { "type": "string" }, "response_format": { "type": "string" }, "background": { "type": "string", "enum": [ "transparent", "opaque", "auto" ] }, "output_format": { "type": "string", "enum": [ "png", "jpeg", "webp" ] }, "output_compression": { "type": "integer", "minimum": 0, "maximum": 100 }, "compression": { "type": "integer", "minimum": 0, "maximum": 100 }, "moderation": { "type": "string", "enum": [ "auto", "low" ] }, "async": { "type": "boolean" }, "stream": { "type": "boolean" }, "user": { "type": "string" }, "image[]": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "string", "format": "binary" }, "description": "Alternative repeated multipart field name for multiple source images. The same model-specific limits apply: GPT Image up to 16, xAI Grok Imagine up to 3." } }, "additionalProperties": true, "anyOf": [ { "required": [ "image" ] }, { "required": [ "image[]" ] } ] } } } }, "responses": { "200": { "description": "Edited image response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] } }, "/v1/images/variations": { "post": { "tags": [ "Images" ], "summary": "Create image variation", "description": "Generates image variations from a multipart image upload.", "operationId": "createImageVariation", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "model", "image" ], "properties": { "image": { "type": "string", "format": "binary" }, "model": { "type": "string", "description": "Required model identifier for legacy variation-compatible routes. For current image-to-image workflows, prefer /v1/images/edits with gpt-image-2 or /v1/images/generations with an image-to-image model." }, "n": { "type": "integer", "minimum": 1 }, "size": { "type": "string" }, "response_format": { "type": "string" }, "user": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Variation response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] } }, "/v1beta/models": { "get": { "tags": [ "Gemini" ], "summary": "List Gemini-native models", "description": "Lists enabled models through the Gemini-compatible v1beta model discovery surface.", "operationId": "listGeminiModels", "parameters": [ { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "pageToken", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Gemini model list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiModelListResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiErrorResponse" } } } } }, "security": [] } }, "/v1beta/models/{model}": { "get": { "tags": [ "Gemini" ], "summary": "Get Gemini-native model", "description": "Retrieves model metadata through the Gemini-compatible v1beta surface.", "operationId": "getGeminiModel", "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Gemini model details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiModelInfo" } } } }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiErrorResponse" } } } } }, "security": [] } }, "/v1/worlds/media-assets/prepare-upload": { "post": { "tags": [ "Worlds" ], "summary": "Prepare World Labs media asset upload", "description": "Creates a World Labs media asset record and returns a signed upload URL. Use the returned media_asset_id from native world_prompt objects with source=media_asset. Media assets can only be used by the organization that created them.", "operationId": "prepareWorldMediaAssetUpload", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "file_name", "kind" ], "properties": { "file_name": { "type": "string", "maxLength": 64, "description": "File name, such as landscape.jpg." }, "kind": { "type": "string", "enum": [ "image", "video" ], "description": "High-level media type." }, "extension": { "type": [ "string", "null" ], "description": "File extension without dot, such as jpg, png, or mp4." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Optional application metadata." } } } } } }, "responses": { "200": { "description": "Upload prepared", "content": { "application/json": { "schema": { "type": "object", "required": [ "media_asset", "upload_info" ], "properties": { "media_asset": { "type": "object", "required": [ "media_asset_id", "file_name" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "file_name": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "video" ] }, "media_asset_id": { "type": "string" }, "extension": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "upload_info": { "type": "object", "required": [ "upload_url" ], "properties": { "upload_method": { "type": "string" }, "upload_url": { "type": "string", "format": "uri" }, "curl_example": { "type": "string" }, "required_headers": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/v1/worlds/media-assets/{id}": { "get": { "tags": [ "Worlds" ], "summary": "Get World Labs media asset", "description": "Retrieves metadata for a World Labs media asset prepared through TokenLab. The media asset must belong to the authenticated organization.", "operationId": "getWorldMediaAsset", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset ID." } ], "responses": { "200": { "description": "Media asset metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "media_asset_id", "file_name" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "file_name": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "video" ] }, "media_asset_id": { "type": "string" }, "extension": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/v1/worlds/generations": { "post": { "tags": [ "Worlds" ], "summary": "Create world generation task", "description": "Creates a World Labs Marble world generation task for TokenLab-supported Marble models. Returns a task ID for polling. TokenLab supports native world_prompt media_asset references when the media asset was prepared through TokenLab.", "operationId": "createWorld", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "model": { "type": "string", "default": "marble-1.0", "enum": [ "marble-1.0", "marble-1.1", "marble-1.1-plus" ], "description": "Marble model to use. Defaults to marble-1.0 to match the current World Labs compatibility default when model is omitted." }, "prompt": { "type": "string", "description": "Text prompt used for text or guided image/video world generation." }, "display_name": { "type": "string", "description": "Optional display name for the generated world, up to 64 characters.", "maxLength": 64 }, "world_prompt": { "type": "object", "additionalProperties": true, "description": "Native World Labs world_prompt object for advanced callers. Supported prompt types are text, image, multi-image, and video. Content references may use source=media_asset with a media_asset_id prepared by /v1/worlds/media-assets/prepare-upload." }, "image": { "type": "string", "description": "Base64 or data URL image prompt." }, "image_url": { "type": "string", "format": "uri", "description": "Image URL prompt." }, "images": { "type": "array", "description": "Shortcut multi-image prompts. Provide up to 4 images. Use native world_prompt.reconstruct_images=true for up to 8 images.", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "uri": { "type": "string" }, "image_url": { "type": "string" }, "url": { "type": "string" }, "azimuth": { "type": "number" } }, "additionalProperties": true } ] }, "maxItems": 4 }, "video_url": { "type": "string", "format": "uri", "description": "Video URL prompt." }, "is_pano": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "auto" ] } ], "description": "Whether an image prompt is an existing panorama. Use true for pano input, false for single-image input, or auto." }, "seed": { "type": "integer", "description": "Optional seed from 0 through 4294967295.", "minimum": 0, "maximum": 4294967295 }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 32 }, "description": "Optional World Labs tags. Provide up to 10 tags, each up to 32 characters.", "maxItems": 10 }, "permission": { "type": "object", "additionalProperties": true, "description": "Optional World Labs permission object." }, "user": { "type": "string", "description": "End-user identifier." } }, "anyOf": [ { "required": [ "world_prompt" ] }, { "required": [ "prompt" ] }, { "required": [ "image" ] }, { "required": [ "image_url" ] }, { "required": [ "images" ] }, { "required": [ "video_url" ] } ] } } } }, "responses": { "200": { "description": "Task created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "task_id": { "type": "string" }, "operation_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "poll_url": { "type": "string" }, "world_id": { "type": "string" }, "world_marble_url": { "type": "string" }, "model_url": { "type": "string" }, "glb_url": { "type": "string" }, "pano_url": { "type": "string" }, "thumbnail_url": { "type": "string" }, "caption": { "type": "string" }, "cost": { "type": "object", "additionalProperties": true }, "error": { "$ref": "#/components/schemas/AsyncTaskError" }, "error_details": { "$ref": "#/components/schemas/AsyncTaskErrorDetails" } }, "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ] } }, "/v1/worlds/generations/{id}": { "get": { "tags": [ "Worlds" ], "summary": "Get world generation status", "description": "Retrieves the status and result of a World Labs Marble world generation task.", "operationId": "getWorldStatus", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "World generation task ID." } ], "responses": { "200": { "description": "Task status", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string" }, "task_id": { "type": "string" }, "operation_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "timeout" ] }, "world_id": { "type": "string" }, "world_marble_url": { "type": "string" }, "model_url": { "type": "string" }, "glb_url": { "type": "string" }, "pano_url": { "type": "string" }, "thumbnail_url": { "type": "string" }, "caption": { "type": "string" }, "cost": { "type": "object", "additionalProperties": true }, "error": { "$ref": "#/components/schemas/AsyncTaskError" }, "error_details": { "$ref": "#/components/schemas/AsyncTaskErrorDetails" } }, "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/worlds/list": { "post": { "tags": [ "Worlds" ], "summary": "List World Labs worlds", "description": "Lists World Labs worlds created through TokenLab for the authenticated organization. Results only include resources created through TokenLab.", "operationId": "listWorlds", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "page_token": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "enum": [ "SUCCEEDED", "PENDING", "FAILED", "RUNNING" ] }, "model": { "type": [ "string", "null" ], "enum": [ "marble-1.0", "marble-1.1", "marble-1.1-plus", "marble-1.0-draft" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "is_public": { "type": [ "boolean", "null" ] }, "created_after": { "type": [ "string", "null" ], "format": "date-time" }, "created_before": { "type": [ "string", "null" ], "format": "date-time" }, "sort_by": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "TokenLab extension for ascending or descending order." } } } } } }, "responses": { "200": { "description": "World list", "content": { "application/json": { "schema": { "type": "object", "required": [ "worlds" ], "properties": { "worlds": { "type": "array", "items": { "type": "object", "required": [ "world_id" ], "properties": { "display_name": { "type": "string" }, "world_id": { "type": "string" }, "world_marble_url": { "type": "string", "format": "uri" }, "assets": { "type": "object", "additionalProperties": true }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "model": { "type": [ "string", "null" ] }, "permission": { "type": "object", "additionalProperties": true }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "world_prompt": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "next_page_token": { "type": [ "string", "null" ] } }, "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/v1/worlds/{id}": { "get": { "tags": [ "Worlds" ], "summary": "Get World Labs world", "description": "Retrieves a World Labs world generated through TokenLab. The world ID must be owned by the authenticated organization.", "operationId": "getWorld", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "World ID." } ], "responses": { "200": { "description": "World details", "content": { "application/json": { "schema": { "type": "object", "required": [ "world_id" ], "properties": { "display_name": { "type": "string" }, "world_id": { "type": "string" }, "world_marble_url": { "type": "string", "format": "uri" }, "assets": { "type": "object", "additionalProperties": true }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "model": { "type": [ "string", "null" ] }, "permission": { "type": "object", "additionalProperties": true }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "world_prompt": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Worlds" ], "summary": "Delete World Labs world", "description": "Deletes a World Labs world generated through TokenLab. This permanently deletes the world and associated assets when World Labs accepts the deletion. TokenLab keeps task status records for usage history.", "operationId": "deleteWorld", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "World ID." } ], "responses": { "200": { "description": "World deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted", "world_id" ], "properties": { "deleted": { "type": "boolean" }, "world_id": { "type": "string" } }, "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/v1/videos/assets/groups": { "post": { "tags": [ "Video" ], "summary": "Create Seedance material asset group", "description": "Creates a TokenLab Seedance virtual-avatar material group. Real-person material groups are created by GetVisualValidateResult after the H5 validation succeeds.", "operationId": "createSeedanceMaterialAssetGroup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedanceMaterialAssetGroupCreateRequest" }, "examples": { "virtual_avatar_group": { "summary": "Create a virtual-avatar material group", "value": { "library_type": "aigc_avatar", "group_name": "Product references", "description": "Reusable product shots" } } } } } }, "responses": { "201": { "description": "Material asset group created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedanceMaterialAssetGroup" }, "examples": { "group_created": { "summary": "Material group created", "value": { "id": "group-20260720123456-vrt01", "object": "seedance.material_asset_group", "library_type": "aigc_avatar", "group_name": "Product references", "description": "Reusable product shots", "status": "ACTIVE", "metadata": null, "created_at": 1782998400000 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Material group mapping conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MaterialLibraryUnavailable" } } }, "get": { "tags": [ "Video" ], "summary": "List Seedance material asset groups", "description": "Lists Seedance material groups owned by the authenticated organization. Real-person groups are returned after GetVisualValidateResult succeeds.", "operationId": "listSeedanceMaterialAssetGroups", "parameters": [ { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "page_token", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "DELETED" ] } }, { "name": "library_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "aigc_avatar", "liveness_face" ] }, "description": "Filter by TokenLab material library class." }, { "name": "project_name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "default": "default" }, "description": "Project scope for the material resource." } ], "responses": { "200": { "description": "Material asset groups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedanceMaterialAssetGroupList" }, "examples": { "groups": { "summary": "Material groups", "value": { "groups": [ { "id": "group-20260720123456-vrt01", "object": "seedance.material_asset_group", "library_type": "aigc_avatar", "group_name": "Product references", "description": "Reusable product shots", "status": "ACTIVE", "metadata": null, "created_at": 1782998400000 }, { "id": "group-20260720123456-real1", "object": "seedance.material_asset_group", "library_type": "liveness_face", "group_name": "Creator A", "description": null, "status": "ACTIVE", "metadata": null, "created_at": 1782998400000 } ], "next_page_token": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/videos/assets/groups/{groupId}": { "get": { "tags": [ "Video" ], "summary": "Get Seedance material asset group", "description": "Retrieves one TokenLab Seedance material group.", "operationId": "getSeedanceMaterialAssetGroup", "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "group-20260720123456-vrt01" }, { "name": "project_name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "default": "default" }, "description": "Project scope for the material resource." } ], "responses": { "200": { "description": "Material asset group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedanceMaterialAssetGroup" }, "examples": { "group": { "summary": "Material group", "value": { "id": "group-20260720123456-vrt01", "object": "seedance.material_asset_group", "library_type": "aigc_avatar", "group_name": "Product references", "description": "Reusable product shots", "status": "ACTIVE", "metadata": null, "created_at": 1782998400000 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MaterialLibraryUnavailable" } } }, "put": { "tags": [ "Video" ], "summary": "Update Seedance material asset group", "description": "Updates display metadata for a TokenLab Seedance material group.", "operationId": "updateSeedanceMaterialAssetGroup", "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "group-20260720123456-vrt01" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedanceMaterialAssetGroupUpdateRequest" }, "examples": { "update_group": { "summary": "Update group display fields", "value": { "group_name": "Updated references", "description": "Images approved for summer videos" } } } } } }, "responses": { "200": { "description": "Material asset group updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedanceMaterialAssetGroup" }, "examples": { "group_updated": { "summary": "Material group updated", "value": { "id": "group-20260720123456-vrt01", "object": "seedance.material_asset_group", "library_type": "aigc_avatar", "group_name": "Updated references", "description": "Images approved for summer videos", "status": "ACTIVE", "metadata": null, "created_at": 1782998400000 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MaterialLibraryUnavailable" } } }, "delete": { "tags": [ "Video" ], "summary": "Delete Seedance material asset group", "description": "Deletes a TokenLab Seedance material group and its material assets. The operation is irreversible when accepted.", "operationId": "deleteSeedanceMaterialAssetGroup", "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "group-20260720123456-vrt01" }, { "name": "project_name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "default": "default" }, "description": "Project scope for the material resource." } ], "responses": { "200": { "description": "Material asset group deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedanceMaterialAssetDeleteResponse" }, "examples": { "group_deleted": { "summary": "Material group deleted", "value": { "deleted": true, "id": "group-20260720123456-vrt01" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/MaterialLibraryUnavailable" } } } }, "/api/v3/contents/generations/tasks": { "post": { "tags": [ "Seedance Volc Compatible" ], "summary": "Create Seedance task (Volc wire-compatible)", "description": "Creates a Seedance 2.0 video task with the official Volc REST body and response shape. Authentication uses a TokenLab Bearer API key. TokenLab additionally accepts an optional Idempotency-Key header so a client can recover the same task ID after a lost create response.", "operationId": "createVolcCompatibleSeedanceTask", "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Client-generated key for idempotent REST task creation. Under the same TokenLab API credential, reusing the same key with the same JSON body returns the original cgt task ID; reusing it with a different body returns 409. Keep the credential, key, and request body unchanged when retrying after a timeout or disconnect." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceCreateTaskRequest" }, "example": { "model": "doubao-seedance-2-0-260128", "content": [ { "type": "text", "text": "A cinematic forest at sunset" }, { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://example.com/ref.png" } } ], "ratio": "16:9", "duration": 5, "resolution": "720p", "generate_audio": false } } } }, "responses": { "200": { "description": "Task created", "headers": { "Idempotency-Replayed": { "description": "Present with value true when this response recovered an earlier create request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceCreateTaskResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceError" } } } }, "401": { "description": "Missing or unsupported authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceError" } } } }, "409": { "description": "Idempotency key conflict or original request still in progress", "headers": { "Retry-After": { "description": "Seconds to wait before retrying an in-progress request with the same key and body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceError" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceError" } } } }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } } }, "get": { "tags": [ "Seedance Volc Compatible" ], "summary": "List Seedance tasks (Volc-compatible)", "description": "Lists recent Seedance compatibility tasks for the authenticated organization.", "operationId": "listVolcCompatibleSeedanceTasks", "parameters": [ { "name": "page_num", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 1 }, "description": "Page number." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 20 }, "description": "Page size." }, { "name": "filter.status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled", "expired" ] }, "description": "Filter by task status." }, { "name": "filter.task_ids", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Exact task IDs. Repeat filter.task_ids for multiple IDs." }, { "name": "filter.model", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by model identifier." }, { "name": "filter.service_tier", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by service tier." } ], "responses": { "200": { "description": "Task list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceTaskListResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceError" } } } }, "401": { "description": "Missing or unsupported authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceError" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceError" } } } } } } }, "/api/v3/contents/generations/tasks/{id}": { "get": { "tags": [ "Seedance Volc Compatible" ], "summary": "Get Seedance task (Volc-compatible)", "operationId": "getVolcCompatibleSeedanceTask", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Compatibility task ID returned by the create endpoint. IDs start with cgt-." } ], "responses": { "200": { "description": "Task status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceTask" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceError" } } } }, "401": { "description": "Missing or unsupported authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceError" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceError" } } } } } }, "delete": { "tags": [ "Seedance Volc Compatible" ], "summary": "Cancel Seedance task (Volc-compatible)", "operationId": "deleteVolcCompatibleSeedanceTask", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Compatibility task ID returned by the create endpoint. IDs start with cgt-." } ], "responses": { "200": { "description": "Cancellation accepted. The response body is empty." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceError" } } } }, "401": { "description": "Missing or unsupported authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceError" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceError" } } } } } } }, "/api/v3": { "get": { "tags": [ "Seedance Volc Compatible" ], "summary": "Seedance Action dispatcher (GET)", "description": "Dispatches Volc-style Action requests. Use Version=2024-01-01 or omit Version.", "operationId": "dispatchVolcCompatibleSeedanceActionGet", "parameters": [ { "name": "Action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "CreateContentsGenerationsTasks", "GetContentsGenerationsTask", "ListContentsGenerationsTasks", "DeleteContentsGenerationsTasks" ] } }, { "name": "Version", "in": "query", "required": false, "schema": { "type": "string", "default": "2024-01-01" } } ], "responses": { "200": { "description": "Action response. Create/Get/List actions return JSON; DeleteContentsGenerationsTasks returns an empty body.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/VolcSeedanceCreateTaskResponse" }, { "$ref": "#/components/schemas/VolcSeedanceTask" }, { "$ref": "#/components/schemas/VolcSeedanceTaskListResponse" } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceError" } } } }, "401": { "description": "Missing or unsupported authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceError" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolcSeedanceError" } } } } } }, "post": { "tags": [ "Seedance Volc Compatible" ], "summary": "Seedance Action dispatcher (POST)", "description": "Dispatches Volc-style Action requests with TokenLab Bearer authentication. Real-person validation and material asset Actions use Version=2024-01-01 and are POST-only. The same POST contract is also available at the API root for endpoint-only migration from Volcengine.", "operationId": "dispatchVolcCompatibleSeedanceActionPost", "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" }, { "name": "Action", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "CreateContentsGenerationsTasks", "GetContentsGenerationsTask", "ListContentsGenerationsTasks", "DeleteContentsGenerationsTasks", "CreateVisualValidateSession", "GetVisualValidateResult", "CreateAssetGroup", "ListAssetGroups", "GetAssetGroup", "UpdateAssetGroup", "DeleteAssetGroup", "CreateAsset", "ListAssets", "GetAsset", "UpdateAsset", "DeleteAsset" ] } }, { "name": "Version", "in": "query", "required": false, "schema": { "type": "string", "default": "2024-01-01" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/VolcCreateVisualValidateSessionRequest" }, { "$ref": "#/components/schemas/VolcGetVisualValidateResultRequest" }, { "$ref": "#/components/schemas/VolcMaterialActionRequest" }, { "type": "object", "additionalProperties": true } ] } } } }, "responses": { "200": { "description": "Action response. Content-generation actions return task JSON; real-person validation and material asset actions return the official ResponseMetadata + Result envelope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/VolcSeedanceCreateTaskResponse" }, { "$ref": "#/components/schemas/VolcSeedanceTask" }, { "$ref": "#/components/schemas/VolcSeedanceTaskListResponse" }, { "$ref": "#/components/schemas/VolcCreateVisualValidateSessionResponse" }, { "$ref": "#/components/schemas/VolcGetVisualValidateResultResponse" }, { "$ref": "#/components/schemas/VolcMaterialActionResponse" } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/VolcSeedanceError" }, { "$ref": "#/components/schemas/VolcVisualValidationError" } ] } } } }, "401": { "description": "Missing or unsupported authentication", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/VolcSeedanceError" }, { "$ref": "#/components/schemas/VolcVisualValidationError" } ] } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/VolcSeedanceError" }, { "$ref": "#/components/schemas/VolcVisualValidationError" } ] } } } }, "405": { "description": "Action does not support this HTTP method", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/VolcSeedanceError" }, { "$ref": "#/components/schemas/VolcVisualValidationError" } ] } } } }, "409": { "description": "Material group mapping conflict", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/VolcSeedanceError" }, { "$ref": "#/components/schemas/VolcVisualValidationError" } ] } } } }, "422": { "description": "Real-person validation is unavailable for the current account configuration", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/VolcSeedanceError" }, { "$ref": "#/components/schemas/VolcVisualValidationError" } ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/VolcSeedanceError" }, { "$ref": "#/components/schemas/VolcVisualValidationError" } ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/VolcSeedanceError" }, { "$ref": "#/components/schemas/VolcVisualValidationError" } ] } } } }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } } } }, "/v1/systemone": { "post": { "tags": [ "Decisions" ], "summary": "Evaluate decision questions", "description": "Evaluate state with named probability, choice, and ordered score questions. Synchronous JSON only. Token usage is reported when available; zero-priced output tokens are still included.", "operationId": "createSystemOneDecision", "parameters": [ { "$ref": "#/components/parameters/DeliveryPolicy" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "state", "questions" ], "properties": { "model": { "type": "string", "minLength": 1 }, "state": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} } ] }, "questions": { "type": "object", "minProperties": 1, "additionalProperties": { "oneOf": [ { "type": "object", "required": [ "type", "instructions" ], "properties": { "type": { "type": "string", "enum": [ "noul" ] }, "instructions": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} } ] }, "criteria": { "type": "object", "properties": { "true": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} } ] }, "false": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} } ] } }, "required": [ "true", "false" ], "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "instructions", "criteria" ], "properties": { "type": { "type": "string", "enum": [ "choice" ] }, "instructions": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} } ] }, "criteria": { "type": "object", "minProperties": 1, "maxProperties": 255, "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} }, { "type": "null" } ] } } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "instructions", "criteria" ], "properties": { "type": { "type": "string", "enum": [ "score" ] }, "instructions": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} } ] }, "criteria": { "type": "array", "minItems": 2, "maxItems": 10, "items": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} } ] } } }, "additionalProperties": false } ] } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Decision results", "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "answers" ], "properties": { "id": { "type": "string" }, "model": { "type": "string" }, "answers": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "object", "required": [ "type", "noul" ], "properties": { "type": { "type": "string", "enum": [ "noul" ] }, "noul": { "type": "number", "minimum": 0, "maximum": 1 } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "choice" ], "properties": { "type": { "type": "string", "enum": [ "choice" ] }, "choice": { "type": "string" }, "probabilities": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 } }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "score" ], "properties": { "type": { "type": "string", "enum": [ "score" ] }, "score": { "type": "number", "minimum": 0 }, "probabilities": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 } }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "legend": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} } ] } } }, "additionalProperties": false } ] } }, "usage": { "type": "object", "required": [ "input_tokens", "output_tokens" ], "properties": { "input_tokens": { "type": "integer", "minimum": 0 }, "output_tokens": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/DeliveryUnavailable" } } } }, "/v1/management/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "description": "Requires a workspace Management Token (mt-...), created at Dashboard > API > Management Tokens. Send Authorization: Bearer mt-.... Inference API keys (sk-...) and webhook signing secrets (whsec_...) are not accepted. Only the token workspace is accessible.", "operationId": "listWebhooks", "security": [ { "ManagementTokenAuth": [] } ], "responses": { "200": { "description": "List webhook endpoints result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Webhook not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Endpoint quota reached or endpoint paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-mint": { "metadata": { "playground": "simple" } }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook endpoint", "description": "Requires a workspace Management Token (mt-...), created at Dashboard > API > Management Tokens. Send Authorization: Bearer mt-.... Inference API keys (sk-...) and webhook signing secrets (whsec_...) are not accepted. Only the token workspace is accessible. The full whsec_ signing secret is returned only on creation or rotation. Store it securely; GET/list never return it. Rotation takes effect immediately for new deliveries; already in-flight deliveries can still use the previous secret. Up to 10 endpoints per workspace. Subscriptions cover future terminal async task events; existing tasks are not replayed.", "operationId": "createWebhook", "security": [ { "ManagementTokenAuth": [] } ], "responses": { "201": { "description": "Create webhook endpoint result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedWebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Webhook not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Endpoint quota reached or endpoint paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-mint": { "metadata": { "playground": "simple" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointRequest" } } } } } }, "/v1/management/webhooks/{webhookId}": { "get": { "tags": [ "Webhooks" ], "summary": "Retrieve webhook endpoint", "description": "Requires a workspace Management Token (mt-...), created at Dashboard > API > Management Tokens. Send Authorization: Bearer mt-.... Inference API keys (sk-...) and webhook signing secrets (whsec_...) are not accepted. Only the token workspace is accessible.", "operationId": "getWebhook", "security": [ { "ManagementTokenAuth": [] } ], "responses": { "200": { "description": "Retrieve webhook endpoint result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Webhook not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Endpoint quota reached or endpoint paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-mint": { "metadata": { "playground": "simple" } }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] }, "patch": { "tags": [ "Webhooks" ], "summary": "Update webhook endpoint", "description": "Requires a workspace Management Token (mt-...), created at Dashboard > API > Management Tokens. Send Authorization: Bearer mt-.... Inference API keys (sk-...) and webhook signing secrets (whsec_...) are not accepted. Only the token workspace is accessible.", "operationId": "updateWebhook", "security": [ { "ManagementTokenAuth": [] } ], "responses": { "200": { "description": "Update webhook endpoint result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Webhook not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Endpoint quota reached or endpoint paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-mint": { "metadata": { "playground": "simple" } }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpointRequest" } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete webhook endpoint", "description": "Requires a workspace Management Token (mt-...), created at Dashboard > API > Management Tokens. Send Authorization: Bearer mt-.... Inference API keys (sk-...) and webhook signing secrets (whsec_...) are not accepted. Only the token workspace is accessible.", "operationId": "deleteWebhook", "security": [ { "ManagementTokenAuth": [] } ], "responses": { "200": { "description": "Delete webhook endpoint result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedWebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Webhook not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Endpoint quota reached or endpoint paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-mint": { "metadata": { "playground": "simple" } }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] } }, "/v1/management/webhooks/{webhookId}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate webhook signing secret", "description": "Requires a workspace Management Token (mt-...), created at Dashboard > API > Management Tokens. Send Authorization: Bearer mt-.... Inference API keys (sk-...) and webhook signing secrets (whsec_...) are not accepted. Only the token workspace is accessible. The full whsec_ signing secret is returned only on creation or rotation. Store it securely; GET/list never return it. Rotation takes effect immediately for new deliveries; already in-flight deliveries can still use the previous secret.", "operationId": "rotateWebhookSecret", "security": [ { "ManagementTokenAuth": [] } ], "responses": { "200": { "description": "Rotate webhook signing secret result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedWebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Webhook not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Endpoint quota reached or endpoint paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-mint": { "metadata": { "playground": "simple" } }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] } }, "/v1/management/webhooks/{webhookId}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Send a test webhook", "description": "Requires a workspace Management Token (mt-...), created at Dashboard > API > Management Tokens. Send Authorization: Bearer mt-.... Inference API keys (sk-...) and webhook signing secrets (whsec_...) are not accepted. Only the token workspace is accessible. Sends webhook.test through the same signed delivery path. HTTP 200 reports a persisted attempt; inspect outcome and http_status to determine receiver success. Resume a paused endpoint before testing.", "operationId": "testWebhook", "security": [ { "ManagementTokenAuth": [] } ], "responses": { "200": { "description": "Send a test webhook result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Webhook not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Endpoint quota reached or endpoint paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-mint": { "metadata": { "playground": "simple" } }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] } }, "/v1/management/webhooks/{webhookId}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook deliveries", "description": "Requires a workspace Management Token (mt-...), created at Dashboard > API > Management Tokens. Send Authorization: Bearer mt-.... Inference API keys (sk-...) and webhook signing secrets (whsec_...) are not accepted. Only the token workspace is accessible. Returns cumulative attempts and latest outcome per event and endpoint. A previously confirmed delivery remains delivered even if a duplicate fails. History contains no payloads or signing secrets; no manual replay operation is provided.", "operationId": "listWebhookDeliveries", "security": [ { "ManagementTokenAuth": [] } ], "responses": { "200": { "description": "List webhook deliveries result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Webhook not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Endpoint quota reached or endpoint paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-mint": { "metadata": { "playground": "simple" } }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ] } } }, "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" ], "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", "description": "Streaming options such as usage chunk inclusion.", "additionalProperties": true }, "parallel_tool_calls": { "type": "boolean", "description": "Whether the model may issue parallel tool calls." }, "reasoning_effort": { "type": "string", "description": "Reasoning effort hint for compatible model families." }, "logprobs": { "type": "boolean", "description": "Whether to return log probabilities for output tokens." }, "top_logprobs": { "type": "integer", "minimum": 0, "maximum": 20, "description": "Number of most likely tokens to return at each position when logprobs is enabled." }, "logit_bias": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Per-token logit bias map." }, "modalities": { "type": "array", "items": { "type": "string" }, "description": "Requested output modalities such as text or audio." }, "audio": { "type": "object", "additionalProperties": true, "description": "Audio output configuration when requesting audio modality." }, "translation_options": { "type": "object", "required": [ "target_lang" ], "properties": { "source_lang": { "type": "string", "description": "Source language code. Omit when the model supports automatic detection." }, "target_lang": { "type": "string", "description": "Target language code." } }, "description": "Language settings for models that translate audio or video through Chat Completions." }, "prediction": { "type": "object", "additionalProperties": true, "description": "Prediction hints for models that support draft or speculative decoding." }, "service_tier": { "type": [ "string", "null" ], "description": "Service tier hint where supported by the model." } }, "additionalProperties": true }, "ChatMessage": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "function", "tool", "developer" ], "description": "The role of the message author" }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ] } }, "required": [ "type", "image_url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "video_url" ] }, "video_url": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } }, "required": [ "type", "video_url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "input_audio" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string", "description": "Public audio URL or Base64 data URL." }, "format": { "type": "string" } }, "required": [ "data" ] } }, "required": [ "type", "input_audio" ] } ] } }, { "type": "null" } ], "description": "Message content (text or multimodal)" }, "name": { "type": "string", "description": "Name of the function/tool (for function/tool messages)" }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCall" }, "description": "Tool calls made by the assistant" }, "tool_call_id": { "type": "string", "description": "ID of the tool call being responded to" } } }, "Tool": { "type": "object", "required": [ "type", "function" ], "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "Tool type (currently only 'function')" }, "function": { "$ref": "#/components/schemas/FunctionDefinition" } } }, "FunctionDefinition": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 64, "description": "Function name" }, "description": { "type": "string", "description": "Function description" }, "parameters": { "type": "object", "description": "JSON Schema for function parameters" } } }, "ToolCall": { "type": "object", "required": [ "id", "type", "function" ], "properties": { "id": { "type": "string", "description": "Tool call ID" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } }, "required": [ "name", "arguments" ] } } }, "ChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the completion", "example": "chatcmpl-abc123" }, "object": { "type": "string", "enum": [ "chat.completion" ], "description": "Object type" }, "created": { "type": "integer", "description": "Unix timestamp of creation" }, "model": { "type": "string", "description": "Model used for completion" }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/ChatChoice" } }, "usage": { "$ref": "#/components/schemas/UsageInfo" }, "system_fingerprint": { "type": "string", "description": "System fingerprint" } }, "required": [ "id", "object", "created", "model", "choices" ] }, "ChatChoice": { "type": "object", "properties": { "index": { "type": "integer", "description": "Choice index" }, "message": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "content": { "type": [ "string", "null" ] }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCall" } }, "refusal": { "type": [ "string", "null" ] } } }, "finish_reason": { "type": [ "string", "null" ], "enum": [ "stop", "length", "tool_calls", "content_filter" ], "description": "Reason for completion" } }, "required": [ "index", "message", "finish_reason" ] }, "UsageInfo": { "type": "object", "properties": { "prompt_tokens": { "type": "integer", "description": "Tokens in the prompt" }, "completion_tokens": { "type": "integer", "description": "Tokens in the completion" }, "total_tokens": { "type": "integer", "description": "Total tokens used" }, "prompt_tokens_details": { "type": "object", "properties": { "cached_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" } } }, "completion_tokens_details": { "type": "object", "properties": { "reasoning_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" } } } } }, "EmbeddingRequest": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "ID of the model to use", "example": "text-embedding-3-small" }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "number" } }, { "type": "array", "items": { "type": "array", "items": { "type": "number" } } } ], "description": "Input text(s) or token array(s) to embed." }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ], "default": "float", "description": "Output format" }, "dimensions": { "type": "integer", "minimum": 1, "description": "Output vector dimensions" }, "user": { "type": "string", "description": "End-user identifier" } } }, "EmbeddingResponse": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "index": { "type": "integer" }, "embedding": { "oneOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "string" } ] } }, "required": [ "object", "index", "embedding" ] } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } }, "required": [ "prompt_tokens", "total_tokens" ] } }, "required": [ "object", "data", "model", "usage" ] }, "ImageGenerationRequest": { "type": "object", "required": [ "model", "prompt" ], "properties": { "prompt": { "type": "string", "maxLength": 4000, "description": "Image description" }, "model": { "type": "string", "description": "Model to use. Send this explicitly; query GET /v1/models?recommended_for=image for current recommendations." }, "operation": { "type": "string", "enum": [ "text-to-image", "image-to-image", "image-edit" ], "description": "Public image operation family. Reference-image models use image-to-image with image_url, image_urls, or reference_image_urls." }, "image_url": { "type": "string", "format": "uri", "description": "Single reference image URL for compatible image-to-image models." }, "image_urls": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "string", "format": "uri" }, "description": "Reference image URLs for compatible image-to-image models." }, "reference_image_urls": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "string", "format": "uri" }, "description": "Alias used by compatible reference-image model families." }, "mask_url": { "type": "string", "format": "uri", "description": "Optional mask URL for compatible image operations." }, "n": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "description": "Number of images to generate" }, "size": { "type": "string", "description": "Image size. Defaults are model-specific. For gpt-image-2, omit this field or use auto for automatic sizing, or send WIDTHxHEIGHT; custom dimensions must both be multiples of 16, longest edge <= 3840px, long/short ratio <= 3:1, and total pixels between 655,360 and 8,294,400." }, "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 models may accept different values; check the model details." }, "style": { "type": "string", "enum": [ "vivid", "natural" ], "description": "Optional model-specific style selector. Only send when the selected model documents support for this parameter." }, "expand_prompt": { "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." }, "seed": { "type": "integer", "description": "Seed for deterministic-compatible image models." }, "response_format": { "type": "string", "enum": [ "url", "b64_json" ], "default": "url", "description": "Response format" }, "async": { "type": "boolean", "description": "Return a task before the final image is ready when the selected model supports public async execution." }, "background": { "type": "string", "enum": [ "transparent", "opaque", "auto" ], "description": "Background handling for compatible image flows. For gpt-image-2 generation and edits, accepted values are auto and opaque; transparent is not supported. Other models may support different values." }, "output_format": { "type": "string", "enum": [ "png", "jpeg", "webp" ], "description": "Output image format for compatible image models such as gpt-image-2" }, "output_compression": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Output compression level from 0 to 100 for compressed formats" }, "compression": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Alias for output_compression when supported by the selected model" }, "moderation": { "type": "string", "enum": [ "auto", "low" ], "description": "Moderation strictness for compatible image models such as gpt-image-2" }, "stream": { "type": "boolean", "description": "Reserved image streaming flag. The public generation route currently rejects true." }, "aspect_ratio": { "type": "string", "description": "Aspect-ratio selector for compatible image model families." }, "resolution": { "type": "string", "description": "Resolution selector for compatible image model families." }, "user": { "type": "string", "description": "End-user identifier" } } }, "ImageGenerationMultipartRequest": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "Model to use. Send this explicitly." }, "prompt": { "type": "string", "maxLength": 4000, "description": "Image description" }, "operation": { "type": "string", "enum": [ "text-to-image", "image-to-image", "image-edit" ] }, "image": { "type": "string", "format": "binary", "description": "Local reference image upload for compatible image-to-image models." }, "image_urls": { "type": "string", "description": "Comma-separated reference image URLs." }, "reference_image_urls": { "type": "string", "description": "Comma-separated reference image URLs for compatible model families." }, "mask_url": { "type": "string", "format": "uri" }, "n": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 }, "quality": { "type": "string" }, "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" }, "seed": { "type": "integer" }, "response_format": { "type": "string", "enum": [ "url", "b64_json" ] }, "async": { "type": "boolean" }, "background": { "type": "string", "enum": [ "transparent", "opaque", "auto" ] }, "output_format": { "type": "string", "enum": [ "png", "jpeg", "webp" ] }, "output_compression": { "type": "integer", "minimum": 0, "maximum": 100 }, "compression": { "type": "integer", "minimum": 0, "maximum": 100 }, "moderation": { "type": "string", "enum": [ "auto", "low" ] }, "stream": { "type": "boolean" }, "size": { "type": "string" }, "aspect_ratio": { "type": "string" }, "resolution": { "type": "string" }, "style": { "type": "string" }, "user": { "type": "string" } }, "additionalProperties": false }, "ImageGenerationResponse": { "type": "object", "properties": { "created": { "type": "integer", "description": "Unix timestamp" }, "data": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Image URL" }, "b64_json": { "type": "string", "description": "Base64 encoded image" }, "revised_prompt": { "type": "string", "description": "Revised prompt returned by models that rewrite or enhance the submitted prompt." } } } }, "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": [ "created", "data" ] }, "AudioSpeechRequest": { "type": "object", "required": [ "input" ], "properties": { "model": { "type": "string", "default": "tts-1", "description": "TTS model. Query GET /v1/models?recommended_for=tts for the current shortlist.", "example": "tts-1" }, "input": { "type": "string", "maxLength": 4096, "description": "Text to synthesize." }, "voice": { "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } }, "additionalProperties": false } ], "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": "Voice selector for MiniMax-compatible speech models." }, "instructions": { "type": "string", "maxLength": 2000, "description": "Optional style or delivery instructions for OpenAI-compatible TTS models that support them." }, "prompt": { "type": "string", "maxLength": 2000, "description": "Optional speaking style prompt for Gemini TTS models." }, "language_code": { "type": "string", "description": "Optional language code for Gemini, xAI, and compatible TTS models.", "example": "en-US" }, "response_format": { "type": "string", "description": "Audio format. Common values include mp3, opus, aac, flac, wav, and pcm. Supported values vary by model family.", "example": "mp3" }, "stream_format": { "type": "string", "enum": [ "audio", "sse" ], "default": "audio", "description": "TokenLab delivery format. stream_format=sse is not supported for tts-1 or tts-1-hd." }, "speed": { "type": "number", "minimum": 0.25, "maximum": 4, "description": "Speech speed for model families that support it." }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "description": "Sampling temperature for Gemini-compatible TTS models." } }, "additionalProperties": false }, "AudioTranscriptionRequest": { "type": "object", "required": [ "file", "model" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Audio file to transcribe" }, "model": { "type": "string", "description": "Model to use (whisper-1)", "example": "whisper-1" }, "language": { "type": "string", "description": "ISO-639-1 language code" }, "prompt": { "type": "string", "description": "Optional prompt text" }, "response_format": { "type": "string", "enum": [ "json", "text", "srt", "verbose_json", "vtt" ], "default": "json", "description": "Response format" }, "temperature": { "type": "number", "minimum": 0, "maximum": 1, "description": "Sampling temperature" }, "timestamp_granularities": { "type": "array", "items": { "type": "string", "enum": [ "word", "segment" ] }, "description": "Timestamp granularity selection. Requires verbose_json output when requesting word-level timestamps." } } }, "AudioTranscriptionResponse": { "type": "object", "properties": { "text": { "type": "string", "description": "Transcribed text" }, "task": { "type": "string" }, "language": { "type": "string" }, "duration": { "type": "number" }, "words": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "start": { "type": "number" }, "end": { "type": "number" } } } }, "segments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "start": { "type": "number" }, "end": { "type": "number" }, "text": { "type": "string" } } } } } }, "VideoGenerationRequest": { "type": "object", "properties": { "prompt": { "type": "string", "description": "Video description" }, "model": { "type": "string", "description": "Model to use (e.g., veo3.1, kling-v1)" }, "operation": { "type": "string", "enum": [ "text-to-video", "image-to-video", "reference-to-video", "start-end-to-video", "video-to-video", "video-extension", "audio-to-video", "motion-control" ], "description": "Requested video operation. If omitted, TokenLab infers the operation from the provided inputs. Explicit operation is recommended for production reliability." }, "image": { "type": "string", "description": "Inline image as a data URL (for example, data:image/png;base64,...). Prefer image_url for broader production compatibility. When the selected Seedance model can use the TokenLab material library, TokenLab prepares this image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path." }, "image_url": { "type": "string", "format": "uri", "description": "Publicly reachable image URL for image-to-video generation, or asset://asset-YYYYMMDDHHMMSS-xxxxx for an ACTIVE TokenLab Seedance material used as the first frame. Preferred over inline base64 in production. TokenLab verifies material ownership. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path." }, "video_url": { "type": "string", "format": "uri", "description": "Publicly reachable video URL for video-to-video style flows and motion-control models." }, "duration": { "type": "integer", "minimum": -1, "maximum": 60, "description": "Video duration in seconds. Seedance models also accept -1 to let the model choose within its supported duration range; TokenLab estimates billing conservatively for that mode." }, "aspect_ratio": { "type": "string", "enum": [ "adaptive", "16:9", "9:16", "1:1", "4:3", "3:4", "21:9" ], "description": "Canonical video aspect ratio. Seedance defaults to adaptive when omitted. The ratio alias is accepted for compatibility." }, "resolution": { "type": "string", "enum": [ "480p", "720p", "1080p", "4k" ], "description": "Video resolution. Seedance defaults to 720p when omitted; available values are model-dependent." }, "output_format": { "type": "string", "enum": [ "mp4", "mov" ], "description": "Video container format for compatible models. Seedance 2.5 supports mp4 and mov; omit this field for Seedance 2.0 and other models that do not publish an output-format selector." }, "output_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." }, "fps": { "type": "integer", "minimum": 1, "maximum": 120, "description": "Frames per second" }, "negative_prompt": { "type": "string", "description": "What to avoid in the video" }, "seed": { "type": "integer", "minimum": -1, "maximum": 4294967295, "description": "Seed for reproducibility on compatible models. Compatible Seedance models use -1 for a random seed when omitted; Seedance 2.5 does not support this field." }, "cfg_scale": { "type": "number", "minimum": 0, "maximum": 20, "description": "Prompt adherence strength (0-20) for models that expose CFG-style control." }, "motion_strength": { "type": "number", "minimum": 0, "maximum": 1, "description": "Motion intensity (0-1) for models that expose it." }, "start_image": { "type": "string", "description": "First frame image input for start-end-to-video flows. Seedance accepts a public image reference or asset://asset-YYYYMMDDHHMMSS-xxxxx for an ACTIVE TokenLab material owned by the requesting organization. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path." }, "end_image": { "type": "string", "description": "Last frame image input for start-end-to-video flows. Seedance accepts a public image reference or asset://asset-YYYYMMDDHHMMSS-xxxxx for an ACTIVE TokenLab material owned by the requesting organization. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path." }, "user": { "type": "string", "description": "End-user identifier" }, "image_urls": { "type": "array", "description": "Image URL array for compatible image-conditioned video flows. Seedance 2.5 accepts up to 30 aggregate image inputs; other video models retain the shared limit of 9 entries unless the model details specify a lower limit. When the selected Seedance model can use the TokenLab material library, TokenLab prepares this image input as reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.", "minItems": 1, "maxItems": 30, "items": { "type": "string", "format": "uri" } }, "kling_elements": { "type": "array", "description": "Kling 3.0 element references for kling-3.0-video image-conditioned requests. Define 1-3 elements and reference them in the prompt with @name. Each element requires 2-4 image URLs in element_input_urls. Do not combine kling_elements with output_audio=true; omit output_audio or set it to false for element-reference requests.", "minItems": 1, "maxItems": 3, "items": { "type": "object", "required": [ "name", "element_input_urls" ], "properties": { "name": { "type": "string", "description": "Element name used in the prompt without the @ prefix.", "minLength": 1, "maxLength": 64 }, "description": { "type": "string", "description": "Optional short description of the element.", "minLength": 1, "maxLength": 500 }, "element_input_urls": { "type": "array", "description": "Reference image URLs for this element. Kling 3.0 expects 2-4 images per element.", "minItems": 2, "maxItems": 4, "items": { "type": "string", "format": "uri" } } }, "additionalProperties": false } }, "reference_images": { "type": "array", "description": "Canonical public reference-image field for reference-to-video conditioning. Seedance 2.5 accepts up to 30 aggregate image inputs; other video models retain the shared limit of 9 URLs or compatible data URLs unless the model details specify a lower limit. xAI grok-imagine-video accepts up to 7 image references with duration capped at 10 seconds; grok-imagine-video-1.5 and grok-imagine-video-1.5-preview are image-to-video only and do not accept reference images. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.", "minItems": 1, "maxItems": 30, "items": { "type": "string" } }, "material_asset_id": { "type": "string", "description": "TokenLab Seedance material asset ID returned by /v1/videos/assets, by automatic image preparation, or from a real-person group returned by GetVisualValidateResult. Use it after the asset is ACTIVE with Seedance models that can use the TokenLab material library. The asset must belong to the current account. This field is a generic reference input; to assign first-frame, last-frame, or reference-image semantics explicitly, put asset:// in start_image, end_image, or reference_images." }, "material_asset_ids": { "type": "array", "description": "TokenLab Seedance material asset IDs returned by /v1/videos/assets or by automatic image preparation. They share the Seedance image-reference limit; the selected model must be able to use the TokenLab material library and all assets must belong to the current account and be ACTIVE.", "minItems": 1, "maxItems": 9, "items": { "type": "string" } }, "reference_image_type": { "type": "string", "enum": [ "asset", "style" ], "description": "Optional reference image role for models that distinguish between asset and style references. The camelCase alias referenceImageType is accepted for compatibility." }, "audio_url": { "type": "string", "format": "uri", "description": "Public audio URL for an audio-driven or reference-audio operation supported by the selected model." }, "task_id": { "type": "string", "description": "Task identifier used by some continuation, extension, or derivative flows." }, "extend_at": { "type": "integer", "minimum": 0, "description": "Model-specific extension start offset used by some video-extension flows." }, "extend_times": { "type": "string", "description": "Model-specific extension multiplier or repeat count used by some video-extension flows." }, "seconds": { "type": "integer", "minimum": -1, "maximum": 60, "description": "Alias of duration used by compatible request shapes. Seedance models also accept -1 to let the model choose within its supported duration range; duration and seconds must match when both are provided." }, "size": { "type": "string", "description": "Model-specific size tier for compatible video models." }, "watermark": { "type": "boolean", "description": "Optional watermark toggle for models that expose it. Seedance defaults to false when omitted." }, "effect_type": { "type": "string", "description": "Model-specific effect selector for specialized editing flows." }, "video_urls": { "type": "array", "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": { "type": "string", "format": "uri" } }, "audio_urls": { "type": "array", "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": { "type": "string", "format": "uri" } }, "ratio": { "type": "string", "enum": [ "adaptive", "16:9", "9:16", "1:1", "4:3", "3:4", "21:9" ], "description": "Compatibility alias for aspect_ratio. If both ratio and aspect_ratio are provided, they must match." }, "outputAudio": { "type": "boolean", "description": "Compatibility alias for output_audio. If both are provided, they must match." }, "generate_audio": { "type": "boolean", "description": "Compatibility alias for output_audio. If more than one audio toggle is provided, all values must match." }, "execution_expires_after": { "type": "integer", "minimum": 3600, "maximum": 259200, "default": 172800, "description": "Optional execution expiry window in seconds for compatible video models. Seedance defaults to 172800 seconds when omitted." }, "priority": { "type": "integer", "minimum": 0, "maximum": 9, "default": 0, "description": "Optional task priority for compatible video models. Do not combine priority with service_tier=flex." }, "safety_identifier": { "type": "string", "maxLength": 128, "description": "Optional safety/user trace identifier for compatible video models. If omitted for Seedance, TokenLab uses user when provided." }, "service_tier": { "type": "string", "enum": [ "default", "flex" ], "description": "Optional service tier for compatible video models. service_tier=default is accepted as a compatibility no-op for Seedance 2.0 and Seedance 2.5; service_tier=flex is rejected for both models." }, "frames": { "type": "integer", "minimum": 1, "description": "Optional frame count for compatible video models. Seedance 1.5 Pro, Seedance 2.0, and Seedance 2.5 do not support this field." }, "camera_fixed": { "type": "boolean", "description": "Optional fixed-camera selector for compatible video models. Seedance 2.0 and Seedance 2.5 do not support this field." }, "return_last_frame": { "type": "boolean", "default": false, "description": "Return the last generated frame when the selected model supports it. Seedance defaults to false when omitted." }, "draft": { "type": "boolean", "default": false, "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." } } }, "VideoGenerationResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Task ID" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "description": "Task status" }, "created": { "type": "integer", "description": "Unix timestamp" }, "model": { "type": "string" }, "video": { "type": "object", "properties": { "url": { "type": "string" }, "duration": { "type": "number" }, "width": { "type": "integer" }, "height": { "type": "integer" } } }, "error": { "$ref": "#/components/schemas/AsyncTaskError" }, "error_details": { "$ref": "#/components/schemas/AsyncTaskErrorDetails" }, "task_id": { "type": "string", "description": "Canonical async task identifier for polling. Treat this as the same identity as id when both are present." }, "poll_url": { "type": "string", "description": "Preferred polling URL for this task. Use this exact path when checking status." }, "video_url": { "type": "string", "description": "Generated video URL when the create response is already terminal or includes an immediate result." }, "last_frame_url": { "type": "string", "description": "Last generated frame URL when requested and supported by the selected model." }, "content": { "type": "object", "properties": { "video_url": { "type": "string" }, "last_frame_url": { "type": "string" }, "file_url": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "generate_audio": { "type": "boolean", "description": "Resolved audio output flag when returned by the adapter." }, "draft": { "type": "boolean", "description": "Whether the Seedance draft workflow was used for this task." }, "draft_task_id": { "type": "string", "description": "Seedance draft task identifier when returned by the adapter." } }, "required": [ "id" ] }, "VideoTaskResponse": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Optional progress value returned only when a real progress value is available; use status to determine completion." }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "model": { "type": "string" }, "video": { "type": "object", "properties": { "url": { "type": "string" }, "duration": { "type": "number" }, "width": { "type": "integer" }, "height": { "type": "integer" } } }, "error": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } ] }, "error_details": { "$ref": "#/components/schemas/AsyncTaskErrorDetails" }, "task_id": { "type": "string" }, "poll_url": { "type": "string" }, "cancelled": { "type": "boolean", "description": "True when a queued async task was cancelled before execution. Cancelled tasks are represented with `status: failed` for compatibility with existing async task status values." }, "cancellation_status": { "type": "string", "enum": [ "cancelled" ], "description": "Cancellation marker for tasks cancelled through the public async task endpoint." }, "billing_transaction_id": { "type": "string" }, "video_url": { "type": "string" }, "videos": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "audio_url": { "type": "string" }, "title": { "type": "string" }, "lyrics": { "type": "string" }, "model_url": { "type": "string" }, "glb_url": { "type": "string" }, "fbx_url": { "type": "string" } } }, "SeedanceMaterialAssetCreateRequest": { "type": "object", "required": [ "asset_url" ], "additionalProperties": false, "properties": { "asset_url": { "type": "string", "format": "uri", "description": "Publicly reachable source URL to import. TokenLab stores the material for later use; do not rely on this URL as the long-term material address." }, "asset_name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional display name stored with the material asset." }, "asset_type": { "type": "string", "enum": [ "Image", "Video", "Audio" ], "default": "Image" }, "library_type": { "type": "string", "enum": [ "aigc_avatar", "liveness_face" ], "default": "aigc_avatar", "description": "Material library class. aigc_avatar is for virtual-avatar materials. liveness_face is for verified real-person materials." }, "group_id": { "type": "string", "description": "TokenLab material group ID. Required for liveness_face materials; optional for aigc_avatar." }, "project_name": { "type": "string", "minLength": 1, "maxLength": 128, "default": "default", "description": "Project scope for the material asset. Assets and groups are isolated by project inside the authenticated organization." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Optional client metadata stored with the material asset." } } }, "SeedanceMaterialAsset": { "type": "object", "required": [ "id", "object", "status", "asset_type", "ready", "library_type" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "TokenLab material asset ID. Use this as material_asset_id after the asset becomes ACTIVE." }, "object": { "type": "string", "enum": [ "seedance.material_asset" ] }, "group_id": { "type": [ "string", "null" ], "description": "TokenLab material group ID that owns this material asset." }, "project_name": { "type": "string", "description": "Project scope for this material asset." }, "library_type": { "type": "string", "enum": [ "aigc_avatar", "liveness_face" ] }, "asset_name": { "type": [ "string", "null" ] }, "asset_type": { "type": "string", "enum": [ "Image", "Video", "Audio" ] }, "status": { "type": "string", "enum": [ "PROCESSING", "ACTIVE", "FAILED", "DELETED" ] }, "ready": { "type": "boolean", "description": "True when the asset is active and not deleted." }, "error_message": { "type": [ "string", "null" ], "description": "Public-safe terminal processing error. Permanent source validation failures include the rejected dimension constraint." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "created_at": { "type": "integer", "description": "Unix timestamp when the material asset record was created." }, "updated_at": { "type": "integer", "description": "Unix timestamp when the material asset record was last updated." } } }, "SeedanceMaterialAssetList": { "type": "object", "required": [ "assets" ], "properties": { "assets": { "type": "array", "items": { "$ref": "#/components/schemas/SeedanceMaterialAsset" } }, "next_page_token": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "SeedanceMaterialAssetDeleteResponse": { "type": "object", "required": [ "deleted", "id" ], "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string" } }, "additionalProperties": true }, "ModelsResponse": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelListItem" } } }, "required": [ "object", "data" ], "additionalProperties": false }, "CompactModelsResponse": { "type": "object", "description": "Compact model-selection response used by TokenLab MCP and other agent integrations.", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "view": { "type": "string", "enum": [ "compact" ] }, "count": { "type": "integer", "minimum": 0 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompactModelListItem" } } }, "required": [ "object", "view", "count", "data" ], "additionalProperties": false }, "CompactModelListItem": { "type": "object", "description": "Fields needed to shortlist a model before calling get_model or get_model_pricing.", "properties": { "id": { "type": "string", "description": "Model identifier" }, "deliveryAvailability": { "type": "object", "description": "Current model availability by delivery tier; omitted when the source projection is unavailable.", "properties": { "verified": { "type": "boolean", "description": "Whether this model has eligible TokenLab Verified delivery supply." }, "official": { "type": "boolean", "description": "Whether this model has eligible Official delivery supply." }, "operations": { "type": "object", "additionalProperties": { "type": "object", "properties": { "verified": { "type": "boolean" }, "official": { "type": "boolean" } }, "required": [ "verified", "official" ], "additionalProperties": false } } }, "required": [ "verified", "official" ], "additionalProperties": false }, "provider": { "type": "string", "description": "Public model provider" }, "category": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "max_input_tokens": { "type": [ "number", "null" ] }, "max_output_tokens": { "type": [ "number", "null" ] }, "pricing": { "type": "object", "properties": { "unit": { "type": "string" }, "currency": { "type": "string", "enum": [ "USD" ] }, "input_per_1m": { "type": "string" }, "output_per_1m": { "type": "string" }, "per_request": { "type": "string" }, "min_price": { "type": "string", "description": "Minimum TokenLab price for a structured pricing model." }, "max_price": { "type": "string", "description": "Maximum TokenLab price for a structured pricing model." }, "has_complex_pricing": { "type": "boolean" } }, "required": [ "unit", "currency", "has_complex_pricing" ], "additionalProperties": false }, "status": { "type": "string", "description": "Public model lifecycle stage." }, "latest": { "type": "boolean" }, "supported_operations": { "type": "array", "items": { "type": "string" } }, "request_endpoint": { "type": "string" }, "recommendation": { "type": "object", "properties": { "preferred_rank": { "type": [ "number", "null" ] }, "success_rate_24h": { "type": [ "number", "null" ] }, "sample_count_24h": { "type": "integer" }, "status": { "type": "string", "enum": [ "ready", "insufficient_samples" ] } }, "required": [ "preferred_rank", "success_rate_24h", "sample_count_24h", "status" ], "additionalProperties": false } }, "required": [ "id", "provider", "category", "capabilities", "max_input_tokens", "max_output_tokens", "pricing", "status", "latest" ], "additionalProperties": false }, "Model": { "type": "object", "properties": { "id": { "type": "string", "description": "Model identifier", "example": "gpt-4o" }, "object": { "type": "string", "enum": [ "model" ] }, "created": { "type": "integer", "description": "Unix timestamp" }, "owned_by": { "type": "string", "description": "Model provider", "example": "openai" }, "tokenlab": { "$ref": "#/components/schemas/ModelTokenLabExtension" } }, "required": [ "id", "object", "created", "owned_by", "tokenlab" ], "additionalProperties": false }, "ApiError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "type": { "type": "string", "description": "Error type", "enum": [ "unauthorized", "invalid_api_key", "expired_api_key", "permission_error", "insufficient_balance", "quota_exceeded", "invalid_request_error", "model_not_found", "context_length_exceeded", "unsupported_tool_choice", "rate_limit_exceeded", "server_error", "upstream_error", "all_channels_failed", "timeout_error", "not_found_error", "no_contract_compatible_route", "request_shape_channel_mismatch", "upstream_contract_mismatch", "platform_normalization_error", "async_task_not_found", "async_task_mapping_invalid", "delivery_tier_unavailable" ] }, "code": { "type": "string", "description": "Error code" }, "param": { "type": "string", "description": "Parameter that caused the error" }, "model": { "type": "string", "description": "Model associated with the error" }, "did_you_mean": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } }, "additionalProperties": true } }, "alternatives": { "type": "array", "items": { "type": "object", "required": [ "id", "status", "tags" ], "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } }, "hint": { "type": "string" }, "retry_after": { "type": "number" }, "retryable": { "type": "boolean" }, "balance_usd": { "type": "number" }, "estimated_cost_usd": { "type": "number" }, "supported_operations": { "type": "array", "items": { "type": "string" } }, "supported_parameters": { "type": "array", "items": { "type": "string" } }, "required_selectors": { "type": "array", "items": { "type": "string" } }, "optional_selectors": { "type": "array", "items": { "type": "string" } }, "allowed_resolutions": { "type": "array", "items": { "type": "string" } }, "allowed_durations": { "type": "array", "items": { "type": "string" } }, "allowed_aspect_ratios": { "type": "array", "items": { "type": "string" } }, "prompt_max_characters": { "type": "number" }, "recommended_request": { "type": "object", "additionalProperties": true }, "request_endpoint": { "type": [ "string", "null" ] }, "request_shape_mode": { "type": [ "string", "null" ] }, "status_mode": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": true } }, "additionalProperties": true }, "ValidationError": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "type": "object", "properties": { "validation_errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } ] }, "AnthropicMessagesRequest": { "type": "object", "required": [ "model", "max_tokens", "messages" ], "properties": { "model": { "type": "string", "description": "Model to use (e.g., claude-sonnet-4-6)", "example": "claude-sonnet-4-6" }, "max_tokens": { "type": "integer", "minimum": 1, "description": "Maximum number of tokens to generate" }, "messages": { "type": "array", "description": "Messages in the conversation", "items": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "image" ] }, "text": { "type": "string" }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64", "url" ] }, "media_type": { "type": "string" }, "data": { "type": "string" }, "url": { "type": "string" } } } } } } ] } } } }, "system": { "type": "string", "description": "System prompt" }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "top_p": { "type": "number", "minimum": 0, "maximum": 1 }, "top_k": { "type": "integer", "minimum": 1 }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "stream": { "type": "boolean", "default": false }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Tool definitions available to the model." }, "tool_choice": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ], "description": "Tool choice policy or explicit tool selection." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Request metadata echoed into downstream logs or traces when supported." }, "thinking": { "type": "object", "additionalProperties": true, "description": "Thinking configuration for compatible Anthropic-style models." }, "stream_options": { "type": "object", "additionalProperties": true, "description": "Streaming options such as usage chunk inclusion." }, "service_tier": { "type": "string", "description": "Service tier hint where supported by the model." } } }, "AnthropicMessagesResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "msg_01XFDUDYJgAACzvnptvVoYEL" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "model": { "type": "string" }, "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } } } }, "stop_reason": { "type": "string", "enum": [ "end_turn", "max_tokens", "stop_sequence", "tool_use" ] }, "stop_sequence": { "type": [ "string", "null" ] }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" } } } } }, "GeminiRequest": { "type": "object", "description": "Native Gemini GenerateContent request. ProtoJSON lowerCamelCase and original proto snake_case names are both accepted and preserved, including mixed requests. If both spellings of one field are present, TokenLab does not merge them or choose a local precedence. Unknown fields are forwarded on a best-effort basis.", "required": [ "contents" ], "properties": { "contents": { "type": "array", "description": "Conversation contents", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "model" ] }, "parts": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } } }, { "type": "object", "properties": { "inlineData": { "type": "object", "properties": { "mimeType": { "type": "string" }, "data": { "type": "string" } } } } }, { "type": "object", "properties": { "inline_data": { "type": "object", "properties": { "mime_type": { "type": "string" }, "data": { "type": "string" } } } } }, { "type": "object", "properties": { "fileData": { "type": "object", "properties": { "mimeType": { "type": "string" }, "fileUri": { "type": "string" } } } } }, { "type": "object", "properties": { "file_data": { "type": "object", "properties": { "mime_type": { "type": "string" }, "file_uri": { "type": "string" } } } } }, { "type": "object", "properties": { "videoMetadata": { "type": "object", "additionalProperties": true } } }, { "type": "object", "properties": { "video_metadata": { "type": "object", "additionalProperties": true } } }, { "type": "object", "properties": { "thought": { "type": "boolean" }, "thoughtSignature": { "type": "string" }, "thought_signature": { "type": "string" } } }, { "type": "object", "properties": { "functionCall": { "type": "object", "additionalProperties": true } } }, { "type": "object", "properties": { "functionResponse": { "type": "object", "additionalProperties": true } } }, { "type": "object", "properties": { "executableCode": { "type": "object", "additionalProperties": true } } }, { "type": "object", "properties": { "codeExecutionResult": { "type": "object", "additionalProperties": true } } }, { "type": "object", "properties": { "function_call": { "type": "object", "additionalProperties": true } } }, { "type": "object", "properties": { "function_response": { "type": "object", "additionalProperties": true } } }, { "type": "object", "properties": { "executable_code": { "type": "object", "additionalProperties": true } } }, { "type": "object", "properties": { "code_execution_result": { "type": "object", "additionalProperties": true } } } ] } } } } }, "systemInstruction": { "type": "object", "properties": { "parts": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" } } } } } }, "generationConfig": { "type": "object", "properties": { "temperature": { "type": "number", "minimum": 0 }, "topP": { "type": "number", "minimum": 0, "maximum": 1 }, "topK": { "type": "integer", "minimum": 1 }, "maxOutputTokens": { "type": "integer", "minimum": 1 }, "stopSequences": { "type": "array", "items": { "type": "string" } }, "candidateCount": { "type": "integer", "minimum": 1, "description": "Requested number of response candidates. Support is determined by the selected service." }, "responseModalities": { "type": "array", "description": "Requested output modalities for supported Gemini models.", "items": { "type": "string" } }, "responseMimeType": { "type": "string", "description": "Requested output MIME type, such as text/plain or application/json." }, "responseSchema": { "type": "object", "description": "JSON schema for structured output when responseMimeType requests JSON.", "additionalProperties": true }, "thinkingConfig": { "type": "object", "description": "Thinking budget options for compatible Gemini models.", "properties": { "thinkingBudget": { "type": "integer" } }, "additionalProperties": true }, "thinking_config": { "type": "object", "description": "Snake-case thinking budget options for compatible Gemini models.", "properties": { "thinking_budget": { "type": "integer" } }, "additionalProperties": true } } }, "safetySettings": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "threshold": { "type": "string" } } } }, "tools": { "type": "array", "description": "Gemini tools. Tool types and combinations are interpreted by the selected service.", "items": { "type": "object", "properties": { "functionDeclarations": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "function_declarations": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "codeExecution": { "type": "object", "additionalProperties": true }, "code_execution": { "type": "object", "additionalProperties": true }, "googleSearch": { "type": "object", "additionalProperties": true }, "google_search": { "type": "object", "additionalProperties": true }, "googleSearchRetrieval": { "type": "object", "additionalProperties": true }, "google_search_retrieval": { "type": "object", "additionalProperties": true }, "urlContext": { "type": "object", "additionalProperties": true }, "url_context": { "type": "object", "additionalProperties": true }, "computerUse": { "type": "object", "additionalProperties": true }, "computer_use": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "toolConfig": { "type": "object", "description": "Gemini tool configuration such as functionCallingConfig.", "properties": { "functionCallingConfig": { "type": "object", "properties": { "mode": { "type": "string" }, "allowedFunctionNames": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "function_calling_config": { "type": "object", "properties": { "mode": { "type": "string" }, "allowed_function_names": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } }, "additionalProperties": true }, "cachedContent": { "type": "string", "description": "Gemini cached content resource name for compatible models." }, "system_instruction": { "type": "object", "additionalProperties": true, "description": "Original proto field-name spelling of systemInstruction." }, "generation_config": { "type": "object", "additionalProperties": true, "description": "Original proto field-name spelling of generationConfig." }, "safety_settings": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Original proto field-name spelling of safetySettings." }, "tool_config": { "type": "object", "additionalProperties": true, "description": "Original proto field-name spelling of toolConfig." }, "cached_content": { "type": "string", "description": "Original proto field-name spelling of cachedContent." } }, "additionalProperties": true }, "GeminiResponse": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "object", "properties": { "role": { "type": "string" }, "parts": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" } } } } } }, "finishReason": { "type": "string" }, "safetyRatings": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "probability": { "type": "string" } } } } } } }, "usageMetadata": { "type": "object", "properties": { "promptTokenCount": { "type": "integer" }, "candidatesTokenCount": { "type": "integer" }, "totalTokenCount": { "type": "integer" } } } } }, "ManagementBalanceResponse": { "type": "object", "required": [ "object", "organization_id", "balance", "balance_decimal", "total_recharge", "total_recharge_decimal", "total_used", "total_used_decimal" ], "properties": { "object": { "type": "string", "enum": [ "organization_balance" ] }, "organization_id": { "type": "string", "description": "Organization associated with the current management token." }, "balance": { "type": "number", "description": "Current organization balance in USD as a JSON number for display." }, "total_recharge": { "type": "number", "description": "Total successful organization recharge amount in USD as a JSON number for display." }, "total_used": { "type": "number", "description": "Total organization usage spend in USD as a JSON number for display." }, "balance_decimal": { "type": "string", "description": "Exact current organization balance in USD as a decimal string for reconciliation." }, "total_recharge_decimal": { "type": "string", "description": "Exact total successful organization recharge amount in USD as a decimal string for reconciliation." }, "total_used_decimal": { "type": "string", "description": "Exact total organization usage spend in USD as a decimal string for reconciliation." } } }, "ManagementApiKey": { "type": "object", "required": [ "id", "name", "key_prefix", "status", "limit_amount", "limit_amount_decimal", "used_amount", "used_amount_decimal", "models", "expires_at", "last_used_at", "created_at", "delivery_policy" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "key_prefix": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended", "revoked" ], "description": "Lifecycle status for the user API key: active, inactive, or revoked." }, "limit_amount": { "type": [ "number", "null" ], "description": "API key spending cap in USD as a JSON number for display. null means unlimited." }, "used_amount": { "type": "number", "description": "Accumulated API key usage in USD as a JSON number for display." }, "models": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "key": { "type": "string", "description": "Returned only on creation" }, "limit_amount_decimal": { "type": [ "string", "null" ], "description": "Exact API key spending cap in USD as a decimal string. null means unlimited." }, "used_amount_decimal": { "type": "string", "description": "Exact accumulated API key usage in USD as a decimal string for reconciliation." }, "delivery_policy": { "type": [ "string", "null" ], "enum": [ "auto", "verified", "official", null ], "description": "Per-key Delivery policy. null inherits the Workspace default." } } }, "ManagementApiKeyListResponse": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ManagementApiKey" } }, "pagination": { "type": "object", "required": [ "page", "limit", "total", "totalPages" ], "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } }, "ManagementUsageItem": { "type": "object", "required": [ "request_id", "billing_transaction_id", "model", "logical_model", "model_vendor", "scene", "usage_unit", "usage_quantity", "usage_quantity_decimal", "prompt_tokens", "completion_tokens", "total_tokens", "cache_read_tokens", "cache_write_tokens", "cache_write_tokens_5m", "cache_write_tokens_1h", "cost", "cost_decimal", "created_at", "requested_policy", "resolved_tier", "charged_price_basis" ], "properties": { "request_id": { "type": [ "string", "null" ] }, "billing_transaction_id": { "type": [ "string", "null" ], "description": "Settled billing transaction id for request-level reconciliation." }, "model_vendor": { "type": [ "string", "null" ] }, "scene": { "type": [ "string", "null" ] }, "usage_unit": { "type": "string" }, "usage_quantity": { "type": "number" }, "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "cache_read_tokens": { "type": "integer" }, "cache_write_tokens": { "type": "integer" }, "cost": { "type": "number", "description": "Request cost in USD as a JSON number for display." }, "created_at": { "type": "string", "format": "date-time" }, "model": { "type": "string" }, "logical_model": { "type": "string" }, "usage_quantity_decimal": { "type": "string", "description": "Exact usage quantity as a decimal string for non-token units." }, "cache_write_tokens_5m": { "type": "integer" }, "cache_write_tokens_1h": { "type": "integer" }, "cost_decimal": { "type": "string", "description": "Exact request cost in USD as a decimal string for reconciliation." }, "requested_policy": { "type": [ "string", "null" ], "enum": [ "auto", "verified", "official", null ] }, "resolved_tier": { "type": [ "string", "null" ], "enum": [ "verified", "official", null ] }, "charged_price_basis": { "anyOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChargedPriceBasis" } ] } } }, "ManagementUsageSummary": { "type": "object", "required": [ "total_requests", "total_cost", "total_cost_decimal", "total_prompt_tokens", "total_completion_tokens", "total_tokens", "usage_unit_breakdown" ], "properties": { "total_requests": { "type": "integer" }, "total_cost": { "type": "number", "description": "Aggregated total cost in USD as a JSON number for display." }, "total_prompt_tokens": { "type": "integer" }, "total_completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "usage_unit_breakdown": { "type": "array", "items": { "type": "object", "required": [ "usage_unit", "usage_quantity" ], "properties": { "usage_unit": { "type": "string" }, "usage_quantity": { "type": "number" } } } }, "total_cost_decimal": { "type": "string", "description": "Exact aggregated total cost in USD as a decimal string for reconciliation." } } }, "ManagementModelVendorBreakdown": { "type": "object", "required": [ "model_vendor", "requests", "cost" ], "properties": { "model_vendor": { "type": "string" }, "requests": { "type": "integer" }, "cost": { "type": "number", "description": "Cost in USD as a JSON number for display." } } }, "ManagementSceneBreakdown": { "type": "object", "required": [ "scene", "requests", "cost", "cost_decimal" ], "properties": { "scene": { "type": [ "string", "null" ] }, "requests": { "type": "integer" }, "cost": { "type": "number", "description": "Cost in USD as a JSON number for display." }, "cost_decimal": { "type": "string", "description": "Exact cost in USD as a decimal string for reconciliation." } } }, "ManagementDailyCostBreakdown": { "type": "object", "required": [ "date", "cost", "cost_decimal" ], "properties": { "date": { "type": "string", "format": "date-time" }, "cost": { "type": "number", "description": "Cost in USD as a JSON number for display." }, "cost_decimal": { "type": "string", "description": "Exact cost in USD as a decimal string for reconciliation." } } }, "ManagementBreakdowns": { "type": "object", "properties": { "by_model_vendor": { "type": "array", "items": { "$ref": "#/components/schemas/ManagementModelVendorBreakdown" } }, "by_scene": { "type": "array", "items": { "$ref": "#/components/schemas/ManagementSceneBreakdown" } }, "daily_cost": { "type": "array", "items": { "$ref": "#/components/schemas/ManagementDailyCostBreakdown" } }, "by_model": { "type": "array", "items": { "$ref": "#/components/schemas/ManagementModelBreakdown" } }, "by_logical_model": { "type": "array", "items": { "$ref": "#/components/schemas/ManagementModelBreakdown" } } } }, "ManagementUsageResponse": { "type": "object", "required": [ "api_key", "items", "pagination", "summary", "breakdowns" ], "properties": { "api_key": { "$ref": "#/components/schemas/ManagementApiKey" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ManagementUsageItem" } }, "pagination": { "type": "object", "required": [ "page", "limit", "total", "totalPages" ], "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "summary": { "$ref": "#/components/schemas/ManagementUsageSummary" }, "breakdowns": { "$ref": "#/components/schemas/ManagementBreakdowns" } } }, "ManagementBillingResponse": { "type": "object", "required": [ "api_key", "summary", "breakdowns" ], "properties": { "api_key": { "$ref": "#/components/schemas/ManagementApiKey" }, "summary": { "$ref": "#/components/schemas/ManagementUsageSummary" }, "breakdowns": { "$ref": "#/components/schemas/ManagementBreakdowns" } } }, "ModelListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Model identifier", "example": "gpt-4o" }, "object": { "type": "string", "enum": [ "model" ] }, "created": { "type": "integer", "description": "Unix timestamp" }, "owned_by": { "type": "string", "description": "Model provider", "example": "openai" }, "tokenlab": { "$ref": "#/components/schemas/ModelListTokenLabExtension" } }, "required": [ "id", "object", "created", "owned_by", "tokenlab" ], "additionalProperties": false }, "ModelPricingResponse": { "type": "object", "properties": { "model": { "type": "string" }, "pricing_unit": { "type": "string" }, "has_complex_pricing": { "type": "boolean" }, "supported_operations": { "type": "array", "items": { "type": "string" } }, "pricing_summary": { "type": [ "object", "null" ], "additionalProperties": true }, "pricing_provenance": { "type": [ "object", "null" ], "additionalProperties": true }, "pricing_details": { "type": [ "object", "null" ], "additionalProperties": true }, "scalar_pricing": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "FileObject": { "type": "object", "required": [ "id", "object", "bytes", "created_at", "filename", "purpose" ], "properties": { "id": { "type": "string", "example": "file-abc123" }, "object": { "type": "string", "enum": [ "file" ] }, "bytes": { "type": "integer", "example": 1234 }, "created_at": { "type": "integer", "example": 1741339200 }, "filename": { "type": "string", "example": "batch.jsonl" }, "purpose": { "type": "string", "enum": [ "batch", "batch_output", "user_data", "vision" ], "description": "File purpose. batch and batch_output are used by Batches; user_data and vision are used by file-backed image/reference requests." }, "status": { "type": "string", "example": "processed", "description": "Batch file processing status. Image/reference file objects may omit this field." }, "expires_at": { "type": [ "integer", "null" ], "example": 1741425600 } }, "description": "File metadata. Batch files include status; image/reference files may omit status depending on the file purpose." }, "FileListResponse": { "type": "object", "required": [ "object", "data", "first_id", "last_id", "has_more" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FileObject" } }, "first_id": { "type": [ "string", "null" ] }, "last_id": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "AnthropicFileObject": { "type": "object", "required": [ "id", "type", "filename", "mime_type", "size_bytes", "created_at" ], "properties": { "id": { "type": "string", "example": "file_01ABC123" }, "type": { "type": "string", "enum": [ "file" ] }, "filename": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "downloadable": { "type": "boolean" }, "scope": { "type": [ "object", "null" ], "required": [ "id", "type" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "session" ] } }, "additionalProperties": true } }, "additionalProperties": true }, "AnthropicFileListResponse": { "type": "object", "required": [ "data", "first_id", "last_id", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AnthropicFileObject" } }, "first_id": { "type": [ "string", "null" ] }, "last_id": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "additionalProperties": true }, "AnthropicDeletedFile": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "file_deleted" ] } }, "additionalProperties": true }, "BatchRequestCounts": { "type": "object", "required": [ "total", "completed", "failed" ], "properties": { "total": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" } } }, "BatchObject": { "type": "object", "required": [ "id", "object", "endpoint", "input_file_id", "completion_window", "status", "created_at", "request_counts" ], "properties": { "id": { "type": "string", "example": "batch_abc123" }, "object": { "type": "string", "enum": [ "batch" ] }, "endpoint": { "type": "string", "enum": [ "/v1/chat/completions", "/v1/embeddings" ] }, "errors": { "type": [ "object", "array", "null" ] }, "input_file_id": { "type": "string" }, "completion_window": { "type": "string", "enum": [ "24h" ] }, "status": { "type": "string", "enum": [ "validating", "queued", "in_progress", "finalizing", "completed", "failed", "cancelling", "cancelled", "expired" ] }, "output_file_id": { "type": [ "string", "null" ] }, "error_file_id": { "type": [ "string", "null" ] }, "created_at": { "type": "integer" }, "in_progress_at": { "type": [ "integer", "null" ] }, "expires_at": { "type": [ "integer", "null" ] }, "finalizing_at": { "type": [ "integer", "null" ] }, "completed_at": { "type": [ "integer", "null" ] }, "failed_at": { "type": [ "integer", "null" ] }, "expired_at": { "type": [ "integer", "null" ] }, "cancelling_at": { "type": [ "integer", "null" ] }, "cancelled_at": { "type": [ "integer", "null" ] }, "request_counts": { "$ref": "#/components/schemas/BatchRequestCounts" }, "metadata": { "type": [ "object", "null" ] } } }, "BatchListResponse": { "type": "object", "required": [ "object", "data", "has_more" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BatchObject" } }, "first_id": { "type": [ "string", "null" ] }, "last_id": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "BatchOutputExpiresAfter": { "type": "object", "required": [ "anchor", "seconds" ], "properties": { "anchor": { "type": "string", "enum": [ "created_at", "completed_at" ] }, "seconds": { "type": "integer", "minimum": 1 } } }, "BatchCreateRequest": { "type": "object", "required": [ "input_file_id", "endpoint", "completion_window" ], "properties": { "input_file_id": { "type": "string" }, "endpoint": { "type": "string", "enum": [ "/v1/chat/completions", "/v1/embeddings" ] }, "completion_window": { "type": "string", "enum": [ "24h" ] }, "metadata": { "type": "object", "additionalProperties": true }, "output_expires_after": { "$ref": "#/components/schemas/BatchOutputExpiresAfter" } } }, "PricingEntry": { "type": "object", "required": [ "model", "provider", "is_lock_price", "capabilities", "aliases" ], "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "is_lock_price": { "type": "boolean" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "aliases": { "type": "array", "items": { "type": "string" } }, "input_per_1m_tokens": { "type": [ "string", "null" ] }, "output_per_1m_tokens": { "type": [ "string", "null" ] }, "lock_price_per_request": { "type": [ "string", "null" ] }, "has_complex_pricing": { "type": "boolean" }, "supported_operations": { "type": "array", "items": { "type": "string" } }, "pricing_summary": { "type": [ "object", "null" ], "additionalProperties": true }, "pricing_provenance": { "type": [ "object", "null" ], "additionalProperties": true } }, "additionalProperties": true }, "PricingResponse": { "type": "object", "required": [ "object", "updated_at", "currency", "data" ], "properties": { "object": { "type": "string", "enum": [ "pricing" ] }, "updated_at": { "type": "string", "format": "date-time" }, "currency": { "type": "string", "enum": [ "USD" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PricingEntry" } } }, "additionalProperties": true }, "TranslationRequest": { "type": "object", "required": [ "model", "text", "target_language" ], "properties": { "model": { "type": "string" }, "text": { "type": "string" }, "source_language": { "type": "string" }, "target_language": { "type": "string" }, "mime_type": { "type": "string", "enum": [ "text/plain", "text/html" ] }, "user": { "type": "string" } }, "additionalProperties": false }, "TranslationResponse": { "type": "object", "required": [ "text", "model", "target_language" ], "properties": { "text": { "type": "string" }, "model": { "type": "string" }, "source_language": { "type": [ "string", "null" ] }, "target_language": { "type": "string" } }, "additionalProperties": true }, "GeminiModelInfo": { "type": "object", "required": [ "name", "baseModelId", "version" ], "properties": { "name": { "type": "string" }, "baseModelId": { "type": "string" }, "version": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "inputTokenLimit": { "type": "integer" }, "outputTokenLimit": { "type": "integer" }, "supportedGenerationMethods": { "type": "array", "items": { "type": "string" } }, "temperature": { "type": "number" }, "maxTemperature": { "type": "number" }, "topP": { "type": "number" }, "topK": { "type": "number" } }, "additionalProperties": true }, "GeminiModelListResponse": { "type": "object", "required": [ "models" ], "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/GeminiModelInfo" } }, "nextPageToken": { "type": "string" } }, "additionalProperties": true }, "GeminiErrorResponse": { "type": "object", "additionalProperties": true }, "AnthropicCountTokensRequest": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "description": "Model to count tokens for", "example": "claude-sonnet-4-6" }, "messages": { "type": "array", "description": "Messages in the conversation", "items": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string" }, "text": { "type": "string" }, "source": { "type": "object", "properties": { "type": { "type": "string" }, "media_type": { "type": "string" }, "data": { "type": "string" }, "url": { "type": "string" } } } } } } ] } } } }, "cache_control": { "type": "object", "additionalProperties": true, "description": "Top-level Anthropic cache control marker for count_tokens requests." }, "output_config": { "type": "object", "additionalProperties": true, "description": "Anthropic output configuration fields that may affect token counting." }, "system": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string" }, "text": { "type": "string" } } } } ], "description": "System prompt" }, "thinking": { "type": "object", "additionalProperties": true, "description": "Anthropic extended thinking configuration for token counting." }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Tool definitions available to the model." }, "tool_choice": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ], "description": "Tool choice policy or explicit tool selection." } }, "additionalProperties": true }, "AnthropicCountTokensResponse": { "type": "object", "required": [ "input_tokens" ], "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens in the supplied Anthropic messages request", "example": 1234 } }, "additionalProperties": false }, "AnthropicMessageBatchCreateRequest": { "type": "object", "required": [ "requests" ], "properties": { "requests": { "type": "array", "minItems": 1, "maxItems": 100000, "items": { "type": "object", "required": [ "custom_id", "params" ], "properties": { "custom_id": { "type": "string", "description": "Client-supplied identifier for this batch item", "example": "request-1" }, "params": { "$ref": "#/components/schemas/AnthropicMessagesRequest" } }, "additionalProperties": true } } }, "additionalProperties": true }, "AnthropicMessageBatch": { "type": "object", "description": "Anthropic-compatible message batch object.", "required": [ "id", "type", "processing_status", "request_counts", "ended_at", "created_at", "expires_at", "cancel_initiated_at", "archived_at", "results_url" ], "properties": { "id": { "type": "string", "description": "Message batch identifier", "example": "msgbatch_01ABC123" }, "type": { "type": "string", "enum": [ "message_batch" ] }, "processing_status": { "type": "string", "description": "Current processing status for the batch", "example": "in_progress" }, "request_counts": { "type": "object", "additionalProperties": true, "description": "Request count summary for the batch" }, "ended_at": { "type": [ "string", "null" ], "description": "ISO timestamp when processing ended, when available" }, "created_at": { "type": "string", "description": "ISO timestamp when the batch was created, when available" }, "expires_at": { "type": "string", "description": "ISO timestamp when the batch expires, when available" }, "cancel_initiated_at": { "type": [ "string", "null" ], "description": "ISO timestamp when cancellation was initiated, when available" }, "archived_at": { "type": [ "string", "null" ], "description": "ISO timestamp when the batch was archived, when available" }, "results_url": { "type": [ "string", "null" ], "description": "Results URL, when available" } }, "additionalProperties": true }, "AnthropicDeletedMessageBatch": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "Deleted Message Batch identifier" }, "type": { "type": "string", "enum": [ "message_batch_deleted" ] } }, "additionalProperties": true }, "AnthropicMessageBatchListResponse": { "type": "object", "required": [ "data", "has_more", "first_id", "last_id" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AnthropicMessageBatch" } }, "has_more": { "type": "boolean" }, "first_id": { "type": [ "string", "null" ] }, "last_id": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "MultimodalEmbeddingRequest": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "Model to use for multimodal embeddings", "example": "jina-embeddings-v4" }, "input": { "oneOf": [ { "$ref": "#/components/schemas/MultimodalEmbeddingInputItem" }, { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/MultimodalEmbeddingInputItem" } } ] }, "dimensions": { "type": "integer", "minimum": 1, "description": "Optional embedding dimensionality when supported by the selected model" } }, "additionalProperties": false }, "MultimodalEmbeddingInputItem": { "type": "object", "description": "A multimodal embedding input item. Text input is generally available; image input may require feature enablement.", "properties": { "text": { "type": "string", "description": "Text to embed" }, "image_base64": { "type": "string", "description": "Base64-encoded image content" }, "image_mime_type": { "type": "string", "description": "MIME type for image_base64", "example": "image/png" }, "image_url": { "type": "string", "description": "Public image URL to embed" } }, "additionalProperties": false }, "MultimodalEmbeddingResponse": { "type": "object", "required": [ "object", "data", "model", "usage" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "required": [ "object", "index" ], "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "index": { "type": "integer" }, "text_embedding": { "type": "array", "items": { "type": "number" } }, "image_embedding": { "type": "array", "items": { "type": "number" } }, "video_embedding": { "type": "array", "items": { "type": "number" } }, "audio_embedding": { "type": "array", "items": { "type": "number" } } }, "additionalProperties": true } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "ModelListTokenLabExtension": { "type": "object", "description": "TokenLab model discovery fields. Use the model details endpoint for the full supported request and pricing contract.", "properties": { "aliases": { "type": "array", "items": { "type": "string" } }, "deliveryAvailability": { "type": "object", "description": "Current model availability by delivery tier; omitted when the source projection is unavailable.", "properties": { "verified": { "type": "boolean", "description": "Whether this model has eligible TokenLab Verified delivery supply." }, "official": { "type": "boolean", "description": "Whether this model has eligible Official delivery supply." }, "operations": { "type": "object", "additionalProperties": { "type": "object", "properties": { "verified": { "type": "boolean" }, "official": { "type": "boolean" } }, "required": [ "verified", "official" ], "additionalProperties": false } } }, "required": [ "verified", "official" ], "additionalProperties": false }, "pricing": { "type": "object", "additionalProperties": true }, "capabilities": { "type": "array", "items": { "type": "string" } }, "providers": { "type": "array", "items": { "type": "string" } }, "max_input_tokens": { "type": [ "number", "null" ] }, "max_output_tokens": { "type": [ "number", "null" ] }, "category": { "type": "string" }, "pricing_unit": { "type": "string" }, "cache_pricing": { "type": [ "object", "null" ], "additionalProperties": true }, "has_complex_pricing": { "type": "boolean" }, "pricing_summary": { "type": [ "object", "null" ], "additionalProperties": true }, "agent_preferences": { "type": "object", "additionalProperties": true }, "lifecycle": { "type": "object", "required": [ "stage", "reason", "replacement_model", "released_at", "deprecated_at", "retired_at", "sunset_at", "latest", "latest_source", "latest_window_days" ], "properties": { "stage": { "type": "string", "enum": [ "active", "preview", "deprecated", "retired" ], "description": "Model lifecycle stage for public discovery and display." }, "reason": { "type": [ "string", "null" ], "description": "Short model lifecycle explanation." }, "replacement_model": { "type": [ "string", "null" ], "description": "Recommended replacement model when available." }, "released_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Official release date when available." }, "deprecated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Official deprecation date when available." }, "retired_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Official retirement date when the model is no longer public-discoverable." }, "sunset_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Future sunset date for deprecated models." }, "latest": { "type": "boolean", "description": "Whether the model should receive a latest badge." }, "latest_source": { "type": "string", "enum": [ "auto", "override", "none" ], "description": "How the latest badge was derived." }, "latest_window_days": { "type": [ "integer", "null" ], "description": "Window used for automatic latest badges." } }, "additionalProperties": false }, "commercial": { "type": "object", "required": [ "user_charge_policy", "free_reason", "free_until" ], "properties": { "user_charge_policy": { "type": "string", "enum": [ "paid", "free" ], "description": "User billing policy for this model." }, "free_reason": { "type": [ "string", "null" ], "enum": [ "platform", "promotion", null ], "description": "Reason a model is free to users, if applicable." }, "free_until": { "type": [ "string", "null" ], "format": "date-time", "description": "End time for a temporary free policy, if applicable." } }, "additionalProperties": false }, "badges": { "type": "array", "items": { "type": "object", "required": [ "key", "tone", "priority", "tooltip" ], "properties": { "key": { "type": "string", "enum": [ "free", "latest", "preview", "deprecated", "retired" ] }, "tone": { "type": "string", "enum": [ "green", "blue", "amber", "red", "slate" ] }, "priority": { "type": "integer" }, "tooltip": { "type": "object", "required": [ "key", "values" ], "properties": { "key": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "Display badges derived from lifecycle and commercial metadata." }, "request_format_summary": { "$ref": "#/components/schemas/ModelListRequestFormatSummary" } }, "required": [ "aliases", "pricing", "capabilities", "max_input_tokens", "max_output_tokens", "category", "pricing_unit", "has_complex_pricing", "lifecycle", "commercial", "badges" ], "additionalProperties": false }, "ModelTokenLabExtension": { "type": "object", "description": "TokenLab extension fields for the detail route, including pricing, capabilities, recommendation metadata, and detailed non-chat request metadata.", "properties": { "aliases": { "type": "array", "items": { "type": "string" } }, "deliveryAvailability": { "type": "object", "description": "Current model availability by delivery tier; omitted when the source projection is unavailable.", "properties": { "verified": { "type": "boolean", "description": "Whether this model has eligible TokenLab Verified delivery supply." }, "official": { "type": "boolean", "description": "Whether this model has eligible Official delivery supply." }, "operations": { "type": "object", "additionalProperties": { "type": "object", "properties": { "verified": { "type": "boolean" }, "official": { "type": "boolean" } }, "required": [ "verified", "official" ], "additionalProperties": false } } }, "required": [ "verified", "official" ], "additionalProperties": false }, "pricing": { "type": "object", "additionalProperties": true }, "capabilities": { "type": "array", "items": { "type": "string" } }, "providers": { "type": "array", "items": { "type": "string" } }, "max_input_tokens": { "type": [ "number", "null" ] }, "max_output_tokens": { "type": [ "number", "null" ] }, "category": { "type": "string" }, "pricing_unit": { "type": "string" }, "cache_pricing": { "type": [ "object", "null" ], "additionalProperties": true }, "has_complex_pricing": { "type": "boolean" }, "supported_operations": { "type": "array", "items": { "type": "string" } }, "pricing_summary": { "type": [ "object", "null" ], "additionalProperties": true }, "pricing_provenance": { "type": [ "object", "null" ], "additionalProperties": true }, "lifecycle": { "type": "object", "required": [ "stage", "reason", "replacement_model", "released_at", "deprecated_at", "retired_at", "sunset_at", "latest", "latest_source", "latest_window_days" ], "properties": { "stage": { "type": "string", "enum": [ "active", "preview", "deprecated", "retired" ], "description": "Model lifecycle stage for public discovery and display." }, "reason": { "type": [ "string", "null" ], "description": "Short model lifecycle explanation." }, "replacement_model": { "type": [ "string", "null" ], "description": "Recommended replacement model when available." }, "released_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Official release date when available." }, "deprecated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Official deprecation date when available." }, "retired_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Official retirement date when the model is no longer public-discoverable." }, "sunset_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Future sunset date for deprecated models." }, "latest": { "type": "boolean", "description": "Whether the model should receive a latest badge." }, "latest_source": { "type": "string", "enum": [ "auto", "override", "none" ], "description": "How the latest badge was derived." }, "latest_window_days": { "type": [ "integer", "null" ], "description": "Window used for automatic latest badges." } }, "additionalProperties": false }, "commercial": { "type": "object", "required": [ "user_charge_policy", "free_reason", "free_until" ], "properties": { "user_charge_policy": { "type": "string", "enum": [ "paid", "free" ], "description": "User billing policy for this model." }, "free_reason": { "type": [ "string", "null" ], "enum": [ "platform", "promotion", null ], "description": "Reason a model is free to users, if applicable." }, "free_until": { "type": [ "string", "null" ], "format": "date-time", "description": "End time for a temporary free policy, if applicable." } }, "additionalProperties": false }, "badges": { "type": "array", "items": { "type": "object", "required": [ "key", "tone", "priority", "tooltip" ], "properties": { "key": { "type": "string", "enum": [ "free", "latest", "preview", "deprecated", "retired" ] }, "tone": { "type": "string", "enum": [ "green", "blue", "amber", "red", "slate" ] }, "priority": { "type": "integer" }, "tooltip": { "type": "object", "required": [ "key", "values" ], "properties": { "key": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "Display badges derived from lifecycle and commercial metadata." }, "request_format_summary": { "$ref": "#/components/schemas/NonChatRequestFormatSummary" }, "request_format_details": { "$ref": "#/components/schemas/NonChatRequestFormatDetails" }, "accepted_request_formats": { "type": "array", "description": "Request formats accepted by this model.", "items": { "type": "string", "enum": [ "openai_chat_completions", "openai_responses", "anthropic_messages", "gemini_generate_content" ] } } }, "additionalProperties": true, "required": [ "lifecycle", "commercial", "badges", "accepted_request_formats" ] }, "SeedanceMaterialAssetGroupCreateRequest": { "type": "object", "additionalProperties": false, "properties": { "group_name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional display name for the material group." }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "library_type": { "type": "string", "enum": [ "aigc_avatar", "liveness_face" ], "default": "aigc_avatar", "description": "Material library class. Direct creation supports aigc_avatar. Create liveness_face groups through CreateVisualValidateSession followed by GetVisualValidateResult." }, "project_name": { "type": "string", "minLength": 1, "maxLength": 128, "default": "default", "description": "Project scope for the material group." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true } } }, "SeedanceMaterialAssetGroupUpdateRequest": { "type": "object", "properties": { "group_name": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "project_name": { "type": "string", "minLength": 1, "maxLength": 128, "default": "default" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true } } }, "SeedanceMaterialAssetGroup": { "type": "object", "required": [ "id", "object", "status", "library_type" ], "properties": { "id": { "type": "string", "description": "TokenLab material group ID. Use it as group_id when uploading materials." }, "object": { "type": "string", "enum": [ "seedance.material_asset_group" ] }, "library_type": { "type": "string", "enum": [ "aigc_avatar", "liveness_face" ] }, "project_name": { "type": "string", "description": "Project scope for this material group." }, "group_name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "created_at": { "type": "integer", "format": "int64" }, "updated_at": { "type": "integer", "format": "int64" } } }, "SeedanceMaterialAssetGroupList": { "type": "object", "required": [ "groups" ], "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/SeedanceMaterialAssetGroup" } }, "next_page_token": { "type": [ "string", "null" ] } } }, "SeedanceMaterialAssetUpdateRequest": { "type": "object", "minProperties": 1, "properties": { "asset_url": { "type": "string", "format": "uri", "description": "Replacement publicly reachable material asset URL." }, "asset_name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Updated display name stored with the material asset." }, "asset_type": { "type": "string", "enum": [ "Image", "Video", "Audio" ] }, "project_name": { "type": "string", "minLength": 1, "maxLength": 128, "default": "default" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Updated client metadata stored with the material asset." } }, "additionalProperties": false }, "ManagementModelBreakdown": { "type": "object", "required": [ "model", "logical_model", "model_vendor", "requests", "cost", "cost_decimal", "usage_quantity", "usage_quantity_decimal" ], "properties": { "model_vendor": { "type": [ "string", "null" ] }, "requests": { "type": "integer" }, "cost": { "type": "number", "description": "Cost in USD as a JSON number for display." }, "usage_quantity": { "type": "number" }, "model": { "type": "string" }, "logical_model": { "type": "string" }, "cost_decimal": { "type": "string", "description": "Exact cost in USD as a decimal string for reconciliation." }, "usage_quantity_decimal": { "type": "string" } } }, "ModelListRequestFormatSummary": { "type": [ "object", "null" ], "properties": { "public_operations": { "type": "array", "items": { "type": "string" } }, "request_endpoint": { "type": [ "string", "null" ] }, "request_endpoint_by_operation": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } } }, "additionalProperties": false }, "NonChatOperationConstraint": { "type": "object", "properties": { "operation": { "type": "string" }, "request_endpoint": { "type": [ "string", "null" ] }, "request_shape_mode": { "type": [ "string", "null" ] }, "status_mode": { "type": [ "string", "null" ] }, "supported_parameters": { "type": "array", "items": { "type": "string" } }, "required_selectors": { "type": "array", "items": { "type": "string" } }, "optional_selectors": { "type": "array", "items": { "type": "string" } }, "documented_inputs": { "type": "array", "items": { "type": "string" } }, "allowed_resolutions": { "type": "array", "items": { "type": "string" } }, "allowed_durations": { "type": "array", "items": { "type": "string" } }, "allowed_aspect_ratios": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "array", "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 }, "NonChatRequestFormatSummary": { "type": [ "object", "null" ], "properties": { "public_operations": { "type": "array", "items": { "type": "string" } }, "supported_parameters": { "type": "array", "items": { "type": "string" } }, "feature_flags": { "type": "object", "additionalProperties": { "type": "boolean" } }, "output_formats": { "type": "array", "items": { "type": "string" } }, "service_limits": { "type": [ "object", "null" ], "properties": { "online_rpm": { "type": [ "number", "null" ] }, "concurrency": { "type": [ "number", "null" ] }, "offline_inference": { "type": "boolean" }, "offline_tpd": { "type": [ "string", "null" ] }, "prompt_max_characters": { "type": [ "number", "null" ] } }, "additionalProperties": false }, "required_selectors": { "type": "array", "items": { "type": "string" } }, "optional_selectors": { "type": "array", "items": { "type": "string" } }, "resolutions": { "type": "array", "items": { "type": "string" } }, "resolutions_label": { "type": [ "string", "null" ] }, "durations": { "type": "array", "items": { "type": "string" } }, "durations_label": { "type": [ "string", "null" ] }, "aspect_ratios": { "type": "array", "items": { "type": "string" } }, "aspect_ratios_label": { "type": [ "string", "null" ] }, "request_endpoint": { "type": [ "string", "null" ] }, "status_mode": { "type": [ "string", "null" ] }, "request_shape_mode": { "type": [ "string", "null" ] }, "recommended_request_summary": { "type": [ "object", "null" ], "additionalProperties": true }, "request_endpoint_by_operation": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "operation_constraints": { "type": "array", "items": { "$ref": "#/components/schemas/NonChatOperationConstraint" } } }, "additionalProperties": true }, "NonChatRequestFormatDetails": { "allOf": [ { "$ref": "#/components/schemas/NonChatRequestFormatSummary" }, { "type": [ "object", "null" ], "properties": { "documented_inputs": { "type": "array", "items": { "type": "string" } }, "documented_outputs": { "type": "array", "items": { "type": "string" } }, "fallback_status_endpoints": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "array", "items": { "type": "string" } }, "recommended_request": { "type": [ "object", "null" ], "additionalProperties": true } }, "additionalProperties": true } ] }, "FileDeletedObject": { "type": "object", "required": [ "id", "object", "deleted" ], "properties": { "id": { "type": "string", "example": "file-abc123" }, "object": { "type": "string", "enum": [ "file" ] }, "deleted": { "type": "boolean", "example": true } }, "additionalProperties": true }, "ManagementCreatedApiKey": { "allOf": [ { "$ref": "#/components/schemas/ManagementApiKey" }, { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "Full secret API key value returned only on creation. Store it immediately." } } } ] }, "VolcSeedanceContentItem": { "type": "object", "description": "Volc-style content item. Use text, image_url, video_url, audio_url, or draft_task. For image_url, omitting role treats the image as first_frame; use role=reference_image for reference images.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "image_url", "video_url", "audio_url", "draft_task" ] }, "text": { "type": "string", "description": "Text prompt content. Required when type=text." }, "role": { "type": "string", "enum": [ "first_frame", "last_frame", "reference_image", "reference_video", "reference_audio" ], "description": "Media role. first_frame/last_frame inputs cannot be mixed with reference_image/reference_video/reference_audio inputs." }, "image_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } }, "additionalProperties": false, "description": "Image reference in the official {\"url\":\"https://...\"} shape. TokenLab material URIs remain available as URL values without changing the request object shape." }, "video_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } }, "additionalProperties": false, "description": "Video URL. Use role=reference_video." }, "audio_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } }, "additionalProperties": false, "description": "Audio URL. Use role=reference_audio." }, "draft_task": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } }, "additionalProperties": false, "description": "Draft task reference in the official {\"id\":\"cgt-...\"} shape." } }, "additionalProperties": false }, "VolcSeedanceCreateTaskRequest": { "type": "object", "required": [ "model", "content" ], "properties": { "model": { "type": "string", "example": "doubao-seedance-2-0-260128", "description": "Seedance model or endpoint identifier. TokenLab maps supported Seedance 2.0 identifiers to the matching platform model." }, "content": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "$ref": "#/components/schemas/VolcSeedanceContentItem" }, "description": "At most 16 content items: one text item, nine image_url items, three video_url items, three audio_url items, and one draft_task item. Model- and operation-specific combination rules still apply." }, "ratio": { "type": "string", "enum": [ "16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "adaptive" ], "default": "adaptive", "description": "Output aspect ratio. Defaults to adaptive when omitted." }, "duration": { "oneOf": [ { "type": "integer", "enum": [ -1 ] }, { "type": "integer", "minimum": 4, "maximum": 15 } ], "default": 5, "example": 5, "description": "Video duration in seconds. Seedance 2.0 supports normal integer durations and -1 for automatic duration where the selected model supports it." }, "resolution": { "type": "string", "enum": [ "480p", "720p", "1080p" ], "default": "720p", "example": "720p", "description": "Requested output resolution. Model-specific availability still applies." }, "generate_audio": { "type": "boolean", "default": false, "description": "Whether to generate synchronized audio. The official default is false." }, "return_last_frame": { "type": "boolean", "default": false, "description": "Return the final frame URL when supported." }, "watermark": { "type": "boolean", "default": false }, "seed": { "type": "integer", "minimum": -1, "maximum": 4294967295, "default": -1, "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", "minimum": 3600, "maximum": 259200, "default": 172800, "description": "Task execution expiration window in seconds." }, "safety_identifier": { "type": "string", "maxLength": 64, "description": "Stable caller-side safety identifier." }, "service_tier": { "type": "string", "enum": [ "default", "flex" ], "default": "default", "description": "default is accepted. flex is rejected for Seedance 2.0 compatibility tasks because the selected model family does not support it here." }, "tools": { "type": "array", "maxItems": 1, "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "web_search" ] } }, "additionalProperties": false }, "description": "Optional tools such as {\"type\":\"web_search\"} when supported by the selected model." }, "draft": { "type": "boolean", "description": "draft=true is not supported for Seedance 2.0 compatibility tasks and is rejected." }, "frames": { "type": "integer", "description": "Not supported for Seedance 2.0 compatibility tasks. Use duration instead." }, "camera_fixed": { "type": "boolean", "description": "camera_fixed=true is not supported for Seedance 2.0 compatibility tasks. false is accepted as a no-op." }, "callback_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Public HTTP(S) endpoint notified by POST whenever status changes. The body is identical to the get-task response. queued, running, succeeded, failed, and expired are delivered. For succeeded and failed, a delivery without success within 5 seconds is retried up to three times." } }, "additionalProperties": false }, "VolcSeedanceCreateTaskResponse": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "example": "cgt-20260102030405-a1b2c" } }, "additionalProperties": false }, "VolcSeedanceTask": { "type": "object", "required": [ "id", "model", "status" ], "properties": { "id": { "type": "string", "example": "cgt-20260102030405-a1b2c" }, "model": { "type": "string", "example": "doubao-seedance-2-0-260128" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled", "expired" ] }, "content": { "type": "object", "properties": { "video_url": { "type": "string", "format": "uri" }, "last_frame_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "seed": { "type": "integer" }, "resolution": { "type": "string" }, "ratio": { "type": "string" }, "duration": { "type": "string" }, "frames": { "type": "integer" }, "framespersecond": { "type": "integer" }, "generate_audio": { "type": "boolean" }, "tools": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "web_search" ] } }, "additionalProperties": false }, "safety_identifier": { "type": "string" }, "draft": { "type": "boolean" }, "draft_task_id": { "type": "string" }, "service_tier": { "type": "string" }, "execution_expires_after": { "type": "integer" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "integer", "minimum": 0 }, "total_tokens": { "type": "integer", "minimum": 0 }, "tool_usage": { "type": "object", "properties": { "web_search": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } }, "additionalProperties": false }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false }, "created_at": { "type": "integer", "description": "Unix timestamp in seconds." }, "updated_at": { "type": "integer", "description": "Unix timestamp in seconds." } }, "additionalProperties": false }, "VolcSeedanceTaskListResponse": { "type": "object", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/VolcSeedanceTask" } }, "total": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "VolcSeedanceError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "param", "type" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "VolcVisualValidationResponseMetadata": { "type": "object", "required": [ "RequestId", "Action", "Version", "Service", "Region" ], "properties": { "RequestId": { "type": "string", "description": "TokenLab request identifier." }, "Action": { "type": "string", "enum": [ "CreateVisualValidateSession", "GetVisualValidateResult" ] }, "Version": { "type": "string", "enum": [ "2024-01-01" ] }, "Service": { "type": "string", "enum": [ "ark" ] }, "Region": { "type": "string", "enum": [ "cn-beijing" ] } }, "additionalProperties": false }, "VolcCreateVisualValidateSessionRequest": { "type": "object", "required": [ "CallbackURL" ], "properties": { "CallbackURL": { "type": "string", "format": "uri", "description": "Public HTTPS URL opened by the H5 flow after validation. Official callback query names are preserved." }, "ProjectName": { "type": "string", "default": "default", "description": "Case-sensitive project name. Omit to use default." } }, "additionalProperties": false }, "VolcGetVisualValidateResultRequest": { "type": "object", "required": [ "BytedToken" ], "properties": { "BytedToken": { "type": "string", "description": "Opaque token returned by CreateVisualValidateSession. It is valid for 30 minutes and scoped to the authenticated organization, actor, and ProjectName." }, "ProjectName": { "type": "string", "default": "default", "description": "Must match the ProjectName used to create the token." } }, "additionalProperties": false }, "VolcCreateVisualValidateSessionResponse": { "type": "object", "required": [ "ResponseMetadata", "Result" ], "properties": { "ResponseMetadata": { "$ref": "#/components/schemas/VolcVisualValidationResponseMetadata" }, "Result": { "type": "object", "required": [ "BytedToken", "H5Link", "CallbackURL" ], "properties": { "BytedToken": { "type": "string" }, "H5Link": { "type": "string", "format": "uri" }, "CallbackURL": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "additionalProperties": false }, "VolcGetVisualValidateResultResponse": { "type": "object", "required": [ "ResponseMetadata", "Result" ], "properties": { "ResponseMetadata": { "$ref": "#/components/schemas/VolcVisualValidationResponseMetadata" }, "Result": { "type": "object", "required": [ "GroupId" ], "properties": { "GroupId": { "type": "string", "pattern": "^group-[0-9]{14}-[a-z0-9]{5}$", "description": "TokenLab-mapped real-person Asset Group ID returned after successful validation." } }, "additionalProperties": false } }, "additionalProperties": false }, "VolcMaterialActionRequest": { "type": "object", "description": "PascalCase request body for the material Action selected by the Action query parameter. Required fields depend on the selected Action.", "properties": { "Id": { "type": "string", "description": "Asset or Asset Group identifier for get, update, and delete Actions." }, "Name": { "type": "string", "minLength": 1, "maxLength": 64 }, "Description": { "type": "string", "maxLength": 300 }, "GroupType": { "type": "string", "enum": [ "AIGC", "LivenessFace" ] }, "GroupId": { "type": "string" }, "URL": { "type": "string", "format": "uri" }, "AssetType": { "type": "string", "enum": [ "Image", "Video", "Audio" ] }, "Filter": { "type": "object", "properties": { "GroupIds": { "type": "array", "maxItems": 100, "items": { "type": "string" } }, "GroupType": { "type": "string", "enum": [ "AIGC", "LivenessFace" ] }, "Statuses": { "type": "array", "items": { "type": "string", "enum": [ "Active", "Processing", "Failed" ] } }, "Name": { "type": "string", "minLength": 1, "maxLength": 64 } }, "additionalProperties": false }, "PageNumber": { "type": "integer", "minimum": 1, "default": 1 }, "PageSize": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "SortBy": { "type": "string", "enum": [ "CreateTime", "UpdateTime", "GroupId" ], "default": "CreateTime" }, "SortOrder": { "type": "string", "enum": [ "Desc", "Asc" ], "default": "Desc" }, "ProjectName": { "type": "string", "minLength": 1, "maxLength": 128, "default": "default", "description": "Project isolation scope within the authenticated organization." } }, "additionalProperties": false }, "VolcMaterialResponseMetadata": { "type": "object", "required": [ "RequestId", "Action", "Version", "Service", "Region" ], "properties": { "RequestId": { "type": "string" }, "Action": { "type": "string", "enum": [ "CreateAssetGroup", "ListAssetGroups", "GetAssetGroup", "UpdateAssetGroup", "DeleteAssetGroup", "CreateAsset", "ListAssets", "GetAsset", "UpdateAsset", "DeleteAsset" ] }, "Version": { "type": "string", "enum": [ "2024-01-01" ] }, "Service": { "type": "string", "enum": [ "ark" ] }, "Region": { "type": "string", "enum": [ "cn-beijing" ] } }, "additionalProperties": false }, "VolcMaterialActionResponse": { "type": "object", "required": [ "ResponseMetadata", "Result" ], "properties": { "ResponseMetadata": { "$ref": "#/components/schemas/VolcMaterialResponseMetadata" }, "Result": { "type": "object", "description": "Action-dependent result. List Actions return Items, TotalCount, PageNumber, and PageSize; create and update Actions return Id; delete Actions return an empty object.", "additionalProperties": true } }, "additionalProperties": false }, "VolcVisualValidationError": { "type": "object", "required": [ "ResponseMetadata" ], "properties": { "ResponseMetadata": { "type": "object", "required": [ "RequestId", "Action", "Version", "Service", "Region", "Error" ], "properties": { "RequestId": { "type": "string" }, "Action": { "type": "string" }, "Version": { "type": "string" }, "Service": { "type": "string", "enum": [ "ark" ] }, "Region": { "type": "string", "enum": [ "cn-beijing" ] }, "Error": { "type": "object", "required": [ "Code", "Message" ], "properties": { "CodeN": { "type": "integer" }, "Code": { "type": "string" }, "Message": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "VolcSeedanceActionError": { "oneOf": [ { "$ref": "#/components/schemas/VolcSeedanceError" }, { "$ref": "#/components/schemas/VolcVisualValidationError" } ] }, "ChargedPriceBasis": { "type": "object", "required": [ "version", "resolvedTier", "priceVersion", "measure", "effectiveUnitPrices" ], "properties": { "version": { "type": "integer", "enum": [ 1 ] }, "resolvedTier": { "type": "string", "enum": [ "verified", "official" ] }, "priceVersion": { "type": "string" }, "measure": { "type": "object", "required": [ "unit", "quantity", "dimensions" ], "properties": { "unit": { "type": "string" }, "quantity": { "type": "string" }, "dimensions": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "additionalProperties": false }, "effectiveUnitPrices": { "type": "object", "required": [ "unit" ], "properties": { "unit": { "type": "string" }, "input": { "type": [ "string", "null" ] }, "output": { "type": [ "string", "null" ] }, "cacheRead": { "type": [ "string", "null" ] }, "cacheWrite": { "type": [ "string", "null" ] }, "cacheWrite1h": { "type": [ "string", "null" ] }, "fixed": { "type": [ "string", "null" ] }, "structured": { "anyOf": [ { "type": "null" }, { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "WebhookEndpoint": { "type": "object", "required": [ "id", "object", "url", "events", "is_active", "description", "created_at", "updated_at", "last_delivered_at", "failure_count" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "webhook_endpoint" ] }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "task.completed", "task.failed", "task.timeout" ] } }, "is_active": { "type": "boolean" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "last_delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "failure_count": { "type": "integer" } }, "additionalProperties": false }, "CreatedWebhookEndpoint": { "type": "object", "required": [ "id", "object", "url", "events", "is_active", "description", "created_at", "updated_at", "last_delivered_at", "failure_count", "secret" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "webhook_endpoint" ] }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "task.completed", "task.failed", "task.timeout" ] } }, "is_active": { "type": "boolean" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "last_delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "failure_count": { "type": "integer" }, "secret": { "type": "string" } }, "additionalProperties": false }, "WebhookDelivery": { "type": "object", "required": [ "id", "webhook_id", "delivery_id", "event_type", "outcome", "http_status", "attempts", "delivered_at", "created_at" ], "properties": { "id": { "type": "string" }, "webhook_id": { "type": "string" }, "delivery_id": { "type": "string" }, "event_type": { "type": "string" }, "outcome": { "type": "string", "enum": [ "delivered", "failed" ] }, "http_status": { "type": [ "integer", "null" ] }, "attempts": { "type": "integer" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "WebhookEndpointList": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "object", "url", "events", "is_active", "description", "created_at", "updated_at", "last_delivered_at", "failure_count" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "webhook_endpoint" ] }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "task.completed", "task.failed", "task.timeout" ] } }, "is_active": { "type": "boolean" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "last_delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "failure_count": { "type": "integer" } }, "additionalProperties": false } }, "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 }, "WebhookDeliveryList": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "webhook_id", "delivery_id", "event_type", "outcome", "http_status", "attempts", "delivered_at", "created_at" ], "properties": { "id": { "type": "string" }, "webhook_id": { "type": "string" }, "delivery_id": { "type": "string" }, "event_type": { "type": "string" }, "outcome": { "type": "string", "enum": [ "delivered", "failed" ] }, "http_status": { "type": [ "integer", "null" ] }, "attempts": { "type": "integer" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "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": [ "message" ], "properties": { "message": { "type": "string" }, "type": { "type": "string" }, "code": { "type": "string" }, "param": { "type": "string" }, "retryable": { "type": "boolean" } }, "additionalProperties": false } ] } }, "responses": { "BadRequest": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "error": { "message": "model: Model is required", "type": "invalid_request_error", "param": "model" }, "validation_errors": [ { "field": "model", "message": "Model is required" } ] } } } }, "Unauthorized": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "message": "Invalid API key provided", "type": "invalid_api_key" } } } } }, "PaymentRequired": { "description": "Payment Required - Insufficient balance or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "message": "Insufficient balance. Please top up your account.", "type": "insufficient_balance" } } } } }, "RateLimitExceeded": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "message": "Rate limit exceeded. Please slow down.", "type": "rate_limit_exceeded" } } } }, "headers": { "X-RateLimit-Limit": { "description": "Request limit per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when limit resets", "schema": { "type": "integer" } } } }, "ServerError": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "message": "An internal error occurred", "type": "server_error" } } } } }, "UpstreamError": { "description": "Service Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "message": "The service could not complete the request", "type": "upstream_error" } } } } }, "AllChannelsFailed": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "message": "The service is temporarily unable to process this request", "type": "all_channels_failed" } } } } }, "Forbidden": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "message": "Organization is not active", "type": "invalid_request_error" } } } } }, "NotFound": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "message": "API key not found", "type": "invalid_request_error" } } } } }, "MaterialLibraryUnavailable": { "description": "Material library unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "message": "Seedance material library request failed", "type": "server_error", "code": "seedance_material_library_request_failed" } } } } }, "DeliveryUnavailable": { "description": "The requested Delivery tier is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "requestedTierUnavailable": { "summary": "The requested Delivery tier is unavailable", "value": { "error": { "message": "The requested Delivery tier is temporarily unavailable for model gpt-5.4.", "type": "all_channels_failed", "code": "delivery_tier_unavailable", "retryable": true, "request_id": "req_01JEXAMPLE" } } }, "eligibleRoutesFailed": { "summary": "The requested Delivery tier could not complete this request", "value": { "error": { "message": "All available routes failed to process the request.", "type": "all_channels_failed", "retryable": true, "request_id": "req_01JEXAMPLE" } } } } } } } }, "parameters": { "DeliveryPolicy": { "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, request acceptance, or persistent resource creation.", "schema": { "type": "string", "enum": [ "auto", "verified", "official" ] } } } }, "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." } } } } } }