Skip to main content

Get API Key

Get your API key from the API Platform

PyPI

Download and view the SDK on PyPI

​
Install

pip install octen
Requires Python 3.8+

​
Quick Start

from octen import Octen

client = Octen(api_key="your-api-key") # or set OCTEN_API_KEY env var
Decompose a query into sub-queries, search them concurrently, and get results grouped per sub-query. Best for comparisons, surveys, and multi-angle questions. 
response = client.search.broad_search(
    query="compare cloud GPU pricing across providers",
    max_queries=5,  # up to N sub-queries (1-30, default 5)
)
# response.queries -> sub-queries; response.search_results -> grouped results
Search the live web and get ranked results with highlights and optional full content. Best for search bars, answer engines, and news lookup. 
results = client.search.search(
    query="blog post about artificial intelligence",
    count=10,
    time_range="week",
    include_domains=["techcrunch.com", "wired.com"],
)
In beta — contact us for beta access. Search images by text query and/or a reference image; set topic="design" for UI design references. Best for image lookup, visual references, and design assets. 
results = client.image_search.search(
    query="golden retriever puppy",
    topic="general",  # "general" or "design"
    count=5,
)
In beta — contact us for beta access. Search the web for videos by text query, with the timestamped segment matching each result. Best for video lookup, clip discovery, and media previews. 
results = client.video_search.search(
    query="how to make fresh pasta",
    count=5,
)

​
Extract

Fetch 1-20 URLs in one call and return clean markdown or text. Best for reading pages, cleaning articles, and knowledge ingestion. 
response = client.extract.extract(
    urls=["https://docs.octen.ai/api-reference/search", "https://octen.ai"],
    format="markdown",
)

for item in response.items:
    if item.status == "success":
        print(item.title, item.full_content[:200])
    else:
        print(f"[FAIL] {item.url}: {item.error_message}")

​
Model

Send messages to leading LLMs through one API, with optional web search via an OctenSearchTool in tools. Best for Q&A, chat assistants, and grounded answers. 
from octen import ChatMessage, OctenSearchTool

response = client.chat.create(
    model="openai/gpt-5.4",
    messages=[ChatMessage(role="user", content="What happened in tech today?")],
    tools=[OctenSearchTool()],  # enable live web search
)
print(response.text)
print(response.search_results)

​
Embedding

Create text embeddings with models of different sizes. Best for semantic search, RAG, and recommendations. 
response = client.embedding.create(
    input=["first document", "second document"],
    model="octen-embedding-8b",
    input_type="document",
)
vectors = response.get_embeddings()

​
VL Embedding

Create multimodal embeddings from text, images, and videos. Best for cross-modal search and visual retrieval. 
response = client.vl_embedding.create(
    model="octen-vl-embedding-large",
    contents=[
        {"text": "A cute orange cat on a wooden chair"},
        {"image": "https://example.com/cat.jpg"},
    ],
    enable_fusion=True,
)
vector = response.get_first_embedding()

​
Async

Use AsyncOcten for async operations. Every resource mirrors the sync client. 
import asyncio
from octen import AsyncOcten

async def main():
    async with AsyncOcten(api_key="your-api-key") as client:
        results = await client.search.search(query="machine learning startups", count=10)

asyncio.run(main())

​
Error Handling

from octen import (
    OctenAuthenticationError,
    OctenRateLimitError,
    OctenTimeoutError,
    OctenConnectionError,
    OctenStreamError,
    OctenAPIError,
)

try:
    results = client.search.search("query")
except OctenAuthenticationError:
    print("Invalid API key")
except OctenRateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except OctenTimeoutError:
    print("Request timed out")
except OctenConnectionError:
    print("Network connection failed")
except OctenStreamError as e:
    print(f"Stream error: {e.message} (code: {e.code})")
except OctenAPIError as e:
    print(f"API error: {e.status_code} - {e.message}")
Requests that fail due to timeouts, rate limits, or server errors (5xx) are automatically retried with exponential backoff.