### Install and Start LiteLLM Proxy

Source: https://docs.thesean.ai/integrations/litellm

Install the proxy tool and launch the server using the configuration file.

```bash
uv tool install "litellm[proxy]"
litellm --config config.yaml
```

--------------------------------

### Install OpenCode

Source: https://docs.thesean.ai/integrations/opencode

Use the curl command to install OpenCode on your system.

```bash
curl -fsSL https://opencode.ai/install | bash
```

--------------------------------

### Install LiteLLM SDK

Source: https://docs.thesean.ai/integrations/litellm

Install the LiteLLM package using uv.

```bash
uv add litellm
```

--------------------------------

### Install Anthropic SDK

Source: https://docs.thesean.ai/integrations/anthropic-sdk

Install the required package using uv.

```bash
uv add anthropic
```

--------------------------------

### Start OpenCode

Source: https://docs.thesean.ai/integrations/opencode

Navigate to the project directory and launch the OpenCode application.

```bash
cd your-project
opencode
```

--------------------------------

### Install Codex CLI

Source: https://docs.thesean.ai/integrations/codex

Install the Codex CLI globally using npm.

```bash
npm install -g @openai/codex
```

--------------------------------

### Chat Completions Request Example

Source: https://docs.thesean.ai/api-reference/endpoints

Example request for the chat completions endpoint using cURL.

```bash
curl https://api.thesean.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $THESEAN_API_KEY" \
  -d '{
    "model": "ship-like/claude-opus-4-8",
    "messages": [
      {
        "role": "user",
        "content": "Explain the importance of biodiversity."
      }
    ]
  }'
```

--------------------------------

### Start Codex with Profile

Source: https://docs.thesean.ai/integrations/codex

Launch the Codex CLI using a specific model profile.

```bash
cd your-project
codex --profile ship-gpt
```

--------------------------------

### List Models Request

Source: https://docs.thesean.ai/api-reference/endpoints

Example request to retrieve the list of models using an API key.

```bash
curl https://api.thesean.ai/v1/models \
  -H "Authorization: Bearer $THESEAN_API_KEY"
```

--------------------------------

### Install Claude Code via cURL

Source: https://docs.thesean.ai/integrations/claude-code

Use this command to install Claude Code on your system.

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

--------------------------------

### First Request Response Metadata

Source: https://docs.thesean.ai/api-reference/advanced

Example JSON response showing successful cache creation via cache_creation_input_tokens.

```json
{
  "id": "msg_XXXxXxXXxXxxXX",
  "type": "message",
  "role": "assistant",
  "model": "ship-like/claude-opus-4-8",
  "content": [
    {
      "type": "text",
      "text": "According to the information provided, Jupiter is the largest planet in our solar system..."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 27,
    "cache_creation_input_tokens": 1279,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 1279,
      "ephemeral_1h_input_tokens": 0
    },
    "output_tokens": 45,
    "service_tier": "standard"
  }
}
```

--------------------------------

### GPT Model Inference

Source: https://docs.thesean.ai/api-reference/models

Example of how to invoke the GPT model using the OpenAI-compatible client.

```APIDOC
## GPT Model Inference

### Description
Invoke the `ship-like/gpt-5.6-sol` model using the OpenAI-compatible SDK.

### Usage
```python
import openai

client = openai.OpenAI(
    base_url="https://api.thesean.ai/v1",
    api_key=THESEAN_API_KEY,
)

response = client.responses.create(
    model="ship-like/gpt-5.6-sol",
    input="Hello!",
)

print(response.output_text)
```
```

--------------------------------

### Request a Response via cURL

Source: https://docs.thesean.ai/api-reference/endpoints

Example request for the responses endpoint using cURL.

```bash
curl https://api.thesean.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $THESEAN_API_KEY" \
  -d '{
    "model": "ship-like/gpt-5.6-sol",
    "input": "Explain the importance of biodiversity."
  }'
```

--------------------------------

### Verify Thesean API Setup

Source: https://docs.thesean.ai/integrations/claude-code

Use this curl command to confirm your credentials and model access by sending a direct request to the Thesean messages endpoint.

```bash
curl https://api.thesean.ai/v1/messages \
  -H "Authorization: Bearer sk-your-thesean-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ship-like/claude-sonnet-5",
    "max_tokens": 16,
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

--------------------------------

### Request a Message via cURL

Source: https://docs.thesean.ai/api-reference/endpoints

Example request for the messages endpoint using cURL.

```bash
curl https://api.thesean.ai/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $THESEAN_API_KEY" \
  -d '{
    "model": "ship-like/claude-opus-4-8",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Explain the importance of biodiversity."
      }
    ]
  }'
