Documentation

One OpenAI & Anthropic compatible endpoint — from your first request to error recovery, everything lives on this page.

Get started in three steps#

1from openai import OpenAI
2
3client = OpenAI(
4    base_url="https://api.cosmosin.io/v1",
5    api_key="sk-cos...",
6)
7
8resp = client.chat.completions.create(
9    model="deepseek-v4-flash",
10    messages=[{"role": "user", "content": "Hello!"}],
11)
12print(resp.choices[0].message.content)

Authentication & API keys#

Every request must carry your key in the Authorization: Bearer header. One account can hold many keys — mint separate ones per tool or project.

1Authorization: Bearer sk-cos...

Key format

Keys are prefixed sk-cos followed by 48 hex characters. The full secret is shown only once at creation; afterwards the dashboard only shows a masked form (sk-cos…c56789).

Manage keys

Mint and revoke keys from the dashboard. A revoked key stops working immediately. Rotate regularly: mint a new key, update your tools, then revoke the old one. Treat keys like passwords — never put them in client-side code, mobile apps, or public repositories.

Tool configuration#

Copy-paste snippets for popular tools. Compatible clients read the environment variables automatically.

1export ANTHROPIC_BASE_URL=https://api.cosmosin.io
2export ANTHROPIC_AUTH_TOKEN=sk-cos...
3
4# continue as usual
5claude "finish the migration"

1{
2  "openai.baseURL": "https://api.cosmosin.io/v1",
3  "openai.apiKey": "sk-cos..."
4}

1# set the key first: export COSMOSIN_API_KEY=sk-cos...
2model = "deepseek-v4-flash"
3model_provider = "cosmosin"
4
5[model_providers.cosmosin]
6name = "CosmosIn"
7base_url = "https://api.cosmosin.io/v1"
8env_key = "COSMOSIN_API_KEY"
9wire_api = "responses"

1{
2  "$schema": "https://opencode.ai/config.json",
3  "provider": {
4    "cosmosin": {
5      "npm": "@ai-sdk/openai-compatible",
6      "options": {
7        "baseURL": "https://api.cosmosin.io/v1",
8        "apiKey": "sk-cos..."
9      }
10    }
11  }
12}

1Provider:  OpenAI Compatible
2Base URL:  https://api.cosmosin.io/v1
3API Key:   sk-cos...
4Model:     deepseek-v4-flash

1name: CosmosIn
2version: 1.0.0
3schema: v1
4
5models:
6  - name: CosmosIn
7    provider: openai
8    model: deepseek-v4-flash
9    apiBase: https://api.cosmosin.io/v1
10    apiKey: sk-cos...
11    roles:
12      - chat
13      - edit
14      - apply
15    capabilities:
16      - tool_use

Endpoints#

Every endpoint uses the same key. Request bodies and responses follow the compatible OpenAI or Anthropic format — an example for /v1/chat/completions:

1{
2  "model": "deepseek-v4-flash",
3  "messages": [
4    { "role": "user", "content": "Hello!" }
5  ]
6}

1{
2  "id": "chatcmpl-...",
3  "object": "chat.completion",
4  "model": "deepseek-v4-flash",
5  "choices": [
6    {
7      "message": { "role": "assistant", "content": "Hello! How can I help?" }
8    }
9  ],
10  "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 }
11}

Streaming#

Set stream: true to receive the response incrementally as Server-Sent Events (SSE). Each event carries a JSON delta in the OpenAI streaming format; the connection uses content-type text/event-stream and ends with a data: [DONE] sentinel. Most OpenAI SDKs expose streaming natively — just iterate the chunks.

1stream = client.chat.completions.create(
2    model="deepseek-v4-flash",
3    messages=[{"role": "user", "content": "Hello!"}],
4    stream=True,
5)
6
7for chunk in stream:
8    delta = chunk.choices[0].delta.content
9    if delta:
10        print(delta, end="", flush=True)

Models#

Fill the model field with a model name from the catalog — CosmosIn uses real model names, no aliases. The full list with per-token pricing is always up to date on the pricing page; the /v1/models endpoint returns the models your key can call.

Reasoning models#

