Docs

Get started with Cloudsome's OpenAI-compatible endpoints.

Quick Start

1. Create an account and generate an API key from the dashboard.
2. Make sure the current workspace has sufficient balance; top up if needed.
3. Install the OpenAI SDK for your language.
4. Get an available model ID from the Models page or GET /v1/models, then point the base URL to Cloudsome and make requests with that model ID.

Python
Python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cloudsome.ai/v1",
    api_key="sk_live_...",
)

response = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
)

for chunk in response:
    print(chunk.choices[0].delta.content, end="")
Node.js
JavaScript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.cloudsome.ai/v1",
  apiKey: "sk_live_...",
});

const response = await client.chat.completions.create({
  model: "YOUR_MODEL_ID",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(response.choices[0].message.content);
cURL
Bash
curl https://api.cloudsome.ai/v1/chat/completions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
Image Generation

Use your API key to call POST /v1/images/generations. Replace model with the image model ID shown on the Models page.

Bash
curl https://api.cloudsome.ai/v1/images/generations \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_IMAGE_MODEL_ID",
    "prompt": "A futuristic city floating above a sea of clouds",
    "n": 1,
    "resolution": "1080P",
    "ratio": "1:1",
    "response_format": "url"
  }'

Common parameters: model and prompt are required; n controls the number of images; resolution and ratio control the output dimensions; response_format selects url or b64_json output.

You may also send additional parameters supported by the selected model's upstream API. Parameter names, values, and limits vary by model; refer to the original documentation from that model's upstream provider.

IDE & Tool Integration

Cloudsome is compatible with popular AI coding tools. Here's how to configure Claude Code, Codex, OpenCode, and CC Switch.

Claude Code
Install Claude Code

Set environment variables in your terminal to use Cloudsome as the Claude Code backend. You can also persist settings in ~/.claude/settings.json.

macOS / Linux
Windows
Terminal environment variables
Bash
export ANTHROPIC_BASE_URL="https://api.cloudsome.ai"
export ANTHROPIC_AUTH_TOKEN="sk_live_your_key_here"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
Config file (recommended) — ~/.claude/settings.json
JavaScript
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.cloudsome.ai",
    "ANTHROPIC_AUTH_TOKEN": "sk_live_your_key_here",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_MODEL": "claude-opus-4-6",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}
Codex
Install Codex

After setting CLOUDSOME_API_KEY, configure Cloudsome as a custom provider in ~/.codex/config.toml. The default model is GPT-5.6 Sol with high reasoning effort, and requests use the Responses API.

macOS / Linux
Windows
Terminal environment variable
Bash
export CLOUDSOME_API_KEY="sk_live_your_key_here"
Config file (recommended) — ~/.codex/config.toml
TOML
model = "gpt-5.6-sol"
model_reasoning_effort = "high"
model_provider = "cloudsome"

[model_providers.cloudsome]
name = "Cloudsome Production"
base_url = "https://api.cloudsome.ai/v1"
env_key = "CLOUDSOME_API_KEY"
wire_api = "responses"
OpenCode
Install OpenCode

Create an opencode.json config file in your project root to use Cloudsome as the provider.

JavaScript
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "cloudsome": {
      "models": {
        "claude-haiku-4-5-20251001": {
          "name": "Claude Haiku 4.5"
        },
        "claude-opus-4-6": {
          "name": "Claude Opus 4.6"
        },
        "claude-sonnet-4-6": {
          "name": "Claude Sonnet 4.6"
        }
      },
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "apiKey": "sk_live_your_key_here",
        "baseURL": "https://api.cloudsome.ai/v1",
        "setCacheKey": true
      }
    }
  }
}
CC Switch

CC Switch is a multi-provider switcher for Claude Code. After installation, import Cloudsome config with a single click via deep link.

Install CC Switch
Endpoints
POST

/v1/chat/completions

Chat completions (streaming supported)
POST

/v1/embeddings

Text embeddings
POST

/v1/rerank

Document reranking
POST

/v1/images/generations

Image generation
POST

/v1/responses

Responses API
GET

/v1/models

List available models
Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from your dashboard. Keys start with sk_live_.

Bash
curl https://api.cloudsome.ai/v1/chat/completions \
  -H "Authorization: Bearer sk_live_your_key_here"
API Key Guardrails

Guardrails define reusable usage and access policies for API keys and organization members. Use them to keep spend limits, model access, and provider access consistent without editing every key one by one.

Budget limits

Set a spend limit with a daily, weekly, or monthly reset period.

Model and provider access

Choose which models and providers covered requests can use.

Flexible binding

Bind to API keys in a personal workspace, or to API keys or members in an organization. You can also save an unbound policy.
Configure a Guardrail
1

Open Dashboard > API Key Guardrails.

2

Create a Guardrail, name it, and choose whether it is active.

3

Configure the optional budget, allowed models, and allowed providers.

4

Select API keys or organization members to bind, or leave it unbound for later use.

How budgets are counted
API key binding: the budget is tracked separately for each bound key.
Member binding: the budget is shared by all keys owned by that member.
A direct API key budget can still apply. Requests must pass both the key budget and the Guardrail budget.
Request behavior
Personal workspaces can bind Guardrails to API keys.
Organization workspaces can bind Guardrails to API keys or members.
IP Allowlist stays on each API key. Platform traffic safeguards are automatic and are not user-configurable.
Model or provider denials return an HTTP 403 policy error. Exhausted budgets and platform protection return HTTP 429.
Streaming

All chat completion endpoints support streaming via stream: true. Tokens are delivered as server-sent events (SSE) in real time.

Python
response = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
Streaming Billing Rules

If the upstream errors before any data is streamed, you are fully refunded.

If you disconnect after streaming begins, billing uses the actual usage generated when available. If exact usage is unavailable, it is estimated from the generated content.

If the upstream fails mid-stream, billing uses the actual usage generated when available. If exact usage is unavailable, it is estimated from the partial response received.

Usage Protection

Cloudsome applies platform stability safeguards by default. User-configured spend limits are managed through API Key Guardrails or direct API key budgets. When a request exceeds a safeguard or budget, the API returns HTTP 429.

Platform stability

Default traffic safeguards

Burst protection

Automatic overload protection

Budget guardrails

Spend caps by day, week, or month
Error Codes

Common platform error codes for OpenAI-compatible endpoints are listed below. Upstream providers may return additional codes, so clients should also handle unknown codes. The Anthropic Messages endpoint returns errors in Anthropic-compatible format.

Bash
{
  "error": {
    "message": "Insufficient balance",
    "type": "invalid_request_error",
    "code": "personal_balance_insufficient"
  }
}
CodeCategoryDescription

invalid_api_key

Request

The API key is missing or invalid

invalid_json

Request

Request body is not valid JSON

invalid_request

Request

Request parameter or field validation failed

personal_balance_insufficient

Billing

Personal account balance is insufficient; top up before retrying

guardrail_model_not_allowed

Guardrail

The requested model is not allowed by the current policy

guardrail_budget_exceeded

Guardrail

The Guardrail budget limit has been exceeded

rate_limit_exceeded

Rate limit

Rate or concurrency limit exceeded

route_unavailable

Routing

No routing target is currently available

no_channel

Routing

No available channel matches the current request

upstream_error

Upstream

The upstream request failed; retry later

One API for the world’s leading AI models.
ProductModelsDocsBillingFAQ
CompanyAboutContactPrivacy

© 2026 Cloudsome. All rights reserved.