{ "openapi": "3.1.0", "info": { "title": "Octen API", "description": "Octen API provides Broad Search, Web Search, Image Search, Video Search, Extract, Embeddings, VL Embeddings, Answer, and Deep Research services. The Web Search API searches ranked web results with optional filters, highlights, and full content. The Image Search API searches for images from a text query or an image. The Video Search API searches for videos from a text query. The Broad Search API decomposes a query into multiple sub-queries, searches them in parallel, and returns results grouped by sub-query. The Extract API extracts clean content from URLs, with optional query-focused highlights, page classification, and multimedia resources. The Embeddings API converts text into vector representations. The VL Embeddings API converts multimodal inputs into vector representations. The Answer API decomposes queries into multiple sub-queries for comprehensive search and synthesis. The Deep Research API runs a multi-round adaptive research pipeline that produces a structured research plan, executes iterative searches, and streams a final long-form report.", "version": "1.0.0" }, "servers": [ { "url": "https://api.octen.ai" } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "paths": { "/search": { "post": { "summary": "Web Search", "description": "Searches the live web and returns ranked results with model-ready highlights and optional full content. Optional filters narrow sources, time windows, and languages.", "operationId": "search", "security": [ { "bearerAuthNoPayment": [] }, { "apiKeyAuthNoPayment": [] } ], "x-mint": { "href": "/api-reference/search", "metadata": { "title": "Web Search", "sidebarTitle": "Web Search" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" }, "examples": { "basic": { "summary": "Basic Search", "value": { "query": "What record did Kendrick Lamar break at the 2026 Grammy Awards?", "count": 5 } }, "domainFiltering": { "summary": "Domain Filtering + Time Range + Highlights", "value": { "query": "summary judgment", "count": 10, "time_basis": "published", "start_time": "2024-01-01T00:00:00+08:00", "end_time": "2025-01-01T00:00:00+08:00", "include_domains": [ "uscourts.gov" ], "highlight": { "enable": true, "max_tokens": 300 }, "full_content": { "enable": false }, "format": "text" } }, "fullContent": { "summary": "Full Content Enabled", "value": { "query": "latest WHO guidance on influenza vaccination", "count": 5, "full_content": { "enable": true, "max_tokens": 1000 } } } } } } }, "responses": { "200": { "description": "Successful search response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" }, "example": { "code": 0, "msg": "success", "request_id": "req_abc123def456", "data": { "query": "latest WHO guidance on influenza vaccination", "results": [ { "title": "Influenza (Seasonal) - World Health Organization (WHO)", "url": "https://www.who.int/news-room/fact-sheets/detail/influenza-(seasonal)", "highlight": "WHO recommends annual vaccination for high-risk groups\n\n...\n\nSeasonal influenza vaccination policies vary by region...", "authors": "World Health Organization", "time_published": "2024-10-15T00:00:00Z", "time_last_crawled": "2026-01-20T02:12:34Z", "favicon": "https://www.who.int/favicon.ico", "cover_image": { "url": "https://www.who.int/images/default-source/influenza/seasonal-influenza-cover.jpg", "description": "Seasonal influenza vaccination" }, "images": [ { "url": "https://www.who.int/images/default-source/influenza/influenza-vaccine-vial.jpg", "description": "A vial of seasonal influenza vaccine." } ] } ] }, "meta": { "usage": { "num_search_queries": 1, "full_content_extra_count": 0 }, "latency": 237, "warning": null } } } } }, "400": { "description": "Missing parameter query — Returned when a required parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 400, "msg": "Missing parameter query", "request_id": "req_abc123def456" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientBalance" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/news-search": { "post": { "summary": "News Search", "description": "Searches live news and returns ranked articles with model-ready highlights, images, and optional full content. Related articles are also grouped into subjects, each with a summary, a representative article, and its own timeline.", "operationId": "news-search", "security": [ { "bearerAuthNoPayment": [] }, { "apiKeyAuthNoPayment": [] } ], "x-mint": { "href": "/api-reference/news-search", "metadata": { "title": "News Search", "sidebarTitle": "News Search" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsSearchRequest" }, "examples": { "basic": { "summary": "Basic News Search", "value": { "query": "Federal Reserve interest rate decision", "count": 5 } }, "subjects": { "summary": "Subject Grouping", "value": { "query": "Federal Reserve interest rate decision", "count": 5, "subjects": { "enable": true, "count": 3, "max_sub_news": 5 } } }, "filtering": { "summary": "Domain Filtering + Time Range + Language", "value": { "query": "semiconductor export controls", "count": 10, "include_domains": [ "reuters.com" ], "language": [ "en" ], "time_basis": "published", "start_time": "2026-08-22T00:00:00Z", "end_time": "2026-08-24T00:00:00Z", "highlight": { "enable": true, "max_tokens": 300 }, "subjects": { "enable": false } } } } } } }, "responses": { "200": { "description": "Successful news search response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsSearchResponse" }, "example": { "code": 0, "msg": "success", "request_id": "req_abc123def456", "data": { "query": "Federal Reserve interest rate decision", "results": [ { "title": "Federal Reserve raises interest rates by 25 basis points", "url": "https://www.example-news.com/markets/fed-raises-rates", "highlight": "The committee voted unanimously to lift the benchmark rate to a range of 3.75% to 4.00%...", "authors": "Example News", "time_published": "2026-09-15T15:32:37Z", "time_last_crawled": "2026-09-15T18:04:11Z", "favicon": "https://www.example-news.com/favicon.ico", "cover_image": { "url": "https://cdn.example-news.com/2026/09/fed-building.png", "description": "The Federal Reserve building in Washington." }, "images": [ { "url": "https://cdn.example-news.com/2026/09/trading-floor.png", "description": "A trading floor after the announcement." } ] } ], "subjects": [ { "name": "Federal Reserve raises interest rates in first hike since 2023", "summary": "The Federal Reserve voted unanimously to raise its benchmark rate by 25 basis points, the first increase since 2023, citing persistent inflation.", "time_start": "2026-09-15T05:53:22Z", "time_latest": "2026-09-15T15:32:37Z", "top_news": { "title": "Fed delivers first rate hike in years with unanimous vote", "url": "https://www.example-news.com/markets/fed-first-hike", "summary": "Policymakers raised the benchmark rate by a quarter point and signaled that further increases depend on incoming inflation data.", "highlight": "Every voting member backed the increase, an unusual show of consensus...", "authors": "Example News", "time_published": "2026-09-15T15:32:37Z", "time_last_crawled": "2026-09-15T18:04:11Z", "favicon": "https://www.example-news.com/favicon.ico", "cover_image": { "url": "https://cdn.example-news.com/2026/09/fed-press-conference.png", "description": "The chair speaking at the post-meeting press conference." }, "images": [] }, "sub_news": [ { "title": "Mortgage rates climb after the Fed announcement", "url": "https://www.example-news.com/markets/mortgage-rates-climb", "highlight": "Lenders repriced within hours of the decision...", "authors": "Example News", "time_published": "2026-09-15T09:11:02Z", "time_last_crawled": "2026-09-15T12:40:55Z", "favicon": "https://www.example-news.com/favicon.ico", "cover_image": { "url": "https://cdn.example-news.com/2026/09/mortgage-rates.png", "description": "A chart of average mortgage rates." }, "images": [] } ] } ] }, "meta": { "usage": { "num_search_queries": 1, "num_subject_search_queries": 1, "full_content_extra_count": 0 }, "latency": 245, "warning": "" } } } } }, "400": { "description": "Invalid or missing parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 400, "msg": "Invalid params. Missing parameter query", "request_id": "req_abc123def456" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientBalance" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/business-search": { "post": { "summary": "Business Search", "description": "Searches the web for business content. The companies and people behind the query are also returned as entity cards.", "operationId": "business-search", "security": [ { "bearerAuthNoPayment": [] }, { "apiKeyAuthNoPayment": [] } ], "x-mint": { "href": "/api-reference/business-search", "metadata": { "title": "Business Search", "sidebarTitle": "Business Search" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessSearchRequest" }, "examples": { "basic": { "summary": "Basic Business Search", "value": { "query": "NVIDIA quarterly results", "count": 5 } }, "entities": { "summary": "Entity Cards", "value": { "query": "NVIDIA quarterly results", "count": 5, "entities": { "enable": true, "count": 2, "max_activities": 5, "max_news": 5 } } }, "filtering": { "summary": "Domain Filtering + Time Range + Language", "value": { "query": "semiconductor export controls", "count": 10, "include_domains": [ "reuters.com" ], "language": [ "en" ], "time_basis": "published", "start_time": "2026-08-22T00:00:00Z", "end_time": "2026-08-24T00:00:00Z", "highlight": { "enable": true, "max_tokens": 300 }, "entities": { "enable": false } } } } } } }, "responses": { "200": { "description": "Successful business search response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessSearchResponse" }, "examples": { "company": { "summary": "Company Entity", "value": { "code": 0, "msg": "success", "request_id": "req_abc123def456", "data": { "query": "NVIDIA quarterly results", "results": [ { "title": "NVIDIA Announces Financial Results for Second Quarter Fiscal 2027", "url": "https://investor.nvidia.com/financial-info/financial-reports/default.aspx", "highlight": "Second-quarter revenue rose 106% from a year ago, with data center revenue up 117%...", "time_published": "2026-08-26T00:00:00Z", "time_last_crawled": "2026-10-13T01:31:46Z", "favicon": "https://investor.nvidia.com/favicon.ico" } ], "entities": [ { "type": "company", "name": "NVIDIA", "summary": "Since its founding in 1993, NVIDIA has been a pioneer in accelerated computing. Its invention of the GPU in 1999 redefined computer graphics and ignited the era of modern AI...", "aliases": [ "nvidia", "nvidia corporation" ], "identifiers": { "website": "nvidia.com", "linkedin_url": "https://www.linkedin.com/company/nvidia", "stock_ticker": "XNAS:NVDA", "sec_cik": "0001045810" }, "attributes": { "industry": "Computer Hardware Manufacturing", "hq_location": "2701 San Tomas Expressway, Santa Clara, CA 95050, US", "founded_year": 1993 }, "metrics": { "financials": [ { "revenue": 81615003648, "net_income": 58320998400, "gross_profit": 61156999168, "period": "Q1, 2027", "currency": "USD" } ], "stock": { "price": 224.45, "todays_change_percent": -2.11, "week_52_high": 243.37, "week_52_low": 164.27, "date": "2026-10-12", "currency": "USD" }, "funding": [ { "round": "Post-IPO Debt", "amount": 25000000000, "date": "2026-06-01", "currency": "USD" } ], "web_traffic": { "visits_monthly": 38505903, "rank": 903, "period": "2026-08" } }, "key_people": [ { "name": "Jensen Huang", "title": "Founder, President and Chief Executive Officer" } ], "logo": { "url": "https://cdn.example-cdn.com/logos/nvidia.png" }, "activities": [ { "title": "A new beginning for Windows PCs", "url": "https://www.linkedin.com/company/nvidia/posts", "highlight": "Join us at one of our RTX Spark launch events for demos on the new laptops...", "authors": "NVIDIA", "time_published": "2026-10-12T18:15:39Z" } ], "news": [ { "title": "Chipmaker weighs buyback option in data centre listing dispute", "url": "https://www.example-news.com/markets/data-centre-listing-dispute", "highlight": "Confidential agreements put the AI infrastructure venture on a collision course with its own backers...", "time_published": "2026-10-11T18:00:00Z", "time_last_crawled": "2026-10-11T18:01:35Z", "favicon": "https://www.example-news.com/favicon.ico", "cover_image": { "url": "https://cdn.example-news.com/2026/10/data-centre.png", "description": "A data centre under construction." } } ] } ] }, "meta": { "usage": { "num_search_queries": 1 }, "latency": 229, "warning": "" } } }, "person": { "summary": "Person Entity", "value": { "code": 0, "msg": "success", "request_id": "req_abc123def456", "data": { "query": "Jensen Huang NVIDIA CEO", "results": [ { "title": "Jensen Huang | NVIDIA", "url": "https://www.nvidia.com/en-us/about-nvidia/board-of-directors/jensen-huang/", "highlight": "Jensen Huang founded NVIDIA in 1993 and has served since its inception as president, chief executive officer and a member of the board of directors...", "time_last_crawled": "2026-10-12T15:28:10Z" } ], "entities": [ { "type": "person", "name": "Jensen Huang", "summary": "Co-founder, president and chief executive officer of NVIDIA, which he started in 1993 to solve the problem of 3D graphics for the PC...", "linkedin_url": "https://www.linkedin.com/in/jenhsunhuang", "current_position": "Founder and CEO, NVIDIA", "career": [ { "organization": "NVIDIA", "title": "Founder and CEO", "start": "1993" } ], "photo": { "url": "https://cdn.example-cdn.com/photos/jensen-huang.jpg" }, "activities": [ { "title": "AI factories are the defining infrastructure of the AI era", "url": "https://www.linkedin.com/in/jenhsunhuang/recent-activity/", "highlight": "In the AI economy, compute is revenue...", "authors": "Jensen Huang", "time_published": "2026-08-17T12:47:03Z", "time_last_crawled": "2026-08-24T14:15:01Z" } ], "news": [ { "title": "NVIDIA chief becomes the world's seventh-richest person as shares hit a record", "url": "https://www.example-news.com/markets/nvidia-chief-net-worth", "highlight": "His fortune has surged alongside the chipmaker's rise to the most valuable public company in the world...", "time_published": "2026-10-03T01:55:07Z", "time_last_crawled": "2026-10-03T01:56:55Z", "favicon": "https://www.example-news.com/favicon.ico", "cover_image": { "url": "https://cdn.example-news.com/2026/10/keynote-stage.png", "description": "The NVIDIA chief executive on stage at a keynote." } } ] } ] }, "meta": { "usage": { "num_search_queries": 1 }, "latency": 246, "warning": "" } } } } } } }, "400": { "description": "Invalid or missing parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 400, "msg": "Invalid params. Missing parameter query", "request_id": "req_abc123def456" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientBalance" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/image-search": { "post": { "summary": "Image Search", "operationId": "image-search", "description": "Searches the web for images.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageSearchRequest" }, "examples": { "plainText": { "summary": "Plain text query", "value": { "inputs": [ { "type": "text", "data": "DJI Mavic 4 Pro review" } ], "count": 5 } }, "imageByUrl": { "summary": "Search by image (image as URL)", "value": { "inputs": [ { "type": "image", "url": "https://cdn.example-fashion.com/refs/vintage-dress.jpg" } ], "count": 5 } }, "imageByBase64": { "summary": "Search by image (base64 upload)", "value": { "inputs": [ { "type": "image", "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=" } ], "count": 5 } } } } } }, "responses": { "200": { "description": "Successful image search response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageSearchResponse" }, "examples": { "general": { "summary": "General image search", "value": { "code": 0, "msg": "success", "request_id": "req_9d1c4f7a2e6b0853", "data": { "results": [ { "title": "Scandinavian Minimalist Living Room", "url": "https://images.unsplash.com/photo-scandi-living-room.jpg", "source_page": "https://unsplash.com/photos/scandi-living-room", "description": "A Scandinavian minimalist living room with light wood flooring, an off-white sofa, and greenery; the composition is very close to the uploaded image.", "width": 1920, "height": 1280, "thumbnail": "https://images.unsplash.com/photo-scandi-living-room.jpg?w=200" }, { "title": "Minimalist Interior Inspiration", "url": "https://i.pinimg.com/originals/minimal-interior.jpg", "source_page": "https://www.pinterest.com/pin/minimal-interior-inspiration", "description": "Minimalist interior design inspiration; the palette and layout are close to the uploaded image.", "width": 736, "height": 981, "thumbnail": "https://i.pinimg.com/236x/minimal-interior.jpg" } ] }, "meta": { "usage": { "num_search_queries": 1 }, "latency": 642 } } } } } } }, "400": { "description": "Missing parameter inputs — Returned when a required parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 400, "msg": "Missing parameter inputs", "request_id": "req_abc123def456" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientBalance" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "description": "Input unreadable or invalid — Returned when an input cannot be read or is otherwise invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 422, "msg": "Input unreadable or invalid", "request_id": "req_abc123def456" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/video-search": { "post": { "summary": "Video Search", "operationId": "video-search", "description": "Searches the web for videos from a text query. Contact us to request beta access.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoSearchRequest" }, "examples": { "text": { "summary": "Text query", "value": { "inputs": [ { "type": "text", "data": "how to make sourdough bread at home" } ], "count": 5 } } } } } }, "responses": { "200": { "description": "Successful video search response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoSearchResponse" }, "example": { "code": 0, "msg": "success", "request_id": "20260627120000001ABCDE12345", "data": { "results": [ { "title": "How to Make Sourdough Bread at Home (Beginner's Guide)", "url": "https://videos.example.com/watch/sourdough-beginners-guide.mp4", "source_page": "https://www.example.com/blog/sourdough-beginners-guide", "description": "A step-by-step beginner tutorial covering starter feeding, autolyse, stretch-and-fold, shaping, and baking in a Dutch oven.", "cover_url": "https://cdn.example.com/thumbs/sourdough-beginners-guide.jpg", "duration_seconds": 842, "authors": "The Home Baker", "time_published": "2026-02-14T09:30:00Z", "time_last_crawled": "2026-06-20T11:02:18Z" }, { "title": "Easy No-Knead Sourdough for Beginners", "url": "https://videos.example.com/watch/no-knead-sourdough.mp4", "source_page": "https://www.example.com/recipes/no-knead-sourdough", "description": "Demonstrates a simplified no-knead method, from mixing a high-hydration dough to scoring and baking a crusty loaf in a home oven.", "cover_url": "https://cdn.example.com/thumbs/no-knead-sourdough.jpg", "duration_seconds": 615, "authors": "Everyday Sourdough", "time_published": "2026-01-28T17:45:00Z", "time_last_crawled": "2026-06-19T22:14:55Z" } ] }, "meta": { "usage": { "num_search_queries": 1 }, "latency": 482 } } } } }, "400": { "description": "Missing parameter inputs — Returned when a required parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 400, "msg": "Missing parameter inputs", "request_id": "req_abc123def456" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientBalance" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/extract": { "post": { "summary": "Extract", "description": "Extracts clean markdown content from URLs. Supports batch processing, query-focused highlights, page classification, and multimedia resources.", "operationId": "extract", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractRequest" }, "examples": { "basic": { "summary": "Basic Extract", "value": { "urls": [ "https://octen.ai/", "https://docs.octen.ai/api-reference/search" ] } }, "intentQuery": { "summary": "Intent-focused Highlights with Query", "value": { "urls": [ "https://www.who.int/news-room/fact-sheets/detail/influenza-(seasonal)" ], "query": "vaccination guidelines" } }, "withMedia": { "summary": "With Multimedia Resources", "value": { "urls": [ "https://octen.ai/" ], "include_images": true, "include_videos": true, "include_audio": true } }, "advancedMode": { "summary": "Advanced Mode", "value": { "urls": [ "https://x.com/kzouapt" ], "mode": "advanced" } }, "withLinks": { "summary": "With Page Links", "value": { "urls": [ "https://octen.ai/" ], "include_links": { "scope": "prefer_internal", "max_links": 200 } } } } } } }, "responses": { "200": { "description": "Successful extraction response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractResponse" }, "example": { "code": 0, "msg": "success", "request_id": "req_abc123def456", "data": { "results": [ { "url": "https://octen.ai/", "status": "success", "resolved_mode": "standard", "title": "Octen | The Search infrastructure for AI", "full_content": "# Search infrastructure for AI\n\nReal-time indexing | Low latency | High reliability\n\nStart Building | View Docs\n\n## Search Beyond Text\n\nBeyond text queries: Octen's multimodal search understands images and videos alongside text...", "highlights": null, "time_published": null, "time_last_crawled": "2026-07-03T09:35:43Z", "page_structure": { "primary": "Index Page", "secondary": "Home Page" }, "category": { "primary": "Computers, Electronics & Technology", "secondary": "Search Engines" }, "favicon": "https://octen.ai/favicon.ico", "cover_image": { "url": "https://octen.ai/_next/static/media/octen-cover.dc74905e.png" }, "images": [ { "url": "https://octen.ai/_next/static/media/multi-modal-img.ccffddff.png" }, { "url": "https://octen.ai/_next/static/media/showcase-multimodal1.449ae003.png" } ], "videos": [ { "url": "https://octen.ai/static/video/multimodal-video.mp4" } ], "links": [ { "url": "https://octen.ai/pricing", "anchor_text": "Pricing", "is_external": false }, { "url": "https://docs.octen.ai/overview/welcome", "anchor_text": "View Docs", "is_external": false }, { "url": "https://github.com/Octen-Team/octen-skills", "anchor_text": "GitHub", "is_external": true } ] }, { "url": "https://docs.octen.ai/api-reference/search", "status": "success", "resolved_mode": "standard", "title": "Search - Octen", "full_content": "# Search API\n\nOcten Search API enables ranked web results with query-focused highlights, time filtering, and multimodal assets...", "highlights": null, "time_published": "2024-10-15T00:00:00Z", "time_last_crawled": "2026-07-03T09:34:29Z", "page_structure": { "primary": "Content Page", "secondary": "Code" }, "category": { "primary": "Computers, Electronics & Technology", "secondary": "Search Engines" }, "favicon": "https://docs.octen.ai/favicon.ico", "cover_image": { "url": "https://octen.ai/_next/static/media/octen-cover.dc74905e.png" } } ] }, "meta": { "usage": { "total_urls": 2, "successful_urls": 2, "successful_by_mode": { "standard_urls": 2, "advanced_urls": 0 } }, "latency": 1832, "warning": "" } } } } }, "400": { "description": "Invalid params — Returned when a required parameter is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 400, "msg": "Invalid params. Missing parameter urls", "request_id": "req_abc123def456" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientBalance" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/embedding": { "post": { "summary": "Embedding", "description": "Converts text into vector representations. Supports batch input, multiple models, and configurable output dimensions.", "operationId": "embedding", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingRequest" }, "examples": { "singleInput": { "summary": "Single Input", "value": { "input": [ "What is vector search?" ], "model": "octen-embedding-8b", "dimension": 4096, "input_type": "query" } }, "batchInput": { "summary": "Batch Input", "value": { "input": [ "Vector databases store embeddings.", "Embeddings enable semantic search." ], "model": "octen-embedding-0.6b", "input_type": "document" } } } } } }, "responses": { "200": { "description": "Successful embedding response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingResponse" }, "example": { "code": 0, "msg": "success", "request_id": "req_abc123def456", "data": { "results": [ { "index": 0, "embedding": [ 0.0123, -0.0456, 0.0789 ] }, { "index": 1, "embedding": [ -0.0011, 0.0234, 0.0567 ] } ], "model": "octen-embedding-0.6b" }, "meta": { "usage": { "input_tokens": 128 }, "warning": "Input was truncated for one or more items." } } } } }, "400": { "description": "Missing required parameter — Returned when a required parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 400, "msg": "Missing required parameter", "request_id": "req_abc123def456" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientBalance" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/vl-embedding": { "post": { "summary": "VL Embedding", "description": "Converts multimodal input (text, images, and videos) into vector representations. Supports a single fused vector across modalities, independent per-element vectors, configurable output dimensions, video frame sampling control, and a custom task instruction.", "operationId": "vl-embedding", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VLEmbeddingRequest" }, "examples": { "textOnly": { "summary": "Text Only", "value": { "model": "octen-vl-embedding", "input": { "contents": [ { "text": "What is multimodal vector search?" } ] } } }, "multimodalFusion": { "summary": "Multimodal Fusion (text + images + video)", "value": { "model": "octen-vl-embedding-large", "input": { "contents": [ { "text": "Outdoor tent, 3-4 person, waterproof and windproof" }, { "image": "https://example.com/tent_setup.jpg" }, { "image": "https://example.com/tent_inside.jpg" }, { "video": "https://example.com/tent_demo.mp4" } ] }, "enable_fusion": true, "dimension": 2048, "fps": 0.3, "instruct": "Represent the outdoor product for retrieval" } }, "independentImages": { "summary": "Independent Image Embeddings", "value": { "model": "octen-vl-embedding", "input": { "contents": [ { "image": "https://example.com/product_1.jpg" }, { "image": "https://example.com/product_2.jpg" } ] }, "enable_fusion": false } } } } } }, "responses": { "200": { "description": "Successful VL embedding response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VLEmbeddingResponse" }, "examples": { "fusion": { "summary": "Fusion mode response (single fused vector)", "value": { "code": 0, "msg": "success", "request_id": "a7b8c9d0-e1f2-3456-abcd-789012345678", "data": { "results": [ { "index": 0, "embedding": [ 0.0156, -0.0298, 0.0411 ], "type": "fusion" } ], "model": "octen-vl-embedding-large" }, "meta": { "usage": { "input_tokens": 6814, "text_tokens": 18, "image_tokens": 6796, "image_count": 2, "duration": 22 }, "warning": null } } }, "independent": { "summary": "Independent mode response (one vector per element)", "value": { "code": 0, "msg": "success", "request_id": "a7b8c9d0-e1f2-3456-abcd-789012345678", "data": { "results": [ { "index": 0, "embedding": [ 0.0234, -0.0167, 0.0389 ], "type": "vl" }, { "index": 1, "embedding": [ -0.0312, 0.0445, 0.0178 ], "type": "vl" }, { "index": 2, "embedding": [ 0.0198, -0.0267, 0.0356 ], "type": "vl" }, { "index": 3, "embedding": [ -0.0089, 0.0334, -0.0223 ], "type": "vl" } ], "model": "octen-vl-embedding-large" }, "meta": { "usage": { "input_tokens": 6814, "text_tokens": 18, "image_tokens": 6796, "image_count": 2, "duration": 22 }, "warning": null } } } } } } }, "400": { "description": "Missing or invalid parameter — Returned when a required parameter is missing or has an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 400, "msg": "Missing or invalid parameter", "request_id": "req_abc123def456" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientBalance" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/chat/completions": { "post": { "summary": "Create a chat completion", "description": "Compatible with the OpenAI Chat Completions protocol, with optional built-in `octen_broad_search` and `octen_search` tools.", "operationId": "chat-completions", "x-mint": { "href": "/api-reference/chat-completions", "metadata": { "title": "LLM Chat (OpenAI-Compatible)", "sidebarTitle": "LLM Chat (OpenAI-Compatible)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" }, "examples": { "pureModel": { "summary": "Plain model call", "value": { "model": "anthropic/claude-opus-4.8", "messages": [ { "role": "user", "content": "Explain attention in one sentence." } ], "stream": false, "max_tokens": 2048, "temperature": 1 } }, "withBroadSearch": { "summary": "Built-in broad search tool", "value": { "model": "anthropic/claude-sonnet-4.6", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "Compare cloud GPU pricing across major providers." } ], "tools": [ { "type": "octen_broad_search", "parameters": { "max_queries": 5, "count": 10, "highlight": { "enable": true, "max_tokens": 300 }, "format": "markdown" } } ], "tool_choice": "auto", "stream": false } }, "withSearch": { "summary": "Built-in search tool", "value": { "model": "anthropic/claude-sonnet-4.6", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "What's the weather in Beijing today?" } ], "tools": [ { "type": "octen_search", "parameters": { "max_searches": 3, "count": 10, "highlight": { "enable": true, "max_tokens": 300 }, "format": "markdown" } } ], "tool_choice": "auto", "stream": false } }, "functionAndSearch": { "summary": "Custom function + built-in search", "value": { "model": "openai/gpt-5.4", "messages": [ { "role": "user", "content": "Check tomorrow's weather in Shanghai, then create a travel reminder." } ], "tools": [ { "type": "octen_search" }, { "type": "function", "function": { "name": "create_reminder", "description": "Create a reminder", "parameters": { "type": "object", "properties": { "content": { "type": "string", "description": "Reminder content" }, "time": { "type": "string", "description": "Reminder time, ISO 8601" } }, "required": [ "content", "time" ] } } } ], "tool_choice": "auto" } }, "promptCaching": { "summary": "Prompt caching", "value": { "model": "anthropic/claude-sonnet-4.6", "messages": [ { "role": "system", "content": [ { "type": "text", "text": "Product manual (long stable prefix)...", "cache_control": { "type": "ephemeral", "ttl": "5m" } } ] }, { "role": "user", "content": "What is the return policy?" } ], "max_tokens": 1024 } } } } } }, "responses": { "200": { "description": "Successful chat completion. When `stream=false`, returns a single `chat.completion` object. When `stream=true`, returns a stream of `chat.completion.chunk` objects (`search_done`, `content`, `finish`, `usage`), followed by `data: [DONE]`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ChatCompletionResponse" }, { "$ref": "#/components/schemas/ChatCompletionChunk" } ], "discriminator": { "propertyName": "object", "mapping": { "chat.completion": "#/components/schemas/ChatCompletionResponse", "chat.completion.chunk": "#/components/schemas/ChatCompletionChunk" } } }, "examples": { "nonStreaming": { "summary": "Non-streaming, plain model call", "value": { "id": "gen-1749812456-xyz7890", "object": "chat.completion", "created": 1749812456, "model": "anthropic/claude-opus-4.8", "choices": [ { "index": 0, "finish_reason": "stop", "message": { "role": "assistant", "content": "Attention lets a model dynamically weight its inputs and focus on the most relevant information.", "refusal": null, "reasoning": null } } ], "usage": { "prompt_tokens": 18, "completion_tokens": 32, "total_tokens": 50 } } }, "promptCache": { "summary": "Non-streaming, prompt cache hit", "value": { "id": "gen-1749812999-cache01", "object": "chat.completion", "created": 1749812999, "model": "anthropic/claude-sonnet-4.6", "choices": [ { "index": 0, "finish_reason": "stop", "message": { "role": "assistant", "content": "Per the manual, 7-day no-reason returns are supported.", "refusal": null, "reasoning": null } } ], "usage": { "prompt_tokens": 2106, "completion_tokens": 18, "total_tokens": 2124, "prompt_tokens_details": { "cached_tokens": 2048 } } } }, "withSearch": { "summary": "Non-streaming, with built-in search", "value": { "id": "gen-1749812345-abcd1234", "object": "chat.completion", "created": 1749812345, "model": "anthropic/claude-sonnet-4.6", "choices": [ { "index": 0, "finish_reason": "stop", "message": { "role": "assistant", "content": "OpenRouter is a unified platform aggregating multiple LLM providers behind one API.", "refusal": null, "reasoning": null, "annotations": [ { "type": "url_citation", "url_citation": { "url": "https://openrouter.ai/docs", "title": "OpenRouter Documentation", "start_index": 0, "end_index": 31 } } ] } } ], "search_results": [ { "query": "What is OpenRouter AI", "results": [ { "title": "OpenRouter Documentation", "url": "https://openrouter.ai/docs", "highlights": "OpenRouter provides a unified API for multiple LLM providers", "authors": "OpenRouter", "time_published": "2024-11-02T00:00:00Z", "time_last_crawled": "2025-01-10T12:30:00Z" } ] } ], "usage": { "num_search_queries": 1, "prompt_tokens": 1058, "completion_tokens": 132, "total_tokens": 1190 } } }, "toolCall": { "summary": "Non-streaming, custom function call", "value": { "id": "gen-1749812800-tool0001", "object": "chat.completion", "created": 1749812800, "model": "openai/gpt-5.4", "choices": [ { "index": 0, "finish_reason": "tool_calls", "message": { "role": "assistant", "content": null, "tool_calls": [ { "id": "call_abc123", "type": "function", "function": { "name": "create_reminder", "arguments": "{\"content\": \"Rain in Shanghai tomorrow, bring an umbrella\", \"time\": \"2026-06-11T08:00:00+08:00\"}" } } ], "refusal": null, "reasoning": null } } ], "usage": { "prompt_tokens": 230, "completion_tokens": 45, "total_tokens": 275 } } }, "streamSearchDone": { "summary": "Streaming, search_done chunk", "value": { "type": "search_done", "id": "20260318143837845RJQ9P28ZEC", "object": "chat.completion.chunk", "created": 1773844717, "model": "anthropic/claude-opus-4.6", "search_results": [ { "query": "weather Beijing today", "results": [ { "title": "Beijing Weather", "url": "https://weather.com/beijing", "highlights": "Partly cloudy, high of 32C", "authors": "weather.com", "time_published": "2026-06-10T00:00:00Z", "time_last_crawled": "2026-06-10T06:00:00Z" } ] } ] } }, "streamContent": { "summary": "Streaming, content chunk", "value": { "type": "content", "id": "gen-1749812600-stream001", "object": "chat.completion.chunk", "created": 1749812600, "model": "openai/gpt-5.4", "choices": [ { "index": 0, "delta": { "role": "assistant", "content": "OpenRouter is " }, "finish_reason": null } ] } }, "streamFinish": { "summary": "Streaming, finish chunk", "value": { "type": "finish", "id": "gen-1749812600-stream001", "object": "chat.completion.chunk", "created": 1749812600, "model": "openai/gpt-5.4", "choices": [ { "index": 0, "delta": {}, "finish_reason": "stop" } ] } }, "streamUsage": { "summary": "Streaming, usage chunk", "value": { "type": "usage", "id": "20260318143837845RJQ9P28ZEC", "object": "chat.completion.chunk", "created": 1773844727, "model": "anthropic/claude-opus-4.6", "usage": { "num_search_queries": 2, "full_content_extra_count": 5, "prompt_tokens": 1841, "completion_tokens": 638, "total_tokens": 2479, "completion_tokens_details": { "reasoning_tokens": 30 } } } }, "refusal": { "summary": "Safety refusal", "value": { "id": "gen-1749812700-refusal", "object": "chat.completion", "created": 1749812700, "model": "openai/gpt-5.4", "choices": [ { "index": 0, "finish_reason": "stop", "message": { "role": "assistant", "content": null, "refusal": "I can't help with that request.", "reasoning": null } } ] } } } } } }, "400": { "description": "Missing or invalid parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" }, "example": { "error": { "message": "Missing or invalid parameter", "type": "invalid_request_error", "param": null, "code": null } } } } }, "401": { "description": "Invalid API Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" }, "example": { "error": { "message": "Invalid API Key", "type": "authentication_error", "param": null, "code": null } } } } }, "403": { "description": "Insufficient balance in account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" }, "example": { "error": { "message": "Insufficient balance in account", "type": "permission_error", "param": null, "code": null } } } } }, "404": { "description": "Model or resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" }, "example": { "error": { "message": "Model or resource not found", "type": "not_found_error", "param": null, "code": null } } } } }, "429": { "description": "Exceeding the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" }, "example": { "error": { "message": "Exceeding the rate limit", "type": "rate_limit_error", "param": null, "code": null } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" }, "example": { "error": { "message": "Internal error", "type": "api_error", "param": null, "code": null } } } } } } } }, "/answer": { "post": { "summary": "Answer", "description": "Automatically decomposes user messages into multiple sub-queries, performs searches, and synthesizes results using an LLM.", "operationId": "answer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerRequest" }, "examples": { "basic": { "summary": "Basic Answer", "value": { "model": "anthropic/claude-sonnet-4.6", "messages": [ { "role": "user", "content": "Latest trends and major players in the global AI chip market in 2026" } ], "max_queries": 5, "stream": false, "web_search_options": { "count": 10, "highlight": { "enable": true, "max_tokens": 300 }, "full_content": { "enable": true, "max_tokens": 2048 } } } }, "queriesOnly": { "summary": "Queries Only Mode", "value": { "model": "anthropic/claude-sonnet-4.6", "messages": [ { "role": "user", "content": "What are the latest developments in quantum computing?" } ], "mode": "queries_only", "max_queries": 10 } }, "queriesAndSearch": { "summary": "Queries and Search Mode", "value": { "model": "anthropic/claude-sonnet-4.6", "messages": [ { "role": "user", "content": "Compare Tesla and BYD electric vehicle sales in 2026" } ], "mode": "queries_and_search", "max_queries": 8, "web_search_options": { "count": 5, "highlight": { "enable": true, "max_tokens": 300 } } } }, "multiTurn": { "summary": "Multi-turn Conversation", "value": { "model": "anthropic/claude-sonnet-4.6", "messages": [ { "role": "user", "content": "Who are the major players in the current chip market?" }, { "role": "assistant", "content": "Major players include NVIDIA, AMD, Intel, Broadcom, Google, Amazon, etc." }, { "role": "user", "content": "What are their latest developments?" } ], "max_queries": 10, "stream": false } }, "withDomainFilter": { "summary": "With Domain and Time Filters", "value": { "model": "anthropic/claude-sonnet-4.6", "messages": [ { "role": "user", "content": "Latest central bank interest rate decisions globally" } ], "max_queries": 15, "stream": false, "web_search_options": { "count": 10, "include_domains": [ "reuters.com" ], "exclude_domains": [ "medium.com" ], "include_text": [ "interest rate", "central bank" ], "exclude_text": [ "opinion", "rumor" ], "time_basis": "published", "start_time": "2025-01-01T00:00:00Z", "end_time": "2025-01-31T23:59:59Z", "highlight": { "enable": true, "max_tokens": 300 }, "format": "markdown", "safesearch": "strict", "full_content": { "enable": true, "max_tokens": 2048 } } } } } } } }, "responses": { "200": { "description": "Successful Answer response. When `stream=false`, returns a single `chat.completion` object with `queries` and `search_results` at the top level. When `stream=true`, returns a stream of `chat.completion.chunk` objects with types: `queries` (generated sub-queries), `search_done` (search results), `content` (incremental content), `finish` (completion signal), and `usage` (token usage).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AnswerResponse" }, { "$ref": "#/components/schemas/AnswerChunk" } ], "discriminator": { "propertyName": "object", "mapping": { "chat.completion": "#/components/schemas/AnswerResponse", "chat.completion.chunk": "#/components/schemas/AnswerChunk" } } }, "examples": { "nonStreaming": { "summary": "Non-streaming response (chat.completion)", "value": { "request_id": "20260403120000001ABCDE12345", "object": "chat.completion", "created": 1775361600, "model": "anthropic/claude-sonnet-4.6", "choices": [ { "index": 0, "finish_reason": "stop", "message": { "role": "assistant", "content": "## Global AI Chip Market in 2026: Latest Trends & Major Players\n\n**The AI chip market was valued at approximately $102.9 billion in 2025, and is projected to grow at a 29.4% CAGR to $1.35 trillion by 2035.** NVIDIA continues to dominate with over 80% data center market share, but the custom ASIC chip wave is accelerating challenges to its position.[^1][^6]\n\n### Major Players Overview\n\n| Company | Core Strength | Key 2026 Developments |\n|---|---|---|\n| **NVIDIA** | Data center GPU, >80% market share | Blackwell/Rubin roadmap, $1T revenue target |\n| **Broadcom** | Custom ASIC chips | Expected to capture 60% of custom AI chip market by 2027 |\n| **AMD** | GPU alternative | MI450 chip volume ramp in H2, OpenAI/Meta large orders |\n| **Intel** | CPU + foundry | Gaudi 3 launch, Xeon 6 selected for Nvidia DGX systems |\n| **Google** | In-house TPU (Ironwood) | Surging HBM demand |\n| **Amazon AWS** | Trainium series | Anthropic training Claude on over 1M Trainium2 chips |" } } ], "queries": [ "2026 global AI chip market trends", "AI chip market share 2026", "top AI chip manufacturers 2026", "NVIDIA AI chip dominance 2026", "AMD AI chip strategy 2026" ], "search_results": [ { "query": "2026 global AI chip market trends", "results": [ { "title": "AI Chip Market Size to Exceed USD 1354.35 Billion by 2035", "url": "http://globenewswire.com/news-release/2026/04/01/...", "highlight": "According to the SNS Insider, The AI Chip Market Size was valued at USD 102.89 Billion in 2025 and is expected to reach USD 1354.35 Billion by 2035...", "full_content": "", "authors": "SNS Insider pvt ltd", "time_published": "2026-04-01T07:30:00Z", "time_last_crawled": "2026-04-02T03:18:46Z" } ], "latency": 69 }, { "query": "AI chip market share 2026", "results": [ { "title": "Another result title...", "url": "https://example.com/...", "highlight": "...", "full_content": "", "authors": "...", "time_published": "2026-03-28T00:00:00Z", "time_last_crawled": "2026-03-29T12:00:00Z" } ], "latency": 72 } ], "meta": { "usage": { "num_search_queries": 20, "prompt_tokens": 35351, "completion_tokens": 942, "total_tokens": 36293 }, "latency": 24048 } } }, "streamQueries": { "summary": "Streaming chunk — queries (type: queries)", "value": { "type": "queries", "request_id": "20260403120000002XYZAB67890", "object": "chat.completion.chunk", "created": 1775361600, "model": "anthropic/claude-sonnet-4.6", "queries": [ "latest quantum computing developments 2026", "quantum computing breakthroughs 2026" ] } }, "streamSearchDone": { "summary": "Streaming chunk — search results (type: search_done)", "value": { "type": "search_done", "request_id": "20260403120000002XYZAB67890", "object": "chat.completion.chunk", "created": 1775361600, "model": "anthropic/claude-sonnet-4.6", "search_results": [ { "query": "latest quantum computing developments 2026", "results": [ { "title": "Stocks to Gain From Quantum Computing in 2025", "url": "https://www.nasdaq.com/articles/...", "highlight": "This year has seen quantum computing being pushed from lab interests toward practical deployments...", "full_content": "", "authors": "", "time_published": "2026-03-15T00:00:00Z", "time_last_crawled": "2026-03-16T12:00:00Z" } ], "latency": 65 } ] } }, "streamContent": { "summary": "Streaming chunk — content (type: content)", "value": { "type": "content", "request_id": "20260403120000002XYZAB67890", "object": "chat.completion.chunk", "created": 1775361600, "model": "anthropic/claude-sonnet-4.6", "choices": [ { "index": 0, "delta": { "content": "**Quantum computing" }, "finish_reason": null } ] } }, "streamFinish": { "summary": "Streaming chunk — finish (type: finish)", "value": { "type": "finish", "request_id": "20260403120000002XYZAB67890", "object": "chat.completion.chunk", "created": 1775361600, "model": "anthropic/claude-sonnet-4.6", "choices": [ { "index": 0, "delta": {}, "finish_reason": "stop" } ] } }, "streamUsage": { "summary": "Streaming chunk — usage (type: usage)", "value": { "type": "usage", "request_id": "20260403120000002XYZAB67890", "object": "chat.completion.chunk", "created": 1775361600, "model": "anthropic/claude-sonnet-4.6", "meta": { "usage": { "num_search_queries": 2, "prompt_tokens": 2664, "completion_tokens": 78, "total_tokens": 2742 }, "latency": 3565 } } } } } } }, "400": { "description": "Missing parameter messages — Returned when a required parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 400, "msg": "Missing parameter messages", "request_id": "req_abc123def456" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientBalance" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/broad-search": { "post": { "summary": "Broad Search", "description": "Decomposes a query into related sub-queries from multiple angles, searches them concurrently.", "operationId": "broad-search", "security": [ { "bearerAuthNoPayment": [] }, { "apiKeyAuthNoPayment": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadSearchRequest" }, "examples": { "basic": { "summary": "Basic Broad Search", "value": { "query": "compare cloud GPU pricing across major providers", "max_queries": 5 } }, "fullContent": { "summary": "With Full Content", "value": { "query": "compare cloud GPU pricing across major providers", "max_queries": 5, "search_options": { "count": 10, "highlight": { "enable": true, "max_tokens": 512 }, "full_content": { "enable": true, "max_tokens": 2048 } } } }, "domainFiltering": { "summary": "With Domain and Time Filters", "value": { "query": "Latest central bank interest rate decisions globally", "max_queries": 8, "search_options": { "count": 10, "include_domains": [ "reuters.com" ], "exclude_domains": [ "medium.com" ], "include_text": [ "interest rate", "central bank" ], "exclude_text": [ "opinion", "rumor" ], "time_basis": "published", "start_time": "2025-01-01T00:00:00Z", "end_time": "2025-01-31T23:59:59Z", "highlight": { "enable": true, "max_tokens": 512 }, "format": "markdown", "safesearch": "strict" } } }, "allOptions": { "summary": "All Options (every available parameter)", "value": { "query": "Latest central bank interest rate decisions globally", "max_queries": 8, "search_options": { "count": 10, "include_domains": [ "reuters.com", "bloomberg.com" ], "exclude_domains": [ "medium.com" ], "include_text": [ "interest rate", "central bank" ], "exclude_text": [ "opinion", "rumor" ], "time_basis": "published", "start_time": "2025-01-01T00:00:00Z", "end_time": "2025-01-31T23:59:59Z", "highlight": { "enable": true, "max_tokens": 512 }, "format": "markdown", "safesearch": "strict", "full_content": { "enable": true, "max_tokens": 2048 }, "include_images": true } } } } } } }, "responses": { "200": { "description": "Successful broad search response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadSearchResponse" }, "example": { "data": { "query": "Latest central bank interest rate decisions globally", "queries": [ "central bank interest rate decisions 2026", "latest global central bank rate hikes", "recent central bank monetary policy changes", "major central bank interest rate announcements today", "ECB interest rate decision 2026" ], "search_results": [ { "query": "recent central bank monetary policy changes", "results": [ { "title": "United States Monetary Policy June 2026 - FocusEconomics", "url": "https://www.focus-economics.com/countries/united-states/news/monetary-policy/...", "highlight": "United States: Central Bank keeps rates steady in June. At its 17 June meeting, the Central Bank kept the target range for the federal funds rate at 3.50-3.75%...", "full_content": "United States: Central Bank keeps rates steady in June\nLatest bank decision: At its 17 June meeting, the Central Bank kept the target range for the federal funds rate at 3.50-3.75%, following 75 basis points of rate cuts from August to December last year. [...truncated...]", "authors": "FocusEconomics", "time_published": "2026-06-18T00:00:00Z", "time_last_crawled": "2026-06-18T14:18:27Z", "favicon": "" } ], "latency": 116 }, { "query": "ECB interest rate decision 2026", "results": [ { "title": "Monetary policy decisions", "url": "https://www.ecb.europa.eu/press/pr/date/2025/html/ecb.mp251218~58b0e415a6.en.html", "highlight": "The Governing Council today decided to keep the three key ECB interest rates unchanged...", "full_content": "Monetary policy decisions\n18 December 2025\nThe Governing Council today decided to keep the three key ECB interest rates unchanged. [...truncated...]", "authors": "European Central Bank", "time_published": "2025-12-18T00:00:00Z", "time_last_crawled": "2026-05-20T22:27:18Z", "favicon": "" } ], "latency": 110 } ] }, "request_id": "20260626113629956CJ6G3AG7C2", "meta": { "usage": { "num_search_queries": 5, "full_content_extra_count": 20 }, "latency": 1649 }, "code": 0 } } } }, "400": { "description": "Invalid params — Returned when a required parameter is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 400, "msg": "Invalid params. query is required", "request_id": "req_abc123def456" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientBalance" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/research": { "post": { "summary": "Deep Research", "description": "Generates a deep research report at the selected tier. The `pro-visual` tier also returns relevant images and videos.\n\n**Two-phase invocation**\n- **Phase 1:** the server generates a research plan. If the plan has no ambiguity, the server proceeds directly to research and streams the final report. If the plan is ambiguous, the `plan` event carries `requires_selection=true` together with a `plan_id`, and the SSE stream ends there — waiting for the client to confirm.\n- **Phase 2:** call this endpoint again with the `plan_id` and `selections`. The server loads the stored plan, applies the selections, and streams the final report.\n\n**Notes**\n- Phase 2 only inherits the stored `plan` via `plan_id`. Other parameters are NOT inherited from Phase 1 — they must be supplied again in Phase 2, otherwise they fall back to defaults.\n- `messages` is required in both phases and should carry the same user question.", "operationId": "deep-research", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepResearchRequest" }, "examples": { "phase1": { "summary": "Phase 1 — Initial request", "value": { "tier": "standard", "messages": [ { "role": "user", "content": "Progress and key milestones of the Artemis program" } ] } }, "phase2": { "summary": "Phase 2 — Continue with plan_id and selections", "value": { "tier": "standard", "messages": [ { "role": "user", "content": "Progress and key milestones of the Artemis program" } ], "plan_id": "plan_20260403abc123", "selections": [ { "term": "Artemis", "chosen": "nasa_program", "indices": [ 0, 1, 3 ] } ], "extra_context": "Focus on developments after 2024; de-emphasize early program background." } } } } } }, "responses": { "200": { "description": "Successful Deep Research response. Always streamed as Server-Sent Events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepResearchChunk" }, "examples": { "streamStatus": { "summary": "Streaming chunk — pipeline progress (type: status)", "value": { "type": "status", "request_id": "20260403120000003ABCDE12345", "object": "research.chunk", "created": 1775361600, "model": "moonshotai/kimi-k2.5", "status": "Analyzing your question..." } }, "streamPlan": { "summary": "Streaming chunk — research plan (type: plan, requires_selection=true ends the stream)", "value": { "type": "plan", "request_id": "20260403120000003ABCDE12345", "object": "research.chunk", "created": 1775361600, "model": "moonshotai/kimi-k2.5", "plan_id": "plan_20260403abc123", "latency": 4120, "plan": { "title": "Artemis program research plan", "overview": "...", "interpretations": [ { "term": "Artemis", "meanings": [ { "id": "nasa_program", "label": "NASA-led crewed lunar program" }, { "id": "greek_goddess", "label": "Greek goddess of the hunt and the moon" } ], "chosen": "nasa_program", "reasoning": "The user asks about 'progress and milestones', which strongly points to the NASA program." } ], "angles": [ { "focus": "Artemis I-III mission progress", "focus_desc": "Timeline, payloads, and outcomes of launched and upcoming missions", "interpretation_id": "nasa_program", "queries": [ "Artemis I mission summary", "Artemis II crew launch date", "Artemis III lunar landing timeline" ], "sub_question_ids": [ "sq_progress" ] } ], "requires_selection": true } } }, "streamQueries": { "summary": "Streaming chunk — sub-queries for this round (type: queries)", "value": { "type": "queries", "request_id": "20260403120000003ABCDE12345", "object": "research.chunk", "created": 1775361600, "model": "moonshotai/kimi-k2.5", "round": 1, "latency": 312, "queries": [ "Artemis I mission summary", "Artemis II crew launch date", "Artemis III lunar landing timeline" ] } }, "streamSearchDone": { "summary": "Streaming chunk — search results for this round (type: search_done)", "value": { "type": "search_done", "request_id": "20260403120000003ABCDE12345", "object": "research.chunk", "created": 1775361600, "model": "moonshotai/kimi-k2.5", "round": 1, "latency": 1820, "search_result_count": 28, "search_results": [ { "query": "Artemis I mission summary", "results": [ { "title": "Artemis I Mission Overview - NASA", "url": "https://www.nasa.gov/...", "highlight": "Artemis I successfully launched on November 16, 2022...", "full_content": "", "authors": "NASA", "time_published": "2022-12-11T00:00:00Z", "time_last_crawled": "2026-04-02T03:18:46Z" } ], "latency": 69 } ] } }, "streamAnalysis": { "summary": "Streaming chunk — per-round findings (type: analysis)", "value": { "type": "analysis", "request_id": "20260403120000003ABCDE12345", "object": "research.chunk", "created": 1775361600, "model": "moonshotai/kimi-k2.5", "round": 1, "latency": 2940, "analysis": { "findings": [ "Artemis I completed a 25.5-day uncrewed lunar flyby in November 2022.", "Artemis II crewed lunar flyby is scheduled for 2026 with a 4-person crew.", "Artemis III lunar landing has slipped from 2025 to 2027." ], "should_continue": true, "follow_up_suggestions": [ "SLS Block 1B upgrade progress", "Starship HLS lander test milestones" ] } } }, "streamBrief": { "summary": "Streaming chunk — report outline and evidence (type: brief)", "value": { "type": "brief", "request_id": "20260403120000003ABCDE12345", "object": "research.chunk", "created": 1775361600, "model": "moonshotai/kimi-k2.5", "latency": 5310, "brief": { "report_type": "trend", "total_word_budget": 1800, "assertiveness_required": false, "tables": [ { "table_id": "t_milestones", "title": "Artemis mission milestones", "columns": [ "Mission", "Type", "Planned date", "Status" ], "description": "Key milestones across Artemis I-V.", "placement": "sec_timeline" } ], "outline": [ { "section_id": "sec_overview", "section_title": "Program background and goals", "thesis": "Artemis is NASA's first crewed lunar program since Apollo, aiming to return astronauts to the lunar surface before 2027.", "target_words": 300, "evidence": [ { "content": "Artemis was formally announced by NASA in 2017.", "source_indices": [ 1 ], "confidence": "strong" } ] } ], "unresolved": { "contradictions": [], "weak_claims": [ "Artemis IV commercial payload manifest" ], "unanswered": [] }, "suggested_title": "Artemis program: from uncrewed flyby to crewed landing", "references": [ { "index": 1, "url": "https://www.nasa.gov/...", "title": "Artemis I Mission Overview" } ] } } }, "streamContent": { "summary": "Streaming chunk — incremental report text (type: content)", "value": { "type": "content", "request_id": "20260403120000003ABCDE12345", "object": "research.chunk", "created": 1775361600, "model": "moonshotai/kimi-k2.5", "choices": [ { "index": 0, "delta": { "content": "## Program background and goals\n\nArtemis" }, "finish_reason": null } ] } }, "streamFinish": { "summary": "Streaming chunk — report stream complete (type: finish)", "value": { "type": "finish", "request_id": "20260403120000003ABCDE12345", "object": "research.chunk", "created": 1775361600, "model": "moonshotai/kimi-k2.5", "latency": 18420, "choices": [ { "index": 0, "delta": {}, "finish_reason": "stop" } ] } }, "streamUsage": { "summary": "Streaming chunk — usage and totals, last event in the stream (type: usage)", "value": { "type": "usage", "request_id": "20260403120000003ABCDE12345", "object": "research.chunk", "created": 1775361600, "model": "moonshotai/kimi-k2.5", "meta": { "usage": { "num_search_queries": 14, "prompt_tokens": 58210, "completion_tokens": 1832, "total_tokens": 60042 }, "latency": 32480, "total_rounds": 3, "total_search_count": 84 } } } } } } }, "400": { "description": "Missing parameter messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 400, "msg": "Missing parameter messages", "request_id": "req_abc123def456" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientBalance" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/messages": { "post": { "summary": "Create a message", "description": "Compatible with the Anthropic Messages protocol, with optional built-in `octen_broad_search` and `octen_search` tools.", "operationId": "messages", "x-mint": { "href": "/api-reference/messages", "metadata": { "title": "LLM Chat (Anthropic-Compatible)", "sidebarTitle": "LLM Chat (Anthropic-Compatible)" } }, "parameters": [ { "name": "anthropic-version", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Anthropic protocol version, e.g. `2023-06-01`. Sent automatically by the Anthropic SDK. Defaults to `2023-06-01` if omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesRequest" }, "examples": { "pureModel": { "summary": "Plain model call", "value": { "model": "anthropic/claude-opus-4.8", "max_tokens": 2048, "messages": [ { "role": "user", "content": "Explain attention in one sentence." } ] } }, "withBroadSearch": { "summary": "Built-in broad search tool", "value": { "model": "anthropic/claude-sonnet-4.6", "max_tokens": 2048, "system": "You are a helpful assistant.", "messages": [ { "role": "user", "content": "Compare cloud GPU pricing across major providers." } ], "tools": [ { "type": "octen_broad_search", "name": "octen_broad_search", "parameters": { "max_queries": 5, "count": 10, "highlight": { "enable": true, "max_tokens": 300 }, "format": "markdown" } } ], "tool_choice": { "type": "auto" } } }, "withSearch": { "summary": "Built-in search tool", "value": { "model": "anthropic/claude-sonnet-4.6", "max_tokens": 2048, "system": "You are a helpful assistant.", "messages": [ { "role": "user", "content": "What's the weather in Beijing today?" } ], "tools": [ { "type": "octen_search", "name": "octen_search", "parameters": { "max_searches": 3, "count": 10, "highlight": { "enable": true, "max_tokens": 300 }, "format": "markdown" } } ], "tool_choice": { "type": "auto" } } }, "customTool": { "summary": "Custom tool with tool_result", "value": { "model": "openai/gpt-5.4", "max_tokens": 2048, "messages": [ { "role": "user", "content": "Create a travel reminder for 8am tomorrow." }, { "role": "assistant", "content": [ { "type": "tool_use", "id": "toolu_abc123", "name": "create_reminder", "input": { "content": "Travel reminder", "time": "2026-06-11T08:00:00+08:00" } } ] }, { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_abc123", "content": "Reminder created." } ] } ], "tools": [ { "name": "create_reminder", "description": "Create a reminder", "input_schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Reminder content" }, "time": { "type": "string", "description": "Reminder time, ISO 8601" } }, "required": [ "content", "time" ] } } ] } } } } } }, "responses": { "200": { "description": "Successful message response. When `stream=false`, returns a single `message` object. When `stream=true`, returns an Anthropic SSE event stream.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/MessagesResponse" }, { "$ref": "#/components/schemas/MessagesStreamEvent" } ] }, "examples": { "pureModel": { "summary": "Non-streaming, plain model call", "value": { "id": "msg_01XFDUDYJgAACzvnptvVoYEL", "type": "message", "role": "assistant", "model": "anthropic/claude-opus-4.8", "content": [ { "type": "text", "text": "Attention lets a model dynamically weight its inputs and focus on the most relevant information." } ], "stop_reason": "end_turn", "stop_sequence": null, "usage": { "input_tokens": 18, "output_tokens": 32 } } }, "promptCache": { "summary": "Non-streaming, prompt cache hit", "value": { "id": "msg_01CacheHit789", "type": "message", "role": "assistant", "model": "anthropic/claude-sonnet-4.6", "content": [ { "type": "text", "text": "Per the manual, 7-day no-reason returns are supported." } ], "stop_reason": "end_turn", "stop_sequence": null, "usage": { "input_tokens": 58, "output_tokens": 18, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 2048 } } }, "withSearch": { "summary": "Non-streaming, with built-in search", "value": { "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF", "type": "message", "role": "assistant", "model": "anthropic/claude-sonnet-4.6", "content": [ { "type": "server_tool_use", "id": "srvtoolu_01ABC123", "name": "octen_search", "input": { "query": "weather Beijing today" } }, { "type": "web_search_tool_result", "tool_use_id": "srvtoolu_01ABC123", "content": [ { "type": "web_search_result", "title": "Beijing Weather", "url": "https://weather.com/beijing", "highlights": "Partly cloudy, high of 32C", "authors": "weather.com", "time_published": "2026-06-10T00:00:00Z", "time_last_crawled": "2026-06-10T06:00:00Z" } ] }, { "type": "text", "text": "Beijing is partly cloudy today with a high of 32C.", "citations": [ { "type": "web_search_result_location", "url": "https://weather.com/beijing", "title": "Beijing Weather", "cited_text": "Partly cloudy, high of 32C", "encrypted_index": "EpEBCioIAhgBIiQ4MmJjZD..." } ] } ], "stop_reason": "end_turn", "stop_sequence": null, "usage": { "input_tokens": 1058, "output_tokens": 132, "server_tool_use": { "web_search_requests": 1 } } } }, "toolUse": { "summary": "Non-streaming, custom tool call", "value": { "id": "msg_01HJK456", "type": "message", "role": "assistant", "model": "openai/gpt-5.4", "content": [ { "type": "tool_use", "id": "toolu_abc123", "name": "create_reminder", "input": { "content": "Rain in Shanghai tomorrow, bring an umbrella", "time": "2026-06-11T08:00:00+08:00" } } ], "stop_reason": "tool_use", "stop_sequence": null, "usage": { "input_tokens": 230, "output_tokens": 45 } } }, "streamMessageStart": { "summary": "Streaming, message_start event", "value": { "type": "message_start", "message": { "id": "msg_01XFD...", "type": "message", "role": "assistant", "model": "anthropic/claude-sonnet-4.6", "content": [], "usage": { "input_tokens": 1058, "output_tokens": 0 } } } }, "streamContentDelta": { "summary": "Streaming, content_block_delta event", "value": { "type": "content_block_delta", "index": 2, "delta": { "type": "text_delta", "text": "北京今天多云转晴，最高气温32度。" } } }, "streamMessageDelta": { "summary": "Streaming, message_delta event (cumulative usage)", "value": { "type": "message_delta", "delta": { "stop_reason": "end_turn", "stop_sequence": null }, "usage": { "output_tokens": 132, "server_tool_use": { "web_search_requests": 1 } } } }, "streamMessageStop": { "summary": "Streaming, message_stop event", "value": { "type": "message_stop" } } } } } }, "400": { "description": "Missing or invalid parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicErrorResponse" }, "example": { "type": "error", "error": { "type": "invalid_request_error", "message": "Missing or invalid parameter" } } } } }, "401": { "description": "Invalid API Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicErrorResponse" }, "example": { "type": "error", "error": { "type": "authentication_error", "message": "Invalid API Key" } } } } }, "403": { "description": "Insufficient balance in account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicErrorResponse" }, "example": { "type": "error", "error": { "type": "permission_error", "message": "Insufficient balance in account" } } } } }, "404": { "description": "Model or resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicErrorResponse" }, "example": { "type": "error", "error": { "type": "not_found_error", "message": "Model or resource not found" } } } } }, "413": { "description": "Request exceeds the maximum allowed size", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicErrorResponse" }, "example": { "type": "error", "error": { "type": "request_too_large", "message": "Request exceeds the maximum allowed size" } } } } }, "429": { "description": "Exceeding the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicErrorResponse" }, "example": { "type": "error", "error": { "type": "rate_limit_error", "message": "Exceeding the rate limit" } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicErrorResponse" }, "example": { "type": "error", "error": { "type": "api_error", "message": "Internal error" } } } } }, "529": { "description": "Service is temporarily overloaded, retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicErrorResponse" }, "example": { "type": "error", "error": { "type": "overloaded_error", "message": "Service is temporarily overloaded, retry later" } } } } } } } }, "/v1/images/generations": { "post": { "summary": "Generate an image", "description": "Compatible with the OpenAI Images protocol. Text-to-image when no image is provided; image editing when an image is provided.", "operationId": "images-generations", "x-mint": { "href": "/api-reference/images-generations", "metadata": { "title": "Image Generation", "sidebarTitle": "Image Generation" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationRequest" }, "examples": { "textToImageGpt": { "summary": "Text-to-image (gpt-image-2)", "value": { "model": "openai/gpt-image-2", "prompt": "A shiba inu wearing an astronaut helmet, flat illustration, starry background", "n": 1, "size": "1536x1024", "quality": "high", "output_format": "png" } }, "textToImageGemini": { "summary": "Text-to-image (Nano Banana 2)", "value": { "model": "google/gemini-3.1-flash-image", "prompt": "Cyberpunk Hong Kong street, neon lights, rainy night", "size": "1024x1536" } }, "imageEdit": { "summary": "Image editing", "value": { "model": "openai/gpt-image-2", "prompt": "Replace the dog's hat with a Santa hat", "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", "mask": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", "size": "1024x1024" } }, "layoutGemini": { "summary": "Complex layout and in-image text (gemini-3-pro-image)", "value": { "model": "google/gemini-3-pro-image", "prompt": "A cafe menu poster, big title MORNING BREW, four drinks with prices laid out clearly below, retro hand-drawn style", "size": "1024x1536", "thinking_level": "high" } } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImageGenerationFormRequest" } } } }, "responses": { "200": { "description": "Successful image response. When `stream=false`, returns a single object. When `stream=true` (GPT only), returns an SSE stream of `image_generation.partial_image` / `image_edit.partial_image` preview events followed by a `image_generation.completed` / `image_edit.completed` event.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ImageGenerationResponse" }, { "$ref": "#/components/schemas/ImageGenerationStreamEvent" } ] }, "examples": { "textToImage": { "summary": "Text-to-image (gpt-image-2)", "value": { "id": "img-9f2c1a7b3e6d4082", "created": 1749812456, "background": "opaque", "output_format": "png", "quality": "high", "size": "1536x1024", "data": [ { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." } ], "usage": { "input_tokens": 22, "input_tokens_details": { "text_tokens": 22, "image_tokens": 0 }, "output_tokens": 1056, "output_tokens_details": { "image_tokens": 1056, "text_tokens": 0 }, "total_tokens": 1078 } } }, "imageEdit": { "summary": "Image editing", "value": { "id": "img-4b8e2d1f6a9c7035", "created": 1749812680, "background": "opaque", "output_format": "png", "quality": "high", "size": "1024x1024", "data": [ { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." } ], "usage": { "input_tokens": 552, "input_tokens_details": { "text_tokens": 40, "image_tokens": 512 }, "output_tokens": 1056, "output_tokens_details": { "image_tokens": 1024, "text_tokens": 32 }, "total_tokens": 1608 } } }, "interleaved": { "summary": "Interleaved text and images (gemini-3-pro-image)", "value": { "id": "img-7c3a5e9d2b1f8460", "created": 1749812900, "output_format": "png", "data": [ { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...img1..." }, { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...img2..." } ], "text": "Step 1: mix flour and water into shreds.\nStep 2: knead into a smooth dough, rest 30 min.", "parts": [ { "type": "text", "text": "Step 1: mix flour and water into shreds." }, { "type": "image", "index": 0 }, { "type": "text", "text": "Step 2: knead into a smooth dough, rest 30 min." }, { "type": "image", "index": 1 } ], "usage": { "input_tokens": 20, "input_tokens_details": { "text_tokens": 20, "image_tokens": 0 }, "output_tokens": 2600, "output_tokens_details": { "image_tokens": 2560, "text_tokens": 40 }, "total_tokens": 2620 } } }, "streamPartialImage": { "summary": "Streaming, partial_image event", "value": { "id": "img-2e7a9c4f1b8d6053", "type": "image_generation.partial_image", "b64_json": "iVBORw0KGgoAAAANSUhEUg...", "created_at": 1749812456, "size": "1536x1024", "quality": "high", "background": "opaque", "output_format": "png", "partial_image_index": 0 } }, "streamCompleted": { "summary": "Streaming, completed event (with usage)", "value": { "id": "img-2e7a9c4f1b8d6053", "type": "image_generation.completed", "b64_json": "iVBORw0KGgoAAAANSUhEUg...", "created_at": 1749812461, "size": "1536x1024", "quality": "high", "background": "opaque", "output_format": "png", "usage": { "input_tokens": 22, "input_tokens_details": { "text_tokens": 22, "image_tokens": 0 }, "output_tokens": 1256, "output_tokens_details": { "image_tokens": 1256, "text_tokens": 0 }, "total_tokens": 1278 } } } } } } }, "400": { "description": "Missing or invalid parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" }, "example": { "error": { "message": "Missing or invalid parameter", "type": "invalid_request_error", "param": null, "code": null } } } } }, "401": { "description": "Invalid API Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" }, "example": { "error": { "message": "Invalid API Key", "type": "authentication_error", "param": null, "code": null } } } } }, "403": { "description": "Insufficient balance in account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" }, "example": { "error": { "message": "Insufficient balance in account", "type": "permission_error", "param": null, "code": null } } } } }, "404": { "description": "Model or resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" }, "example": { "error": { "message": "Model or resource not found", "type": "not_found_error", "param": null, "code": null } } } } }, "429": { "description": "Exceeding the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" }, "example": { "error": { "message": "Exceeding the rate limit", "type": "rate_limit_error", "param": null, "code": null } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" }, "example": { "error": { "message": "Internal error", "type": "api_error", "param": null, "code": null } } } } } } } }, "/v1/videos": { "post": { "summary": "Generate a video", "description": "Generates a video from a text prompt, optionally guided by reference images.", "operationId": "post-video", "x-mint": { "href": "/api-reference/post-video", "metadata": { "title": "Video Generation", "sidebarTitle": "Video Generation" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoGenerationRequest" } } } }, "responses": { "200": { "description": "Successful video generation response. The task starts in `queued`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoGenerationResponse" } } } }, "400": { "description": "Missing or invalid parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" } } } }, "401": { "description": "Invalid API Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient balance in account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" } } } }, "404": { "description": "Model or resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" } } } }, "429": { "description": "Exceeding the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" } } } } } } }, "/v1/videos/{id}": { "get": { "summary": "Download a video", "description": "Returns a video generation task by id.", "operationId": "get-video", "x-mint": { "href": "/api-reference/get-video", "metadata": { "title": "Video Download", "sidebarTitle": "Video Download" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "video-1756789012-abc123", "description": "The task id returned by the Video Generation API." } ], "responses": { "200": { "description": "Successful video task response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoTask" } } } }, "401": { "description": "Invalid API Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Video task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" } } } }, "429": { "description": "Exceeding the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" } } } } } } }, "/v1/grounded-generation": { "post": { "summary": "Generate an image or a video", "description": "Generates an image or a video from a text prompt, grounded in reference material found by search.", "operationId": "post-grounded-generation", "x-mint": { "href": "/api-reference/post-grounded-generation", "metadata": { "title": "Grounded Generation", "sidebarTitle": "Grounded Generation" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroundedGenerationRequest" }, "examples": { "image": { "summary": "Generate an image", "value": { "modality": "image", "prompt": "Ronaldo lifting the World Cup trophy, stadium lights", "model": "google/gemini-3-pro-image", "aspect_ratio": "16:9" } }, "video": { "summary": "Generate a video", "value": { "modality": "video", "prompt": "A Tesla Cybertruck driving through a snowy mountain pass at dawn", "aspect_ratio": "9:16", "duration": 10 } } } } } }, "responses": { "200": { "description": "Successful grounded generation response. The task starts in `queued`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroundedGenerationResponse" }, "example": { "request_id": "20260924020604287FV3DLUK7ZX", "generation_id": "mm-3ca3c4ff37c546b6b59f2e9cde09f2f6", "modality": "image", "status": "queued", "created_at": 1790215572 } } } }, "400": { "description": "Invalid params — Returned when a required parameter is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 400, "msg": "Unsupported multimodal model.", "request_id": "req_abc123def456" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientBalance" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/grounded-generation/{generation_id}": { "get": { "summary": "Get a generation result", "description": "Returns a grounded generation task by id.", "operationId": "get-grounded-generation", "x-mint": { "href": "/api-reference/get-grounded-generation", "metadata": { "title": "Generation Result", "sidebarTitle": "Generation Result" } }, "parameters": [ { "name": "generation_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "mm-3ca3c4ff37c546b6b59f2e9cde09f2f6", "description": "The task id returned by the Grounded Generation API." } ], "responses": { "200": { "description": "Successful grounded generation task response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroundedGenerationTask" }, "example": { "request_id": "20260924021635985E9WHYPV4FI", "generation_id": "mm-3ca3c4ff37c546b6b59f2e9cde09f2f6", "modality": "image", "status": "succeeded", "output_url": "https://apt-multimodal-output.octen.ai/apt-multimodal-output/images%2F2026_09_24%2Fmm-3ca3c4ff37c546b6b59f2e9cde09f2f6.jpg?se=...&sig=...", "references": [ { "source_id": "source1", "url": "https://upload.wikimedia.org/wikipedia/commons/2/26/Cristiano_Ronaldo_2026.jpg", "title": "Cristiano Ronaldo - Wikipedia", "cover_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:..." } ], "search_results": [ { "query": "Cristiano Ronaldo", "results": [ { "type": "image", "title": "Cristiano Ronaldo - Wikipedia", "url": "https://upload.wikimedia.org/wikipedia/commons/2/26/Cristiano_Ronaldo_2026.jpg", "source_page": "https://en.wikipedia.org/wiki/Cristiano_Ronaldo", "description": "en.wikipedia.org", "cover_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:..." } ] } ], "created_at": 1790215572, "updated_at": 1790215601, "usage": { "image_count": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Task not found or expired — Returned when the generation id does not exist or is older than 7 days.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 404, "msg": "Task not found or expired.", "request_id": "req_abc123def456" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "responses": { "Unauthorized": { "description": "Invalid API Key — Returned when the API key is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 401, "msg": "Invalid API Key", "request_id": "req_abc123def456" } } } }, "InsufficientBalance": { "description": "Insufficient balance in account — Returned when the account balance is insufficient to complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 403, "msg": "Insufficient balance in account", "request_id": "req_abc123def456" } } } }, "PayloadTooLarge": { "description": "Payload too large — Returned when the request payload exceeds the size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 413, "msg": "Payload too large", "request_id": "req_abc123def456" } } } }, "UnsupportedMediaType": { "description": "Unsupported media type — Returned when the input media format is not supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 415, "msg": "Unsupported media type", "request_id": "req_abc123def456" } } } }, "RateLimited": { "description": "Exceeding the rate limit — Returned when the request exceeds the configured rate limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 429, "msg": "Exceeding the rate limit", "request_id": "req_abc123def456" } } } }, "InternalError": { "description": "Internal error — Returned when an unexpected server-side error occurs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 500, "msg": "Internal error", "request_id": "req_abc123def456" } } } } }, "schemas": { "SearchRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "maxLength": 500, "description": "The search query.\n\n**Operators**\n\n- `site:`: restrict results to a single domain. For multiple domains, use `include_domains` and `exclude_domains`.\n- `-site:`: exclude a single domain from the results." } }, "allOf": [ { "$ref": "#/components/schemas/WebSearchOptions" } ] }, "HighlightOptions": { "type": "object", "description": "Controls highlight extraction from result pages.", "properties": { "enable": { "type": "boolean", "default": true, "description": "If true, returns query-relevant highlight in each result." }, "max_tokens": { "type": "integer", "default": 512, "minimum": 100, "maximum": 20000, "description": "Max tokens returned per highlight." } } }, "FullContentOptions": { "type": "object", "description": "Controls whether to return the full raw content of each result page.", "properties": { "enable": { "type": "boolean", "default": false, "description": "If true, returns full_content for each result." }, "max_tokens": { "type": "integer", "default": 2048, "minimum": 100, "maximum": 100000, "description": "Maximum tokens of full content included per result." } } }, "SearchResponse": { "type": "object", "properties": { "code": { "type": "integer", "description": "Business status code. 0 indicates success." }, "msg": { "type": "string", "description": "A message describing the result." }, "request_id": { "type": "string", "description": "The unique identifier for this request." }, "data": { "$ref": "#/components/schemas/SearchData" }, "meta": { "$ref": "#/components/schemas/SearchMeta" } } }, "SearchData": { "type": "object", "description": "The main response payload.", "properties": { "query": { "type": "string", "description": "The original query." }, "results": { "type": "array", "description": "A list of search results.", "items": { "$ref": "#/components/schemas/SearchResult" } } } }, "SearchResult": { "type": "object", "description": "A single search result.", "properties": { "title": { "type": "string", "description": "The title of the result page." }, "url": { "type": "string", "description": "The URL of the result page." }, "highlight": { "type": "string", "description": "Query-relevant highlight snippets. Returned only if highlight.enable is true." }, "full_content": { "type": "string", "description": "Full raw page content. Returned only if full_content.enable is true." }, "authors": { "type": "string", "description": "Website name or author." }, "time_published": { "type": "string", "format": "date-time", "description": "Publish time in ISO 8601." }, "time_last_crawled": { "type": "string", "format": "date-time", "description": "Last crawl time in ISO 8601." }, "favicon": { "type": "string", "description": "The favicon URL of the result site." }, "cover_image": { "type": "object", "description": "The page cover image. Returned only when `include_images` is true and the page has a cover image.", "properties": { "url": { "type": "string", "description": "The cover image URL." }, "description": { "type": "string", "description": "Text description of the cover image." } } }, "images": { "type": "array", "description": "In-body images of the page, in order of appearance. Returned only when `include_images` is true.", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "The image URL." }, "description": { "type": "string", "description": "Text description of the image." } } } } } }, "SearchMeta": { "type": "object", "description": "Additional metadata for the search request.", "properties": { "usage": { "$ref": "#/components/schemas/SearchUsage" }, "latency": { "type": "number", "description": "Response time in milliseconds." }, "warning": { "type": "string", "nullable": true, "description": "Warning message, if any." } } }, "SearchUsage": { "type": "object", "description": "Usage information for the search request.", "properties": { "num_search_queries": { "type": "integer", "description": "Number of search queries executed." }, "full_content_extra_count": { "type": "integer", "description": "Billable full_content results beyond the free allowance." } } }, "NewsSearchRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "maxLength": 500, "description": "The search query.\n\n**Operators**\n\n- `site:`: restrict results to a single domain. For multiple domains, use `include_domains` and `exclude_domains`.\n- `-site:`: exclude a single domain from the results." }, "count": { "type": "integer", "default": 5, "minimum": 1, "maximum": 100, "description": "Number of results to return." }, "include_domains": { "type": "array", "items": { "type": "string", "maxLength": 60 }, "maxItems": 1200, "description": "A list of domains to specifically include in the search results. The `site:` query operator adds to this list. Applies to `results` only; subject grouping does not support domain filtering.", "example": [ "reuters.com", "apnews.com" ] }, "exclude_domains": { "type": "array", "items": { "type": "string", "maxLength": 60 }, "maxItems": 1200, "description": "A list of domains to specifically exclude from the search results. The `-site:` query operator adds to this list. If a domain appears in both `include_domains` and `exclude_domains`, `exclude_domains` takes precedence. Applies to `results` only; subject grouping does not support domain filtering.", "example": [ "spam.com", "ads.example.net" ] }, "time_basis": { "type": "string", "enum": [ "auto", "published", "crawled" ], "default": "auto", "description": "Determines which time field is used for time filtering. `published` uses time_published; `crawled` uses time_last_crawled. Results missing this field are excluded when filtering by time." }, "time_range": { "type": "string", "enum": [ "day", "week", "month", "year", "d", "w", "m", "y" ], "description": "Relative time window counting back from the current time based on `time_basis`. Mutually exclusive with `start_time`/`end_time`: if both are provided, `start_time`/`end_time` take precedence." }, "start_time": { "type": "string", "format": "date-time", "description": "Start time for filtering results. ISO 8601 format.", "example": "2026-08-22T00:00:00Z" }, "end_time": { "type": "string", "format": "date-time", "description": "End time for filtering results. ISO 8601 format.", "example": "2026-08-24T00:00:00Z" }, "language": { "type": "array", "items": { "type": "string", "enum": [ "ar", "de", "en", "es", "fr", "hi", "id", "it", "ja", "ko", "nl", "pl", "pt", "ru", "th", "tr", "vi", "zh" ] }, "default": [], "description": "A list of languages to restrict results to, as ISO 639-1 codes. Applies to both `results` and `subjects`.", "example": [ "en", "zh" ] }, "highlight": { "$ref": "#/components/schemas/HighlightOptions" }, "full_content": { "$ref": "#/components/schemas/FullContentOptions" }, "subjects": { "$ref": "#/components/schemas/NewsSubjectOptions" } } }, "NewsSubjectOptions": { "type": "object", "description": "Controls subject grouping, which clusters related articles into events.", "properties": { "enable": { "type": "boolean", "default": true, "description": "If true, returns data.subjects." }, "count": { "type": "integer", "default": 2, "minimum": 1, "maximum": 5, "description": "Maximum number of subjects to return." }, "max_sub_news": { "type": "integer", "default": 5, "minimum": 1, "maximum": 20, "description": "Maximum number of sub-events to return per subject." } } }, "NewsSearchResponse": { "type": "object", "properties": { "code": { "type": "integer", "description": "Business status code. 0 indicates success." }, "msg": { "type": "string", "description": "A message describing the result." }, "request_id": { "type": "string", "description": "The unique identifier for this request." }, "data": { "$ref": "#/components/schemas/NewsSearchData" }, "meta": { "$ref": "#/components/schemas/NewsSearchMeta" } } }, "NewsSearchData": { "type": "object", "description": "The main response payload.", "properties": { "query": { "type": "string", "description": "The original query." }, "results": { "type": "array", "description": "A list of news results.", "items": { "$ref": "#/components/schemas/NewsSearchResult" } }, "subjects": { "type": "array", "description": "A list of subjects, each grouping related articles into one event. Returned only when subjects.enable is true and the query produces at least one subject.", "items": { "$ref": "#/components/schemas/NewsSubject" } } } }, "NewsSearchResult": { "type": "object", "description": "A single news result.", "properties": { "title": { "type": "string", "description": "The title of the article." }, "url": { "type": "string", "description": "The URL of the article." }, "highlight": { "type": "string", "description": "Query-relevant highlight snippets. Returned only if highlight.enable is true." }, "full_content": { "type": "string", "description": "Full raw page content. Returned only if full_content.enable is true." }, "authors": { "type": "string", "description": "Website name or author." }, "time_published": { "type": "string", "format": "date-time", "description": "Publish time in ISO 8601." }, "time_last_crawled": { "type": "string", "format": "date-time", "description": "Last crawl time in ISO 8601." }, "favicon": { "type": "string", "description": "The favicon URL of the source site." }, "cover_image": { "$ref": "#/components/schemas/NewsImage" }, "images": { "type": "array", "description": "In-body images of the article, in order of appearance.", "items": { "$ref": "#/components/schemas/NewsImage" } } } }, "NewsImage": { "type": "object", "description": "An image attached to an article.", "properties": { "url": { "type": "string", "description": "The image URL." }, "description": { "type": "string", "description": "Text description of the image." } } }, "NewsSubject": { "type": "object", "description": "A group of related articles covering one event.", "properties": { "name": { "type": "string", "description": "The event name." }, "summary": { "type": "string", "description": "A summary of the event." }, "time_start": { "type": "string", "format": "date-time", "description": "When the event started, in ISO 8601." }, "time_latest": { "type": "string", "format": "date-time", "description": "Publish time of the most recent article in the event, in ISO 8601." }, "top_news": { "$ref": "#/components/schemas/NewsSubjectTopNews" }, "sub_news": { "type": "array", "description": "Sub-events within the subject, sorted by event time in descending order.", "items": { "$ref": "#/components/schemas/NewsSubjectSubNews" } } } }, "NewsSubjectTopNews": { "type": "object", "description": "The representative article for the subject.", "properties": { "title": { "type": "string", "description": "The title of the article." }, "url": { "type": "string", "description": "The URL of the article." }, "summary": { "type": "string", "description": "A summary of the article, in the language of the original." }, "highlight": { "type": "string", "description": "Query-relevant highlight snippets. Returned only if highlight.enable is true." }, "full_content": { "type": "string", "description": "Full raw page content. Returned only if full_content.enable is true." }, "authors": { "type": "string", "description": "Website name or author." }, "time_published": { "type": "string", "format": "date-time", "description": "Publish time in ISO 8601." }, "time_last_crawled": { "type": "string", "format": "date-time", "description": "Last crawl time in ISO 8601." }, "favicon": { "type": "string", "description": "The favicon URL of the source site." }, "cover_image": { "$ref": "#/components/schemas/NewsImage" }, "images": { "type": "array", "description": "In-body images of the article, in order of appearance.", "items": { "$ref": "#/components/schemas/NewsImage" } } } }, "NewsSubjectSubNews": { "type": "object", "description": "The article representing one sub-event.", "properties": { "title": { "type": "string", "description": "The title of the article." }, "url": { "type": "string", "description": "The URL of the article." }, "highlight": { "type": "string", "description": "Query-relevant highlight snippets. Returned only if highlight.enable is true." }, "full_content": { "type": "string", "description": "Full raw page content. Returned only if full_content.enable is true." }, "authors": { "type": "string", "description": "Website name or author." }, "time_published": { "type": "string", "format": "date-time", "description": "Publish time in ISO 8601." }, "time_last_crawled": { "type": "string", "format": "date-time", "description": "Last crawl time in ISO 8601." }, "favicon": { "type": "string", "description": "The favicon URL of the source site." }, "cover_image": { "$ref": "#/components/schemas/NewsImage" }, "images": { "type": "array", "description": "In-body images of the article, in order of appearance.", "items": { "$ref": "#/components/schemas/NewsImage" } } } }, "NewsSearchMeta": { "type": "object", "description": "Additional metadata for the search request.", "properties": { "usage": { "$ref": "#/components/schemas/NewsSearchUsage" }, "latency": { "type": "number", "description": "Response time in milliseconds." }, "warning": { "type": "string", "nullable": true, "description": "Warning message, if any." } } }, "NewsSearchUsage": { "type": "object", "description": "Usage information for the search request.", "properties": { "num_search_queries": { "type": "integer", "description": "Number of text search queries executed." }, "num_subject_search_queries": { "type": "integer", "description": "Number of subject search queries executed. 0 when subjects.enable is false." }, "full_content_extra_count": { "type": "integer", "description": "Billable full_content results beyond the free allowance." } } }, "BusinessSearchRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "maxLength": 500, "description": "The search query.\n\n**Operators**\n\n- `site:`: restrict results to a single domain. For multiple domains, use `include_domains` and `exclude_domains`.\n- `-site:`: exclude a single domain from the results." }, "count": { "type": "integer", "default": 5, "minimum": 1, "maximum": 100, "description": "Number of results to return." }, "include_domains": { "type": "array", "items": { "type": "string", "maxLength": 60 }, "maxItems": 1200, "description": "A list of domains to specifically include in the search results. The `site:` query operator adds to this list. Applies to `results` only; entity cards do not support domain filtering.", "example": [ "reuters.com", "bloomberg.com" ] }, "exclude_domains": { "type": "array", "items": { "type": "string", "maxLength": 60 }, "maxItems": 1200, "description": "A list of domains to specifically exclude from the search results. The `-site:` query operator adds to this list. If a domain appears in both `include_domains` and `exclude_domains`, `exclude_domains` takes precedence. Applies to `results` only; entity cards do not support domain filtering.", "example": [ "spam.com", "ads.example.net" ] }, "time_basis": { "type": "string", "enum": [ "auto", "published", "crawled" ], "default": "auto", "description": "Determines which time field is used for time filtering. `published` uses time_published; `crawled` uses time_last_crawled. Results missing this field are excluded when filtering by time. Applies to `results` only; entity cards do not support time filtering." }, "time_range": { "type": "string", "enum": [ "day", "week", "month", "year", "d", "w", "m", "y" ], "description": "Relative time window counting back from the current time based on `time_basis`. Mutually exclusive with `start_time`/`end_time`: if both are provided, `start_time`/`end_time` take precedence." }, "start_time": { "type": "string", "format": "date-time", "description": "Start time for filtering results. ISO 8601 format.", "example": "2026-08-22T00:00:00Z" }, "end_time": { "type": "string", "format": "date-time", "description": "End time for filtering results. ISO 8601 format.", "example": "2026-08-24T00:00:00Z" }, "language": { "type": "array", "items": { "type": "string", "enum": [ "ar", "de", "en", "es", "fr", "hi", "id", "it", "ja", "ko", "nl", "pl", "pt", "ru", "th", "tr", "vi", "zh" ] }, "default": [], "description": "A list of languages to restrict results to, as ISO 639-1 codes. Applies to `results` only; entity cards do not support language filtering.", "example": [ "en", "zh" ] }, "highlight": { "$ref": "#/components/schemas/HighlightOptions" }, "full_content": { "$ref": "#/components/schemas/FullContentOptions" }, "entities": { "$ref": "#/components/schemas/BusinessEntityOptions" } } }, "BusinessEntityOptions": { "type": "object", "description": "Controls the entity cards returned for companies and people.", "properties": { "enable": { "type": "boolean", "default": true, "description": "If true, returns data.entities." }, "count": { "type": "integer", "default": 2, "minimum": 1, "maximum": 20, "description": "Maximum number of entity cards to return." }, "max_activities": { "type": "integer", "default": 5, "minimum": 1, "maximum": 20, "description": "Maximum number of recent activities to return per entity card." }, "max_news": { "type": "integer", "default": 5, "minimum": 1, "maximum": 20, "description": "Maximum number of related news items to return per entity card." } } }, "BusinessSearchResponse": { "type": "object", "properties": { "code": { "type": "integer", "description": "Business status code. 0 indicates success." }, "msg": { "type": "string", "description": "A message describing the result." }, "request_id": { "type": "string", "description": "The unique identifier for this request." }, "data": { "$ref": "#/components/schemas/BusinessSearchData" }, "meta": { "$ref": "#/components/schemas/BusinessSearchMeta" } } }, "BusinessSearchData": { "type": "object", "description": "The main response payload. Fields without data are omitted, at every level.", "properties": { "query": { "type": "string", "description": "The original query." }, "results": { "type": "array", "description": "A list of business results.", "items": { "$ref": "#/components/schemas/BusinessSearchResult" } }, "entities": { "type": "array", "description": "A list of entity cards for the companies and people in the query. Returned only when entities.enable is true and the query matches at least one entity.", "items": { "$ref": "#/components/schemas/BusinessEntity" } } } }, "BusinessSearchResult": { "type": "object", "description": "A single business result.", "properties": { "title": { "type": "string", "description": "The title of the page." }, "url": { "type": "string", "description": "The URL of the page." }, "highlight": { "type": "string", "description": "Query-relevant highlight snippets. Returned only if highlight.enable is true." }, "full_content": { "type": "string", "description": "Full raw page content. Returned only if full_content.enable is true." }, "authors": { "type": "string", "description": "Website name or author." }, "time_published": { "type": "string", "format": "date-time", "description": "Publish time in ISO 8601." }, "time_last_crawled": { "type": "string", "format": "date-time", "description": "Last crawl time in ISO 8601." }, "favicon": { "type": "string", "description": "The favicon URL of the source site." }, "cover_image": { "$ref": "#/components/schemas/BusinessImage" }, "images": { "type": "array", "description": "In-body images of the page, in order of appearance.", "items": { "$ref": "#/components/schemas/BusinessImage" } } } }, "BusinessNewsItem": { "type": "object", "description": "A single news item. The same fields as a business result, without `authors`.", "properties": { "title": { "type": "string", "description": "The title of the page." }, "url": { "type": "string", "description": "The URL of the page." }, "highlight": { "type": "string", "description": "Query-relevant highlight snippets. Returned only if highlight.enable is true." }, "full_content": { "type": "string", "description": "Full raw page content. Returned only if full_content.enable is true." }, "time_published": { "type": "string", "format": "date-time", "description": "Publish time in ISO 8601." }, "time_last_crawled": { "type": "string", "format": "date-time", "description": "Last crawl time in ISO 8601." }, "favicon": { "type": "string", "description": "The favicon URL of the source site." }, "cover_image": { "$ref": "#/components/schemas/BusinessImage" }, "images": { "type": "array", "description": "In-body images of the page, in order of appearance.", "items": { "$ref": "#/components/schemas/BusinessImage" } } } }, "BusinessImage": { "type": "object", "description": "An image attached to a page.", "properties": { "url": { "type": "string", "description": "The image URL." }, "description": { "type": "string", "description": "Text description of the image. Can be empty." } } }, "BusinessEntity": { "oneOf": [ { "$ref": "#/components/schemas/BusinessCompanyEntity" }, { "$ref": "#/components/schemas/BusinessPersonEntity" } ], "discriminator": { "propertyName": "type", "mapping": { "company": "#/components/schemas/BusinessCompanyEntity", "person": "#/components/schemas/BusinessPersonEntity" } } }, "BusinessCompanyEntity": { "type": "object", "title": "Company", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "company" ], "description": "The kind of entity this card describes. Always `company`." }, "name": { "type": "string", "description": "The company name." }, "summary": { "type": "string", "description": "A profile of the company." }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Other names and spellings for the company." }, "identifiers": { "$ref": "#/components/schemas/BusinessEntityIdentifiers" }, "attributes": { "$ref": "#/components/schemas/BusinessEntityAttributes" }, "metrics": { "$ref": "#/components/schemas/BusinessEntityMetrics" }, "key_people": { "type": "array", "description": "Key people at the company.", "items": { "$ref": "#/components/schemas/BusinessKeyPerson" } }, "logo": { "type": "object", "description": "The company logo.", "properties": { "url": { "type": "string", "description": "The logo image URL." } } }, "activities": { "type": "array", "description": "Recent activity from the company's own channels.", "items": { "$ref": "#/components/schemas/BusinessSearchResult" } }, "news": { "type": "array", "description": "Recent news about the company from third-party outlets.", "items": { "$ref": "#/components/schemas/BusinessNewsItem" } } } }, "BusinessPersonEntity": { "type": "object", "title": "Person", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "person" ], "description": "The kind of entity this card describes. Always `person`." }, "name": { "type": "string", "description": "The person's name." }, "summary": { "type": "string", "description": "A profile of the person." }, "linkedin_url": { "type": "string", "description": "LinkedIn profile URL." }, "current_position": { "type": "string", "description": "Current role and organization." }, "career": { "type": "array", "description": "Career history.", "items": { "$ref": "#/components/schemas/BusinessCareerEntry" } }, "photo": { "type": "object", "description": "A photo of the person.", "properties": { "url": { "type": "string", "description": "The photo URL." } } }, "activities": { "type": "array", "description": "Recent activity from the person's own channels.", "items": { "$ref": "#/components/schemas/BusinessSearchResult" } }, "news": { "type": "array", "description": "Recent news about the person from third-party outlets.", "items": { "$ref": "#/components/schemas/BusinessNewsItem" } } } }, "BusinessEntityIdentifiers": { "type": "object", "description": "Identifiers for the company.", "properties": { "website": { "type": "string", "description": "The official website." }, "linkedin_url": { "type": "string", "description": "LinkedIn company page URL." }, "stock_ticker": { "type": "string", "description": "Stock ticker." }, "sec_cik": { "type": "string", "description": "SEC Central Index Key." } } }, "BusinessEntityAttributes": { "type": "object", "description": "Basic attributes of the company.", "properties": { "industry": { "type": "string", "description": "The industry the company operates in." }, "hq_location": { "type": "string", "description": "Headquarters location." }, "founded_year": { "type": "integer", "description": "The year the company was founded." }, "employee_range": { "type": "string", "description": "Employee count, as a range." } } }, "BusinessEntityMetrics": { "type": "object", "description": "Quantitative metrics for the company.", "properties": { "financials": { "type": "array", "description": "Financial results by reporting period.", "items": { "$ref": "#/components/schemas/BusinessFinancials" } }, "stock": { "$ref": "#/components/schemas/BusinessStock" }, "funding": { "type": "array", "description": "Funding rounds.", "items": { "$ref": "#/components/schemas/BusinessFunding" } }, "web_traffic": { "$ref": "#/components/schemas/BusinessWebTraffic" } } }, "BusinessFinancials": { "type": "object", "description": "Financial results for one reporting period.", "properties": { "revenue": { "type": "number", "description": "Revenue." }, "net_income": { "type": "number", "description": "Net income. Negative for a loss." }, "gross_profit": { "type": "number", "description": "Gross profit." }, "period": { "type": "string", "description": "The reporting period." }, "currency": { "type": "string", "description": "The currency the figures are reported in." } } }, "BusinessStock": { "type": "object", "description": "Live stock data from Octen. Returned for listed companies.", "properties": { "price": { "type": "number", "description": "Current stock price." }, "todays_change_percent": { "type": "number", "description": "Change from the previous close, as a percentage." }, "week_52_high": { "type": "number", "description": "Highest price over the past 52 weeks." }, "week_52_low": { "type": "number", "description": "Lowest price over the past 52 weeks." }, "date": { "type": "string", "description": "The trading date the figures belong to." }, "currency": { "type": "string", "description": "The currency the figures are reported in." } } }, "BusinessFunding": { "type": "object", "description": "A single funding round.", "properties": { "round": { "type": "string", "description": "The funding round." }, "amount": { "type": "number", "description": "The amount raised in this round." }, "date": { "type": "string", "description": "The date this round was announced." }, "lead_investors": { "type": "string", "description": "Lead investors in this round, separated by semicolons." }, "currency": { "type": "string", "description": "The currency the figures are reported in." } } }, "BusinessWebTraffic": { "type": "object", "description": "Web traffic for the company's website.", "properties": { "visits_monthly": { "type": "integer", "description": "Monthly visits." }, "rank": { "type": "integer", "description": "Global traffic rank." }, "period": { "type": "string", "description": "The month the figures belong to.", "example": "2026-08" } } }, "BusinessKeyPerson": { "type": "object", "description": "A key person at the company.", "properties": { "name": { "type": "string", "description": "The person's name." }, "title": { "type": "string", "description": "The person's title." } } }, "BusinessCareerEntry": { "type": "object", "description": "One role in a person's career history.", "properties": { "organization": { "type": "string", "description": "The organization." }, "title": { "type": "string", "description": "The role held." }, "start": { "type": "string", "description": "When the role started, as a year or a year and month." }, "end": { "type": "string", "description": "When the role ended, as a year or a year and month. Omitted while the role is current." } } }, "BusinessSearchMeta": { "type": "object", "description": "Additional metadata for the search request.", "properties": { "usage": { "$ref": "#/components/schemas/BusinessSearchUsage" }, "latency": { "type": "number", "description": "Response time in milliseconds." }, "warning": { "type": "string", "description": "Warning message, if any." } } }, "BusinessSearchUsage": { "type": "object", "description": "Usage information for the search request.", "properties": { "num_search_queries": { "type": "integer", "description": "Number of text search queries executed." }, "full_content_extra_count": { "type": "integer", "description": "Billable full_content results beyond the free allowance." } } }, "BroadSearchRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "maxLength": 500, "description": "The original search query." }, "max_queries": { "type": "integer", "minimum": 1, "maximum": 30, "default": 5, "description": "Upper bound on the number of sub-queries generated." }, "search_options": { "allOf": [ { "$ref": "#/components/schemas/WebSearchOptions" } ], "description": "Search options applied to each sub-query. Shares the same parameters and defaults as the Web Search API." } } }, "BroadSearchData": { "type": "object", "description": "The main response payload.", "properties": { "query": { "type": "string", "description": "The original query." }, "queries": { "type": "array", "items": { "type": "string" }, "description": "Sub-queries generated from the query." }, "search_results": { "type": "array", "description": "Results are grouped by sub-query and are not de-duplicated across groups.", "items": { "$ref": "#/components/schemas/SearchResultGroup" } } } }, "BroadSearchResponse": { "type": "object", "properties": { "code": { "type": "integer", "description": "Business status code. 0 indicates success." }, "request_id": { "type": "string", "description": "The unique identifier for this request." }, "data": { "$ref": "#/components/schemas/BroadSearchData" }, "meta": { "$ref": "#/components/schemas/SearchMeta" } } }, "ExtractRequest": { "type": "object", "required": [ "urls" ], "description": "Request body for the Extract API.", "properties": { "urls": { "type": "array", "items": { "type": "string" }, "description": "List of URLs to extract content from. Maximum URLs per request: 20. Maximum length per URL: 2048. Failed URLs are not billed.", "example": [ "https://example.com/article-1", "https://example.com/article-2" ] }, "mode": { "type": "string", "enum": [ "standard", "advanced", "auto" ], "default": "standard", "description": "Processing mode. `standard` prioritizes speed, `advanced` prioritizes success rate on hard-to-reach pages, and `auto` picks one per URL. `advanced` and `auto` can take longer, so raise `timeout` accordingly." }, "query": { "type": "string", "maxLength": 500, "description": "Intent-focused keywords. When provided, returns query-relevant highlights per URL; otherwise returns the complete page content." }, "max_age_seconds": { "type": "integer", "default": 86400, "minimum": 300, "maximum": 31536000, "description": "Maximum age (in seconds) of cached content. URLs whose cached version exceeds this threshold will be re-fetched. Values outside the allowed range are adjusted to the nearest bound." }, "format": { "type": "string", "enum": [ "markdown", "text" ], "default": "markdown", "description": "Format of the returned content." }, "timeout": { "type": "integer", "default": 30, "minimum": 1, "maximum": 60, "description": "Per-URL extraction timeout in seconds. Values outside the allowed range are adjusted to the nearest bound." }, "include_images": { "type": "boolean", "default": false, "description": "Whether to return image URLs detected on the page." }, "include_videos": { "type": "boolean", "default": false, "description": "Whether to return video URLs detected on the page." }, "include_audio": { "type": "boolean", "default": false, "description": "Whether to return audio URLs detected on the page." }, "include_links": { "type": "object", "description": "Controls whether to return links detected on the page.", "properties": { "scope": { "type": "string", "enum": [ "prefer_internal", "prefer_external" ], "default": "prefer_internal", "description": "Which links to prioritize. `prefer_internal` favors links within the page's registered domain; `prefer_external` favors external links. Prioritized links come first, and links of the same kind keep their order on the page." }, "max_links": { "type": "integer", "default": 200, "minimum": 1, "maximum": 1000, "description": "Maximum number of links to return per URL." } } } } }, "ExtractResponse": { "type": "object", "properties": { "code": { "type": "integer", "description": "Business status code. 0 indicates success." }, "msg": { "type": "string", "description": "A message describing the result." }, "request_id": { "type": "string", "description": "The unique identifier for this request." }, "data": { "$ref": "#/components/schemas/ExtractData" }, "meta": { "$ref": "#/components/schemas/ExtractMeta" } } }, "ExtractData": { "type": "object", "description": "The main extract response payload.", "properties": { "results": { "type": "array", "description": "Extraction result for each requested URL. Order matches the input urls array.", "items": { "$ref": "#/components/schemas/ExtractResult" } } } }, "ExtractResult": { "type": "object", "description": "A single extraction result. Batch requests may return 200 OK overall while individual items fail; failed items are marked with `status: \"failed\"` and an `error_message`, and are not billed.", "properties": { "url": { "type": "string", "description": "The requested URL." }, "status": { "type": "string", "enum": [ "success", "failed" ], "description": "Extraction status for this URL." }, "resolved_mode": { "type": "string", "enum": [ "standard", "advanced" ], "description": "The mode this URL is billed at. For `auto`, the mode chosen for this URL. Returned when `status` is `success`." }, "title": { "type": "string", "nullable": true, "description": "Page title, extracted from HTML `` or `<meta>` tags." }, "full_content": { "type": "string", "nullable": true, "description": "Complete page content in the requested format. Returned when `query` is not provided." }, "highlights": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Query-relevant snippets, sorted by relevance. Returned when `query` is provided." }, "time_published": { "type": "string", "format": "date-time", "nullable": true, "description": "Content publication time, ISO 8601 format." }, "time_last_crawled": { "type": "string", "format": "date-time", "description": "Most recent time Octen crawled this URL, ISO 8601 format." }, "page_structure": { "allOf": [ { "$ref": "#/components/schemas/ExtractPageStructure" } ], "description": "Detected page structure. Returns `null` when the structure cannot be determined." }, "category": { "allOf": [ { "$ref": "#/components/schemas/ExtractCategory" } ], "description": "Detected content category. Returns `null` when the category cannot be determined." }, "favicon": { "type": "string", "nullable": true, "description": "The page's favicon URL. Returned by default when available." }, "cover_image": { "type": "object", "nullable": true, "description": "The page cover image. Returned only when `include_images` is `true` and the page has a cover image.", "properties": { "url": { "type": "string", "description": "Image URL." } } }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractMediaResource" }, "description": "Image resources detected on the page. Returned when `include_images` is `true` and the page contains images." }, "videos": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractMediaResource" }, "description": "Video resources detected on the page. Returned when `include_videos` is `true` and the page contains videos." }, "audio": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractMediaResource" }, "description": "Audio resources detected on the page. Returned when `include_audio` is `true` and the page contains audio." }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractLink" }, "description": "Links detected on the page, deduplicated. Returned for successful results when `include_links` is set and links are detected on the page." }, "error_message": { "type": "string", "description": "Failure reason. Only present when `status` is `failed`. See the Error Codes reference for the complete list of result-level error messages." } } }, "ExtractPageStructure": { "type": "object", "description": "Detected page structure for an extraction result.", "properties": { "primary": { "type": "string", "enum": [ "Index Page", "Content Page", "No Main Content" ], "description": "Top-level page type." }, "secondary": { "type": "string", "nullable": true, "description": "Sub-type within the primary structure. 50+ possible values. `null` when no sub-type applies." } } }, "ExtractCategory": { "type": "object", "description": "Detected content category for an extraction result.", "properties": { "primary": { "type": "string", "description": "Top-level content category. 23 possible values." }, "secondary": { "type": "string", "nullable": true, "description": "Sub-category within the primary category. 160+ possible values. `null` when no sub-category applies." } } }, "ExtractMediaResource": { "type": "object", "description": "A single multimedia resource detected on the page.", "properties": { "url": { "type": "string", "description": "Resource URL." } } }, "ExtractLink": { "type": "object", "description": "A single link found on the page.", "properties": { "url": { "type": "string", "description": "Absolute URL of the link target." }, "anchor_text": { "type": "string", "description": "The link's visible text on the page. Empty when the link has no visible text." }, "is_external": { "type": "boolean", "description": "Whether the link points to a different registered domain than the page." } } }, "ExtractMeta": { "type": "object", "description": "Additional metadata for the extract request.", "properties": { "usage": { "$ref": "#/components/schemas/ExtractUsage" }, "latency": { "type": "integer", "description": "Total request latency in milliseconds." }, "warning": { "type": "string", "description": "Warning messages for the request, separated by semicolons. An empty string when there is nothing to report." } } }, "ExtractUsage": { "type": "object", "description": "Usage and billing breakdown for the extract request.", "properties": { "total_urls": { "type": "integer", "description": "Total number of URLs in the request." }, "successful_urls": { "type": "integer", "description": "Number of successfully extracted URLs (billed). Failed URLs are not counted." }, "successful_by_mode": { "type": "object", "description": "Breakdown of successful URLs by `resolved_mode`.", "properties": { "standard_urls": { "type": "integer", "description": "Successful URLs billed at the standard rate." }, "advanced_urls": { "type": "integer", "description": "Successful URLs billed at the advanced rate." } } } } }, "EmbeddingRequest": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "array", "items": { "type": "string" }, "default": [ "What is vector search?" ], "maxItems": 1000, "description": "The text to be converted into embeddings. Maximum characters per element: 10000. Maximum request body size: 2MB" }, "model": { "type": "string", "enum": [ "octen-embedding-0.6b", "octen-embedding-4b", "octen-embedding-8b" ], "default": "octen-embedding-4b", "description": "The embedding model used for this request. `octen-embedding-0.6b` (max dim: 1024) for cost/throughput priority; `octen-embedding-4b` (max dim: 2560) for most applications; `octen-embedding-8b` (max dim: 4096) for accuracy-critical tasks." }, "dimension": { "type": "integer", "description": "The dimensionality of the output embedding vectors. Defaults to the model's max dimension (0.6b: 1024, 4b: 2560, 8b: 4096). If set to a value smaller than the model default, the embedding will be truncated to the first N values. Any positive integer ≤ model default dimension is allowed." }, "input_type": { "type": "string", "enum": [ "query", "document" ], "nullable": true, "default": null, "description": "Specifies whether the input is a query or a document for retrieval. Different values apply different internal prompts: `query` → \"Represent the query for retrieving supporting\" (prepended and counted in input_tokens); `document` and `null` mean no special prompt is applied." } } }, "EmbeddingResponse": { "type": "object", "properties": { "code": { "type": "integer", "description": "Business status code. 0 indicates success." }, "msg": { "type": "string", "description": "A message describing the result." }, "request_id": { "type": "string", "description": "The unique identifier for this request." }, "data": { "$ref": "#/components/schemas/EmbeddingData" }, "meta": { "$ref": "#/components/schemas/EmbeddingMeta" } } }, "EmbeddingData": { "type": "object", "description": "The main embedding response payload.", "properties": { "results": { "type": "array", "description": "A list of embedding results. Each item corresponds to one input.", "items": { "$ref": "#/components/schemas/EmbeddingResult" } }, "model": { "type": "string", "description": "The embedding model used for this request." } } }, "EmbeddingResult": { "type": "object", "description": "A single embedding result.", "properties": { "index": { "type": "integer", "description": "The position of the embedding in the input array (useful when input is a list)." }, "embedding": { "type": "array", "items": { "type": "number" }, "description": "The generated embedding vector." } } }, "EmbeddingMeta": { "type": "object", "description": "Additional metadata for the embedding request.", "properties": { "usage": { "$ref": "#/components/schemas/EmbeddingUsage" }, "warning": { "type": "string", "nullable": true, "description": "Optional warning message." } } }, "EmbeddingUsage": { "type": "object", "description": "Usage information for the embedding request.", "properties": { "input_tokens": { "type": "integer", "description": "The number of input tokens processed in this request." } } }, "VLEmbeddingRequest": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "enum": [ "octen-vl-embedding", "octen-vl-embedding-large" ], "description": "The multimodal embedding model used for this request." }, "input": { "$ref": "#/components/schemas/VLEmbeddingInput" }, "enable_fusion": { "type": "boolean", "default": false, "description": "Whether to generate a fused embedding. When `true`, all elements in `contents` are fused into a single vector; when `false`, each element produces an independent vector." }, "dimension": { "type": "integer", "description": "The dimensionality of the output embedding vectors. Defaults to the model's max dimension (octen-vl-embedding: 2048, octen-vl-embedding-large: 4096). Any positive integer ≤ the model's max dimension is allowed." }, "fps": { "type": "number", "minimum": 0, "maximum": 1, "default": 1.0, "description": "Frames sampled per second of video. For example, `0.5` samples one frame every two seconds. Lower values sample fewer frames and reduce video token consumption. Each video is sampled to at most 64 frames." }, "instruct": { "type": "string", "default": "Represent the user's input.", "description": "Custom task description used to guide the model in understanding the query intent. Its length counts toward `input_tokens` and shares the 10,000-character total limit with `contents`." } } }, "VLEmbeddingInput": { "type": "object", "required": [ "contents" ], "description": "The multimodal content to be vectorized. Supports text, images, videos, and combinations. Maximum total elements per request: 20. Maximum images per request: 5. Maximum videos per request: 1.", "properties": { "contents": { "type": "array", "maxItems": 20, "description": "The list of content elements to process.", "items": { "$ref": "#/components/schemas/VLEmbeddingContent" } } } }, "VLEmbeddingContent": { "type": "object", "description": "A single content element. Each object should provide exactly one of `text`, `image`, or `video`. For multiple images, include multiple content objects (one image per object).", "properties": { "text": { "type": "string", "description": "Text input. Maximum 10,000 characters per entry." }, "image": { "type": "string", "description": "Image input. Supports a URL or a Base64 string. Maximum 5MB per image. Supported formats: JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS, SGI." }, "video": { "type": "string", "description": "Video input. URL only. Maximum 50MB per file. Supported formats: MP4, AVI, MOV." } } }, "VLEmbeddingResponse": { "type": "object", "properties": { "code": { "type": "integer", "description": "Business status code. 0 indicates success." }, "msg": { "type": "string", "description": "A message describing the result." }, "request_id": { "type": "string", "description": "The unique identifier for this request." }, "data": { "$ref": "#/components/schemas/VLEmbeddingData" }, "meta": { "$ref": "#/components/schemas/VLEmbeddingMeta" } } }, "VLEmbeddingData": { "type": "object", "description": "The main VL embedding response payload.", "properties": { "results": { "type": "array", "description": "A list of embedding results.", "items": { "$ref": "#/components/schemas/VLEmbeddingResult" } }, "model": { "type": "string", "description": "The embedding model used for this request." } } }, "VLEmbeddingResult": { "type": "object", "description": "A single VL embedding result.", "properties": { "index": { "type": "integer", "description": "The position of the embedding in the input array." }, "embedding": { "type": "array", "items": { "type": "number" }, "description": "The generated embedding vector. Type and encoding may vary based on the input parameters." }, "type": { "type": "string", "enum": [ "vl", "fusion" ], "description": "The result type." } } }, "VLEmbeddingMeta": { "type": "object", "description": "Additional metadata for the VL embedding request.", "properties": { "usage": { "$ref": "#/components/schemas/VLEmbeddingUsage" }, "warning": { "type": "string", "nullable": true, "description": "Optional warning message, if any." } } }, "VLEmbeddingUsage": { "type": "object", "description": "Usage information for the VL embedding request.", "properties": { "input_tokens": { "type": "integer", "description": "Total number of input tokens processed in this request." }, "text_tokens": { "type": "integer", "description": "Number of tokens consumed by text inputs." }, "image_tokens": { "type": "integer", "description": "Total tokens consumed by image and video inputs (videos are sampled into frames before counting)." }, "image_count": { "type": "integer", "description": "Number of images in the request (excluding frames extracted from videos)." }, "duration": { "type": "integer", "description": "Total duration of video inputs in seconds." } } }, "ErrorResponse": { "type": "object", "properties": { "code": { "type": "integer", "description": "Business status code. Non-zero values indicate an error." }, "msg": { "type": "string", "description": "A message describing the error." }, "request_id": { "type": "string", "description": "Unique identifier for the request." } }, "required": [ "code", "msg", "request_id" ] }, "ChatCompletionRequest": { "type": "object", "required": [ "model", "messages" ], "description": "Request body for the Chat Completions API. Some parameters apply only to certain models; unsupported parameters are ignored for the selected model.", "properties": { "model": { "type": "string", "enum": [ "openai/gpt-6.1-sol", "openai/gpt-6-astra", "openai/gpt-5.6-sol", "openai/gpt-5.6-terra", "openai/gpt-5.6-luna", "openai/gpt-5.4", "anthropic/claude-fable-5.1", "anthropic/claude-fable-5", "anthropic/claude-opus-5.5", "anthropic/claude-opus-5", "anthropic/claude-opus-4.8", "anthropic/claude-opus-4.6", "anthropic/claude-sonnet-5.5", "anthropic/claude-sonnet-5", "anthropic/claude-sonnet-4.6", "anthropic/claude-haiku-5.5", "anthropic/claude-haiku-4.5", "google/gemini-4-argon", "google/gemini-3.8-flash", "google/gemini-3.5-flash", "google/gemini-3.5-flash-lite", "google/gemini-3.1-pro-preview", "google/gemini-3.1-flash-lite", "google/gemini-3-flash-preview", "moonshotai/kimi-k3", "moonshotai/kimi-k2.6", "moonshotai/kimi-k2.5", "minimax/minimax-m2.5", "qwen/qwen3.6-plus", "deepseek/deepseek-v4-pro", "deepseek/deepseek-v4-flash-0731" ], "description": "The model to use for chat completion." }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" }, "description": "The conversation so far. System prompt plus user and assistant messages in chronological order." }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ChatToolDefinition" } }, "tool_choice": { "description": "Controls tool invocation. `none`: never call tools; `auto`: model decides (default); `required`: must call a tool. Can also be an object to force a specific tool. Only valid when `tools` is set.", "oneOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "$ref": "#/components/schemas/ChatToolChoiceObject" } ] }, "parallel_tool_calls": { "type": "boolean", "default": true, "description": "Whether the model may issue multiple tool calls in one reply. When `false`, at most one tool call per turn." }, "stream": { "type": "boolean", "default": false, "description": "Whether to enable streaming output. When `true`, returns `chat.completion.chunk` objects incrementally." }, "max_tokens": { "type": "integer", "minimum": 1, "description": "Maximum number of tokens the model can output. If not set, the model's internal default limit is used." }, "max_completion_tokens": { "type": "integer", "minimum": 1, "description": "Maximum completion tokens, including reasoning and visible output tokens. If not set, the model's internal default limit is used." }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "default": 1.0, "description": "Controls randomness in generation. Higher values produce more diverse output; lower values produce more deterministic output." }, "top_p": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "default": 1.0, "description": "Nucleus sampling. Only tokens with cumulative probability up to `top_p` are considered." }, "top_k": { "type": "integer", "minimum": 0, "default": 0, "description": "Sample only from the top K most probable tokens. `0` disables it." }, "min_p": { "type": "number", "minimum": 0, "maximum": 1, "default": 0, "description": "Minimum probability threshold relative to the most probable token. Tokens below it are filtered out. `0` disables it." }, "top_a": { "type": "number", "minimum": 0, "maximum": 1, "default": 0, "description": "Dynamic filtering threshold based on the most probable token. `0` disables it." }, "repetition_penalty": { "type": "number", "exclusiveMinimum": 0, "maximum": 2, "default": 1.0, "description": "Penalizes tokens already present in the input. Above 1 suppresses repetition; below 1 encourages it." }, "frequency_penalty": { "type": "number", "minimum": -2, "maximum": 2, "default": 0, "description": "Penalizes tokens by their frequency in the output so far. Positive values reduce repetition." }, "presence_penalty": { "type": "number", "minimum": -2, "maximum": 2, "default": 0, "description": "Penalizes tokens that have already appeared. Positive values encourage new topics." }, "response_format": { "$ref": "#/components/schemas/ChatResponseFormat" }, "stop": { "type": "array", "items": { "type": "string" }, "description": "Stop sequences. Generation stops when any of these strings is encountered." }, "seed": { "type": "integer", "description": "Seed for reproducibility. With the same parameters and model version, output should be as consistent as possible." }, "reasoning": { "$ref": "#/components/schemas/ChatReasoningOptions" }, "reasoning_effort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "description": "Top-level alias for `reasoning.effort`. If both are set, `reasoning` takes precedence." }, "verbosity": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium", "description": "Controls how verbose the reply is." }, "logit_bias": { "type": "object", "additionalProperties": { "type": "number", "minimum": -100, "maximum": 100 }, "description": "A JSON object mapping token IDs to bias values (-100 to 100), added to the logits before sampling." }, "logprobs": { "type": "boolean", "default": false, "description": "Whether to return the log probabilities of the output tokens." }, "top_logprobs": { "type": "integer", "minimum": 0, "maximum": 20, "description": "Number of most likely tokens to return at each position. Requires `logprobs` to be `true`." }, "user": { "type": "string", "description": "A unique identifier for the end user. Use hashed or pseudonymous identifiers to avoid passing personally identifiable information." }, "modalities": { "type": "array", "items": { "type": "string" }, "default": [ "text" ], "description": "Requested output modalities." }, "prompt_cache_key": { "type": "string", "description": "Cache key for prompt caching." }, "prompt_cache_options": { "type": "object", "description": "Prompt caching controls.", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ], "description": "`implicit` caches automatically; `explicit` caches only prefixes marked with a cache breakpoint." }, "ttl": { "type": "string", "enum": [ "30m" ], "description": "How long a cache entry is retained." } } }, "prompt_cache_retention": { "type": "string", "enum": [ "in_memory", "24h" ], "description": "Prompt cache retention policy." }, "previous_response_id": { "type": "string", "description": "The `id` of a previous response, used to chain state across turns." } } }, "ChatMessage": { "oneOf": [ { "$ref": "#/components/schemas/SystemMessage" }, { "$ref": "#/components/schemas/DeveloperMessage" }, { "$ref": "#/components/schemas/UserMessage" }, { "$ref": "#/components/schemas/AssistantMessage" }, { "$ref": "#/components/schemas/ToolMessage" } ], "discriminator": { "propertyName": "role", "mapping": { "system": "#/components/schemas/SystemMessage", "developer": "#/components/schemas/DeveloperMessage", "user": "#/components/schemas/UserMessage", "assistant": "#/components/schemas/AssistantMessage", "tool": "#/components/schemas/ToolMessage" } } }, "SystemMessage": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "system" ], "description": "The role of the message author. Always `system`." }, "content": { "description": "The system prompt content. A plain string or an array of content blocks.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ChatContentBlock" } } ] } } }, "UserMessage": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user" ], "description": "The role of the message author. Always `user`." }, "content": { "description": "The content of the message. A plain string or an array of content blocks.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ChatContentBlock" } } ] } } }, "AssistantMessage": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "assistant" ], "description": "The role of the message author. Always `assistant`." }, "content": { "type": "string", "nullable": true, "description": "The assistant's text content. May be `null` or omitted when the assistant only produces tool calls." }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ChatToolCall" }, "description": "Tool calls generated by the model in a previous turn, replayed verbatim. Only valid when `role` is `assistant`." } } }, "ToolMessage": { "type": "object", "required": [ "role", "tool_call_id", "content" ], "properties": { "role": { "type": "string", "enum": [ "tool" ], "description": "The role of the message author. Always `tool`." }, "tool_call_id": { "type": "string", "description": "The ID of the tool call this message responds to." }, "content": { "type": "string", "description": "The tool output, typically a JSON string with the function result." } } }, "ChatToolCall": { "type": "object", "required": [ "id", "type", "function" ], "description": "A custom function call generated by the model.", "properties": { "index": { "type": "integer", "description": "The index of this tool call in the array." }, "id": { "type": "string", "description": "A unique identifier for this tool call. Referenced by the corresponding `tool` message's `tool_call_id`." }, "type": { "type": "string", "enum": [ "function" ], "description": "The type of tool call. Always `function`." }, "function": { "$ref": "#/components/schemas/ChatToolCallFunction" }, "thought_signature": { "type": "string", "description": "Encrypted reasoning state, replayed verbatim. Required when the request ends with a `tool` message." } } }, "ChatToolCallFunction": { "type": "object", "required": [ "name", "arguments" ], "description": "The function invocation details within a tool call.", "properties": { "name": { "type": "string", "description": "The name of the function to call." }, "arguments": { "type": "string", "description": "The arguments to the function, as a JSON string generated by the model." } } }, "ChatContentBlock": { "type": "object", "description": "A content block within a message.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "image", "image_url" ], "description": "The type of content block." }, "text": { "type": "string", "description": "The text content. Required when `type` is `text`." }, "image": { "type": "string", "description": "Base64-encoded image. Required when `type` is `image`." }, "image_url": { "type": "object", "description": "Image URL object. Required when `type` is `image_url`.", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "The URL of the image." } } }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } }, "ChatResponseFormat": { "type": "object", "description": "Controls the output format. Some models may not support structured output and will automatically fall back to `text`.", "properties": { "type": { "type": "string", "enum": [ "text", "json_object", "json_schema" ], "default": "text", "description": "The output format type." }, "json_schema": { "$ref": "#/components/schemas/ChatJsonSchemaSpec" } } }, "ChatReasoningOptions": { "type": "object", "description": "Options for reasoning models. Turns thinking on or off and sets the effort and budget.", "properties": { "enabled": { "type": "boolean", "description": "Set to `false` to turn off thinking. Overrides `effort` and `max_tokens`." }, "effort": { "type": "string", "enum": [ "max", "xhigh", "high", "medium", "low", "minimal", "none" ], "description": "The reasoning effort level." }, "max_tokens": { "type": "integer", "minimum": 1024, "description": "Thinking token budget." } } }, "ChatFunctionTool": { "type": "object", "required": [ "type", "function" ], "description": "A custom function tool, executed by the caller.", "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "The type of tool. Always `function` for a custom tool." }, "function": { "allOf": [ { "$ref": "#/components/schemas/ChatFunctionDefinition" } ], "description": "The function definition." } } }, "ChatOctenBroadSearchTool": { "type": "object", "required": [ "type" ], "description": "The built-in `octen_broad_search` server tool, executed by Octen.", "properties": { "type": { "type": "string", "enum": [ "octen_broad_search" ], "description": "The type of tool. Always `octen_broad_search`." }, "parameters": { "allOf": [ { "$ref": "#/components/schemas/OctenBroadSearchToolParameters" } ], "description": "Broad search behavior configuration. Optional." } } }, "ChatOctenSearchTool": { "type": "object", "required": [ "type" ], "description": "The built-in `octen_search` server tool, executed by Octen.", "properties": { "type": { "type": "string", "enum": [ "octen_search" ], "description": "The type of tool. Always `octen_search`." }, "parameters": { "allOf": [ { "$ref": "#/components/schemas/OctenSearchToolParameters" } ], "description": "Search behavior configuration. Optional." } } }, "ChatToolDefinition": { "oneOf": [ { "$ref": "#/components/schemas/ChatFunctionTool" }, { "$ref": "#/components/schemas/ChatOctenBroadSearchTool" }, { "$ref": "#/components/schemas/ChatOctenSearchTool" } ], "discriminator": { "propertyName": "type", "mapping": { "function": "#/components/schemas/ChatFunctionTool", "octen_broad_search": "#/components/schemas/ChatOctenBroadSearchTool", "octen_search": "#/components/schemas/ChatOctenSearchTool" } }, "description": "A tool definition. One of a custom `function` tool, the built-in `octen_broad_search` tool, or the `octen_search` tool." }, "ChatFunctionDefinition": { "type": "object", "required": [ "name" ], "description": "A custom function definition.", "properties": { "name": { "type": "string", "description": "The name of the function." }, "description": { "type": "string", "description": "A description of what the function does." }, "parameters": { "type": "object", "description": "The function's parameter definition in JSON Schema format." }, "strict": { "type": "boolean", "default": false, "description": "Whether to enable strict mode. When enabled, generated arguments strictly conform to `parameters`." } } }, "ChatCompletionResponse": { "type": "object", "required": [ "id", "object", "created", "model", "choices" ], "description": "A non-streaming chat completion response. Returned when `stream=false`.", "properties": { "id": { "type": "string", "description": "The unique identifier for this request." }, "object": { "type": "string", "enum": [ "chat.completion" ], "description": "The object type, always `chat.completion` for non-streaming responses." }, "created": { "type": "integer", "description": "Unix timestamp (in seconds) of when the completion was created." }, "model": { "type": "string", "description": "The model used for this completion." }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionChoice" }, "description": "A list of completion choices." }, "search_results": { "type": "array", "items": { "$ref": "#/components/schemas/ChatSearchResultGroup" }, "description": "Search results. Present only when `octen_search` was actually triggered." }, "usage": { "$ref": "#/components/schemas/ChatCompletionUsage" }, "warning": { "type": "string", "description": "Warning message, if any." } } }, "ChatCompletionChoice": { "type": "object", "description": "A single completion choice in a non-streaming response.", "properties": { "index": { "type": "integer", "description": "The index of this choice. Usually 0." }, "finish_reason": { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "error" ], "description": "The reason the model stopped generating. `stop` indicates normal completion." }, "message": { "$ref": "#/components/schemas/ChatCompletionMessage" }, "logprobs": { "$ref": "#/components/schemas/ChatLogprobs" } } }, "ChatCompletionMessage": { "type": "object", "description": "The assistant's response message.", "properties": { "role": { "type": "string", "enum": [ "assistant" ], "description": "The role of the message author. Always `assistant`." }, "content": { "type": "string", "nullable": true, "description": "The assistant's text content. May be `null` when the model only produces tool calls or refuses." }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ChatToolCall" }, "description": "Custom function calls generated by the model. Present only when `finish_reason` is `tool_calls`." }, "annotations": { "type": "array", "items": { "$ref": "#/components/schemas/ChatAnnotation" }, "description": "Citation annotations. Present only when `octen_broad_search` or `octen_search` was used." }, "refusal": { "type": "string", "nullable": true, "description": "A model-generated refusal message, or `null`." }, "reasoning": { "type": "string", "nullable": true, "description": "Reasoning text. Present only for reasoning models, otherwise `null`." }, "reasoning_details": { "type": "array", "items": { "$ref": "#/components/schemas/ChatReasoningDetail" }, "description": "Detailed reasoning information. Present only for reasoning models." } } }, "ChatCompletionUsage": { "type": "object", "required": [ "prompt_tokens", "completion_tokens", "total_tokens" ], "description": "Token usage information. When `stream=true`, returned only in the final `usage` chunk.", "properties": { "num_search_queries": { "type": "integer", "description": "Number of searches executed. Returned only when search was used." }, "full_content_extra_count": { "type": "integer", "description": "Billable full_content results beyond the free allowance. Returned only when `full_content` is enabled." }, "prompt_tokens": { "type": "integer", "description": "Number of input tokens. Cache read and write tokens are included here, not listed separately." }, "completion_tokens": { "type": "integer", "description": "Number of output tokens (reasoning tokens are included)." }, "total_tokens": { "type": "integer", "description": "Total tokens (prompt_tokens + completion_tokens)." }, "prompt_tokens_details": { "type": "object", "description": "Breakdown of input tokens. Returned only when the prompt cache is hit or written to.", "properties": { "cached_tokens": { "type": "integer", "description": "Portion of `prompt_tokens` served from cache (a subset of `prompt_tokens`)." }, "cache_write_tokens": { "type": "integer", "description": "Tokens written to cache (a subset of `prompt_tokens`). Returned only when `cache_control` was used and the model supports cache writes." }, "cache_write_5m_tokens": { "type": "integer", "description": "Tokens written to the 5-minute cache (a subset of `cache_write_tokens`). Only the field matching the TTL used is returned." }, "cache_write_1h_tokens": { "type": "integer", "description": "Tokens written to the 1-hour cache (a subset of `cache_write_tokens`). Only the field matching the TTL used is returned." } } }, "completion_tokens_details": { "type": "object", "description": "Breakdown of output tokens. Returned only for reasoning models.", "properties": { "reasoning_tokens": { "type": "integer", "description": "Number of reasoning tokens (already included in `completion_tokens`)." } } } } }, "ChatCompletionChunk": { "type": "object", "required": [ "object", "created", "model" ], "description": "A streaming chunk. Returned when `stream=true`. The `type` field indicates the chunk kind: `search_done`, `content`, `finish`, `usage`. After the last chunk, `data: [DONE]` is sent.", "properties": { "type": { "type": "string", "enum": [ "search_done", "content", "finish", "usage" ], "description": "The type of this streaming chunk." }, "id": { "type": "string", "description": "The unique identifier for this request." }, "object": { "type": "string", "enum": [ "chat.completion.chunk" ], "description": "The object type, always `chat.completion.chunk` for streaming responses." }, "created": { "type": "integer", "description": "Unix timestamp (in seconds) of when the chunk was created." }, "model": { "type": "string", "description": "The model used for this completion." }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionChunkChoice" }, "description": "Incremental choices. Present in `content` and `finish` chunks." }, "search_results": { "type": "array", "items": { "$ref": "#/components/schemas/ChatSearchResultGroup" }, "description": "Search results. Present in `search_done` chunks." }, "usage": { "$ref": "#/components/schemas/ChatCompletionUsage" } } }, "ChatCompletionChunkChoice": { "type": "object", "description": "A single choice in a streaming chunk.", "properties": { "index": { "type": "integer", "description": "The index of this choice. Usually 0." }, "delta": { "$ref": "#/components/schemas/ChatCompletionDelta" }, "finish_reason": { "type": "string", "nullable": true, "enum": [ "stop", "length", "tool_calls", "content_filter", "error", null ], "description": "The reason generation stopped. `null` for intermediate chunks; set in the `finish` chunk." }, "logprobs": { "$ref": "#/components/schemas/ChatLogprobs" } } }, "ChatCompletionDelta": { "type": "object", "description": "Incremental content in a streaming chunk. Contains only the new fields for this chunk.", "properties": { "role": { "type": "string", "enum": [ "assistant" ], "description": "The role. Typically included in the first chunk." }, "content": { "type": "string", "description": "Incremental text content." }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ChatToolCallDelta" }, "description": "Incremental tool call data." } } }, "ChatToolCallDelta": { "type": "object", "description": "Incremental tool call data in a streaming chunk. The first chunk for a tool call includes `id`, `type`, and `function.name`. Subsequent chunks append to `function.arguments`.", "properties": { "index": { "type": "number", "description": "The index of this tool call in the tool_calls array." }, "id": { "type": "string", "description": "The tool call ID. Only present in the first chunk for this tool call." }, "type": { "type": "string", "enum": [ "function" ], "description": "The type of tool call." }, "function": { "type": "object", "description": "Incremental function call data.", "properties": { "name": { "type": "string", "description": "The function name. Only present in the first chunk for this tool call." }, "arguments": { "type": "string", "description": "Incremental JSON string of the function arguments. Concatenate across chunks to build the complete arguments." } } }, "thought_signature": { "type": "string", "description": "Encrypted reasoning state, replayed verbatim." } } }, "ChatToolChoiceObject": { "type": "object", "required": [ "type" ], "description": "Forces a specific tool. The named tool must be declared in `tools`.", "properties": { "type": { "type": "string", "enum": [ "function", "octen_broad_search", "octen_search" ], "description": "The type of tool to force." }, "function": { "type": "object", "description": "The function to call. Required when `type` is `function`.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the function to call." } } } } }, "ChatJsonSchemaSpec": { "type": "object", "required": [ "name" ], "description": "JSON Schema specification for structured output. Required when `response_format.type` is `json_schema`.", "properties": { "name": { "type": "string", "description": "A user-defined name for the schema." }, "strict": { "type": "boolean", "default": true, "description": "Whether the model output must strictly conform to the schema." }, "description": { "type": "string", "description": "A description of the schema." }, "schema": { "type": "object", "description": "The JSON Schema definition object. May contain `type`, `properties`, `required`, `additionalProperties`, etc." } } }, "AnswerRequest": { "type": "object", "required": [ "messages" ], "description": "Request body for the Answer API.", "properties": { "model": { "type": "string", "enum": [ "openai/gpt-6.1-sol", "openai/gpt-6-astra", "openai/gpt-5.6-sol", "openai/gpt-5.6-terra", "openai/gpt-5.6-luna", "openai/gpt-5.4", "anthropic/claude-fable-5.1", "anthropic/claude-fable-5", "anthropic/claude-opus-5.5", "anthropic/claude-opus-5", "anthropic/claude-opus-4.8", "anthropic/claude-opus-4.6", "anthropic/claude-sonnet-5.5", "anthropic/claude-sonnet-5", "anthropic/claude-sonnet-4.6", "anthropic/claude-haiku-5.5", "anthropic/claude-haiku-4.5", "google/gemini-4-argon", "google/gemini-3.8-flash", "google/gemini-3.5-flash", "google/gemini-3.5-flash-lite", "google/gemini-3.1-pro-preview", "google/gemini-3.1-flash-lite", "google/gemini-3-flash-preview", "moonshotai/kimi-k3", "moonshotai/kimi-k2.6", "moonshotai/kimi-k2.5", "minimax/minimax-m2.5", "qwen/qwen3.6-plus", "deepseek/deepseek-v4-pro", "deepseek/deepseek-v4-flash-0731" ], "default": "anthropic/claude-sonnet-4.6", "description": "The model to use for query decomposition and response synthesis." }, "messages": { "type": "array", "description": "A list of messages comprising the conversation so far. User and assistant messages in chronological order for multi-turn conversations.", "items": { "$ref": "#/components/schemas/ChatMessage" } }, "mode": { "type": "string", "enum": [ "queries_only", "queries_and_search", "full" ], "default": "full", "description": "Controls the execution depth. `queries_only`: only decompose the message into sub-queries without performing searches; `queries_and_search`: decompose into sub-queries and return search results without LLM synthesis; `full`: decompose, search, and synthesize a final response using the LLM." }, "max_queries": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30, "description": "Maximum number of sub-queries to generate." }, "web_search_options": { "allOf": [ { "$ref": "#/components/schemas/WebSearchOptions" } ], "description": "Search options. Shares the same parameters and defaults as the Web Search API, except `highlight.max_tokens` defaults to 256. Queries are automatically generated from the messages." }, "stream": { "type": "boolean", "default": false, "description": "Whether to enable streaming output. When `true`, returns `chat.completion.chunk` objects incrementally with types: `queries`, `search_done`, `content`, `finish`, and `usage`." } } }, "AnswerResponse": { "type": "object", "description": "A non-streaming Answer response. Returned when `stream=false`.", "required": [ "request_id", "object", "created", "model", "choices" ], "properties": { "request_id": { "type": "string", "description": "The unique identifier for this request." }, "object": { "type": "string", "enum": [ "chat.completion" ], "description": "The object type, always `chat.completion` for non-streaming responses." }, "created": { "type": "number", "description": "Unix timestamp (in seconds) of when the completion was created." }, "model": { "type": "string", "description": "The model used for this completion." }, "choices": { "type": "array", "description": "A list of completion choices containing the synthesized response.", "items": { "$ref": "#/components/schemas/ChatCompletionChoice" } }, "queries": { "type": "array", "items": { "type": "string" }, "description": "The list of sub-queries automatically generated from the user message by the system." }, "search_results": { "type": "array", "description": "Search results grouped by query. Each sub-query has a corresponding result group.", "items": { "$ref": "#/components/schemas/SearchResultGroup" } }, "meta": { "$ref": "#/components/schemas/AnswerMeta" }, "warning": { "type": "string", "nullable": true, "description": "Warning message, if any." } } }, "SearchResultGroup": { "type": "object", "description": "A group of search results for a single sub-query.", "properties": { "query": { "type": "string", "description": "The sub-query that produced these results." }, "results": { "type": "array", "description": "The search results for this sub-query.", "items": { "$ref": "#/components/schemas/SearchResult" } }, "latency": { "type": "integer", "description": "Search latency for this query in milliseconds." } } }, "AnswerMeta": { "type": "object", "description": "Metadata for the Answer response.", "properties": { "usage": { "$ref": "#/components/schemas/SynthesisUsage" }, "latency": { "type": "integer", "description": "Total request latency in milliseconds." } } }, "SynthesisUsage": { "type": "object", "description": "Token usage information for the Answer response. When `stream=true`, this is only present in the `usage` type chunk.", "required": [ "num_search_queries", "prompt_tokens", "completion_tokens", "total_tokens" ], "properties": { "num_search_queries": { "type": "integer", "description": "Total number of search queries executed across all sub-queries." }, "prompt_tokens": { "type": "integer", "description": "Number of input tokens." }, "completion_tokens": { "type": "integer", "description": "Number of output tokens." }, "total_tokens": { "type": "integer", "description": "Total tokens used (prompt_tokens + completion_tokens)." } } }, "AnswerChunk": { "type": "object", "description": "A streaming chunk of an Answer response. Returned when `stream=true`. The `type` field indicates the chunk kind: `queries`, `search_done`, `content`, `finish`, `usage`.", "required": [ "request_id", "object", "created", "model" ], "properties": { "type": { "type": "string", "enum": [ "queries", "search_done", "content", "finish", "usage" ], "description": "The type of this streaming chunk. The `queries` type contains the auto-generated sub-queries." }, "request_id": { "type": "string", "description": "The unique identifier for this request." }, "object": { "type": "string", "enum": [ "chat.completion.chunk" ], "description": "The object type, always `chat.completion.chunk` for streaming responses." }, "created": { "type": "number", "description": "Unix timestamp (in seconds) of when the chunk was created." }, "model": { "type": "string", "description": "The model used for this completion." }, "queries": { "type": "array", "items": { "type": "string" }, "description": "Auto-generated sub-queries. Present only in `queries` type chunks." }, "choices": { "type": "array", "description": "Incremental choices. Present in `content` and `finish` chunks.", "items": { "$ref": "#/components/schemas/ChatCompletionChunkChoice" } }, "search_results": { "type": "array", "description": "Search results grouped by query. Present in `search_done` chunks.", "items": { "$ref": "#/components/schemas/SearchResultGroup" } }, "meta": { "$ref": "#/components/schemas/AnswerMeta" } } }, "DeepResearchRequest": { "type": "object", "required": [ "messages" ], "description": "Request body for the Deep Research API.", "properties": { "tier": { "type": "string", "enum": [ "lite", "standard", "pro", "pro-visual" ], "default": "lite", "description": "The research tier. `lite`, `standard`, and `pro` increase research depth, cost, and time in that order. `pro-visual` additionally illustrates each report section with images and videos and streams an HTML version of the report." }, "messages": { "type": "array", "description": "Conversation messages. Only the last `role=user` message is used as the research question; other messages are ignored and do not enter plan generation, search, analysis, or report writing.", "items": { "$ref": "#/components/schemas/DeepResearchMessage" } }, "extra_context": { "type": "string", "description": "Additional research background, constraints, or preferences, used as extra context for query rewriting and research direction supplementation." }, "skip_brief": { "type": "boolean", "default": false, "description": "Skip the Research Brief stage and write the final report directly from raw search and analysis results.\n\nNote: when enabled, no `brief` event is emitted. Clients can rebuild the citation index by accumulating `search_results` events in the order they arrive (round-by-round / query-by-query / result-by-result) into a global index, then look up the corresponding url/title by the `N` in `[^N]`." }, "skip_plan": { "type": "boolean", "default": false, "description": "Phase 1 only. Skip the Research Plan stage and proceed straight to the search loop. With `skip_plan=true`, the call never enters the Phase 2 pause mechanism." }, "skip_plan_confirm": { "type": "boolean", "default": false, "description": "Phase 1 only. When `true`, the run continues with all angles even if the plan is ambiguous, instead of pausing and waiting for the user to confirm a selection." }, "plan_id": { "type": "string", "description": "Phase 2 only. The plan ID returned by a Phase 1 `plan` event with `requires_selection=true`. When provided, the server skips plan generation and applies the supplied `selections` against the stored plan. Each `plan_id` is retained for 30 minutes; after expiry the plan is regenerated." }, "selections": { "type": "array", "description": "Phase 2 only. The user's corrections and angle filtering against the Phase 1 plan.", "items": { "$ref": "#/components/schemas/DeepResearchSelection" } } } }, "DeepResearchMessage": { "type": "object", "required": [ "role", "content" ], "description": "A single message in the Deep Research request.", "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant" ], "description": "The role of the message author." }, "content": { "description": "The content of the message. Can be a plain string, or an array of text content blocks.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/DeepResearchTextContentBlock" } } ] } } }, "DeepResearchTextContentBlock": { "type": "object", "required": [ "type" ], "description": "A text content block.", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "The block type. Always `text` for Deep Research." }, "text": { "type": "string", "description": "The text content." } } }, "DeepResearchSelection": { "type": "object", "description": "A single user correction or angle filter applied against a Phase 1 plan.", "properties": { "term": { "type": "string", "description": "An ambiguous term, matching `plan.interpretations[].term`. When present, overrides the LLM's default `chosen` meaning." }, "chosen": { "type": "string", "description": "The selected meaning ID (from `plan.interpretations[].meanings[].id`, e.g. `\"nasa_program\"`). Pass `\"all\"` to keep every meaning. When used as an angle filter, this carries the `interpretation_id` of the angles to keep." }, "indices": { "type": "array", "items": { "type": "integer" }, "description": "0-based angle indices within the group identified by `chosen`. Absent means keep every angle in that group." } } }, "DeepResearchChunk": { "type": "object", "description": "A streaming chunk of a Deep Research response.", "required": [ "request_id", "created" ], "properties": { "type": { "type": "string", "enum": [ "status", "plan", "queries", "search_done", "analysis", "brief", "content", "visual", "html_delta", "html", "finish", "usage", "error" ], "description": "The type of this streaming chunk. On the `pro-visual` tier, `html_delta` chunks stream an HTML version of the report after the report content completes, and a final `html` chunk marks the end of that stream." }, "request_id": { "type": "string", "description": "The unique identifier for this request." }, "object": { "type": "string", "enum": [ "research.chunk" ], "description": "The object type, always `research.chunk`." }, "created": { "type": "number", "description": "Unix timestamp (in seconds) of when the chunk was created." }, "round": { "type": "integer", "description": "Current research round. Present only in `queries`, `search_done`, and `analysis` chunks." }, "latency": { "type": "integer", "description": "Latency in milliseconds for the stage represented by this chunk." }, "status": { "type": "string", "description": "Pipeline progress copy. Present only in `status` chunks." }, "plan": { "$ref": "#/components/schemas/DeepResearchPlan" }, "plan_id": { "type": "string", "description": "Plan ID carried by `plan` chunks. The client must echo this back as `plan_id` when entering Phase 2." }, "queries": { "type": "array", "items": { "type": "string" }, "description": "Sub-queries generated for this round. Present only in `queries` chunks." }, "search_result_count": { "type": "integer", "description": "Total number of search results returned this round. Present only in `search_done` chunks." }, "search_results": { "type": "array", "description": "Search results for this round, one group per sub-query. Present only in `search_done` chunks.", "items": { "$ref": "#/components/schemas/SearchResultGroup" } }, "analysis": { "$ref": "#/components/schemas/DeepResearchAnalysis" }, "brief": { "$ref": "#/components/schemas/DeepResearchBrief" }, "choices": { "type": "array", "description": "Incremental choices for the final report. Present in `content` and `finish` chunks.", "items": { "$ref": "#/components/schemas/DeepResearchChunkChoice" } }, "visual": { "allOf": [ { "$ref": "#/components/schemas/DeepResearchVisual" } ], "description": "Visual material for one report section. Present only in `visual` chunks, emitted on the `pro-visual` tier." }, "html_delta": { "type": "object", "description": "An incremental fragment of the HTML report. Present only in `html_delta` chunks. Concatenate the fragments in order to rebuild the full page.", "properties": { "delta": { "type": "string", "description": "The next fragment of the HTML page." } } }, "meta": { "$ref": "#/components/schemas/DeepResearchMeta" } } }, "DeepResearchPlan": { "type": "object", "description": "Research plan generated in Phase 1. Carried by `plan` chunks.", "properties": { "title": { "type": "string", "description": "Plan title." }, "overview": { "type": "string", "description": "Plan overview." }, "interpretations": { "type": "array", "description": "Ambiguous terms in the question along with their possible meanings. Empty when the question has no ambiguity.", "items": { "$ref": "#/components/schemas/DeepResearchInterpretation" } }, "angles": { "type": "array", "description": "Research angles the plan will explore.", "items": { "$ref": "#/components/schemas/DeepResearchAngle" } }, "requires_selection": { "type": "boolean", "description": "When `true`, the SSE stream ends at this `plan` chunk and waits for the client to continue via Phase 2 (`plan_id` + `selections`). When `false`, research continues automatically." } } }, "DeepResearchInterpretation": { "type": "object", "description": "An ambiguous term and its candidate meanings.", "properties": { "term": { "type": "string", "description": "The ambiguous term." }, "meanings": { "type": "array", "description": "All candidate meanings for this term.", "items": { "$ref": "#/components/schemas/DeepResearchMeaning" } }, "chosen": { "type": "string", "description": "The meaning ID the LLM picked by default." }, "reasoning": { "type": "string", "description": "The LLM's rationale for the chosen meaning." } } }, "DeepResearchMeaning": { "type": "object", "description": "A candidate meaning for an ambiguous term.", "properties": { "id": { "type": "string", "description": "Unique meaning ID." }, "label": { "type": "string", "description": "Description of the meaning." } } }, "DeepResearchAngle": { "type": "object", "description": "A single research angle within the plan.", "properties": { "focus": { "type": "string", "description": "Angle name." }, "focus_desc": { "type": "string", "description": "Angle description." }, "interpretation_id": { "type": "string", "description": "The meaning ID this angle serves. `\"general\"` denotes a cross-interpretation angle." }, "queries": { "type": "array", "items": { "type": "string" }, "description": "Search queries planned for this angle." }, "sub_question_ids": { "type": "array", "items": { "type": "string" }, "description": "Sub-question IDs covered by this angle." } } }, "DeepResearchAnalysis": { "type": "object", "description": "Analysis output for one research round. Carried by `analysis` chunks.", "properties": { "findings": { "type": "array", "items": { "type": "string" }, "description": "Key findings extracted from this round." }, "should_continue": { "type": "boolean", "description": "Whether the pipeline should run another research round." }, "follow_up_suggestions": { "type": "array", "items": { "type": "string" }, "description": "Suggested research directions for the next round." } } }, "DeepResearchBrief": { "type": "object", "description": "Report outline and evidence set. Carried by `brief` chunks.", "properties": { "report_type": { "type": "string", "enum": [ "general", "comparison", "trend", "how-to", "evaluation", "framework", "deep_explainer", "theoretical_analysis", "landscape_mapping", "multi_part" ], "description": "Report type, classified by the LLM from the question. `general`: general synthesis; `comparison`: cross-entity comparison; `trend`: time-axis trend analysis; `how-to`: step-by-step guide; `evaluation`: ranked or scored evaluation; `framework`: methodology or scoring framework; `deep_explainer`: deep explanation of a single topic; `theoretical_analysis`: scholarly analysis across multiple theoretical lenses; `landscape_mapping`: taxonomy and players in a domain; `multi_part`: composite question with explicit sub-questions." }, "secondary_report_types": { "type": "array", "items": { "type": "string" }, "description": "Secondary type tags for hybrid reports, combined with `report_type`." }, "total_word_budget": { "type": "integer", "description": "Total word budget for the report." }, "assertiveness_required": { "type": "boolean", "description": "Whether the report must deliver a clear verdict." }, "verdict_scaffold": { "$ref": "#/components/schemas/DeepResearchVerdictScaffold" }, "tables": { "type": "array", "description": "Table metadata to render in the report. Mutually exclusive with `presentation_notes`.", "items": { "$ref": "#/components/schemas/DeepResearchTable" } }, "presentation_notes": { "type": "array", "items": { "type": "string" }, "description": "Presentation notes for reports that do not use tables. Mutually exclusive with `tables`." }, "outline": { "type": "array", "description": "Report outline in section order.", "items": { "$ref": "#/components/schemas/DeepResearchOutlineSection" } }, "sub_question_to_section_map": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Mapping from sub-question ID to section ID." }, "unresolved": { "$ref": "#/components/schemas/DeepResearchUnresolved" }, "suggested_title": { "type": "string", "description": "Suggested title for the report." }, "references": { "type": "array", "description": "List of cited references.", "items": { "$ref": "#/components/schemas/DeepResearchReference" } } } }, "DeepResearchVerdictScaffold": { "type": "object", "description": "Structured scaffold for reports that need to deliver a verdict.", "properties": { "verdict_type": { "type": "string", "enum": [ "ranked_list", "single_pick", "tiered_recommendation", "qualified_pick" ], "description": "Shape of the verdict. `ranked_list`: ordered ranking; `single_pick`: a single best answer; `tiered_recommendation`: tiered recommendation; `qualified_pick`: conditional recommendation." }, "items_expected": { "type": "integer", "description": "Expected number of items in the verdict." }, "justification_dimensions": { "type": "array", "items": { "type": "string" }, "description": "Data dimensions supporting the verdict." } } }, "DeepResearchTable": { "type": "object", "description": "Table metadata referenced from an outline section.", "properties": { "table_id": { "type": "string", "description": "Unique table ID, referenced by `outline.table_ids`." }, "title": { "type": "string", "description": "Table title." }, "columns": { "type": "array", "items": { "type": "string" }, "description": "Column names." }, "description": { "type": "string", "description": "Description of the table contents, guiding how the report-writing stage should populate the cells." }, "placement": { "type": "string", "description": "Section ID this table belongs to." } } }, "DeepResearchOutlineSection": { "type": "object", "description": "A single section in the report outline.", "properties": { "section_id": { "type": "string", "description": "Unique section ID, referenced by `sub_question_to_section_map` and `table.placement`." }, "section_title": { "type": "string", "description": "Section title." }, "thesis": { "type": "string", "description": "Central claim of this section." }, "table_ids": { "type": "array", "items": { "type": "string" }, "description": "Table IDs belonging to this section." }, "covers_sub_questions": { "type": "array", "items": { "type": "string" }, "description": "Sub-question IDs covered by this section." }, "target_words": { "type": "integer", "description": "Target word count for this section." }, "evidence": { "type": "array", "description": "Evidence supporting this section.", "items": { "$ref": "#/components/schemas/DeepResearchEvidence" } } } }, "DeepResearchEvidence": { "type": "object", "description": "A single piece of evidence within a section.", "properties": { "content": { "type": "string", "description": "Evidence content." }, "source_indices": { "type": "array", "items": { "type": "integer" }, "description": "Source indices cited by this evidence (matching `brief.references[].index`)." }, "confidence": { "type": "string", "enum": [ "strong", "moderate", "weak", "conflicting" ], "description": "Confidence level of the evidence." }, "layer": { "type": "string", "enum": [ "phenomenon", "mechanism", "evidence", "implication" ], "description": "Depth layer of the evidence." } } }, "DeepResearchUnresolved": { "type": "object", "description": "Items the brief stage flagged as unresolved.", "properties": { "contradictions": { "type": "array", "items": { "type": "string" }, "description": "Contradictions between sources." }, "weak_claims": { "type": "array", "items": { "type": "string" }, "description": "Claims with thin evidence." }, "depth_gaps": { "type": "array", "items": { "type": "string" }, "description": "Depth-layer gaps across sections." }, "unanswered": { "type": "array", "items": { "type": "string" }, "description": "Sub-questions left unanswered." } } }, "DeepResearchReference": { "type": "object", "description": "A single cited reference.", "properties": { "index": { "type": "integer", "description": "Reference index; cited in the report body as `[^N]`." }, "url": { "type": "string", "description": "Source URL." }, "title": { "type": "string", "description": "Source title." } } }, "DeepResearchVisual": { "type": "object", "description": "Visual material for one report section. Carried by `visual` chunks on the `pro-visual` tier.", "properties": { "section_id": { "type": "string", "description": "The report section this material belongs to, matching `brief.outline[].section_id`." }, "images": { "type": "array", "description": "Images selected for this section.", "items": { "$ref": "#/components/schemas/DeepResearchVisualImage" } }, "videos": { "type": "array", "description": "Videos selected for this section.", "items": { "$ref": "#/components/schemas/DeepResearchVisualVideo" } } } }, "DeepResearchVisualImage": { "type": "object", "description": "An image selected for a report section.", "properties": { "url": { "type": "string", "description": "The image URL." }, "thumbnail": { "type": "string", "description": "Thumbnail URL." }, "caption": { "type": "string", "description": "A short caption for the image." }, "visual_evidence": { "type": "string", "description": "Why this image supports the section's content." }, "source_page": { "type": "string", "description": "URL of the page the image was found on." }, "width": { "type": "integer", "description": "Image width in pixels." }, "height": { "type": "integer", "description": "Image height in pixels." }, "confidence": { "type": "number", "description": "Relevance confidence score." } } }, "DeepResearchVisualVideo": { "type": "object", "description": "A video selected for a report section.", "properties": { "url": { "type": "string", "description": "The video URL." }, "cover_url": { "type": "string", "description": "Video cover image URL." }, "title": { "type": "string", "description": "The video title." }, "duration_seconds": { "type": "integer", "description": "Video duration in seconds." }, "source_page": { "type": "string", "description": "URL of the page the video was found on." }, "time_published": { "type": "string", "description": "Publish time in ISO 8601." } } }, "DeepResearchMeta": { "type": "object", "description": "Usage and latency metadata for the Deep Research call. Carried by `usage` chunks.", "properties": { "usage": { "type": "object", "description": "Search usage.", "properties": { "num_search_queries": { "type": "integer", "description": "Total number of search queries executed across all rounds." } } }, "latency": { "type": "integer", "description": "Total request latency in milliseconds." }, "total_rounds": { "type": "integer", "description": "Total number of research rounds completed." }, "total_search_count": { "type": "integer", "description": "Total search results accumulated across all rounds." }, "billed_tier": { "type": "string", "description": "The tier actually billed for this request." } } }, "DeepResearchChunkChoice": { "type": "object", "description": "A single choice in a Deep Research streaming chunk. Carried by `content` and `finish` chunks.", "properties": { "index": { "type": "number", "description": "The index of this choice. Usually `0`." }, "delta": { "$ref": "#/components/schemas/DeepResearchChunkDelta" }, "finish_reason": { "type": "string", "nullable": true, "enum": [ "stop", "length", "content_filter", "error" ], "description": "The reason generation stopped. `null` in `content` chunks; populated in the `finish` chunk." } } }, "DeepResearchChunkDelta": { "type": "object", "description": "Incremental content in a Deep Research streaming chunk.", "properties": { "content": { "type": "string", "description": "Incremental report text. Concatenate across `content` chunks to build the final report." } } }, "ImageSearchInput": { "type": "object", "required": [ "type" ], "description": "A single multimodal input. Currently each request accepts exactly one input: either one text input or one image input.", "properties": { "type": { "type": "string", "enum": [ "text", "image" ], "description": "The input type. A single image must be at most 5MB and one of: JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS, SGI." }, "url": { "type": "string", "description": "Image input as a public URL. For an image input, provide either `url` or `data`, not both." }, "data": { "type": "string", "description": "When `type` is `text`: the query content, max 500 characters. When `type` is `image`: base64-encoded image data, at most 5MB after encoding." } } }, "ImageSearchRequest": { "type": "object", "required": [ "inputs" ], "description": "Request body for the Image Search API.", "properties": { "inputs": { "type": "array", "minItems": 1, "maxItems": 1, "description": "Multimodal input array. Currently only a single input is supported: either one text input or one image input.", "items": { "$ref": "#/components/schemas/ImageSearchInput" } }, "count": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5, "description": "Number of results to return." }, "include_domains": { "type": "array", "items": { "type": "string" }, "description": "Domains to include, matched against each result's `source_page` URL." }, "exclude_domains": { "type": "array", "items": { "type": "string" }, "description": "Domains to exclude, matched against each result's `source_page` URL." }, "safesearch": { "type": "string", "enum": [ "off", "strict" ], "default": "strict", "description": "Controls filtering of explicit/adult content. `off` disables filtering; `strict` drops all adult content." } } }, "ImageSearchResult": { "type": "object", "description": "A single image search result.", "properties": { "title": { "type": "string", "description": "The title of the image." }, "url": { "type": "string", "description": "The image URL." }, "source_page": { "type": "string", "description": "URL of the original page hosting the image." }, "description": { "type": "string", "description": "Server-generated text description of the image content." }, "width": { "type": "integer", "description": "Image width in pixels." }, "height": { "type": "integer", "description": "Image height in pixels." }, "thumbnail": { "type": "string", "description": "Thumbnail URL." } } }, "ImageSearchUsage": { "type": "object", "description": "Usage information for the Image Search request.", "properties": { "num_search_queries": { "type": "integer", "description": "Number of search queries executed." } } }, "ImageSearchMeta": { "type": "object", "description": "Additional metadata for the Image Search request.", "properties": { "usage": { "$ref": "#/components/schemas/ImageSearchUsage" }, "latency": { "type": "number", "description": "Response time in milliseconds." }, "warning": { "type": "string", "nullable": true, "description": "Warning message, if any." } } }, "ImageSearchData": { "type": "object", "description": "The main response payload.", "properties": { "results": { "type": "array", "description": "A list of image search results.", "items": { "$ref": "#/components/schemas/ImageSearchResult" } } } }, "ImageSearchResponse": { "type": "object", "properties": { "code": { "type": "integer", "description": "Business status code. 0 indicates success." }, "msg": { "type": "string", "description": "A message describing the result." }, "request_id": { "type": "string", "description": "The unique identifier for this request." }, "data": { "$ref": "#/components/schemas/ImageSearchData" }, "meta": { "$ref": "#/components/schemas/ImageSearchMeta" } } }, "VideoSearchInput": { "type": "object", "required": [ "type" ], "description": "A single text input. At most one input per request.", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "The input type." }, "data": { "type": "string", "description": "The query content, max 500 characters." } } }, "VideoSearchRequest": { "type": "object", "required": [ "inputs" ], "description": "Request body for the Video Search API.", "properties": { "inputs": { "type": "array", "maxItems": 1, "description": "Input array carrying a text query (at most 1).", "items": { "$ref": "#/components/schemas/VideoSearchInput" } }, "count": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5, "description": "Number of results to return." }, "time_range": { "type": "string", "enum": [ "day", "week", "month", "year", "d", "w", "m", "y" ], "description": "Relative time window counting back from the current time, filtered by publish time. Mutually exclusive with `start_time`/`end_time` — if both are provided, `start_time`/`end_time` take precedence." }, "start_time": { "type": "string", "format": "date-time", "description": "Start time for filtering results by publish time. ISO 8601 format.", "example": "2025-01-01T00:00:00+08:00" }, "end_time": { "type": "string", "format": "date-time", "description": "End time for filtering results by publish time. ISO 8601 format.", "example": "2025-01-01T00:00:00+08:00" }, "safesearch": { "type": "string", "enum": [ "off", "strict" ], "default": "strict", "description": "Controls filtering of explicit/adult content. `off` disables filtering; `strict` drops all adult content." } } }, "VideoSearchResult": { "type": "object", "description": "A single video search result.", "properties": { "title": { "type": "string", "description": "The title of the video." }, "url": { "type": "string", "description": "The video URL." }, "source_page": { "type": "string", "description": "URL of the original page hosting the video." }, "description": { "type": "string", "description": "Server-generated text description of the video content." }, "cover_url": { "type": "string", "description": "Video cover image URL." }, "duration_seconds": { "type": "integer", "description": "Video duration in seconds." }, "authors": { "type": "string", "description": "Website name or author." }, "time_published": { "type": "string", "format": "date-time", "description": "Publish time in ISO 8601." }, "time_last_crawled": { "type": "string", "format": "date-time", "description": "Last crawl time in ISO 8601." } } }, "VideoSearchUsage": { "type": "object", "description": "Usage information for the Video Search request.", "properties": { "num_search_queries": { "type": "integer", "description": "Number of search queries executed." } } }, "VideoSearchMeta": { "type": "object", "description": "Additional metadata for the Video Search request.", "properties": { "usage": { "$ref": "#/components/schemas/VideoSearchUsage" }, "latency": { "type": "number", "description": "Response time in milliseconds." }, "warning": { "type": "string", "nullable": true, "description": "Warning message, if any." } } }, "VideoSearchData": { "type": "object", "description": "The main response payload.", "properties": { "results": { "type": "array", "description": "A list of video search results.", "items": { "$ref": "#/components/schemas/VideoSearchResult" } } } }, "VideoSearchResponse": { "type": "object", "properties": { "code": { "type": "integer", "description": "Business status code. 0 indicates success." }, "msg": { "type": "string", "description": "A message describing the result." }, "request_id": { "type": "string", "description": "The unique identifier for this request." }, "data": { "$ref": "#/components/schemas/VideoSearchData" }, "meta": { "$ref": "#/components/schemas/VideoSearchMeta" } } }, "OpenAIErrorResponse": { "type": "object", "description": "Error body in the OpenAI protocol format.", "required": [ "error" ], "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "A human-readable description of the error." }, "type": { "type": "string", "description": "The error category, e.g. `invalid_request_error`." }, "param": { "type": "string", "nullable": true, "description": "The parameter related to the error, if any." }, "code": { "type": "string", "nullable": true, "description": "A machine-readable error code, if any." } }, "required": [ "message", "type" ] } } }, "AnthropicErrorResponse": { "type": "object", "description": "Error body in the Anthropic protocol format.", "required": [ "type", "error" ], "properties": { "type": { "type": "string", "enum": [ "error" ], "description": "Always `error`." }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "The error category, e.g. `invalid_request_error`." }, "message": { "type": "string", "description": "A human-readable description of the error." } }, "required": [ "type", "message" ] } } }, "WebSearchOptions": { "type": "object", "properties": { "count": { "type": "integer", "default": 5, "minimum": 1, "maximum": 100, "description": "Number of results to return." }, "include_domains": { "type": "array", "items": { "type": "string", "maxLength": 60 }, "maxItems": 1200, "description": "A list of domains to specifically include in the search results. The `site:` query operator adds to this list.", "example": [ "octen.ai", "wikipedia.org" ] }, "exclude_domains": { "type": "array", "items": { "type": "string", "maxLength": 60 }, "maxItems": 1200, "description": "A list of domains to specifically exclude from the search results. The `-site:` query operator adds to this list. If a domain appears in both `include_domains` and `exclude_domains`, `exclude_domains` takes precedence.", "example": [ "spam.com", "ads.example.net" ] }, "include_text": { "type": "array", "items": { "type": "string", "maxLength": 30 }, "maxItems": 5, "description": "Strings that must appear in the result page text." }, "exclude_text": { "type": "array", "items": { "type": "string", "maxLength": 30 }, "maxItems": 5, "description": "Strings that must not appear in the result page text." }, "time_basis": { "type": "string", "enum": [ "auto", "published", "crawled" ], "default": "auto", "description": "Determines which time field is used for time filtering. `published` uses time_published; `crawled` uses time_last_crawled. Results missing this field are excluded when filtering by time." }, "time_range": { "type": "string", "enum": [ "day", "week", "month", "year", "d", "w", "m", "y" ], "description": "Relative time window counting back from the current time based on `time_basis`. Mutually exclusive with `start_time`/`end_time` — if both are provided, `start_time`/`end_time` take precedence." }, "start_time": { "type": "string", "format": "date-time", "description": "Start time for filtering results. ISO 8601 format.", "example": "2025-01-01T00:00:00+08:00" }, "end_time": { "type": "string", "format": "date-time", "description": "End time for filtering results. ISO 8601 format.", "example": "2025-01-01T00:00:00+08:00" }, "language": { "type": "array", "items": { "type": "string", "enum": [ "ar", "de", "en", "es", "fr", "hi", "id", "it", "ja", "ko", "nl", "pl", "pt", "ru", "th", "tr", "vi", "zh" ] }, "default": [], "description": "A list of languages to restrict results to, as ISO 639-1 codes. By default, no language filter is applied.", "example": [ "en", "zh" ] }, "highlight": { "$ref": "#/components/schemas/HighlightOptions" }, "full_content": { "$ref": "#/components/schemas/FullContentOptions" }, "format": { "type": "string", "enum": [ "markdown", "text" ], "default": "text", "description": "Controls the formatting of highlight outputs." }, "safesearch": { "type": "string", "enum": [ "off", "strict" ], "default": "strict", "description": "Controls filtering of explicit/adult content. `off` disables filtering; `strict` drops all adult content." }, "include_images": { "type": "boolean", "default": false, "description": "Whether to include images in each result." } } }, "OctenBroadSearchToolParameters": { "description": "Behavior configuration for the built-in `octen_broad_search` tool. Identical to `octen_search` except it accepts `max_queries` instead of `max_searches`. All parameters are optional and share the same semantics and defaults as the Web Search API.", "allOf": [ { "type": "object", "properties": { "max_queries": { "type": "integer", "minimum": 1, "maximum": 30, "default": 5, "description": "Upper bound on the number of sub-queries generated." } } }, { "$ref": "#/components/schemas/WebSearchOptions" } ] }, "OctenSearchToolParameters": { "description": "Behavior configuration for the built-in `octen_search` tool. All parameters are optional and share the same semantics and defaults as the Web Search API. The query is generated automatically by the model; a single request may trigger multiple searches.", "allOf": [ { "type": "object", "properties": { "max_searches": { "type": "integer", "default": 5, "description": "Maximum number of searches allowed in a single request." } } }, { "$ref": "#/components/schemas/WebSearchOptions" } ] }, "CacheControl": { "type": "object", "description": "Prompt caching marker. Sets a cache breakpoint so the stable prefix up to this block can be reused.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "ephemeral" ], "description": "The cache control type. Always `ephemeral`." }, "ttl": { "type": "string", "enum": [ "5m", "1h" ], "default": "5m", "description": "Cache lifetime." } } }, "DeveloperMessage": { "type": "object", "required": [ "role", "content" ], "description": "A developer message. The OpenAI-protocol equivalent of `system` (sent by newer OpenAI SDKs); handled as `system`.", "properties": { "role": { "type": "string", "enum": [ "developer" ], "description": "The role of the message author. Always `developer`." }, "content": { "description": "The content. A plain string or an array of content blocks.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ChatContentBlock" } } ] } } }, "ChatAnnotation": { "type": "object", "description": "A citation annotation. Returned only when `octen_search` was used, currently only for `anthropic/` models. For other models, results are still available in `search_results`.", "properties": { "type": { "type": "string", "enum": [ "url_citation" ], "description": "The annotation type." }, "url_citation": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL of the cited source." }, "title": { "type": "string", "description": "The title of the cited source." }, "start_index": { "type": "integer", "description": "Start position of the cited span in `content`." }, "end_index": { "type": "integer", "description": "End position of the cited span in `content`." } } } } }, "ChatReasoningDetail": { "type": "object", "description": "Detailed reasoning information. Returned only for reasoning models.", "properties": { "format": { "type": "string", "enum": [ "unknown", "openai-responses-v1", "azure-openai-responses-v1", "xai-responses-v1", "anthropic-claude-v1", "google-gemini-v1" ], "description": "The format of the reasoning information." }, "index": { "type": "integer", "description": "The position of this entry in the output. Usually 0." }, "type": { "type": "string", "enum": [ "reasoning.text", "reasoning.summary", "reasoning.encrypted" ], "description": "The kind of reasoning information." }, "text": { "type": "string", "description": "Reasoning text. Present only when `type` is `reasoning.text`." }, "summary": { "type": "string", "description": "Reasoning summary. Present only when `type` is `reasoning.summary`." }, "data": { "type": "string", "description": "Encrypted reasoning. Present only when `type` is `reasoning.encrypted`." } } }, "ChatLogprobs": { "type": "object", "nullable": true, "description": "Log probability information for the output tokens. Present only when `logprobs` is `true`, otherwise `null`.", "properties": { "content": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "token": { "type": "string", "description": "The token text." }, "logprob": { "type": "number", "description": "The log probability of this token." }, "bytes": { "type": "array", "nullable": true, "items": { "type": "integer" }, "description": "UTF-8 byte representation." }, "top_logprobs": { "type": "array", "description": "The top candidate tokens at this position, same structure.", "items": { "type": "object" } } } } } } }, "ChatSearchResultItem": { "type": "object", "description": "A single search result.", "properties": { "title": { "type": "string", "description": "The title of the result page." }, "url": { "type": "string", "description": "The URL of the result page." }, "highlights": { "type": "string", "description": "Query-relevant highlight snippets. Returned only if `highlight.enable` is true." }, "full_content": { "type": "string", "description": "Full raw page content. Returned only if `full_content.enable` is true." }, "authors": { "type": "string", "description": "Website name or author." }, "time_published": { "type": "string", "format": "date-time", "description": "Publish time in ISO 8601." }, "time_last_crawled": { "type": "string", "format": "date-time", "description": "Last crawl time in ISO 8601." } } }, "ChatSearchResultGroup": { "type": "object", "description": "Search results for a single auto-generated query. One element per search.", "properties": { "query": { "type": "string", "description": "The query the model actually searched for. One message may produce multiple queries." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ChatSearchResultItem" }, "description": "The search results for this query." } } }, "MessagesContentBlock": { "type": "object", "required": [ "type" ], "description": "A content block within a message. The fields used depend on `type`. For replaying a multi-turn conversation, blocks such as `tool_use`, `tool_result`, `thinking`, `redacted_thinking`, `server_tool_use`, and `web_search_tool_result` are returned verbatim.", "properties": { "type": { "type": "string", "enum": [ "text", "image", "tool_use", "tool_result", "thinking", "redacted_thinking", "server_tool_use", "web_search_tool_result" ], "description": "The type of content block." }, "text": { "type": "string", "description": "Text content. Required when `type` is `text`." }, "source": { "type": "object", "description": "Image source. Required when `type` is `image`.", "properties": { "type": { "type": "string", "enum": [ "url", "base64" ], "description": "How the image is provided." }, "url": { "type": "string", "description": "Image URL. Required when `source.type` is `url`." }, "media_type": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/gif", "image/webp" ], "description": "Image MIME type. Required when `source.type` is `base64`." }, "data": { "type": "string", "description": "Base64-encoded image. Required when `source.type` is `base64`." } } }, "id": { "type": "string", "description": "Block id, replayed verbatim. Used by `tool_use` and `server_tool_use` blocks." }, "name": { "type": "string", "description": "Tool name, replayed verbatim. For `server_tool_use` it is `octen_search`. Used by `tool_use` and `server_tool_use` blocks." }, "input": { "type": "object", "description": "Tool call arguments, replayed verbatim. Used by `tool_use` and `server_tool_use` blocks." }, "tool_use_id": { "type": "string", "description": "The id of the corresponding `tool_use` or `server_tool_use` block. Used by `tool_result` and `web_search_tool_result` blocks." }, "content": { "description": "Result content. A string or content blocks for `tool_result`; the array of `web_search_result` blocks for `web_search_tool_result`.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ] }, "is_error": { "type": "boolean", "default": false, "description": "Whether the tool execution failed. Used by `tool_result` blocks." }, "thinking": { "type": "string", "description": "Thinking content, replayed verbatim. Required when `type` is `thinking`." }, "signature": { "type": "string", "description": "Thinking signature, replayed verbatim. Required when `type` is `thinking`." }, "thought_signature": { "type": "string", "description": "Encrypted reasoning state, replayed verbatim. Required when the request ends with a `tool_result`." }, "data": { "type": "string", "description": "Encrypted thinking content, replayed verbatim. Required when `type` is `redacted_thinking`." }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } }, "MessagesMessage": { "type": "object", "required": [ "role", "content" ], "description": "A message in the conversation. Tool results are returned via a `tool_result` content block in a `user` message.", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ], "description": "The role of the message author." }, "content": { "description": "The content. A plain string or an array of content blocks.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/MessagesContentBlock" } } ] } } }, "MessagesSystemBlock": { "type": "object", "required": [ "type", "text" ], "description": "A system prompt text block.", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "The block type. Always `text`." }, "text": { "type": "string", "description": "The system prompt content." }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } }, "MessagesCustomTool": { "type": "object", "required": [ "name" ], "description": "A custom tool, executed by the caller and returned via a `tool_result` block.", "properties": { "name": { "type": "string", "description": "The tool name." }, "description": { "type": "string", "description": "A description of what the custom tool does." }, "input_schema": { "type": "object", "description": "The custom tool's parameter definition in JSON Schema format." }, "strict": { "type": "boolean", "default": false, "description": "Whether to enable strict mode for a custom tool." }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } }, "MessagesOctenBroadSearchTool": { "type": "object", "required": [ "type", "name" ], "description": "The built-in `octen_broad_search` server tool, executed by Octen.", "properties": { "type": { "type": "string", "enum": [ "octen_broad_search" ], "description": "The type of tool. Always `octen_broad_search`." }, "name": { "type": "string", "enum": [ "octen_broad_search" ], "description": "The tool name. Always `octen_broad_search`." }, "parameters": { "allOf": [ { "$ref": "#/components/schemas/OctenBroadSearchToolParameters" } ], "description": "Broad search behavior configuration. Optional." }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } }, "MessagesOctenSearchTool": { "type": "object", "required": [ "type", "name" ], "description": "The built-in `octen_search` server tool, executed by Octen.", "properties": { "type": { "type": "string", "enum": [ "octen_search" ], "description": "The type of tool. Always `octen_search`." }, "name": { "type": "string", "enum": [ "octen_search" ], "description": "The tool name. Always `octen_search`." }, "parameters": { "allOf": [ { "$ref": "#/components/schemas/OctenSearchToolParameters" } ], "description": "Search behavior configuration. Optional." }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } }, "MessagesToolDefinition": { "oneOf": [ { "$ref": "#/components/schemas/MessagesCustomTool" }, { "$ref": "#/components/schemas/MessagesOctenBroadSearchTool" }, { "$ref": "#/components/schemas/MessagesOctenSearchTool" } ], "description": "A tool definition. One of a custom tool, the built-in `octen_broad_search` tool, or the `octen_search` tool." }, "MessagesToolChoice": { "type": "object", "description": "Controls whether and how the model calls tools.", "properties": { "type": { "type": "string", "enum": [ "auto", "any", "tool", "none" ], "default": "auto", "description": "`auto`: model decides; `any`: must call a tool; `tool`: call a specific tool; `none`: no tools." }, "name": { "type": "string", "description": "The tool name to force. Required when `type` is `tool` (e.g. `octen_broad_search` or `octen_search`)." }, "disable_parallel_tool_use": { "type": "boolean", "default": false, "description": "When `true`, the model issues at most one tool call per turn." } } }, "MessagesThinking": { "type": "object", "description": "Thinking options for reasoning models.", "properties": { "type": { "type": "string", "enum": [ "enabled", "disabled", "adaptive", "between_tools" ], "description": "`adaptive` lets the model decide the thinking depth." }, "budget_tokens": { "type": "integer", "minimum": 1024, "description": "Thinking token budget. Required when `type` is `enabled`; must be less than `max_tokens`. Not allowed when `type` is `adaptive`, `disabled`, or `between_tools`." }, "display": { "type": "string", "enum": [ "summarized", "omitted" ], "default": "summarized", "description": "Controls how thinking is shown. `summarized` returns thinking blocks; `omitted` returns only the signature so blocks can be replayed. Valid only when `type` is `enabled` or `adaptive`." } } }, "MessagesRequest": { "type": "object", "required": [ "model", "max_tokens", "messages" ], "description": "Request body for the Messages API. Some parameters apply only to certain models; unsupported parameters are ignored.", "properties": { "model": { "type": "string", "enum": [ "openai/gpt-6.1-sol", "openai/gpt-6-astra", "openai/gpt-5.6-sol", "openai/gpt-5.6-terra", "openai/gpt-5.6-luna", "openai/gpt-5.4", "anthropic/claude-fable-5.1", "anthropic/claude-fable-5", "anthropic/claude-opus-5.5", "anthropic/claude-opus-5", "anthropic/claude-opus-4.8", "anthropic/claude-opus-4.6", "anthropic/claude-sonnet-5.5", "anthropic/claude-sonnet-5", "anthropic/claude-sonnet-4.6", "anthropic/claude-haiku-5.5", "anthropic/claude-haiku-4.5", "google/gemini-4-argon", "google/gemini-3.8-flash", "google/gemini-3.5-flash", "google/gemini-3.5-flash-lite", "google/gemini-3.1-pro-preview", "google/gemini-3.1-flash-lite", "google/gemini-3-flash-preview", "moonshotai/kimi-k3", "moonshotai/kimi-k2.6", "moonshotai/kimi-k2.5", "minimax/minimax-m2.5", "qwen/qwen3.6-plus", "deepseek/deepseek-v4-pro", "deepseek/deepseek-v4-flash-0731" ], "description": "The model to use. Anthropic models also accept their native ids (e.g. `claude-opus-4-8`), which map to `anthropic/claude-opus-4.8`." }, "max_tokens": { "type": "integer", "minimum": 1, "description": "Maximum number of tokens to generate, including thinking and visible output tokens." }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/MessagesMessage" }, "description": "The conversation so far, in chronological order." }, "system": { "description": "System prompt. A plain string or an array of text blocks supporting `cache_control`.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/MessagesSystemBlock" } } ] }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/MessagesToolDefinition" } }, "tool_choice": { "$ref": "#/components/schemas/MessagesToolChoice" }, "stream": { "type": "boolean", "default": false, "description": "Whether to enable streaming output." }, "temperature": { "type": "number", "minimum": 0, "maximum": 1, "default": 1.0, "description": "Controls randomness." }, "top_p": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "description": "Nucleus sampling. If unset, no nucleus truncation is applied. Set only one of `temperature` and `top_p`." }, "top_k": { "type": "integer", "minimum": 0, "description": "Sample only from the top K tokens. If unset, top-k filtering is disabled." }, "stop_sequences": { "type": "array", "items": { "type": "string" }, "description": "Stop sequences." }, "thinking": { "$ref": "#/components/schemas/MessagesThinking" }, "metadata": { "type": "object", "description": "Request metadata.", "properties": { "user_id": { "type": "string", "description": "A unique identifier for the end user. Use hashed or pseudonymous identifiers to avoid passing personally identifiable information." } } }, "output_config": { "type": "object", "description": "Controls how the model produces its output.", "properties": { "effort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ], "description": "Reasoning effort for reasoning models." }, "format": { "type": "object", "description": "Structured output. Constrains the model to return content matching a JSON Schema.", "required": [ "type", "schema" ], "properties": { "type": { "type": "string", "enum": [ "json_schema" ], "description": "The structured output type. Always `json_schema`." }, "schema": { "type": "object", "description": "The JSON Schema the output must conform to." } } } } }, "cache_control": { "type": "object", "description": "Top-level prompt caching marker. Sets a cache breakpoint on the last cacheable content block in the request, equivalent to setting `cache_control` on that block directly.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "ephemeral" ], "description": "The cache control type. Always `ephemeral`." }, "ttl": { "type": "string", "enum": [ "5m", "1h" ], "default": "5m", "description": "Cache lifetime." } } } } }, "MessagesCitation": { "type": "object", "description": "A citation into a search result. Returned only when `octen_search` was used and the text cites a result.", "properties": { "type": { "type": "string", "enum": [ "web_search_result_location" ], "description": "The citation type." }, "url": { "type": "string", "description": "The URL of the cited source." }, "title": { "type": "string", "description": "The title of the cited source." }, "cited_text": { "type": "string", "description": "The cited source snippet." }, "encrypted_index": { "type": "string", "description": "Encrypted index of the citation location. Replay verbatim when returning text blocks with citations." } } }, "MessagesWebSearchResult": { "type": "object", "description": "A single search result block.", "properties": { "type": { "type": "string", "enum": [ "web_search_result" ], "description": "The block type." }, "title": { "type": "string", "description": "The title of the result page." }, "url": { "type": "string", "description": "The URL of the result page." }, "highlights": { "type": "string", "description": "Query-relevant highlight snippets. Returned only if `highlight.enable` is true." }, "full_content": { "type": "string", "description": "Full raw page content. Returned only if `full_content.enable` is true." }, "authors": { "type": "string", "description": "Website name or author." }, "time_published": { "type": "string", "format": "date-time", "description": "Publish time in ISO 8601." }, "time_last_crawled": { "type": "string", "format": "date-time", "description": "Last crawl time in ISO 8601." } } }, "MessagesResponseContentBlock": { "type": "object", "description": "A content block in the response. The fields present depend on `type`.", "properties": { "type": { "type": "string", "enum": [ "text", "thinking", "redacted_thinking", "tool_use", "server_tool_use", "web_search_tool_result" ], "description": "The type of content block." }, "text": { "type": "string", "description": "The assistant's text content. Present when `type` is `text`." }, "citations": { "type": "array", "items": { "$ref": "#/components/schemas/MessagesCitation" }, "description": "Citation annotations for this text block. Present only when `octen_broad_search` or `octen_search` was used." }, "thinking": { "type": "string", "description": "Reasoning content. Present when `type` is `thinking`." }, "signature": { "type": "string", "description": "Signature of the thinking block. Replay verbatim in multi-turn conversations." }, "thought_signature": { "type": "string", "description": "Encrypted reasoning state of the `tool_use` block. Replay verbatim in multi-turn conversations." }, "data": { "type": "string", "description": "Encrypted thinking content. Present when `type` is `redacted_thinking`." }, "id": { "type": "string", "description": "Block id. Present for `tool_use` and `server_tool_use` blocks." }, "name": { "type": "string", "description": "Tool name. Present for `tool_use` and `server_tool_use` blocks." }, "input": { "type": "object", "description": "Tool call arguments. For `server_tool_use`, contains the auto-generated `query`." }, "tool_use_id": { "type": "string", "description": "The id of the matching `server_tool_use` block. Present for `web_search_tool_result` blocks." }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/MessagesWebSearchResult" }, "description": "Search results. Present for `web_search_tool_result` blocks." } } }, "MessagesUsage": { "type": "object", "required": [ "input_tokens", "output_tokens" ], "description": "Token usage information.", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens." }, "output_tokens": { "type": "integer", "description": "Number of output tokens (thinking tokens are included)." }, "cache_creation_input_tokens": { "type": "integer", "description": "Tokens written to the prompt cache. Returned only when `cache_control` was used and the model supports caching." }, "cache_read_input_tokens": { "type": "integer", "description": "Tokens read from the prompt cache. Returned only when `cache_control` was used and the model supports caching." }, "cache_creation": { "type": "object", "description": "Cache writes broken down by cache lifetime (a breakdown of `cache_creation_input_tokens`). Returned only when this call wrote to the cache.", "properties": { "ephemeral_5m_input_tokens": { "type": "integer", "description": "Tokens written to the 5-minute cache." }, "ephemeral_1h_input_tokens": { "type": "integer", "description": "Tokens written to the 1-hour cache." } } }, "output_tokens_details": { "type": "object", "description": "Breakdown of output tokens. Returned only for reasoning models.", "properties": { "thinking_tokens": { "type": "integer", "description": "Number of thinking tokens (already included in `output_tokens`)." } } }, "server_tool_use": { "type": "object", "description": "Built-in tool usage. Returned only when a built-in tool was used.", "properties": { "web_search_requests": { "type": "integer", "description": "Number of searches executed, used for search billing." } } }, "full_content_extra_count": { "type": "integer", "description": "Billable full_content results beyond the free allowance. Returned only when `full_content` is enabled." } } }, "MessagesResponse": { "type": "object", "required": [ "id", "type", "role", "model", "content", "stop_reason", "usage" ], "description": "A non-streaming response. Returned when `stream=false`.", "properties": { "id": { "type": "string", "description": "The unique identifier for this request." }, "type": { "type": "string", "enum": [ "message", "error" ], "description": "The response type. `message` on success." }, "role": { "type": "string", "enum": [ "assistant" ], "description": "Always `assistant`." }, "model": { "type": "string", "description": "The model used for this response." }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/MessagesResponseContentBlock" }, "description": "The response content, as a list of content blocks." }, "stop_reason": { "type": "string", "enum": [ "end_turn", "max_tokens", "stop_sequence", "tool_use", "pause_turn", "refusal" ], "description": "Why the model stopped." }, "stop_details": { "type": "object", "description": "Additional detail about why the model stopped. Returned only when `stop_reason` is `refusal`.", "properties": { "type": { "type": "string", "enum": [ "refusal" ], "description": "The stop detail type. Always `refusal`." }, "explanation": { "type": "string", "description": "An explanation of why the request was refused." } } }, "stop_sequence": { "type": "string", "nullable": true, "description": "The stop sequence that was hit, or `null`." }, "usage": { "$ref": "#/components/schemas/MessagesUsage" } } }, "MessagesStreamEvent": { "type": "object", "required": [ "type" ], "description": "A streaming SSE event. Returned when `stream=true`. Events arrive in order: `message_start` → `content_block_start`/`content_block_delta`/`content_block_stop` → `message_delta` → `message_stop`. `ping` may appear anywhere and can be ignored. On error, an `error` event is sent.", "properties": { "type": { "type": "string", "enum": [ "message_start", "content_block_start", "content_block_delta", "content_block_stop", "message_delta", "message_stop", "ping", "error" ], "description": "The event type." }, "message": { "type": "object", "description": "Present in `message_start`. The initial message (id, model, role, initial usage)." }, "index": { "type": "integer", "description": "Present in `content_block_*`. The content block index; concatenate deltas by index." }, "content_block": { "type": "object", "description": "Present in `content_block_start`. The block that is starting. For built-in search, the `web_search_tool_result` block carries the full results here." }, "delta": { "type": "object", "description": "Present in `content_block_delta` (`text_delta` / `thinking_delta` / `signature_delta` / `input_json_delta`) and `message_delta` (`stop_reason`, `stop_details`, `stop_sequence`)." }, "usage": { "type": "object", "description": "Present in `message_delta`. Cumulative token counts (not incremental)." }, "error": { "type": "object", "description": "Present in `error` events." } } }, "ImageGenerationBaseRequest": { "type": "object", "required": [ "model", "prompt" ], "description": "Shared parameters for the Image Generation API. Text-to-image when no image is provided; image editing when an image is provided. Parameters marked (GPT only) or (Gemini only) apply only to those model families; unsupported parameters are ignored.", "properties": { "model": { "type": "string", "enum": [ "openai/gpt-image-2.5-flare", "openai/gpt-image-2.5-sunburst", "openai/gpt-image-2", "openai/gpt-image-1-mini", "google/gemini-3-pro-image", "google/gemini-3.1-flash-image" ], "description": "The model to use. Aliases `nano-banana-pro` (= `google/gemini-3-pro-image`) and `nano-banana-2` (= `google/gemini-3.1-flash-image`) are also accepted." }, "prompt": { "type": "string", "description": "The text description for the model. The length limit is set by the model." }, "n": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "description": "(GPT only) Number of images to generate. For Gemini, request multiple images in the `prompt` instead." }, "size": { "type": "string", "default": "auto", "description": "Output size as `width x height` (e.g. `1024x1024`) or `auto`." }, "quality": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max", "auto" ], "default": "auto", "description": "(GPT only) Generation quality." }, "background": { "type": "string", "enum": [ "transparent", "opaque", "auto" ], "default": "auto", "description": "(GPT only) Background setting." }, "output_format": { "type": "string", "enum": [ "png", "jpeg", "webp" ], "default": "png", "description": "Output image format. GPT supports png/jpeg/webp; Gemini supports png/jpeg (webp falls back to png)." }, "output_compression": { "type": "integer", "minimum": 0, "maximum": 100, "default": 100, "description": "(GPT only) Compression level (percent). Effective only when `output_format` is jpeg or webp." }, "moderation": { "type": "string", "enum": [ "low", "auto" ], "default": "auto", "description": "(GPT only) Content moderation strength." }, "thinking_level": { "type": "string", "enum": [ "minimal", "high" ], "default": "minimal", "description": "(Gemini only) Thinking effort before generation." }, "response_modalities": { "type": "array", "items": { "type": "string", "enum": [ "text", "image" ] }, "default": [ "text", "image" ], "description": "(Gemini only) Controls returned modalities. `[\"text\",\"image\"]` returns the image plus accompanying text; `[\"image\"]` returns only the image." }, "media_resolution": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "(Gemini only) Processing resolution for input reference images." }, "response_format": { "type": "string", "enum": [ "b64_json" ], "default": "b64_json", "description": "Return format." }, "stream": { "type": "boolean", "default": false, "description": "(GPT only) Whether to stream the response." }, "partial_images": { "type": "integer", "minimum": 0, "maximum": 3, "default": 0, "description": "(GPT only) Number of intermediate preview images to stream. Effective only when `stream=true`. Each preview costs an extra 100 image output tokens." }, "user": { "type": "string", "description": "A unique identifier for the end user. Use hashed or pseudonymous identifiers to avoid passing personally identifiable information." } } }, "ImageGenerationRequest": { "description": "JSON request body for the Image Generation API.", "allOf": [ { "$ref": "#/components/schemas/ImageGenerationBaseRequest" }, { "type": "object", "properties": { "image": { "description": "Reference/source image(s) for editing, a data URL prefix or a raw base64 string. Providing an image enters edit mode. An array passes multiple reference images.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "mask": { "type": "string", "description": "(GPT only) Mask image, base64-encoded PNG matching the input size. Transparent areas are repainted. Effective only when `image` is provided." } } } ] }, "ImagePart": { "type": "object", "description": "An ordered content part preserving the original text/image interleaving.", "properties": { "type": { "type": "string", "enum": [ "text", "image" ], "description": "The part type." }, "text": { "type": "string", "description": "Text content. Present when `type` is `text`." }, "index": { "type": "integer", "description": "Index into the `data` array. Present when `type` is `image`; read the image bytes from `data[index].b64_json`." } } }, "ImageUsage": { "type": "object", "required": [ "input_tokens", "output_tokens", "total_tokens" ], "description": "Token usage information.", "properties": { "input_tokens": { "type": "integer", "description": "Input tokens (text prompt + input image tokens)." }, "input_tokens_details": { "type": "object", "properties": { "text_tokens": { "type": "integer", "description": "Text tokens of the prompt." }, "image_tokens": { "type": "integer", "description": "Tokens of the input images." } } }, "output_tokens": { "type": "integer", "description": "Output tokens (generated image tokens + reasoning text tokens)." }, "output_tokens_details": { "type": "object", "properties": { "text_tokens": { "type": "integer", "description": "Output tokens used by reasoning text." }, "image_tokens": { "type": "integer", "description": "Tokens of the generated images." } } }, "total_tokens": { "type": "integer", "description": "Total tokens (input_tokens + output_tokens)." } } }, "ImageGenerationResponse": { "type": "object", "required": [ "id", "created", "data", "usage" ], "description": "A non-streaming image response. Images are always returned as base64.", "properties": { "id": { "type": "string", "description": "The unique identifier for this request." }, "created": { "type": "integer", "description": "Unix timestamp (in seconds) of when the request was created." }, "background": { "type": "string", "enum": [ "transparent", "opaque" ], "description": "(GPT only) The background setting actually applied." }, "output_format": { "type": "string", "enum": [ "png", "jpeg", "webp" ], "description": "The output format actually applied; for Gemini, derived from the mimeType." }, "quality": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ], "description": "(GPT only) The quality tier actually applied." }, "size": { "type": "string", "description": "(GPT only) The output size actually applied; useful when `size` was `auto`." }, "data": { "type": "array", "items": { "type": "object", "properties": { "b64_json": { "type": "string", "description": "Base64-encoded image content." } } }, "description": "The generated images, one element per image." }, "text": { "type": "string", "description": "(Gemini only) Plain-text summary of text the model produced alongside the image. For exact interleaving, read `parts`." }, "parts": { "type": "array", "items": { "$ref": "#/components/schemas/ImagePart" }, "description": "(Gemini only) Content parts in the model's original order, preserving text/image interleaving." }, "usage": { "$ref": "#/components/schemas/ImageUsage" } } }, "ImageGenerationStreamEvent": { "type": "object", "required": [ "id", "type", "b64_json" ], "description": "A streaming SSE event. Partial preview images arrive first (each with `partial_image_index`), then one `completed` event with `usage`. The event type prefix is `image_generation` for text-to-image and `image_edit` for editing.", "properties": { "id": { "type": "string", "description": "Request identifier. Identical across all events of one request." }, "type": { "type": "string", "enum": [ "image_generation.partial_image", "image_generation.completed", "image_edit.partial_image", "image_edit.completed" ], "description": "The event type." }, "b64_json": { "type": "string", "description": "Base64 image for this event: the current preview for `partial_image`, the final image for `completed`." }, "created_at": { "type": "integer", "description": "Unix timestamp when the event was generated." }, "size": { "type": "string", "description": "(GPT only) The output size actually applied; useful when `size` was `auto`." }, "quality": { "type": "string", "enum": ["low", "medium", "high", "xhigh", "max"], "description": "(GPT only) The quality tier actually applied." }, "background": { "type": "string", "enum": ["transparent", "opaque"], "description": "(GPT only) The background setting actually applied." }, "output_format": { "type": "string", "enum": ["png", "jpeg", "webp"], "description": "The output format actually applied; for Gemini, derived from the mimeType." }, "partial_image_index": { "type": "integer", "description": "Present only in `partial_image` events. Preview index, starting at 0." }, "usage": { "allOf": [ { "$ref": "#/components/schemas/ImageUsage" } ], "description": "Present only in `completed` events. Same structure as the non-streaming `usage`." } } }, "ImageGenerationFormRequest": { "description": "Multipart form for the Image Generation API. Same fields as the JSON body, except image inputs are uploaded as files.", "allOf": [ { "$ref": "#/components/schemas/ImageGenerationBaseRequest" }, { "type": "object", "properties": { "image": { "type": "string", "format": "binary", "description": "Reference/source image file. Providing an image enters edit mode. For multiple reference images, use the `image[]` field instead." }, "image[]": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Multiple reference image files, combined by the model. Per-model limits apply." }, "mask": { "type": "string", "format": "binary", "description": "(GPT only) Mask image file (PNG matching the input size). Transparent areas are repainted. Effective only when an image is provided." } } } ] }, "VideoGenerationRequest": { "type": "object", "required": [ "model", "prompt" ], "description": "JSON request body for the Video Generation API.", "properties": { "model": { "type": "string", "enum": [ "minimax/minimax-h3", "bytedance/seedance-2.5", "google/veo-3.1", "google/veo-3.1-fast", "google/veo-3.1-lite" ], "description": "The model to use." }, "prompt": { "type": "string", "description": "The text description of the video." }, "duration": { "type": "integer", "description": "Video length in seconds. When omitted, the model default applies." }, "resolution": { "type": "string", "enum": [ "480p", "720p", "768p", "1080p", "2K" ], "description": "Output resolution. When omitted, the model default applies." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "adaptive" ], "description": "Aspect ratio. `adaptive` lets the model follow the input. When omitted, the model default applies." }, "frame_images": { "type": "array", "items": { "$ref": "#/components/schemas/VideoFrameImage" }, "description": "Images to use as the first and last frames of the video." }, "input_references": { "type": "array", "items": { "$ref": "#/components/schemas/VideoInputReference" }, "description": "Reference images that guide generation without locking specific frames." }, "generate_audio": { "type": "boolean", "default": true, "description": "Whether to generate audio along with the video." }, "seed": { "type": "integer", "description": "Random seed, for more reproducible results." }, "extra_params": { "type": "object", "additionalProperties": true, "description": "Vendor-specific parameters, passed through to the upstream model without validation. Keys that duplicate a unified parameter, or that control upstream storage, notification, sample count, or platform behavior, are rejected." } } }, "VideoFrameImage": { "type": "object", "required": [ "image", "frame_type" ], "properties": { "image": { "type": "string", "description": "Image URL or base64 data." }, "frame_type": { "type": "string", "enum": [ "first_frame", "last_frame" ], "description": "Whether the image is the first or the last frame." } } }, "VideoInputReference": { "type": "object", "required": [ "image" ], "properties": { "image": { "type": "string", "description": "Image URL or base64 data." } } }, "VideoUsage": { "type": "object", "description": "Metering for the task. Present only when `status` is `completed`.", "properties": { "video_seconds": { "type": "integer", "description": "Video length in seconds." }, "video_tokens": { "type": "integer", "description": "Billed token count." }, "input_image_count": { "type": "integer", "description": "Number of input images, returned when images were supplied." } } }, "VideoGenerationResponse": { "type": "object", "required": [ "id", "model", "status", "created" ], "properties": { "id": { "type": "string", "description": "Unique task id, used to download the video." }, "model": { "type": "string", "description": "The model used for this task." }, "status": { "type": "string", "enum": [ "queued" ], "description": "Task state." }, "created": { "type": "integer", "description": "Unix timestamp in seconds when the task was created." } } }, "VideoTask": { "type": "object", "required": [ "id", "model", "status", "created" ], "properties": { "id": { "type": "string", "description": "Unique task id, used to download the video." }, "model": { "type": "string", "description": "The model used for this task." }, "status": { "type": "string", "enum": [ "queued", "in_progress", "completed", "failed" ], "description": "Task state." }, "created": { "type": "integer", "description": "Unix timestamp in seconds when the task was created." }, "video_url": { "type": "string", "description": "Signed download URL for the video file, present when `status` is `completed`. Valid for 7 days after generation." }, "expires_at": { "type": "integer", "description": "Unix timestamp in seconds when `video_url` expires. Present when `status` is `completed`." }, "duration": { "type": "integer", "description": "Length of the generated video in seconds. Present when `status` is `completed`." }, "resolution": { "type": "string", "description": "Resolution of the generated video. Present when `status` is `completed`." }, "usage": { "$ref": "#/components/schemas/VideoUsage" }, "error": { "type": "string", "description": "Failure reason, present when `status` is `failed`." }, "code": { "type": "string", "description": "Machine-readable failure code, present when `status` is `failed`." } } }, "GroundedGenerationRequest": { "type": "object", "required": [ "modality", "prompt" ], "description": "Request body for the Grounded Generation API.", "properties": { "modality": { "type": "string", "enum": [ "image", "video" ], "description": "The type of output to generate." }, "prompt": { "type": "string", "minLength": 1, "maxLength": 8000, "description": "The text description of what to generate." }, "model": { "type": "string", "enum": [ "google/gemini-3-pro-image", "google/gemini-3.1-flash-image", "minimax/hailuo-3" ], "description": "The model to use. When omitted, the model default applies." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "1:1", "9:16" ], "default": "16:9", "description": "Aspect ratio of the output." }, "duration": { "type": "integer", "default": 5, "minimum": 5, "maximum": 10, "description": "Video length in seconds. Applies when `modality` is `video`. Values outside the allowed range are adjusted to the nearest bound." } } }, "GroundedGenerationResponse": { "type": "object", "required": [ "generation_id", "modality", "status", "created_at" ], "properties": { "request_id": { "type": "string", "description": "Unique identifier for the request." }, "generation_id": { "type": "string", "description": "Unique task id, used to retrieve the result." }, "modality": { "type": "string", "enum": [ "image", "video" ], "description": "The type of output this task generates." }, "status": { "type": "string", "enum": [ "queued" ], "description": "Task state." }, "created_at": { "type": "integer", "description": "Unix timestamp in seconds when the task was created." } } }, "GroundedGenerationTask": { "type": "object", "required": [ "generation_id", "modality", "status", "created_at", "updated_at" ], "properties": { "request_id": { "type": "string", "description": "Unique identifier for the request." }, "generation_id": { "type": "string", "description": "Unique task id." }, "modality": { "type": "string", "enum": [ "image", "video" ], "description": "The type of output this task generates." }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed" ], "description": "Task state." }, "output_url": { "type": "string", "description": "Signed download URL for the output, present when `status` is `succeeded`. Requires no API key, and is valid for 7 days after the task was created." }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/GroundedGenerationReference" }, "description": "The reference material used to generate the output." }, "search_results": { "type": "array", "items": { "$ref": "#/components/schemas/GroundedGenerationSearchGroup" }, "description": "The search results the references were selected from, grouped by query." }, "error": { "$ref": "#/components/schemas/GroundedGenerationError" }, "created_at": { "type": "integer", "description": "Unix timestamp in seconds when the task was created." }, "updated_at": { "type": "integer", "description": "Unix timestamp in seconds when the task was last updated." }, "usage": { "$ref": "#/components/schemas/GroundedGenerationUsage" } } }, "GroundedGenerationReference": { "type": "object", "description": "A single piece of reference material.", "properties": { "source_id": { "type": "string", "description": "Identifier of the reference, such as `source1`." }, "url": { "type": "string", "description": "The media URL." }, "title": { "type": "string", "description": "The title of the reference." }, "cover_url": { "type": "string", "description": "Thumbnail URL." } } }, "GroundedGenerationSearchGroup": { "type": "object", "description": "The results for one search query.", "properties": { "query": { "type": "string", "description": "The query the task searched for." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/GroundedGenerationSearchResult" }, "description": "Results for this query." } } }, "GroundedGenerationSearchResult": { "type": "object", "description": "A single search result.", "properties": { "type": { "type": "string", "enum": [ "image", "video" ], "description": "Media type of the result." }, "title": { "type": "string", "description": "The title of the result." }, "url": { "type": "string", "description": "The media URL." }, "source_page": { "type": "string", "description": "URL of the original page hosting the media." }, "description": { "type": "string", "description": "Description of the result." }, "cover_url": { "type": "string", "description": "Thumbnail URL." } } }, "GroundedGenerationError": { "type": "object", "description": "Failure reason, present when `status` is `failed`. Failed tasks are not billed.", "properties": { "code": { "type": "string", "enum": [ "MM_GENERATION_CONTENT_POLICY", "MM_GENERATION_INPUT_IMAGE_PRIVACY_BLOCKED", "MM_GENERATION_CONTENT_NOT_SUPPORTED", "MM_GENERATION_NO_REFERENCE_MATERIAL", "MM_GENERATION_REJECTED", "MM_GENERATION_TIMEOUT", "MM_GENERATION_FAILED" ], "description": "Machine-readable failure code. `MM_GENERATION_CONTENT_POLICY`: the prompt triggered a content policy; `MM_GENERATION_INPUT_IMAGE_PRIVACY_BLOCKED`: the reference material was blocked for privacy; `MM_GENERATION_CONTENT_NOT_SUPPORTED`: the content is not supported; `MM_GENERATION_NO_REFERENCE_MATERIAL`: no usable reference material was found; `MM_GENERATION_REJECTED`: the model rejected the request; `MM_GENERATION_TIMEOUT`: generation timed out, retry; `MM_GENERATION_FAILED`: generation failed for another reason, retry." }, "message": { "type": "string", "description": "A message describing the failure." } } }, "GroundedGenerationUsage": { "type": "object", "description": "Metering for the task. Present only when `status` is `succeeded`.", "properties": { "image_count": { "type": "integer", "description": "Number of images generated. Returned when `modality` is `image`." }, "video_count": { "type": "integer", "description": "Number of videos generated. Returned when `modality` is `video`." }, "video_seconds": { "type": "integer", "description": "Length of the generated video in seconds. Returned when `modality` is `video`." } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer token used for request authentication. Alternatively, you can send the API key in the `x-api-key` header. Note: A payment method is required to use the API." }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key used for request authentication. Alternatively, you can send the key as a Bearer token in the `Authorization` header. Note: A payment method is required to use the API." }, "bearerAuthNoPayment": { "type": "http", "scheme": "bearer", "description": "Bearer token used for request authentication. Alternatively, you can send the API key in the `x-api-key` header." }, "apiKeyAuthNoPayment": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key used for request authentication. Alternatively, you can send the key as a Bearer token in the `Authorization` header." } } } }