```

--------------------------------

### Claude Model Inference

Source: https://docs.thesean.ai/api-reference/models

Example of how to invoke the Claude model using the Anthropic-compatible client.

```APIDOC
## Claude Model Inference

### Description
Invoke the `ship-like/claude-opus-4-8` model using the Anthropic-compatible SDK.

### Usage
```python
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.thesean.ai",
    api_key=THESEAN_API_KEY,
)

message = client.messages.create(
    model="ship-like/claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)

print(message.content[0].text)
```
```

--------------------------------

### Second Request Response Metadata

Source: https://docs.thesean.ai/api-reference/advanced

Example JSON response showing successful cache reuse via cache_read_input_tokens.

```json
{
  "id": "msg_YYYyYyYYyYyyYY",
  "type": "message",
  "role": "assistant",
  "model": "ship-like/claude-opus-4-8",
  "content": [
    {
      "type": "text",
      "text": "Mercury is the planet closest to the Sun, orbiting at an average distance of..."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 21,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 1279,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 0,
      "ephemeral_1h_input_tokens": 0
    },
    "output_tokens": 42,
    "service_tier": "standard"
  }
}
```

--------------------------------

### GET /v1/models

Source: https://docs.thesean.ai/api-reference/endpoints

Retrieves a list of the two Ship models supported by Thesean.

```APIDOC
## GET /v1/models

### Description
The /v1/models endpoint returns the two Ship models supported by Thesean.

### Method
GET

### Endpoint
https://api.thesean.ai/v1/models

### Parameters
This endpoint accepts no parameters.

### Request Example
curl https://api.thesean.ai/v1/models \
  -H "Authorization: Bearer $THESEAN_API_KEY"

### Response
#### Success Response (200)
- **data** (array) - A list containing the supported ship models.

#### Response Example
{
  "data": [
    {
      "id": "ship-like/gpt-5.6-sol"
    },
    {
      "id": "ship-like/claude-opus-4-8"
    }
  ]
}
```

--------------------------------

### Submit Feedback Request

Source: https://docs.thesean.ai/ship/feedback

Example cURL request to submit feedback for a single inference ID.

```bash
curl https://api.thesean.ai/v1/feedback \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $THESEAN_API_KEY" \
  -d '[
    {
      "id": "019503a1-b2c3-7d4e-8f01-234567890abc",
      "feedback": {
        "helpful": true,
        "rating": 4.5
      },
      "optimize": "max"
    }
  ]'
```

--------------------------------

### Submit Mixed Feedback Types

Source: https://docs.thesean.ai/ship/feedback

Example of submitting various feedback types including boolean, numeric, string, and structured objects via the API.

```bash
curl https://api.thesean.ai/v1/feedback \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $THESEAN_API_KEY" \
  -d '[
    {
      "id": "019503a2-d4e5-7f60-a1b2-c3d4e5f60718",
      "feedback": {
        "thumbs_up": true,
        "relevance": 0.92,
        "comment": "Answered the question clearly",
        "accuracy": {
          "score": 4,
          "reason": "Correct but could include more detail"
        }
      },
      "tags": {
        "evaluator": "human",
        "task": "question-answering"
      }
    }
  ]'
```

--------------------------------

### Submit Multiple Feedback Events

Source: https://docs.thesean.ai/ship/feedback

Example cURL request to submit feedback for multiple inference IDs in one batch.

```bash
curl https://api.thesean.ai/v1/feedback \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $THESEAN_API_KEY" \
  -d '[
    {
      "id": "019503a1-b2c3-7d4e-8f01-234567890abc",
      "feedback": { "helpful": true }
    },
    {
      "id": "019503a2-d4e5-7f60-a1b2-c3d4e5f60718",
      "feedback": { "quality": 4.5 },
      "optimize": "max"
    }
  ]'
```

--------------------------------

### Feedback API Partial Failure Response

Source: https://docs.thesean.ai/ship/feedback

Example showing how individual failures are reported within a batch request.

```json
[
  {
    "feedback_ids": { "helpful": "019503a1-b2c3-7d4e-8f01-234567890abc" },
    "error": null
  },
  {
    "feedback_ids": null,
    "error": { "status_code": 400, "message": "ID does not exist" }
  }
]
```

--------------------------------

### POST /v1/messages

Source: https://docs.thesean.ai/api-reference/authentication

Example of authenticating a request to the messages endpoint using a Bearer token.

```APIDOC
## POST /v1/messages

### Description
Sends a message to the specified model.

### Method
POST

### Endpoint
https://api.thesean.ai/v1/messages

### Request Body
- **model** (string) - Required - The model identifier (e.g., "ship-like/claude-opus-4-8")
- **max_tokens** (integer) - Required - The maximum number of tokens to generate
- **messages** (array) - Required - A list of message objects with role and content

