Circassian AI API

curl https://api.circassian.ai/v1/me \
  -H "Authorization: Bearer $CIRCASSIAN_API_KEY"

import os, httpx

r = httpx.get(
    "https://api.circassian.ai/v1/me",
    headers={"Authorization": f"Bearer {os.environ['CIRCASSIAN_API_KEY']}"},
)
print(r.json())

const res = await fetch("https://api.circassian.ai/v1/me", {
  headers: { Authorization: `Bearer ${process.env.CIRCASSIAN_API_KEY}` },
});
console.log(await res.json());

<?php
$ch = curl_init("https://api.circassian.ai/v1/me");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CIRCASSIAN_API_KEY")],
]);
echo curl_exec($ch);

req, _ := http.NewRequest("GET", "https://api.circassian.ai/v1/me", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("CIRCASSIAN_API_KEY"))

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()
io.Copy(os.Stdout, resp.Body)

curl https://api.circassian.ai/v1/translate \
  -H "Authorization: Bearer $CIRCASSIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, how are you?",
    "source_lang": "en",
    "target_lang": "kbd"
  }'

import os, httpx

API = "https://api.circassian.ai"
KEY = os.environ["CIRCASSIAN_API_KEY"]


def translate(text: str, target: str, source: str | None = None) -> str:
    payload = {"text": text, "target_lang": target}
    if source:
        payload["source_lang"] = source

    r = httpx.post(
        f"{API}/v1/translate",
        headers={"Authorization": f"Bearer {KEY}"},
        json=payload,
        timeout=60,
    )
    if r.status_code != 200:
        raise RuntimeError(r.json()["error"]["message"])
    return r.json()["text"]


print(translate("Hello, how are you?", "kbd", "en"))

const API = "https://api.circassian.ai";
const KEY = process.env.CIRCASSIAN_API_KEY;

async function translate(text, targetLang, sourceLang) {
  const res = await fetch(`${API}/v1/translate`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text,
      target_lang: targetLang,
      ...(sourceLang && { source_lang: sourceLang }),
    }),
  });

  const data = await res.json();
  if (!res.ok) throw new Error(data.error.message);
  return data.text;
}

console.log(await translate("Hello, how are you?", "kbd", "en"));

<?php
function translate(string $text, string $target, ?string $source = null): string
{
    $payload = ["text" => $text, "target_lang" => $target];
    if ($source !== null) {
        $payload["source_lang"] = $source;
    }

    $ch = curl_init("https://api.circassian.ai/v1/translate");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            "Authorization: Bearer " . getenv("CIRCASSIAN_API_KEY"),
            "Content-Type: application/json",
        ],
        CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
        CURLOPT_TIMEOUT => 60,
    ]);

    $body = json_decode(curl_exec($ch), true);
    if (isset($body["error"])) {
        throw new RuntimeException($body["error"]["message"]);
    }
    return $body["text"];
}

echo translate("Hello, how are you?", "kbd", "en");

type translateRequest struct {
    Text       string `json:"text"`
    SourceLang string `json:"source_lang,omitempty"`
    TargetLang string `json:"target_lang"`
}

type translateResponse struct {
    Text       string `json:"text"`
    SourceLang string `json:"source_lang"`
    TargetLang string `json:"target_lang"`
}

func Translate(text, source, target string) (string, error) {
    body, _ := json.Marshal(translateRequest{text, source, target})

    req, _ := http.NewRequest("POST",
        "https://api.circassian.ai/v1/translate", bytes.NewReader(body))
    req.Header.Set("Authorization", "Bearer "+os.Getenv("CIRCASSIAN_API_KEY"))
    req.Header.Set("Content-Type", "application/json")

    resp, err := (&http.Client{Timeout: 60 * time.Second}).Do(req)
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        return "", fmt.Errorf("api: %s", resp.Status)
    }

    var out translateResponse
    json.NewDecoder(resp.Body).Decode(&out)
    return out.Text, nil
}

curl https://api.circassian.ai/v1/translate/batch \
  -H "Authorization: Bearer $CIRCASSIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": ["Good morning", "Thank you", "Goodbye"],
    "source_lang": "en",
    "target_lang": "ady"
  }'

