> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Install and use the Octen Python SDK

<CardGroup cols={2}>
  <Card title="Get API Key" icon="key" href="https://octen.ai/platform/api-keys">
    Get your API key from the API Platform
  </Card>

  <Card title="PyPI" icon="python" href="https://pypi.org/project/octen/">
    Download and view the SDK on PyPI
  </Card>
</CardGroup>

## Install

<CodeGroup>
  ```bash pip theme={null}
  pip install octen
  ```
</CodeGroup>

Requires Python 3.8+

## Quick Start

```python theme={null}
from octen import Octen

client = Octen(api_key="your-api-key") # or set OCTEN_API_KEY env var
```

## Broad Search

Decompose a query into sub-queries, search them concurrently, and get results grouped per sub-query. Best for comparisons, surveys, and multi-angle questions.

```python theme={null}
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
```

## Web Search

Search the live web and get ranked results with highlights and optional full content. Best for search bars, answer engines, and news lookup.

```python theme={null}
results = client.search.search(
    query="blog post about artificial intelligence",
    count=10,
    time_range="week",
    include_domains=["techcrunch.com", "wired.com"],
)
```

## Image Search

*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.

```python theme={null}
results = client.image_search.search(
    query="golden retriever puppy",
    topic="general",  # "general" or "design"
    count=5,
)
```

## Video Search

*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.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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

```python theme={null}
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.