### Request Example
{
  "model": "ship-like/claude-opus-4-8",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Hello, world!"
    }
  ]
}
```

--------------------------------

### Feedback API Success Response

Source: https://docs.thesean.ai/ship/feedback

Example of a successful response containing feedback IDs for submitted keys.

```json
[
  {
    "feedback_ids": {
      "helpful": "019503a1-b2c3-7d4e-8f01-234567890abc",
      "quality.accuracy": "019503a1-b2c3-7d4e-8f01-234567890def"
    },
    "error": null
  }
]
```

--------------------------------

### Define Nested Feedback Structure

Source: https://docs.thesean.ai/ship/feedback

Example of a JSON payload containing nested feedback objects.

```json
[
  {
    "id": "019503a1-b2c3-7d4e-8f01-234567890abc",
    "feedback": {
      "evaluation": {
        "quality": {
          "precision": 0.95,
          "recall": 0.87
        }
      },
      "helpful": true
    }
  }
]
```

--------------------------------

### Configure Per-Project Environment Variables

Source: https://docs.thesean.ai/integrations/opencode

Create a local .env file and add it to .gitignore to secure your API key within a specific project.

```bash
echo "THESEAN_API_KEY=your-thesean-api-key" >> .env
echo ".env" >> .gitignore
```

--------------------------------

### Define OpenCode Configuration

Source: https://docs.thesean.ai/integrations/opencode

Create a JSON configuration file to define the provider and model settings for Thesean.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "thesean-anthropic/ship-like/claude-opus-4-8",
  "provider": {
    "thesean-anthropic": {
      "npm": "@ai-sdk/anthropic",
      "name": "Thesean Ship Models",
      "options": {
        "baseURL": "https://api.thesean.ai/v1",
        "apiKey": "{env:THESEAN_API_KEY}",
        "timeout": 600000
      },
      "models": {
        "ship-like/claude-opus-4-8": {
          "name": "Ship Claude Opus 4.8"
        }
      }
    }
  }
}
```

--------------------------------

### Configure Anthropic Client

Source: https://docs.thesean.ai/integrations/anthropic-sdk

Initialize the client with the Thesean base URL. Ensure the base URL does not include the /v1 path.

```python
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.thesean.ai",
    api_key="THESEAN_API_KEY"
)
```

```typescript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://api.thesean.ai",
  apiKey: process.env.THESEAN_API_KEY,
});
```

--------------------------------

### Configure Anthropic SDK for Thesean

Source: https://docs.thesean.ai/api-reference/authentication

Initialize the Anthropic client with the Thesean base URL and your API key to automatically use the x-api-key header.

```python
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.thesean.ai",
    api_key=THESEAN_API_KEY,
)
```

--------------------------------

### Perform Basic Completion with LiteLLM

Source: https://docs.thesean.ai/integrations/litellm

Use the completion function to send requests to Thesean models.

```python
from litellm import completion
import os

os.environ["THESEAN_API_KEY"] = "your-thesean-api-key"

response = completion(
    model="anthropic/ship-like/claude-opus-4-8",
    api_base="https://api.thesean.ai",
    api_key=os.environ["THESEAN_API_KEY"],
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)

print(response.choices[0].message.content)
```

--------------------------------

### Create Cache with cURL

Source: https://docs.thesean.ai/api-reference/advanced

Sends a request with a system prompt containing a cache_control block to initialize the cache.

```bash
curl https://api.thesean.ai/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $THESEAN_API_KEY" \
  -d '{
    "model": "ship-like/claude-opus-4-8",
    "max_tokens": 100,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on facts, specifications, and other information.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of Space! : The Universe As You have Never Seen It Before>",
        "cache_control": { "type": "ephemeral" }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What is the largest planet?"
      }
    ]
  }'
```

--------------------------------

### Basic Message with Anthropic SDK

Source: https://docs.thesean.ai/resources/examples

Initializes the Anthropic client with the Thesean base URL and sends a simple text prompt.

```python
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.thesean.ai",
    api_key=THESEAN_API_KEY,
)

message = client.messages.create(
    model="ship-like/claude-opus-4-8",
    max_tokens=1024,
    system="You are a helpful assistant.",
    messages=[
        {"role": "user", "content": "Explain quantum computing in simple terms."}
    ],
)

print(message.content[0].text)
```

--------------------------------

### Create a Message

Source: https://docs.thesean.ai/integrations/anthropic-sdk

Send a basic request to a Ship model.

```python
message = client.messages.create(
    model="ship-like/claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "What is Olympus Mons?"}
    ]
)

print(message.content[0].text)
```

```python
message = client.messages.create(
    model="ship-like/claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)
```

--------------------------------

### Implement Prompt Caching in Python

