{"openapi":"3.1.0","info":{"title":"AI Builder Space Backend","version":"0.1.0"},"servers":[{"url":"/backend"}],"paths":{"/v1/chat/completions":{"post":{"tags":["chat"],"summary":"Create a chat completion using the multi-tool orchestrator","description":"Generate chat completions using the AI Builder multi-tool orchestrator.\n\nThis endpoint supports multiple models with different capabilities:\n- **deepseek**: Fast and cost-effective chat completions (alias for DeepSeek V4 Flash)\n- **deepseek-v4-flash**: Direct access to DeepSeek V4 Flash\n- **deepseek-v4-pro**: DeepSeek V4 Pro with thinking mode support\n- **supermind-agent-v1**: Multi-tool agent with web search and Gemini handoff (DeepSeek V4 Flash as base model)\n- **kimi-k2.5**: Kimi K2.5 multimodal model with vision support (Moonshot AI, OpenAI compatible). Only supports temperature=1.0 (automatically enforced).\n- **gemini-2.5-pro**: Direct access to Google's Gemini model\n- **gemini-3-flash-preview**: Fast Gemini reasoning model\n- **gpt-5**: Passthrough to OpenAI-compatible providers. Only supports temperature=1.0 (automatically enforced). Uses max_completion_tokens instead of max_tokens (automatically converted). Recommended: Use max_tokens >= 1000 for complete responses.\n- **grok-4-fast**: Passthrough to X.AI's Grok API\n\nThe orchestrator can automatically:\n- Execute web searches when detecting information needs\n- Extract content from URLs\n- Switch between models using handoff\n- Provide detailed usage metrics and cost estimates\n\nGemini-specific settings can be passed via `extra_body.gemini` in the OpenAI SDK.\n\nSet `debug=true` to include orchestrator execution traces in the response.","operationId":"create_completion_v1_chat_completions_post","security":[{"bearerAuth":[]}],"parameters":[{"name":"debug","in":"query","required":false,"schema":{"type":"boolean","description":"When true, include orchestrator debug metadata in the response.","default":false,"title":"Debug"},"description":"When true, include orchestrator debug metadata in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}}},"responses":{"200":{"description":"OpenAI-compatible chat completion payload with a single choice and usage metrics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/embeddings":{"post":{"tags":["embeddings"],"summary":"Create embeddings for input text","description":"Generate embedding vectors for input text using OpenAI-compatible models.\n\nThis endpoint supports all OpenAI embedding models including:\n- text-embedding-3-small (default)\n- text-embedding-3-large\n- text-embedding-ada-002\n\nThe endpoint passes through all requests to the configured OpenAI provider,\nallowing you to use any OpenAI-compatible service.","operationId":"create_embedding_v1_embeddings_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingRequest"}}},"required":true},"responses":{"200":{"description":"OpenAI-compatible embedding response with vector data and usage metrics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/audio/transcriptions":{"post":{"tags":["audio"],"summary":"Transcribe spoken audio into text","description":"Transcribe audio files or URLs into text using AI-powered speech recognition.\n    \n    You can provide audio in two ways:\n    - Upload a file: use `audio_file` (AI Builder) or `file` (OpenAI SDK compatible)\n    - Provide a publicly accessible URL via the `audio_url` form field\n    \n    The API supports multiple audio formats (MP3, WAV, FLAC, etc.) and can automatically\n    detect the language or use the provided `language` hint parameter.\n    \n    **Custom prompt and terms (OpenAI Realtime only):**\n    - `prompt`: Optional free-form text appended to the transcription instructions.\n      Use for domain context, style hints, or special handling rules.\n    - `terms`: Optional comma-separated list of terms (e.g. product names, jargon, homophones).\n      The model will prefer these when transcribing ambiguous audio.\n      Example: \"dahlia,tulip\" helps disambiguate \"flower\" vs \"flour\" in context.\n    \n    Returns structured results including:\n    - Full transcript text\n    - Optional word-level timestamps\n    - Detected language\n    - Confidence scores","operationId":"transcribe_audio_v1_audio_transcriptions_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_transcribe_audio_v1_audio_transcriptions_post"}}}},"responses":{"200":{"description":"Structured transcription result with optional segments and language detection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/audio/transcriptions_long":{"post":{"tags":["audio"],"summary":"Transcribe long audio with sentence-level timestamps and advanced features","description":"Transcribe audio files or URLs into text using AssemblyAI's Universal model with advanced features optimized for long audio content.\n    \n    **Key Features:**\n    - **Sentence-level timestamps**: Provides timing information at the sentence level (instead of word-level), making it more efficient for long audio files\n    - **Speaker diarization**: Optionally identify and label different speakers in multi-speaker audio (e.g., meetings, interviews)\n    - **Audio segment selection**: Transcribe only specific portions of long audio files to save processing time and costs\n    - **Disfluency removal**: Automatically remove filler words like \"um\", \"uh\", \"like\" to produce cleaner transcripts\n    \n    **Audio Input Methods:**\n    - Upload a file directly using the `audio_file` form field (multipart/form-data)\n    - Provide a publicly accessible URL via the `audio_url` form field\n    \n    **Supported Audio Formats:**\n    MP3, WAV, FLAC, M4A, OGG, and other common audio formats supported by AssemblyAI.\n    \n    **Response Includes:**\n    - Full transcript text\n    - Sentence-level timestamps with start/end times and confidence scores\n    - Speaker labels and speaker-specific segments (when speaker_labels is enabled)\n    - Automatically detected language (BCP-47 code)\n    - Overall confidence score\n    - Audio duration in seconds\n    \n    **Use Cases:**\n    - Long-form content transcription (podcasts, lectures, webinars)\n    - Meeting recordings with multiple speakers\n    - Interview transcripts\n    - Video caption generation\n    - Content analysis and search indexing\n    \n    **Note:** This endpoint requires AssemblyAI API key configuration. It uses AssemblyAI's Universal model which provides excellent multilingual support and accuracy.","operationId":"transcribe_audio_long_v1_audio_transcriptions_long_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_transcribe_audio_long_v1_audio_transcriptions_long_post"}}}},"responses":{"200":{"description":"Structured transcription result with sentence-level segments, optional speaker diarization, and metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LongTranscriptionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/audio/realtime/sessions":{"post":{"tags":["audio"],"summary":"Create a realtime speech session ticket","description":"Create a short-lived ticket for the realtime speech transcription websocket. This request already supports `prompt`, `terms`, language hinting, VAD, and silence-window tuning. Use the returned `ws_url` to open the websocket, then stream PCM16 mono 24kHz audio frames. The websocket route itself is not part of OpenAPI, so see `GET /v1/audio/realtime/protocol` for the full protocol contract.","operationId":"create_realtime_session_v1_audio_realtime_sessions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealtimeSessionCreateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealtimeSessionCreateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/audio/realtime/protocol":{"get":{"tags":["audio"],"summary":"Describe the realtime speech websocket protocol","description":"Swagger/OpenAPI can describe the HTTP session-creation endpoint, but it does not automatically expose the actual websocket route. This companion endpoint documents the websocket URL, prompt support, client/server message types, and example payloads so the realtime flow remains discoverable inside Swagger UI.","operationId":"get_realtime_protocol_v1_audio_realtime_protocol_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealtimeProtocolDocResponse"}}}}}}},"/v1/search/":{"post":{"tags":["search"],"summary":"Perform web search using Tavily","description":"Execute web searches using the Tavily search engine.\n    \n    This API supports concurrent searches for multiple keywords. Each keyword is independently\n    queried against the Tavily API.\n    \n    The response includes:\n    - Detailed search results for each keyword (title, URL, content, score, etc.)\n    - Optional combined summary answer (if Tavily returns an answer)\n    - Error information for any keywords that failed to search (if any)\n    \n    The response data structure is consistent with the `search` tool call results returned\n    by the `supermind-agent-v1` model.","operationId":"search_v1_search__post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}},"required":true},"responses":{"200":{"description":"Tavily search results including detailed results for each keyword and optional combined summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/usage/summary":{"get":{"tags":["usage"],"summary":"Summarize recent and lifetime usage activity","operationId":"usage_summary_v1_usage_summary_get","responses":{"200":{"description":"Aggregated usage metrics for the authenticated account across lifetime and trailing 30-day windows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSummaryResponse"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/models":{"get":{"tags":["models"],"summary":"List available models","description":"Returns the list of chat and image models available through the AI Builder platform. Models are dynamically populated based on available API keys.","operationId":"list_models_v1_models_get","responses":{"200":{"description":"OpenAI-compatible model list with metadata about supported models.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelListResponse"}}}}}}},"/v1/deployments":{"get":{"tags":["deployments"],"summary":"List deployments owned by the authenticated user","description":"List all deployments owned by the authenticated user.\n\nThis endpoint returns a list of your deployments with their current status, URLs, and hosting information.\n\n**Related Resources:**\n- Deployment prompt for AI assistants: See `deployment_prompt_url` in the response\n- Full API documentation: https://www.ai-builders.com/resources/students-backend/openapi.json","operationId":"list_deployments_v1_deployments_get","responses":{"200":{"description":"Deployments sorted by service name, including hosting policy hints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeploymentListResponse"}}}}},"security":[{"bearerAuth":[]}]},"post":{"tags":["deployments"],"summary":"Queue a deployment via Koyeb + Nginx automation","description":"Queue a deployment for your FastAPI service to the AI Builder platform.\n\nThis experimental feature helps students:\n- Check and prepare repositories for deployment with AI assistance\n- Learn GitHub workflows and create open-source projects\n- Deploy to `ai-builders.space` for easy sharing\n\n**Limitations:**\n- Free hosting for 12 months from first successful deployment\n- Maximum number of services per user (varies by user, default is 2)\n- Contact instructors to delete services or extend hosting\n\n**How to Use:**\n1. Paste the deployment prompt (see `deployment_prompt_url` in response) to Cursor\n2. The AI will help make your repository deployment-ready\n3. Ask the AI to deploy when ready\n4. Wait 5-10 minutes for provisioning\n\n**Technical Requirements:**\n- Single process/single port (serve API and static files from one server)\n- Honor the `PORT` environment variable\n- Public repositories only (no secrets in code)\n- `AI_BUILDER_TOKEN` is injected automatically (read from environment variable)\n- Resource limit: 256 MB RAM (nano containers)\n\n**Related Resources:**\n- Deployment prompt for AI assistants: See `deployment_prompt_url` in the response\n- Full API documentation: https://www.ai-builders.com/resources/students-backend/openapi.json\n\n**Status Updates / Best Practice:**\n- This POST is asynchronous (202 Accepted). Poll `GET /v1/deployments/{service_name}` until `status` is a Koyeb status (`HEALTHY`, `UNHEALTHY`, `DEGRADED`, `ERROR`, etc.) instead of workflow states (`queued`, `deploying`) (typically 5–10 minutes).\n- The response blocks up to `streaming_log_timeout_seconds` (default 60s) to collect initial build logs and returns them in `streaming_logs`.\n- On failure, `message` will include Koyeb rollout errors/log hints to help you retry or iterate with AI assistants.","operationId":"trigger_deployment_v1_deployments_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeploymentCreateRequest"}}},"required":true},"responses":{"202":{"description":"Queued deployment along with reminders about hosting limits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeploymentStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/deployments/{service_name}":{"get":{"tags":["deployments"],"summary":"Retrieve a single deployment","description":"Retrieve detailed status and information for a specific deployment.\n\n**Related Resources:**\n- Deployment prompt for AI assistants: See `deployment_prompt_url` in the response\n- Full API documentation: https://www.ai-builders.com/resources/students-backend/openapi.json","operationId":"get_deployment_status_v1_deployments__service_name__get","security":[{"bearerAuth":[]}],"parameters":[{"name":"service_name","in":"path","required":true,"schema":{"type":"string","description":"Unique service name / subdomain.","title":"Service Name"},"description":"Unique service name / subdomain."}],"responses":{"200":{"description":"Detailed deployment status and suggested next steps.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeploymentStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/deployments/{service_name}/logs":{"get":{"tags":["deployments"],"summary":"Get deployment logs from Koyeb","operationId":"get_deployment_logs_v1_deployments__service_name__logs_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"service_name","in":"path","required":true,"schema":{"type":"string","description":"Unique service name / subdomain.","title":"Service Name"},"description":"Unique service name / subdomain."},{"name":"log_type","in":"query","required":false,"schema":{"type":"string","description":"Log type: build or runtime.","default":"runtime","title":"Log Type"},"description":"Log type: build or runtime."},{"name":"stream","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional stream filter: stdout, stderr, or koyeb.","title":"Stream"},"description":"Optional stream filter: stdout, stderr, or koyeb."},{"name":"timeout","in":"query","required":false,"schema":{"type":"integer","maximum":300,"minimum":1,"description":"Seconds to wait for streaming logs (max 300).","default":5,"title":"Timeout"},"description":"Seconds to wait for streaming logs (max 300)."},{"name":"deployment_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional deployment ID override.","title":"Deployment Id"},"description":"Optional deployment ID override."}],"responses":{"200":{"description":"Streaming logs from Koyeb for the specified deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeploymentLogsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/images/generations":{"post":{"tags":["images"],"summary":"Generate images from a prompt","operationId":"generate_images_v1_images_generations_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageGenerationRequest"}}},"required":true},"responses":{"200":{"description":"OpenAI-compatible image generation response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageGenerationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/images/edits":{"post":{"tags":["images"],"summary":"Edit an image with a prompt","operationId":"edit_images_v1_images_edits_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_edit_images_v1_images_edits_post"}}},"required":true},"responses":{"200":{"description":"OpenAI-compatible image edit response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageGenerationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/health":{"get":{"summary":"Healthcheck","operationId":"healthcheck_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Healthcheck Health Get"}}}}}}}},"components":{"schemas":{"Body_edit_images_v1_images_edits_post":{"properties":{"image":{"items":{"type":"string","format":"binary"},"type":"array","title":"Image","description":"Input image(s) to edit."},"prompt":{"type":"string","title":"Prompt","description":"Text description of desired edits."},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"N","default":1},"size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Size"},"quality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quality"},"response_format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Format"},"user":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User"},"background":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Background"},"output_format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Format"},"output_compression":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Output Compression"},"input_fidelity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Input Fidelity"},"mask":{"anyOf":[{"type":"string","format":"binary"},{"type":"null"}],"title":"Mask","description":"Optional mask PNG for edits."},"moderation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Moderation"},"partial_images":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Partial Images"},"stream":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Stream"}},"type":"object","required":["image","prompt"],"title":"Body_edit_images_v1_images_edits_post"},"Body_transcribe_audio_long_v1_audio_transcriptions_long_post":{"properties":{"audio_file":{"anyOf":[{"type":"string","format":"binary"},{"type":"null"}],"title":"Audio File","description":"Audio file to transcribe. Supported formats include MP3, WAV, FLAC, M4A, OGG, and other common audio formats. Required if audio_url is not provided."},"audio_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Audio Url","description":"Publicly accessible URL of the audio file to transcribe. The URL must be accessible without authentication. Required if audio_file is not provided."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"BCP-47 language code hint (e.g., 'en', 'en-US', 'zh-CN', 'es'). If not provided, the language will be automatically detected. Providing a language hint can improve accuracy and processing speed."},"speaker_labels":{"type":"boolean","title":"Speaker Labels","description":"Enable speaker diarization to automatically identify and label different speakers in the audio. When enabled, the response will include a 'speakers' field with speaker labels (e.g., 'A', 'B') for each sentence. Useful for multi-speaker content like meetings, interviews, or panel discussions. Default: true.","default":true},"disfluencies":{"type":"boolean","title":"Disfluencies","description":"Remove filler words and disfluencies (e.g., 'um', 'uh', 'like', 'you know') from the transcript. This produces cleaner, more professional transcripts but may slightly alter the original speech patterns.","default":false},"audio_start_from":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Audio Start From","description":"Start transcription from this timestamp in milliseconds. Useful for transcribing only a specific portion of long audio files. Must be less than audio_end_at if both are provided. Example: 60000 for 1 minute."},"audio_end_at":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Audio End At","description":"End transcription at this timestamp in milliseconds. Must be greater than audio_start_from if both are provided. Useful for transcribing only a specific portion of long audio files. Example: 300000 for 5 minutes."}},"type":"object","title":"Body_transcribe_audio_long_v1_audio_transcriptions_long_post"},"Body_transcribe_audio_v1_audio_transcriptions_post":{"properties":{"audio_file":{"anyOf":[{"type":"string","format":"binary"},{"type":"null"}],"title":"Audio File","description":"Audio file to transcribe (AI Builder). Supported formats: MP3, WAV, FLAC, M4A, etc."},"file":{"anyOf":[{"type":"string","format":"binary"},{"type":"null"}],"title":"File","description":"Audio file (OpenAI SDK compatibility; same as audio_file)."},"audio_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Audio Url","description":"Publicly accessible URL of the audio file to transcribe."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"BCP-47 language code hint (e.g., 'en', 'zh-CN'). Auto-detected if not provided."},"prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt","description":"Optional custom prompt appended to transcription instructions. Use for domain context or style hints. Applied only when using OpenAI Realtime provider."},"terms":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Terms","description":"Optional comma-separated terms to help recognition (e.g. 'dahlia,tulip'). Use for product names, jargon, or homophones. Applied only when using OpenAI Realtime provider."}},"type":"object","title":"Body_transcribe_audio_v1_audio_transcriptions_post"},"ChatCompletionChoice":{"properties":{"index":{"type":"integer","title":"Index","description":"Zero-based index of the choice in the returned list."},"message":{"$ref":"#/components/schemas/ChatCompletionChoiceMessage","description":"Assistant message produced for this choice."},"finish_reason":{"type":"string","enum":["stop","length","tool_calls","content_filter"],"title":"Finish Reason","description":"Explanation for why the model stopped generating tokens."},"logprobs":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Logprobs","description":"Optional token-level likelihoods when requested by the client."}},"type":"object","required":["index","message","finish_reason"],"title":"ChatCompletionChoice"},"ChatCompletionChoiceMessage":{"properties":{"role":{"type":"string","enum":["system","user","assistant","tool"],"title":"Role","description":"Role of the message as defined by the OpenAI Chat Completions specification."},"content":{"anyOf":[{"type":"string"},{"items":{"$ref":"#/components/schemas/ContentPart"},"type":"array"},{"type":"null"}],"title":"Content","description":"Message body. Can be a string (text) or a list of content parts (multimodal). For assistant messages with tool_calls, this should be null. For tool messages this should contain the tool output."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Optional identifier that lets the caller distinguish among assistant messages."},"tool_calls":{"anyOf":[{"items":{"$ref":"#/components/schemas/ToolCall"},"type":"array"},{"type":"null"}],"title":"Tool Calls","description":"Optional list of tool calls proposed alongside the assistant message."},"tool_call_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Call Id","description":"ID of the tool call that this message is responding to (for tool messages)."}},"type":"object","required":["role"],"title":"ChatCompletionChoiceMessage"},"ChatCompletionMessage":{"properties":{"role":{"type":"string","enum":["system","user","assistant","tool"],"title":"Role","description":"Role of the message as defined by the OpenAI Chat Completions specification."},"content":{"anyOf":[{"type":"string"},{"items":{"$ref":"#/components/schemas/ContentPart"},"type":"array"},{"type":"null"}],"title":"Content","description":"Message body. Can be a string (text) or a list of content parts (multimodal). For assistant messages with tool_calls, this should be null. For tool messages this should contain the tool output."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Optional identifier that lets the caller distinguish among assistant messages."},"tool_calls":{"anyOf":[{"items":{"$ref":"#/components/schemas/ToolCall"},"type":"array"},{"type":"null"}],"title":"Tool Calls","description":"Optional list of tool calls (for assistant messages)."},"tool_call_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Call Id","description":"ID of the tool call that this message is responding to (for tool messages)."}},"type":"object","required":["role"],"title":"ChatCompletionMessage"},"ChatCompletionRequest":{"properties":{"model":{"type":"string","title":"Model","description":"Target model identifier. Accepts `deepseek`, `deepseek-v4-flash`, `deepseek-v4-pro`, `supermind-agent-v1`, `gemini-2.5-pro`, `gemini-3-flash-preview`, `kimi-k2.5`, `gpt-5`, or `grok-4-fast`. Special restrictions: - `kimi-k2.5`: Only supports `temperature=1.0` (server will automatically set to 1.0). - `gpt-5`: Only supports `temperature=1.0` and uses `max_completion_tokens` instead of `max_tokens` (server will automatically convert `max_tokens` to `max_completion_tokens`). Recommended: Use `max_tokens` >= 1000 for `gpt-5` to ensure complete responses. - `grok-4-fast`: Passthrough model that routes to X.AI's Grok API.","default":"supermind-agent-v1"},"messages":{"items":{"$ref":"#/components/schemas/ChatCompletionMessage"},"type":"array","title":"Messages","description":"Ordered conversation history, following the OpenAI Chat Completions schema."},"temperature":{"anyOf":[{"type":"number","maximum":2.0,"minimum":0.0},{"type":"null"}],"title":"Temperature","description":"Sampling temperature; higher values yield more creative but varied outputs. Special restrictions: - For `kimi-k2.5` model, this will be automatically set to 1.0 regardless of the provided value. - For `gpt-5` model, this will be automatically set to 1.0 regardless of the provided value.","default":0.7},"max_tokens":{"anyOf":[{"type":"integer","exclusiveMinimum":0.0},{"type":"null"}],"title":"Max Tokens","description":"Upper bound on the number of tokens to generate in the completion. If not specified, the model will use the maximum available tokens (context window minus input tokens), matching OpenAI API default behavior. Special handling: - For `gpt-5` model, this will be automatically converted to `max_completion_tokens`. Recommended: Use `max_tokens` >= 1000 for `gpt-5` to ensure complete responses (the model generates long reasoning chains). - For `kimi-k2.5` model, standard `max_tokens` parameter is supported."},"top_p":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Top P","description":"Nucleus sampling parameter that limits token selection to a probability mass."},"stream":{"type":"boolean","title":"Stream","description":"When true, requests a streamed response.","default":false},"tools":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Tools","description":"Tool definitions that enable the model to return tool calls."},"tool_choice":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tool Choice","description":"Forces a specific tool call or `none` to disable tool calling."},"response_format":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Response Format","description":"OpenAI-compatible response format, e.g. `{\"type\": \"json_object\"}` for JSON mode."},"user":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User","description":"End-user identifier for abuse monitoring and rate limiting."},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Opaque key-value metadata echoed back in analytics events."}},"additionalProperties":true,"type":"object","required":["messages"],"title":"ChatCompletionRequest"},"ChatCompletionResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Unique identifier for the completion response."},"object":{"type":"string","const":"chat.completion","title":"Object","description":"Object type marker following OpenAI conventions.","default":"chat.completion"},"created":{"type":"integer","title":"Created","description":"Unix timestamp when the completion was generated."},"model":{"type":"string","title":"Model","description":"Identifier for the model that produced the completion."},"choices":{"items":{"$ref":"#/components/schemas/ChatCompletionChoice"},"type":"array","title":"Choices","description":"List of one or more completion choices."},"usage":{"$ref":"#/components/schemas/ChatCompletionUsage","description":"Token accounting for the request."},"system_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Fingerprint","description":"Optional fingerprint used for diagnosing safety system behavior."},"orchestrator_trace":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Orchestrator Trace","description":"调试用途的编排器执行轨迹，仅在显式开启 debug 时返回。"}},"type":"object","required":["id","created","model","choices","usage"],"title":"ChatCompletionResponse"},"ChatCompletionUsage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","description":"Number of tokens processed from the input messages."},"completion_tokens":{"type":"integer","title":"Completion Tokens","description":"Number of tokens generated in the response."},"total_tokens":{"type":"integer","title":"Total Tokens","description":"Sum of prompt and completion tokens."}},"type":"object","required":["prompt_tokens","completion_tokens","total_tokens"],"title":"ChatCompletionUsage"},"ContentPart":{"properties":{"type":{"type":"string","enum":["text","image_url"],"title":"Type","description":"Type of content part"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text","description":"Text content (required when type is 'text')"},"image_url":{"anyOf":[{"$ref":"#/components/schemas/ImageURL"},{"type":"null"}],"description":"Image URL (required when type is 'image_url')"}},"type":"object","required":["type"],"title":"ContentPart","description":"Single part of multimodal content."},"DeploymentCreateRequest":{"properties":{"repo_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Repo Url","description":"Public Git repository URL that Koyeb will clone. Must not contain secrets or private submodules."},"service_name":{"type":"string","pattern":"^[a-z0-9-]{3,32}$","title":"Service Name","description":"Unique service identifier, also used as the subdomain (lowercase letters, digits, hyphen)."},"branch":{"type":"string","maxLength":64,"minLength":1,"title":"Branch","description":"Git branch to deploy (e.g., 'main', 'master', 'develop'). This field is required."},"port":{"type":"integer","maximum":65535.0,"minimum":1.0,"title":"Port","description":"Container port for Koyeb routing configuration. Your application must honor the PORT environment variable set by Koyeb at runtime. This port value is only used for Koyeb's routing configuration.","default":8000},"env_vars":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Env Vars","description":"Environment variables as key-value pairs (maximum 20 variables).\n        \n        **Stateless Design**: These values are NOT stored in the platform database. They are passed directly to Koyeb during deployment. If not provided, no custom environment variables will be injected (only AI_BUILDER_TOKEN will be available).\n        \n        **Use Cases**:\n        - Database connection strings: DATABASE_URL, REDIS_URL\n        - API keys: OPENAI_API_KEY, STRIPE_SECRET_KEY\n        - Application configuration: NODE_ENV, LOG_LEVEL, API_BASE_URL\n        - Feature flags: ENABLE_FEATURE_X, DEBUG_MODE\n        - Application settings: MAX_CONNECTIONS, TIMEOUT_SECONDS\n        \n        **Security Notes**:\n        - Values are transmitted over HTTPS\n        - Never commit sensitive values (passwords, API keys) to Git repositories\n        - Use `.env` files for sensitive values (add to `.gitignore`)\n        - Consider using environment variable management tools\n        \n        **User Responsibility**:\n        - Maintain these values in your own configuration files (e.g., `deploy-config.json`)\n        - Create deployment scripts that read from config files\n        - Let AI assistants help manage your deployment configuration\n        \n        **For AI Assistants**: When helping users deploy:\n        1. Check if a `deploy-config.json` file exists in the project\n        2. If not, help create one with deployment parameters and environment variables\n        3. Remind users not to commit sensitive values to Git\n        4. When user says \"deploy\", read from config file and include env_vars in API request\n        5. Guide users to maintain their configuration for future deployments\n        \n        **Example**:\n        ```json\n        {\n          \"DATABASE_URL\": \"postgresql://user:pass@host:5432/db\",\n          \"NODE_ENV\": \"production\",\n          \"LOG_LEVEL\": \"info\",\n          \"API_BASE_URL\": \"https://api.example.com\"\n        }\n        ```\n        \n        **Best Practice**: Maintain a `deploy-config.json` file to avoid repeating environment variables in each deployment request.\n        "},"streaming_log_timeout_seconds":{"anyOf":[{"type":"integer","maximum":300.0,"minimum":5.0},{"type":"null"}],"title":"Streaming Log Timeout Seconds","description":"How long the deploy API will block to collect initial streaming logs from Koyeb. Defaults to 60 seconds, maximum 300 seconds.","default":60}},"type":"object","required":["repo_url","service_name","branch"],"title":"DeploymentCreateRequest","description":"Payload for queuing a deployment via the backend orchestrator.\n\n**Design Philosophy: Stateless Environment Variables**\n\nThis API follows a stateless design for environment variable injection:\n- Environment variables are NOT stored in the platform database\n- Users maintain their own configuration state (in config files, scripts, or environment)\n- Each deployment request can optionally include environment variables\n- The platform acts as a pass-through, forwarding variables directly to Koyeb\n- If `env_vars` is not provided, deployment proceeds without custom environment variables\n\n**Configuration Management:**\n\nUsers should maintain their environment variables in configuration files (e.g., `deploy-config.json`):\n- Create a `deploy-config.json` file in your project\n- Include deployment parameters and environment variables\n- AI assistants can help create and maintain this file\n- Never commit sensitive values (passwords, API keys) to Git repositories\n\n**Best Practices:**\n- Maintain environment variables in version-controlled config files\n- Use `.env` files for sensitive values (add to `.gitignore`)\n- Create deployment scripts that read from config files\n- Let AI assistants help manage your deployment configuration\n\n**Examples:**\n\nWithout environment variables (default):\n```json\n{\n  \"repo_url\": \"https://github.com/user/my-app\",\n  \"service_name\": \"my-app\",\n  \"branch\": \"main\",\n  \"port\": 8000\n}\n```\n\nWith environment variables:\n```json\n{\n  \"repo_url\": \"https://github.com/user/my-app\",\n  \"service_name\": \"my-app\",\n  \"branch\": \"main\",\n  \"port\": 8000,\n  \"env_vars\": {\n    \"DATABASE_URL\": \"postgresql://user:pass@host:5432/db\",\n    \"NODE_ENV\": \"production\",\n    \"LOG_LEVEL\": \"info\"\n  }\n}\n```\n\n**For AI Assistants**: When helping users deploy:\n1. Check if a `deploy-config.json` file exists\n2. If not, help create one with the deployment parameters\n3. Remind users not to commit sensitive values to Git\n4. When user says \"deploy\", read from config file and call API\n5. Guide users to maintain their configuration for future deployments\n\nFor detailed deployment instructions and AI assistant prompts, see the deployment_prompt_url\nin DeploymentStatusResponse. For complete API documentation, refer to:\nhttps://www.ai-builders.com/resources/students-backend/openapi.json","examples":[{"description":"Default deployment without custom environment variables","title":"Deployment without environment variables","value":{"branch":"main","port":8000,"repo_url":"https://github.com/user/my-app","service_name":"my-app"}},{"description":"Using direct values for configuration","title":"Deployment with environment variables","value":{"branch":"main","env_vars":{"DATABASE_URL":"postgresql://user:pass@host:5432/db","LOG_LEVEL":"info","NODE_ENV":"production"},"port":8000,"repo_url":"https://github.com/user/my-app","service_name":"my-app"}}]},"DeploymentListResponse":{"properties":{"limit":{"type":"integer","title":"Limit","description":"Maximum number of concurrent services permitted for the user."},"active_count":{"type":"integer","title":"Active Count","description":"How many services currently count against the limit."},"deployments":{"items":{"$ref":"#/components/schemas/DeploymentStatusResponse"},"type":"array","title":"Deployments","description":"Deployments owned by the authenticated user."}},"type":"object","required":["limit","active_count"],"title":"DeploymentListResponse"},"DeploymentLogsResponse":{"properties":{"service_name":{"type":"string","title":"Service Name","description":"Service name / deployment identifier."},"deployment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deployment Id","description":"Koyeb deployment ID used to fetch logs (if available)."},"log_type":{"type":"string","enum":["build","runtime"],"title":"Log Type","description":"Log type requested."},"stream":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stream","description":"Stream filter applied, if any."},"timeout":{"type":"integer","title":"Timeout","description":"Seconds waited to collect logs."},"logs":{"type":"string","title":"Logs","description":"Plain-text logs (merged streams).","default":""},"collected_at":{"type":"string","format":"date-time","title":"Collected At","description":"Timestamp when logs were collected."},"total_messages":{"type":"integer","title":"Total Messages","description":"Number of log messages collected."}},"type":"object","required":["service_name","log_type","timeout","collected_at","total_messages"],"title":"DeploymentLogsResponse"},"DeploymentStatusResponse":{"properties":{"service_name":{"type":"string","title":"Service Name","description":"Unique service identifier / subdomain."},"status":{"type":"string","enum":["queued","deploying","HEALTHY","UNHEALTHY","DEGRADED","SLEEPING","ERROR"],"title":"Status","description":"Deployment status: 'queued'/'deploying' for workflow states, or Koyeb service status (HEALTHY, UNHEALTHY, DEGRADED, SLEEPING, ERROR)."},"message":{"type":"string","title":"Message","description":"Human-readable message that includes next steps and contact info."},"streaming_logs":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Streaming Logs","description":"Recent streaming logs from Koyeb captured during the blocking window (build logs only)."},"repo_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Repo Url","description":"Repository currently associated with this deployment."},"branch":{"type":"string","title":"Branch","description":"Git branch currently associated with this deployment."},"port":{"type":"integer","title":"Port","description":"Container port configured for this deployment."},"public_url":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"type":"null"}],"title":"Public Url","description":"Generated domain for the service (https://<service>.ai-builders.space)."},"last_deployed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Deployed At","description":"Timestamp of the most recent successful deployment."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Timestamp of the latest status update."},"hosting_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Hosting Expires At","description":"Free hosting is guaranteed until this timestamp. Contact the instructors to extend."},"deployment_prompt_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Deployment Prompt Url","description":"Public prompt file describing deployment requirements, constraints, and best practices. This document can be pasted to Cursor or other AI assistants to help prepare repositories for deployment. For complete API documentation, see: https://www.ai-builders.com/resources/students-backend/openapi.json"},"ai_builder_token_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ai Builder Token Hint","description":"Explains how the platform injects your API key via environment variables during deployment."},"suggested_actions":{"items":{"type":"string"},"type":"array","title":"Suggested Actions","description":"Actionable reminders such as waiting 5–10 minutes, reviewing docs, and contacting instructors."},"is_experimental":{"type":"boolean","title":"Is Experimental","description":"Marks that the feature is experimental and may change or pause at any time.","default":true},"max_services_per_user":{"type":"integer","title":"Max Services Per User","description":"Maximum number of concurrent services allowed per student."},"git_commit_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Git Commit Id","description":"Git commit SHA of the current deployment."},"koyeb_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Koyeb Status","description":"Real-time Koyeb service status (HEALTHY, SLEEPING, UNHEALTHY, DEGRADED)."}},"type":"object","required":["service_name","status","message","repo_url","branch","port","updated_at","deployment_prompt_url","max_services_per_user"],"title":"DeploymentStatusResponse"},"EmbeddingData":{"properties":{"embedding":{"anyOf":[{"items":{"type":"number"},"type":"array"},{"type":"string"}],"title":"Embedding","description":"The embedding vector for the input text. Can be a list of floats or a base64-encoded string depending on encoding_format."},"index":{"type":"integer","title":"Index","description":"Index of the embedding in the batch."},"object":{"type":"string","const":"embedding","title":"Object","description":"Object type discriminator.","default":"embedding"}},"type":"object","required":["embedding","index"],"title":"EmbeddingData"},"EmbeddingRequest":{"properties":{"input":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}],"title":"Input","description":"Input text or texts to embed. Can be a single string or a list of strings."},"model":{"type":"string","title":"Model","description":"The embedding model to use. Supported models: text-embedding-3-small, text-embedding-3-large, text-embedding-ada-002.","default":"text-embedding-3-small"},"encoding_format":{"anyOf":[{"type":"string","enum":["float","base64"]},{"type":"null"}],"title":"Encoding Format","description":"Format for the embedding vector. 'float' returns a list of floats, 'base64' returns base64-encoded strings.","default":"float"},"dimensions":{"anyOf":[{"type":"integer","exclusiveMinimum":0.0},{"type":"null"}],"title":"Dimensions","description":"Optional dimensionality of the embedding. Only supported for text-embedding-3-* models."},"user":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User","description":"End-user identifier for abuse monitoring and rate limiting."}},"type":"object","required":["input"],"title":"EmbeddingRequest"},"EmbeddingResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Object type discriminator.","default":"list"},"data":{"items":{"$ref":"#/components/schemas/EmbeddingData"},"type":"array","title":"Data","description":"List of embedding objects, one per input text."},"model":{"type":"string","title":"Model","description":"Identifier of the embedding model used."},"usage":{"$ref":"#/components/schemas/EmbeddingUsage","description":"Token usage statistics for the request."}},"type":"object","required":["data","model","usage"],"title":"EmbeddingResponse"},"EmbeddingUsage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","description":"Number of tokens processed for the embedding."},"total_tokens":{"type":"integer","title":"Total Tokens","description":"Total tokens processed (same as prompt_tokens for embeddings)."}},"type":"object","required":["prompt_tokens","total_tokens"],"title":"EmbeddingUsage"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ImageGenerationData":{"properties":{"b64_json":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"B64 Json","description":"Base64-encoded image data."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"URL of the generated image."},"revised_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revised Prompt","description":"Revised prompt returned by the model."}},"type":"object","title":"ImageGenerationData"},"ImageGenerationRequest":{"properties":{"prompt":{"type":"string","title":"Prompt","description":"Text description of the desired image."},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"Image model to use. Defaults to gpt-image-1.5 when omitted."},"n":{"anyOf":[{"type":"integer","maximum":10.0,"minimum":1.0},{"type":"null"}],"title":"N","description":"Number of images to generate.","default":1},"size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Size","description":"Image size, e.g. 1024x1024, 1536x1024, 1024x1536."},"quality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quality","description":"Image quality. GPT image models support low/medium/high/auto."},"response_format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Format","description":"Return format for legacy models: url or b64_json."},"moderation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Moderation","description":"Content moderation level for GPT image models: low or auto."},"partial_images":{"anyOf":[{"type":"integer","maximum":3.0,"minimum":0.0},{"type":"null"}],"title":"Partial Images","description":"Number of partial images to generate for streaming responses (0-3)."},"stream":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Stream","description":"Whether to stream image generation results."},"user":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User","description":"End-user identifier for abuse monitoring."},"background":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Background","description":"Background for GPT image models: transparent, opaque, or auto."},"output_format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Format","description":"Output image format for GPT image models: png, jpeg, or webp."},"output_compression":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Output Compression","description":"Output compression for GPT image models (0-100)."},"style":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Style","description":"Image style for DALL-E 3 models: vivid or natural."}},"additionalProperties":true,"type":"object","required":["prompt"],"title":"ImageGenerationRequest"},"ImageGenerationResponse":{"properties":{"created":{"type":"integer","title":"Created","description":"Unix timestamp (seconds) when the image was created."},"data":{"items":{"$ref":"#/components/schemas/ImageGenerationData"},"type":"array","title":"Data","description":"List of generated images."},"usage":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Usage","description":"Optional usage information returned by the provider."},"background":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Background","description":"Background setting used for generation."},"output_format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Format","description":"Output format of the generated image."},"size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Size","description":"Size of the generated image."},"quality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quality","description":"Quality of the generated image."}},"type":"object","required":["created","data"],"title":"ImageGenerationResponse"},"ImageURL":{"properties":{"url":{"type":"string","title":"Url","description":"Image URL or data URI (e.g., data:image/png;base64,...)"}},"type":"object","required":["url"],"title":"ImageURL","description":"Image URL for multimodal content."},"LongTranscriptionResponse":{"properties":{"request_id":{"type":"string","title":"Request Id","description":"Unique server-generated identifier for this transcription request. Use this ID for tracing, debugging, or support inquiries."},"text":{"type":"string","title":"Text","description":"The complete transcribed text content of the audio file, formatted as a single string."},"sentences":{"anyOf":[{"items":{"$ref":"#/components/schemas/SentenceSegment"},"type":"array"},{"type":"null"}],"title":"Sentences","description":"Array of sentence-level segments with timing information. Each segment includes the transcribed text, start/end times in seconds, and optional confidence score. This provides sentence-level granularity which is more efficient than word-level timestamps for long audio files."},"segments":{"anyOf":[{"items":{"$ref":"#/components/schemas/TranscriptionSegment"},"type":"array"},{"type":"null"}],"title":"Segments","description":"Array of segments with timing information, compatible with OpenAI API format. This field contains the same data as 'sentences' but uses the 'segments' field name for compatibility with OpenAI SDK. Each segment includes start/end times in seconds, transcribed text, and optional confidence score."},"detected_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detected Language","description":"BCP-47 language code of the detected language (e.g., 'en', 'en-US', 'zh-CN'). Automatically detected by the model if no language hint was provided in the request. May be None if language detection failed or was not performed."},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds","description":"Total duration of the processed audio file in seconds. This represents the actual audio length that was transcribed, which may be less than the full file duration if audio_start_from or audio_end_at parameters were used."},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence","description":"Overall confidence score for the entire transcription, ranging from 0.0 to 1.0. Higher values indicate higher transcription confidence. This is an aggregate score across all sentences. May be None if confidence scoring is not available."},"speakers":{"anyOf":[{"items":{"$ref":"#/components/schemas/SpeakerSentence"},"type":"array"},{"type":"null"}],"title":"Speakers","description":"Array of speaker-specific sentence segments with diarization information. Only included when speaker_labels parameter was set to true in the request. Each segment includes the speaker label (e.g., 'A', 'B'), sentence text, timing information, and confidence score. Use this to identify which speaker said what in multi-speaker audio content."},"words":{"anyOf":[{"items":{"$ref":"#/components/schemas/WordSegment"},"type":"array"},{"type":"null"}],"title":"Words","description":"Array of word-level segments with timing and optional speaker. Useful for podcast editing and fine-grained timestamps. Each word includes start/end times in seconds, text, confidence score, and speaker label when speaker_labels is enabled."}},"type":"object","required":["request_id","text"],"title":"LongTranscriptionResponse","description":"Response model for long audio transcription with sentence-level timestamps and advanced features.\n\nThis response includes sentence-level segmentation (instead of word-level) which is more efficient\nfor long audio files, along with optional speaker diarization results."},"ModelInfo":{"properties":{"id":{"type":"string","title":"Id"},"object":{"type":"string","const":"model","title":"Object","default":"model"},"created":{"type":"integer","title":"Created"},"owned_by":{"type":"string","title":"Owned By","default":"ai-builder-student-portal"},"permission":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Permission"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Human-readable description of the model's capabilities and use cases."}},"type":"object","required":["id"],"title":"ModelInfo"},"ModelListResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ModelInfo"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"ModelListResponse"},"RealtimeProtocolDocResponse":{"properties":{"session_endpoint":{"type":"string","title":"Session Endpoint","description":"HTTP endpoint used to create a short-lived realtime session ticket."},"websocket_endpoint":{"type":"string","title":"Websocket Endpoint","description":"WebSocket endpoint template. Replace `ticket` with the value returned by the session endpoint."},"swagger_visibility":{"type":"string","title":"Swagger Visibility","description":"Explains what part of the realtime flow appears in OpenAPI/Swagger and what part does not."},"authentication":{"type":"string","title":"Authentication","description":"Authentication flow for creating and using a realtime session."},"prompt_support":{"type":"string","title":"Prompt Support","description":"How custom prompt support works in the realtime API."},"session_request_example":{"additionalProperties":true,"type":"object","title":"Session Request Example","description":"Example JSON body for `POST /v1/audio/realtime/sessions`."},"session_response_example":{"additionalProperties":true,"type":"object","title":"Session Response Example","description":"Example JSON response returned by the session-creation endpoint."},"websocket_messages":{"items":{"$ref":"#/components/schemas/RealtimeProtocolMessageExample"},"type":"array","title":"Websocket Messages","description":"Representative client/server websocket messages for the realtime protocol."},"notes":{"items":{"type":"string"},"type":"array","title":"Notes","description":"Additional implementation notes and operational guidance."}},"type":"object","required":["session_endpoint","websocket_endpoint","swagger_visibility","authentication","prompt_support","session_request_example","session_response_example"],"title":"RealtimeProtocolDocResponse"},"RealtimeProtocolMessageExample":{"properties":{"direction":{"type":"string","enum":["client_to_server","server_to_client"],"title":"Direction","description":"Direction of the websocket message flow."},"message_type":{"type":"string","title":"Message Type","description":"The `type` field carried in the websocket JSON message."},"description":{"type":"string","title":"Description","description":"What this message is used for."},"example":{"additionalProperties":true,"type":"object","title":"Example","description":"Example websocket payload."}},"type":"object","required":["direction","message_type","description","example"],"title":"RealtimeProtocolMessageExample"},"RealtimeSessionCreateRequest":{"properties":{"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Optional BCP-47 language hint for realtime transcription."},"prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt","description":"Optional custom prompt appended to transcription instructions."},"terms":{"items":{"type":"string"},"type":"array","title":"Terms","description":"Optional custom terms to improve recognition."},"model":{"type":"string","title":"Model","description":"Realtime model to use for the upstream OpenAI session.","default":"gpt-realtime"},"vad":{"type":"boolean","title":"Vad","description":"Enable server-side voice activity detection for auto-commit behavior.","default":true},"silence_duration_ms":{"type":"integer","maximum":10000.0,"minimum":200.0,"title":"Silence Duration Ms","description":"Silence window used by server-side VAD before treating an utterance as stopped.","default":1200}},"type":"object","title":"RealtimeSessionCreateRequest","examples":[{"language":"zh-CN","model":"gpt-realtime","prompt":"Keep the original Chinese wording. Do not translate.","silence_duration_ms":1200,"terms":["Superlinear","Logto","Koyeb"],"vad":true}]},"RealtimeSessionCreateResponse":{"properties":{"session_id":{"type":"string","title":"Session Id","description":"Server-generated identifier for the realtime session."},"ticket":{"type":"string","title":"Ticket","description":"One-time short-lived ticket used to establish the websocket connection."},"ws_url":{"type":"string","title":"Ws Url","description":"Relative websocket URL for the realtime endpoint."},"expires_in":{"type":"integer","title":"Expires In","description":"Ticket lifetime in seconds."}},"type":"object","required":["session_id","ticket","ws_url","expires_in"],"title":"RealtimeSessionCreateResponse"},"SearchError":{"properties":{"keyword":{"type":"string","title":"Keyword","description":"The keyword that failed to search."},"error":{"type":"string","title":"Error","description":"Error description."}},"type":"object","required":["keyword","error"],"title":"SearchError"},"SearchQueryResult":{"properties":{"keyword":{"type":"string","title":"Keyword","description":"The search keyword used for this query."},"response":{"additionalProperties":true,"type":"object","title":"Response","description":"Raw response from Tavily API."}},"type":"object","required":["keyword","response"],"title":"SearchQueryResult"},"SearchRequest":{"properties":{"keywords":{"items":{"type":"string"},"type":"array","minItems":1,"title":"Keywords","description":"List of search keywords. Must contain at least one keyword."},"max_results":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Max Results","description":"Maximum number of results to return per keyword.","default":6}},"type":"object","required":["keywords"],"title":"SearchRequest"},"SearchResponse":{"properties":{"queries":{"items":{"$ref":"#/components/schemas/SearchQueryResult"},"type":"array","title":"Queries","description":"Search results for each keyword."},"combined_answer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Combined Answer","description":"Combined summary answer from all keyword searches, if available."},"errors":{"anyOf":[{"items":{"$ref":"#/components/schemas/SearchError"},"type":"array"},{"type":"null"}],"title":"Errors","description":"List of keywords that failed to search along with error information."}},"type":"object","required":["queries"],"title":"SearchResponse"},"SentenceSegment":{"properties":{"start":{"type":"number","title":"Start","description":"Start time of the sentence in seconds, measured from the beginning of the audio file."},"end":{"type":"number","title":"End","description":"End time of the sentence in seconds, measured from the beginning of the audio file."},"text":{"type":"string","title":"Text","description":"The transcribed text content of this sentence segment."},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence","description":"Confidence score for this sentence segment, ranging from 0.0 to 1.0. Higher values indicate higher transcription confidence. May be None if confidence scoring is not available."}},"type":"object","required":["start","end","text"],"title":"SentenceSegment","description":"Sentence-level segment with timing information and confidence score."},"SpeakerSentence":{"properties":{"speaker":{"type":"string","title":"Speaker","description":"Speaker label identifier (e.g., 'A', 'B', 'C') assigned by the diarization algorithm. Each unique speaker in the audio receives a distinct label."},"start":{"type":"number","title":"Start","description":"Start time of the sentence in seconds, measured from the beginning of the audio file."},"end":{"type":"number","title":"End","description":"End time of the sentence in seconds, measured from the beginning of the audio file."},"text":{"type":"string","title":"Text","description":"The transcribed text content of this sentence segment spoken by the identified speaker."},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence","description":"Confidence score for this sentence segment, ranging from 0.0 to 1.0. Higher values indicate higher transcription confidence. May be None if confidence scoring is not available."}},"type":"object","required":["speaker","start","end","text"],"title":"SpeakerSentence","description":"Sentence segment with speaker diarization information."},"ToolCall":{"properties":{"id":{"type":"string","title":"Id","description":"Unique identifier for the tool call returned by the model."},"type":{"type":"string","const":"function","title":"Type","description":"Type discriminator for OpenAI tool calls.","default":"function"},"function":{"$ref":"#/components/schemas/ToolFunctionCall","description":"Function invocation payload supplied by the model."}},"type":"object","required":["id","function"],"title":"ToolCall"},"ToolFunctionCall":{"properties":{"name":{"type":"string","title":"Name"},"arguments":{"type":"string","title":"Arguments","description":"JSON-encoded arguments as returned by the model."}},"type":"object","required":["name","arguments"],"title":"ToolFunctionCall"},"TranscriptionBillingInfo":{"properties":{"audio_input_tokens":{"type":"integer","title":"Audio Input Tokens","description":"Number of audio input tokens."},"text_input_tokens":{"type":"integer","title":"Text Input Tokens","description":"Number of text input tokens.","default":0},"output_tokens":{"type":"integer","title":"Output Tokens","description":"Number of output tokens."},"audio_input_cost":{"type":"number","title":"Audio Input Cost","description":"Cost for audio input in USD."},"text_input_cost":{"type":"number","title":"Text Input Cost","description":"Cost for text input in USD.","default":0.0},"text_output_cost":{"type":"number","title":"Text Output Cost","description":"Cost for text output in USD."},"total_cost":{"type":"number","title":"Total Cost","description":"Total cost in USD."}},"type":"object","required":["audio_input_tokens","output_tokens","audio_input_cost","text_output_cost","total_cost"],"title":"TranscriptionBillingInfo","description":"Billing information for transcription requests."},"TranscriptionResponse":{"properties":{"request_id":{"type":"string","title":"Request Id","description":"Server-generated identifier for tracing the transcription request."},"text":{"type":"string","title":"Text","description":"Full transcript returned by the speech service."},"segments":{"anyOf":[{"items":{"$ref":"#/components/schemas/TranscriptionSegment"},"type":"array"},{"type":"null"}],"title":"Segments","description":"Segment-level timing data when available."},"detected_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detected Language","description":"Language automatically detected by the model."},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds","description":"Duration of the processed audio in seconds."},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence","description":"Overall confidence estimate for the transcript."},"billing":{"anyOf":[{"$ref":"#/components/schemas/TranscriptionBillingInfo"},{"type":"null"}],"description":"Billing information when available (e.g., for OpenAI Realtime API)."}},"type":"object","required":["request_id","text"],"title":"TranscriptionResponse"},"TranscriptionSegment":{"properties":{"start":{"type":"number","title":"Start","description":"Segment start time in seconds from the beginning of the audio."},"end":{"type":"number","title":"End","description":"Segment end time in seconds from the beginning of the audio."},"text":{"type":"string","title":"Text","description":"Transcribed text for the segment."},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence","description":"Optional confidence score reported by the transcription model."}},"type":"object","required":["start","end","text"],"title":"TranscriptionSegment"},"UsageBreakdown":{"properties":{"model":{"type":"string","title":"Model","description":"Model identifier or `*` when aggregating across models."},"total_requests":{"type":"integer","title":"Total Requests","description":"Number of requests served within the window."},"prompt_tokens":{"type":"integer","title":"Prompt Tokens","description":"Sum of prompt tokens consumed."},"completion_tokens":{"type":"integer","title":"Completion Tokens","description":"Sum of completion tokens generated."},"tool_calls":{"type":"integer","title":"Tool Calls","description":"Total tool calls invoked across all requests."},"estimated_cost_usd":{"type":"number","title":"Estimated Cost Usd","description":"Estimated spend in USD for the window."}},"type":"object","required":["model","total_requests","prompt_tokens","completion_tokens","tool_calls","estimated_cost_usd"],"title":"UsageBreakdown"},"UsageSummaryResponse":{"properties":{"user_id":{"type":"string","title":"User Id","description":"Identifier of the user whose usage is being reported."},"windows":{"items":{"$ref":"#/components/schemas/UsageWindow"},"type":"array","title":"Windows","description":"Collection of usage windows calculated for the user."},"generated_at":{"type":"string","format":"date-time","title":"Generated At","description":"Timestamp when the summary was generated."},"cost_ceiling_usd":{"type":"number","title":"Cost Ceiling Usd","description":"Configured spending ceiling in USD for the user account."},"lifetime_cost_usd":{"type":"number","title":"Lifetime Cost Usd","description":"Total estimated cost accumulated across all usage."},"over_cost_ceiling":{"type":"boolean","title":"Over Cost Ceiling","description":"Indicates whether the lifetime spend has exceeded the configured cost ceiling."}},"type":"object","required":["user_id","windows","generated_at","cost_ceiling_usd","lifetime_cost_usd","over_cost_ceiling"],"title":"UsageSummaryResponse"},"UsageWindow":{"properties":{"period_start":{"type":"string","format":"date-time","title":"Period Start","description":"Inclusive UTC timestamp for the beginning of the window."},"period_end":{"type":"string","format":"date-time","title":"Period End","description":"Exclusive UTC timestamp for the end of the window."},"aggregates":{"$ref":"#/components/schemas/UsageBreakdown","description":"Usage metrics aggregated across the window."}},"type":"object","required":["period_start","period_end","aggregates"],"title":"UsageWindow"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WordSegment":{"properties":{"start":{"type":"number","title":"Start","description":"Start time of the word in seconds, measured from the beginning of the audio file."},"end":{"type":"number","title":"End","description":"End time of the word in seconds, measured from the beginning of the audio file."},"text":{"type":"string","title":"Text","description":"The transcribed text of this word."},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence","description":"Confidence score for this word, ranging from 0.0 to 1.0."},"speaker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Speaker","description":"Speaker label (e.g., 'A', 'B') when speaker_labels is enabled. None otherwise."}},"type":"object","required":["start","end","text"],"title":"WordSegment","description":"Word-level segment with timing and optional speaker. Useful for podcast editing and fine-grained timestamps."}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}}}}