Developer guide & SDKs

Overview

SharkAPI exposes a 100% OpenAI-compatible REST API. Configure the base URL and a customer API key in any OpenAI SDK or HTTP client — no SDK changes, no custom protocol.

Base URL & authentication

Every request goes to the /v1 surface with a bearer token. Keys are issued as sk-shark-… after a Telegram purchase.

Authentication

Send the key in the Authorization header. Missing, invalid or suspended keys return 401 before the request is sent.

curl https://api.sharkapi.store/v1/models \
  -H "Authorization: Bearer sk-shark-YOUR_KEY"

Chat completions

Send a standard Chat Completions request. The gateway resolves the model, picks a healthy route and streams the response back.

Use any model ID from the model catalog.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.sharkapi.store/v1",
    api_key="sk-shark-YOUR_KEY"
)

response = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[{"role": "user", "content": "Explain edge routing in one sentence."}]
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.sharkapi.store/v1",
  apiKey: "sk-shark-YOUR_KEY"
});

const response = await client.chat.completions.create({
  model: "YOUR_MODEL_ID",
  messages: [{ role: "user", content: "Explain edge routing in one sentence." }]
});

console.log(response.choices[0].message.content);

curl -X POST "https://api.sharkapi.store/v1/chat/completions" \
  -H "Authorization: Bearer sk-shark-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "Explain edge routing in one sentence."}]
  }'

Streaming

Set stream: true to receive incremental deltas over server-sent events. The proxy forwards chunks immediately and meters output tokens when the stream finishes.

stream = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[{"role": "user", "content": "Tell me a short story."}],
    stream=True
)

for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)

Audio transcriptions

Transcribe audio files into text using our OpenAI-compatible /v1/audio/transcriptions endpoint. Highly optimized for Whisper V3 (whisper-large-v3, whisper-large-v3-turbo) and Gemini 3.8 Transcribe (gemini-3.8-transcribe) for maximum speed and accuracy.

curl https://api.sharkapi.store/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-shark-YOUR_KEY" \
  -F file=@audio.mp3 \
  -F model=whisper-large-v3 \
  -F response_format=verbose_json

Translations

Translate audio and text cues seamlessly with /v1/audio/translations and /v1/chat/completions. We recommend Gemini 3.8 Flash High (gemini-3.8-flash-high) and GPT 5.6 Luna (gpt-5.6-luna) for superior multi-language translation and subtitle dubbing precision.

response = client.chat.completions.create(
    model="gemini-3.8-flash-high",
    messages=[
        {"role": "system", "content": "Translate dialogue to Khmer accurately preserving timing."},
        {"role": "user", "content": "Welcome to our automated dubbing studio!"}
    ]
)
print(response.choices[0].message.content)

List models

GET /v1/models returns the live catalog. Disabled models are omitted. Anonymous callers get the list without per-model quota; a valid key or admin session adds quota details.

curl https://api.sharkapi.store/v1/models

// 200 OK
{
  "object": "list",
  "data": [
    {
      "id": "MODEL_ID",
      "name": "MODEL_NAME",
      "family": "MODEL_FAMILY",
      "thinking": false,
      "image": false
    }
  ]
}

• id — Model id to send in requests
• name — Display name
• family — Family label returned by the API
• thinking — Whether the model emits reasoning

Errors & status codes

Errors use the OpenAI error envelope. The status code tells you whether the problem is the key, the balance or service availability.

Quotas & rate limits

Keys are metered 1:1 on prompt and completion tokens. Requests over the remaining balance return 429 before the request is sent, and each package applies its own per-key requests-per-minute limit.