Source: https://docs.thesean.ai/api-reference/advanced

Uses the Anthropic client to define a system instruction with cache control and demonstrates cache creation versus cache read metrics.

```python
import anthropic

anth_client = anthropic.Anthropic(
    base_url="https://api.thesean.ai",
    api_key=THESEAN_API_KEY
)

# Define a common system instruction that will be used repeatedly
system_instruction = [
    {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on facts, specifications, and other information.\n",
    },
    {
        "type": "text",
        "text": "<the entire contents of 'Space! : The Universe As You've Never Seen It Before'>",
        "cache_control": {"type": "ephemeral"}
    }
]

# First interaction - the system instruction will be cached
message1 = anth_client.messages.create(
    model="ship-like/claude-opus-4-8",
    max_tokens=100,
    system=system_instruction,
    messages=[{"role": "user", "content": "What is the largest planet?"}],
)

# Check the usage to confirm cache creation
print("First request usage:")
print(f"  cache_creation_input_tokens: {message1.usage.cache_creation_input_tokens}")
print(f"  cache_read_input_tokens: {message1.usage.cache_read_input_tokens}")
print(f"  input_tokens: {message1.usage.input_tokens}")
print(f"  output_tokens: {message1.usage.output_tokens}")

# Output:
# First request usage:
#   cache_creation_input_tokens: 1280
#   cache_read_input_tokens: 0
#   input_tokens: 15
#   output_tokens: 53

# Subsequent interaction - the cached system instruction will be reused
message2 = anth_client.messages.create(
    model="ship-like/claude-opus-4-8",
    max_tokens=100,
    system=system_instruction,  # Must be identical
    messages=[{"role": "user", "content": "Which planet is closest to the sun?"}],
)

# Check the usage to confirm cache hit
print("\nSecond request usage:")
print(f"  cache_creation_input_tokens: {message2.usage.cache_creation_input_tokens}")
print(f"  cache_read_input_tokens: {message2.usage.cache_read_input_tokens}")
print(f"  input_tokens: {message2.usage.input_tokens}")
print(f"  output_tokens: {message2.usage.output_tokens}")

# Output:
# Second request usage:
#   cache_creation_input_tokens: 0
#   cache_read_input_tokens: 1280
#   input_tokens: 16
#   output_tokens: 42
```

--------------------------------

### Prompt Caching

Source: https://docs.thesean.ai/integrations/anthropic-sdk

Reduce latency and costs by caching system instructions.

```python
system_instruction = [
    {
        "type": "text",
        "text": "You are a helpful assistant."
    },
    {
        "type": "text",
        "text": "<large context document here>",
        "cache_control": {"type": "ephemeral"}
    }
]

# First request - creates cache
message1 = client.messages.create(
    model="ship-like/claude-opus-4-8",
    max_tokens=100,
    system=system_instruction,
    messages=[{"role": "user", "content": "Question 1"}]
)

# Second request - uses cache
message2 = client.messages.create(
    model="ship-like/claude-opus-4-8",
    max_tokens=100,
    system=system_instruction,  # Must be identical
    messages=[{"role": "user", "content": "Question 2"}]
)
```

--------------------------------

### Configure OpenAI SDK for Thesean

Source: https://docs.thesean.ai/api-reference/authentication

Use the OpenAI SDK by setting the base_url to the Thesean API endpoint and providing your API key.

```python
import openai

client = openai.OpenAI(
    base_url="https://api.thesean.ai/v1",
    api_key=THESEAN_API_KEY,
)

response = client.responses.create(
    model="ship-like/gpt-5.6-sol",
    input="Hello, world!",
)
```

--------------------------------

### Configure LiteLLM Proxy

Source: https://docs.thesean.ai/integrations/litellm

Define model mappings and master keys in a config.yaml file.

```yaml
model_list:
  - model_name: ship-opus
    litellm_params:
      model: anthropic/ship-like/claude-opus-4-8
      api_base: https://api.thesean.ai
      api_key: "os.environ/THESEAN_API_KEY"

general_settings:
  master_key: sk-1234
```

--------------------------------

### POST /v1/responses

Source: https://docs.thesean.ai/quickstart

Use the OpenAI-compatible Responses API to interact with the ship-like/gpt-5.6-sol model.

```APIDOC
## POST /v1/responses

### Description
Use the Responses API with the ship-like/gpt-5.6-sol model to generate text responses.

### Method
POST

### Endpoint
https://api.thesean.ai/v1/responses

### Request Body
- **model** (string) - Required - The model ID, e.g., "ship-like/gpt-5.6-sol"
- **input** (string) - Required - The prompt or input text

### Request Example
{
  "model": "ship-like/gpt-5.6-sol",
  "input": "What is Olympus Mons?"
}
```

