Quick start

Welcome to SeaWhale AI. As an AI API gateway, we provide a single, unified endpoint that routes to hundreds of AI models. The platform handles failover automatically and picks the best-value provider for you. Most models are also available over several service channels, so you can trade off reliability against cost.

A few lines of code are all you need to add powerful AI capabilities to your application.

Before you begin

1. Create a SeaWhale AI account
2. Add funds to your account
3. Create an API key

Option 1: Use the OpenAI SDK (recommended)

SeaWhale AI is fully compatible with the OpenAI SDK — change baseURL and apiKey and everything else keeps working.

Python

from openai import OpenAI

# Initialize the client
client = OpenAI(
  base_url="https://api.seawhaleai.com/v2",  # SeaWhale AI API endpoint
  api_key="<API_KEY>",  # Replace with your API key
)

# Send a chat request
completion = client.chat.completions.create(
  model="gpt-4o",  # Pick a model
  messages=[
    {
      "role": "user",
      "content": "Hello!"
    }
  ]
)

# Print the result
print(completion.choices[0].message.content)

JavaScript

import OpenAI from 'openai'

// Initialize the client
const openai = new OpenAI({
  baseURL: 'https://api.seawhaleai.com/v2', // SeaWhale AI API endpoint
  apiKey: '<API_KEY>', // Replace with your API key
})

async function main() {
  // Send a chat request
  const completion = await openai.chat.completions.create({
    model: 'gpt-4o', // Pick a model
    messages: [
      {
        role: 'user',
        content: 'Hello!',
      },
    ],
  })

  // Print the result
  console.log(completion.choices[0].message)
}

main()

Option 2: Call the HTTP API directly

If you would rather not use an SDK, you can call the SeaWhale AI API over plain HTTP.

Python

import requests
import json

# Send a POST request
response = requests.post(
  url="https://api.seawhaleai.com/v2/chat/completions",
  headers={
    "Authorization": "<API_KEY>",  # Replace with your API key
    "Content-Type": "application/json"
  },
  data=json.dumps({
    "model": "gpt-4o",  # Pick a model
    "messages": [
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  })
)

# Parse the response
result = response.json()
print(result["choices"][0]["message"]["content"])

JavaScript

// Send a POST request
fetch('https://api.seawhaleai.com/v2/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: '<API_KEY>', // Replace with your API key
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-4o', // Pick a model
    messages: [
      {
        role: 'user',
        content: 'Hello!',
      },
    ],
  }),
})
  .then((response) => response.json())
  .then((data) => {
    // Print the result
    console.log(data.choices[0].message.content)
  })
  .catch((error) => console.error('Error:', error))

cURL

curl https://api.seawhaleai.com/v2/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: <API_KEY>" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'

Multi-channel routing: more reliable, and more affordable

For most models we connect several service channels, and you can pick whichever fits the job: direct for native behavior, preferred for everyday production traffic, economy for cost-sensitive batch work — prices for the same model can differ several-fold between channels.

Value	Channel	Best for
direct	Direct	The official upstream link, for native behavior and the full context window
stable	Preferred	Balanced availability and speed — a good fit for production traffic
economical	Economy	Cost first, well suited to batch processing and price-sensitive workloads

Add a provider field to the request body to choose a channel:

Python

completion = client.chat.completions.create(
  model="gpt-4o",
  messages=[{"role": "user", "content": "Hello!"}],
  # Optional: pick a service channel; omit to use the default
  extra_body={"provider": {"channel": "economical"}},
)

JavaScript

const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
  // Optional: pick a service channel; omit to use the default
  // @ts-expect-error provider is a SeaWhale AI extension, not in the OpenAI SDK types
  provider: { channel: 'economical' },
})

cURL

curl https://api.seawhaleai.com/v2/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}],
    "provider": { "channel": "economical" }
  }'

A few notes:

• Omitting provider works fine — the platform picks a default channel and handles failover for you.
• If the requested channel is not enabled for that model, the request falls back to the default channel and does not error.
• Available channels and prices vary by model; the "Pricing" section on each model's detail page is authoritative.
• provider is a SeaWhale AI extension, not part of the official OpenAI protocol, and only takes effect on this platform.

Important notes

• API key security: never expose your API key in client-side code or a public repository.
• Channel selection: use the provider field to pick a channel — the economy channel cuts costs on batch jobs.
• Choosing a model: browse the model list to see every available model and its pricing.
• Error handling: add proper error handling and retries before going to production.
• Streaming: set stream: true for streamed output.

Contact support

If you run into trouble, scan the QR code to reach our support team on WeChat Work and an engineer will help you complete the integration.

Next steps

• Read the API reference for the full parameter list
• Browse the FAQ for more help
• Visit the model list to find the right model for your use case