Models with the Reasoning badge in the catalog spend part of their token budget thinking before answering. Control the depth per request with reasoning_effort — higher means deeper answers, more tokens, and higher latency. On non-reasoning models the parameter is ignored, so it is safe to always send. Supported levels follow each model; check the Reasoning badge in the catalog. One note: a max_tokens that is too low can leave the answer looking empty because the budget was spent thinking — raise max_tokens or drop the limit.

1{
2  "model": "deepseek-v4-flash",
3  "messages": [
4    { "role": "user", "content": "Hello!" }
5  ],
6  "reasoning_effort": "high"
7}

Embeddings#

Turn text into vectors for semantic search, clustering, and retrieval-augmented generation (RAG). Compatible with the OpenAI Embeddings API: send input, receive float vectors. Embeddings do not stream — the stream flag is rejected.

1from openai import OpenAI
2
3client = OpenAI(base_url="https://api.cosmosin.io/v1", api_key="sk-cos...")
4res = client.embeddings.create(model="text-embedding-3-small", input="Hello!")
5print(res.data[0].embedding[:5])  # [0.012, -0.034, 0.041, ...]

Rerank#

Re-order retrieved candidates so the most relevant documents come first. Rerank uses a cross-encoder that reads the query and document together — more accurate than cosine similarity for picking the best context. The common RAG pattern: embed ±20 candidates via /v1/embeddings, rerank to top-5, then feed to chat completions.

• query — the search text (string)
• documents — array of candidate documents to score
• top_n — optional; limit the number of results
• model — the rerank model name

1import requests
2res = requests.post(
3    "https://api.cosmosin.io/v1/rerank",
4    headers={"Authorization": "Bearer sk-cos..."},
5    json={
6        "model": "rerank-v3",
7        "query": "rerank",
8        "documents": docs,  # 10-20 kandidat
9        "top_n": 5,
10    },
11)
12for r in res.json()["results"]:
13    print(r["index"], r["relevance_score"])

Video generation#

Create short MP4 clips from text or images with one endpoint. The gateway handles the async task server-side: POST returns an id with status pending (HTTP 202), then poll GET /v1/videos/{id} every ~5 seconds until status is succeeded — the response carries the download URL. Clips are stored temporarily; download promptly.

1curl --request POST \
2  --url https://api.cosmosin.io/v1/videos \
3  --header "Authorization: Bearer sk-cos..." \
4  --header "Content-Type: application/json" \
5  --data '{
6    "model": "video-t2v",
7    "prompt": "Kota mini dari kardus hidup di malam hari",
8    "mode": "t2v",
9    "duration": 5
10  }'

Rate limits & quotas#

Limits follow your plan. Subscription plans are governed by a per-minute request rate and a token pool; PAYG credits never expire and are bounded only by your balance. Breaching a limit returns 429 rate_limited — back off and retry after the window resets. Per-plan limits are shown on the pricing page.

Error codes#

First-request errors are almost always 401 or 402: a mis-pasted key or an empty balance. Check the sk-cos prefix, then check your balance on the dashboard.

Error shape

Errors use a single, stable JSON envelope. Switch on the type field rather than parsing the message. The request_id helps correlate a failure with server logs.

1{
2  "error": {
3    "type": "rate_limited",
4    "message": "Rate limit exceeded. Please retry later.",
5    "request_id": "req_..."
6  }
7}

Model combos#

Combos are your own virtual model ids (shaped combo/<name>) bundling 1–5 models behind one fallback strategy. The gateway tries panel models one by one within the same request: target 1 fails (402, 403, 500, timeout) → billing released → target 2, and so on. A circuit breaker skips a model during its cooldown, so a failing model costs no latency. Combos are private to their owner — another key calling your combo gets a 404. Manage them on the dashboard.

1curl https://api.cosmosin.io/v1/chat/completions \
2  -H "Authorization: Bearer sk-cos..." \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model": "combo/free-pack",
6    "messages": [{"role": "user", "content": "Halo!"}]
7  }'

Plans & pricing#

Prices in Rupiah, transparent per token per the catalog — no hidden fees. Two ways to pay: PAYG credits (top-up, never expire) and subscription plans with a token pool. Models, prices, and plan limits are always live on the pricing page.