--------------------------------

### Configure API Key

Source: https://docs.thesean.ai/integrations/codex

Set the Thesean API key in your shell environment variables.

```bash
# Add to ~/.zshrc, ~/.bashrc, etc.
export THESEAN_API_KEY="your-thesean-api-key"
```

--------------------------------

### Execute Tool Use via Python SDK

Source: https://docs.thesean.ai/api-reference/advanced

Implementation using the Anthropic Python client configured with a custom base URL for the Thesean AI API.

```python
import anthropic

anth_client = anthropic.Anthropic(
    base_url="https://api.thesean.ai",
    api_key=THESEAN_API_KEY
)

response = anth_client.messages.create(
    model="ship-like/claude-opus-4-8",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                }
            }
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "What's the weather in San Francisco?"
        }
    ]
)

for item in response.content:
    if item.type == "tool_use":
        print("Tool name:", item.name)
        print("Input args:", item.input)
```

--------------------------------

### POST /v1/chat/completions

Source: https://docs.thesean.ai/api-reference/endpoints

The /v1/chat/completions endpoint allows users to generate chat completions using supported models like ship-like/gpt-5.6-sol or ship-like/claude-opus-4-8.

```APIDOC
## POST https://api.thesean.ai/v1/chat/completions

### Description
Generates a chat completion response based on the provided conversation messages and model configuration.

### Method
POST

### Endpoint
https://api.thesean.ai/v1/chat/completions

### Parameters
#### Request Body
- **model** (string) - Required - Use `ship-like/gpt-5.6-sol` or `ship-like/claude-opus-4-8`.
- **messages** (array) - Required - A list of messages comprising the conversation so far.
- **max_completion_tokens** (integer) - Optional - The maximum number of tokens to generate.
- **reasoning_effort** (string) - Optional - The amount of reasoning effort to use when supported by the selected model.
- **stream** (boolean) - Optional - Whether to incrementally stream the response using server-sent events.
- **temperature** (number) - Optional - The sampling temperature.
- **tool_choice** (string | object) - Optional - Controls whether and how the model uses the supplied tools.
- **tools** (array) - Optional - Definitions of functions the model may call.

### Request Example
```json
{
  "model": "ship-like/claude-opus-4-8",
  "messages": [
    {
      "role": "user",
      "content": "Explain the importance of biodiversity."
    }
  ]
}
```
```

--------------------------------

### Tool Use

Source: https://docs.thesean.ai/integrations/anthropic-sdk

Define and use tools within the message request.

```python
response = client.messages.create(
    model="ship-like/claude-opus-4-8",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                }
            }
        }
    ],
    messages=[
        {"role": "user", "content": "What's the weather in San Francisco?"}
    ]
)

for item in response.content:
    if item.type == "tool_use":
        print(f"Tool: {item.name}")
        print(f"Args: {item.input}")
```

--------------------------------

### Tool Use Implementation

Source: https://docs.thesean.ai/resources/examples

Defines a tool schema and processes the model's tool use request.

```python
response = client.messages.create(
    model="ship-like/claude-opus-4-8",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"},
                },
                "required": ["location"],
            },
        }
    ],
    messages=[
        {"role": "user", "content": "What's the weather like in Boston?"}
    ],
)

for item in response.content:
    if item.type == "tool_use":
        print(item.name, item.input)
```

--------------------------------

### Handle API Errors Comprehensively

Source: https://docs.thesean.ai/api-reference/errors

Demonstrates how to catch and handle specific Anthropic API exceptions to provide granular error feedback.

```python
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.thesean.ai",
    api_key=THESEAN_API_KEY,
)

try:
    response = client.messages.create(
        model="ship-like/claude-opus-4-8",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello!"}],
    )
    print(response.content[0].text)

except anthropic.AuthenticationError as e:
    print(f"Authentication failed: {e}")

except anthropic.RateLimitError as e:
    print(f"Rate limit exceeded: {e}")

except anthropic.BadRequestError as e:
    print(f"Invalid request: {e}")

except anthropic.APIError as e:
    print(f"API error: {e}")

except Exception as e:
    print(f"Unexpected error: {e}")
```

--------------------------------

### Configure Global Claude Code Settings

Source: https://docs.thesean.ai/integrations/claude-code

Define the API base URL and authentication token in the global settings file located at ~/.claude/settings.json.

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.thesean.ai",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-thesean-key",
    "ANTHROPIC_MODEL": "ship-like/claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "ship-like/claude-haiku-4-5",
    "ANTHROPIC_SMALL_FAST_MODEL": "ship-like/claude-haiku-4-5"
  }
}
```

--------------------------------

### Integrate Ship with OpenAI SDK

Source: https://docs.thesean.ai/ship

Use the Ship endpoint by configuring the base URL and API key in the OpenAI client, then specifying a 'ship-like/' model name.

```python
import openai