r = httpx.post(
    f"{API}/v1/translate/batch",
    headers={"Authorization": f"Bearer {KEY}"},
    json={
        "texts": ["Good morning", "Thank you", "Goodbye"],
        "source_lang": "en",
        "target_lang": "ady",
    },
    timeout=120,
)
for line in r.json()["translations"]:
    print(line)

const res = await fetch(`${API}/v1/translate/batch`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    texts: ["Good morning", "Thank you", "Goodbye"],
    source_lang: "en",
    target_lang: "ady",
  }),
});

const { translations } = await res.json();
translations.forEach((t) => console.log(t));

<?php
$payload = [
    "texts" => ["Good morning", "Thank you", "Goodbye"],
    "source_lang" => "en",
    "target_lang" => "ady",
];

$ch = curl_init("https://api.circassian.ai/v1/translate/batch");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("CIRCASSIAN_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);

$body = json_decode(curl_exec($ch), true);
foreach ($body["translations"] as $line) {
    echo $line, PHP_EOL;
}

payload := map[string]any{
    "texts":       []string{"Good morning", "Thank you", "Goodbye"},
    "source_lang": "en",
    "target_lang": "ady",
}
body, _ := json.Marshal(payload)

req, _ := http.NewRequest("POST",
    "https://api.circassian.ai/v1/translate/batch", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("CIRCASSIAN_API_KEY"))
req.Header.Set("Content-Type", "application/json")

resp, _ := (&http.Client{Timeout: 120 * time.Second}).Do(req)
defer resp.Body.Close()

var out struct {
    Translations []string `json:"translations"`
}
json.NewDecoder(resp.Body).Decode(&out)
fmt.Println(out.Translations)

curl https://api.circassian.ai/v1/speech \
  -H "Authorization: Bearer $CIRCASSIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Сэлам, узыншэу ущыт", "language": "kbd", "voice": "female"}' \
  --output speech.wav

r = httpx.post(
    f"{API}/v1/speech",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"text": "Сэлам, узыншэу ущыт", "language": "kbd", "voice": "female"},
    timeout=120,
)
r.raise_for_status()

with open("speech.wav", "wb") as f:
    f.write(r.content)

print("duration:", r.headers["X-Audio-Duration"], "s")

import { writeFile } from "node:fs/promises";

const res = await fetch(`${API}/v1/speech`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Сэлам, узыншэу ущыт",
    language: "kbd",
    voice: "female",
  }),
});

if (!res.ok) throw new Error((await res.json()).error.message);

await writeFile("speech.wav", Buffer.from(await res.arrayBuffer()));
console.log("duration:", res.headers.get("X-Audio-Duration"), "s");

<?php
$payload = [
    "text" => "Сэлам, узыншэу ущыт",
    "language" => "kbd",
    "voice" => "female",
];

$ch = curl_init("https://api.circassian.ai/v1/speech");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("CIRCASSIAN_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
    CURLOPT_TIMEOUT => 120,
]);

file_put_contents("speech.wav", curl_exec($ch));

payload := map[string]string{
    "text":     "Сэлам, узыншэу ущыт",
    "language": "kbd",
    "voice":    "female",
}
body, _ := json.Marshal(payload)

req, _ := http.NewRequest("POST",
    "https://api.circassian.ai/v1/speech", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("CIRCASSIAN_API_KEY"))
req.Header.Set("Content-Type", "application/json")

resp, _ := (&http.Client{Timeout: 120 * time.Second}).Do(req)
defer resp.Body.Close()

audio, _ := io.ReadAll(resp.Body)
os.WriteFile("speech.wav", audio, 0o644)
fmt.Println("duration:", resp.Header.Get("X-Audio-Duration"), "s")

import os, time, httpx

API = "https://api.circassian.ai"
KEY = os.environ["CIRCASSIAN_API_KEY"]
AUTH = {"Authorization": f"Bearer {KEY}"}