client = openai.OpenAI(
    base_url="https://api.thesean.ai/v1",
    api_key=THESEAN_API_KEY,
)

response = client.responses.create(
    model="ship-like/gpt-5.6-sol",
    input="Explain the Navier-Stokes equations.",
)

print(response.output_text)
```

--------------------------------

### Configure Secret Manager Integration

Source: https://docs.thesean.ai/integrations/claude-code

Use the apiKeyHelper property in settings.json to fetch credentials dynamically from a secret manager like 1Password.

```json
{
  "apiKeyHelper": "op read 'op://Private/Thesean API Key/credential'",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.thesean.ai",
    "ANTHROPIC_MODEL": "ship-like/claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "ship-like/claude-haiku-4-5",
    "ANTHROPIC_SMALL_FAST_MODEL": "ship-like/claude-haiku-4-5"
  }
}
```

--------------------------------

### Specify Ship Models

Source: https://docs.thesean.ai/integrations/litellm

Use the anthropic/ prefix to route requests to specific Ship models.

```python
response = completion(
    model="anthropic/ship-like/claude-opus-4-8",
    api_base="https://api.thesean.ai",
    api_key=os.environ["THESEAN_API_KEY"],
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
```

--------------------------------

### anth_client.messages.create

Source: https://docs.thesean.ai/api-reference/advanced

Creates a new message interaction with the AI model, supporting prompt caching via the system instruction parameter.

```APIDOC
## anth_client.messages.create

### Description
Sends a message to the AI model. By providing a system instruction with a `cache_control` field, the API caches the content for reuse in subsequent requests, reducing input token costs.

### Parameters
- **model** (string) - Required - The model identifier (e.g., "ship-like/claude-opus-4-8").
- **max_tokens** (integer) - Required - The maximum number of tokens to generate.
- **system** (array) - Optional - A list of objects containing text and optional `cache_control` settings.
- **messages** (array) - Required - A list of message objects with role and content.

### Usage Example
```python
message = anth_client.messages.create(
    model="ship-like/claude-opus-4-8",
    max_tokens=100,
    system=[{"type": "text", "text": "...", "cache_control": {"type": "ephemeral"}}],
    messages=[{"role": "user", "content": "What is the largest planet?"}]
)
```

### Response Metrics
- **usage.cache_creation_input_tokens** (integer) - Tokens written to cache.
- **usage.cache_read_input_tokens** (integer) - Tokens read from cache.
- **usage.input_tokens** (integer) - Standard input tokens.
- **usage.output_tokens** (integer) - Tokens generated by the model.
```

--------------------------------

### Create Model Profile

Source: https://docs.thesean.ai/integrations/codex

Define a model profile for a specific Ship model.

```toml
model = "ship-like/gpt-5.6-sol"
model_provider = "thesean-responses"

[features]
multi_agent = false
```

--------------------------------

### Retrieve Models Endpoint

Source: https://docs.thesean.ai/api-reference/endpoints

The base URL for fetching the list of supported models.

```http
GET https://api.thesean.ai/v1/models
```

--------------------------------

### Anthropic SDK Integration

Source: https://docs.thesean.ai/ship/integration

Configure the Anthropic client to point to the Thesean API base URL with a ship-like/ model name.

```python
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.thesean.ai",
    api_key=THESEAN_API_KEY,
)

response = client.messages.create(
    model="ship-like/claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Explain the difference between TCP and UDP.",
        }
    ],
)

print(response.content[0].text)
```

--------------------------------

### Send Request with Python httpx

Source: https://docs.thesean.ai/integrations/http-client

Use the httpx library to perform a synchronous POST request to the Responses API.

```python
import httpx

response = httpx.post(
    "https://api.thesean.ai/v1/responses",
    headers={
        "Authorization": "Bearer THESEAN_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "ship-like/gpt-5.6-sol",
        "input": "What is Olympus Mons?",
    },
    timeout=60.0,
)
response.raise_for_status()
print(response.json()["output"][0]["content"][0]["text"])
```

--------------------------------

### Reload Shell Configuration

Source: https://docs.thesean.ai/integrations/codex

Apply changes to your shell profile.

```bash
source ~/.zshrc  # or source ~/.bashrc etc.
```

--------------------------------

### Streaming Responses

Source: https://docs.thesean.ai/ship/integration

Handle streaming responses using the Anthropic client with a ship-like/ model.

```python
with client.messages.stream(
    model="ship-like/claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a haiku about machine learning."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="")
```

--------------------------------

### Enable Streaming with Anthropic Python SDK

Source: https://docs.thesean.ai/api-reference/advanced

Set stream=True in the messages.create call to receive real-time updates. Iterate through the stream object to process content_block_delta chunks.

```python
import anthropic

anth_client = anthropic.Anthropic(
    base_url="https://api.thesean.ai",
    api_key=THESEAN_API_KEY
)

stream = anth_client.messages.create(
    model="ship-like/claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a sonnet to Mars (the god, not the planet)."}],
    stream=True
)

for chunk in stream:
    if chunk.type == "content_block_delta" and chunk.delta.type == "text_delta":
        print(chunk.delta.text, end="")
```

--------------------------------

### POST /v1/messages (Prompt Caching)

Source: https://docs.thesean.ai/api-reference/advanced

Supports Anthropic's message caching to reduce response times and inference costs by caching input tokens.

```APIDOC
## POST /v1/messages

### Description
Thesean supports Anthropic's message caching. This enables you to cache input tokens on the first call to the endpoint, which can then be reused in subsequent calls.

### Parameters
#### Request Body
- **cache_control** (object) - Required - Set to `{"type": "ephemeral"}` after the content of a prompt block to define a cache breakpoint.

### Usage Notes
- In subsequent requests, the entire prompt up to `cache_control` must be identical to the previously cached prompt.
- Anthropic enforces a minimum cacheable prompt size; requests below this threshold will not create a cache entry.
```

--------------------------------

### OpenAI Responses API Integration

Source: https://docs.thesean.ai/ship/integration

Use the ship-like/ prefix with the OpenAI client to route requests through the Thesean API.

```python
import openai

client = openai.OpenAI(
    base_url="https://api.thesean.ai/v1",
    api_key=THESEAN_API_KEY,
)

response = client.responses.create(
    model="ship-like/gpt-5.6-sol",
    input="Explain the difference between TCP and UDP.",
)

print(response.output_text)
```

--------------------------------

### Execute Tool Use via cURL

Source: https://docs.thesean.ai/api-reference/advanced

Direct API request using the Anthropic-compatible messages endpoint with a defined tool schema.

```bash
curl https://api.thesean.ai/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $THESEAN_API_KEY" \
  -d '{
    "model": "ship-like/claude-opus-4-8",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string"
            }
          }
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Use the get_weather tool to check San Francisco weather"
      }
    ]
  }'
```

--------------------------------

### Configure Thesean Provider

Source: https://docs.thesean.ai/integrations/codex

Define the Thesean provider in the Codex configuration file using the responses wire API.

```toml
[model_providers.thesean-responses]
name = "Thesean /responses"
base_url = "https://api.thesean.ai/v1"
env_key = "THESEAN_API_KEY"
wire_api = "responses"
```

--------------------------------

### Reuse Cached Content with cURL

Source: https://docs.thesean.ai/api-reference/advanced

Sends a subsequent request with an identical system prompt to trigger cache reuse.

```bash
# The system prompt must be identical to use the cache
curl https://api.thesean.ai/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $THESEAN_API_KEY" \
  -d '{
    "model": "ship-like/claude-opus-4-8",
    "max_tokens": 100,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on facts, specifications, and other information.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of Space! : The Universe As You have Never Seen It Before>",
        "cache_control": { "type": "ephemeral" }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Which planet is closest to the sun?"
      }
    ]
  }'
```

--------------------------------

### Stream Responses

Source: https://docs.thesean.ai/integrations/anthropic-sdk

Handle streaming output by iterating over chunks.

```python
stream = client.messages.create(
    model="ship-like/claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a story about Mars"}],
    stream=True
)

for chunk in stream:
    if chunk.type == "content_block_delta" and chunk.delta.type == "text_delta":
        print(chunk.delta.text, end="")
```

--------------------------------

### POST /v1/feedback

Source: https://docs.thesean.ai/ship/feedback

Submit an array of feedback events to be associated with specific inference IDs.

```APIDOC
## POST /v1/feedback

### Description
Submits an array of feedback events tied to specific inference IDs. Each event can contain custom feedback metrics, tags, and optimization preferences.

### Method
POST

### Endpoint
https://api.thesean.ai/v1/feedback

### Request Body
- **id** (string, UUID) - Required - The inference ID to attach feedback to.
- **feedback** (object) - Required - A dictionary mapping user-defined keys to feedback values.
- **tags** (object) - Optional - Metadata key-value pairs to attach to all feedback entries in this event.
- **optimize** (string) - Optional - Optimization direction for numeric and boolean metrics ("max" or "min").

### Request Example
[
  {
    "id": "019503a1-b2c3-7d4e-8f01-234567890abc",
    "feedback": {
      "helpful": true,
      "rating": 4.5
    },
    "optimize": "max"
  }
]