def synthesize(text: str, language: str = "kbd", voice: str = "male") -> bytes:
    """Returns wav bytes regardless of the text length."""
    r = httpx.post(
        f"{API}/v1/speech",
        headers=AUTH,
        json={"text": text, "language": language, "voice": voice},
        timeout=120,
    )
    if r.status_code != 200:
        raise RuntimeError(r.json()["error"]["message"])

    # Short text — audio is already here.
    if r.headers["content-type"].startswith("audio/"):
        return r.content

    # Long text — wait for the job.
    job_id = r.json()["job_id"]
    while True:
        time.sleep(2)
        job = httpx.get(f"{API}/v1/jobs/{job_id}", headers=AUTH, timeout=30).json()

        if job["status"] == "done":
            audio = httpx.get(f"{API}{job['audio_url']}", headers=AUTH, timeout=60)
            return audio.content
        if job["status"] == "failed":
            raise RuntimeError(job["error"])


with open("long.wav", "wb") as f:
    f.write(synthesize("A long text…" * 200))

const API = "https://api.circassian.ai";
const auth = { Authorization: `Bearer ${process.env.CIRCASSIAN_API_KEY}` };
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export async function synthesize(text, language = "kbd", voice = "male") {
  const res = await fetch(`${API}/v1/speech`, {
    method: "POST",
    headers: { ...auth, "Content-Type": "application/json" },
    body: JSON.stringify({ text, language, voice }),
  });

  if (!res.ok) throw new Error((await res.json()).error.message);

  // Short text — audio is already here.
  if (res.headers.get("content-type").startsWith("audio/")) {
    return Buffer.from(await res.arrayBuffer());
  }

  // Long text — wait for the job.
  const { job_id } = await res.json();
  for (;;) {
    await sleep(2000);
    const job = await (
      await fetch(`${API}/v1/jobs/${job_id}`, { headers: auth })
    ).json();

    if (job.status === "done") {
      const audio = await fetch(`${API}${job.audio_url}`, { headers: auth });
      return Buffer.from(await audio.arrayBuffer());
    }
    if (job.status === "failed") throw new Error(job.error);
  }
}

# 1. Send the long text — receive a job
JOB=$(curl -s https://api.circassian.ai/v1/speech \
  -H "Authorization: Bearer $CIRCASSIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "…long text…", "language": "kbd"}' \
  | jq -r .job_id)

# 2. Wait until it is done
while true; do
  STATUS=$(curl -s "https://api.circassian.ai/v1/jobs/$JOB" \
    -H "Authorization: Bearer $CIRCASSIAN_API_KEY")
  STATE=$(echo "$STATUS" | jq -r .status)
  [ "$STATE" = "done" ] && break
  [ "$STATE" = "failed" ] && echo "$STATUS" | jq -r .error && exit 1
  sleep 2
done

# 3. Fetch the audio
URL=$(echo "$STATUS" | jq -r .audio_url)
curl -s "https://api.circassian.ai$URL" \
  -H "Authorization: Bearer $CIRCASSIAN_API_KEY" --output long.wav

import time, httpx

RETRIABLE = {429, 502, 503, 504}


def request_with_retry(method: str, url: str, attempts: int = 4, **kwargs):
    for attempt in range(attempts):
        r = httpx.request(method, url, **kwargs)
        if r.status_code not in RETRIABLE:
            return r

        # The service tells you when to come back — listen to it.
        pause = int(r.headers.get("Retry-After", 2 ** attempt))
        if r.json().get("error", {}).get("type") == "quota_exceeded":
            break  # daily quota: wait for tomorrow, do not hammer
        time.sleep(pause)
    return r

const RETRIABLE = new Set([429, 502, 503, 504]);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export async function requestWithRetry(url, options, attempts = 4) {
  let res;
  for (let attempt = 0; attempt < attempts; attempt++) {
    res = await fetch(url, options);
    if (!RETRIABLE.has(res.status)) return res;

    const body = await res.clone().json();
    // Daily quota: wait for tomorrow, do not hammer.
    if (body.error?.type === "quota_exceeded") break;

    const pause = Number(res.headers.get("Retry-After")) || 2 ** attempt;
    await sleep(pause * 1000);
  }
  return res;
}