### Response
#### Success Response (200)
- **feedback_ids** (object | null) - Maps each feedback key to its unique ID (UUID) on success.
- **error** (object | null) - Contains status_code and message on failure.

#### Response Example
[
  {
    "feedback_ids": {
      "helpful": "019503a1-b2c3-7d4e-8f01-234567890abc"
    },
    "error": null
  }
]
```

--------------------------------

### Insufficient Credits Error Response

Source: https://docs.thesean.ai/api-reference/errors

Returned with a 403 status code when the account balance is too low to process the request.

```json
{
  "error": {
    "message": "Insufficient credits. Please add credits to your account.",
    "type": "insufficient_quota",
    "code": "insufficient_credits"
  }
}
```

--------------------------------

### Invoke OpenAI Responses API via cURL

Source: https://docs.thesean.ai/quickstart

Use this cURL command to interact with the Responses API using the ship-like/gpt-5.6-sol model.

```bash
# Note: Replace $THESEAN_API_KEY with your assigned API key
curl https://api.thesean.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $THESEAN_API_KEY" \
  -d '{
    "model": "ship-like/gpt-5.6-sol",
    "input": "What is Olympus Mons?"
  }'
```

--------------------------------

### Configure Shell Environment Variables

Source: https://docs.thesean.ai/integrations/claude-code

Export the required environment variables in your terminal session before launching Claude Code.

```bash
export ANTHROPIC_BASE_URL="https://api.thesean.ai"
export ANTHROPIC_AUTH_TOKEN="sk-your-thesean-key"
export ANTHROPIC_MODEL="ship-like/claude-sonnet-5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="ship-like/claude-haiku-4-5"
export ANTHROPIC_SMALL_FAST_MODEL="ship-like/claude-haiku-4-5"
claude
```

--------------------------------

### Retry Logic with Tenacity

Source: https://docs.thesean.ai/resources/examples

Implements exponential backoff for API calls using the tenacity library.

```python
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=4, max=10),
)
def send_message(messages):
    return client.messages.create(
        model="ship-like/claude-opus-4-8",
        max_tokens=1024,
        messages=messages,
    )
```

--------------------------------

### POST /v1/messages

Source: https://docs.thesean.ai/api-reference/advanced

Sends a message to the AI model. This endpoint supports prompt caching by including a cache_control object within the system prompt configuration.

```APIDOC
## POST /v1/messages

### Description
Sends a message to the AI model. By providing a cache_control object in the system prompt, the API can cache large inputs for reuse in subsequent requests.

### Method
POST

### Endpoint
https://api.thesean.ai/v1/messages

### Request Body
- **model** (string) - Required - The model identifier (e.g., "ship-like/claude-opus-4-8")
- **max_tokens** (integer) - Required - The maximum number of tokens to generate
- **system** (array) - Required - The system prompt configuration, including text and optional cache_control
- **messages** (array) - Required - The conversation history

### Request Example
{
  "model": "ship-like/claude-opus-4-8",
  "max_tokens": 100,
  "system": [
    {
      "type": "text",
      "text": "You are an AI assistant..."
    },
    {
      "type": "text",
      "text": "<content>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [
    { "role": "user", "content": "What is the largest planet?" }
  ]
}

### Response
#### Success Response (200)
- **id** (string) - Unique message identifier
- **content** (array) - The generated response content
- **usage** (object) - Token usage metadata, including cache_creation_input_tokens or cache_read_input_tokens

#### Response Example
{
  "id": "msg_XXXxXxXXxXxxXX",
  "type": "message",
  "usage": {
    "input_tokens": 27,
    "cache_creation_input_tokens": 1279,
    "output_tokens": 45
  }
}
```

--------------------------------

### POST /v1/responses

Source: https://docs.thesean.ai/integrations/http-client

Sends a request to the Responses API to generate model output.

```APIDOC
## POST /v1/responses

### Description
Generates a response from the specified model based on the provided input.

### Method
POST

### Endpoint
https://api.thesean.ai/v1/responses

### Parameters
#### Request Body
- **model** (string) - Required - The model identifier (e.g., "ship-like/gpt-5.6-sol")
- **input** (string) - Required - The input text for the model

### Request Example
{
  "model": "ship-like/gpt-5.6-sol",
  "input": "What is Olympus Mons?"
}

### Response
#### Success Response (200)
- **output** (array) - The generated response content
```

--------------------------------

### Send Request with cURL

Source: https://docs.thesean.ai/integrations/http-client

Use cURL to send a POST request to the Responses API.

```bash
curl https://api.thesean.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer THESEAN_API_KEY" \
  -d '{
    "model": "ship-like/gpt-5.6-sol",
    "input": "What is Olympus Mons?"
  }'
```