API Documentation

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1714000000,
  "model": "<model-id>",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Quantum computing uses qubits instead of traditional bits..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 150,
    "total_tokens": 178
  }
}

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023, -0.0091, 0.0152, ...]
    }
  ],
  "model": "<embedding-model-id>",
  "usage": { "prompt_tokens": 9, "total_tokens": 9 }
}

{
  "object": "list",
  "data": [
    { "id": "<model-id-1>", "object": "model", "created": 1714000000, "owned_by": "your-gateway" },
    { "id": "<model-id-2>", "object": "model", "created": 1714000000, "owned_by": "your-gateway" }
  ]
}

{
  "id": "<model-id>",
  "object": "model",
  "created": 1714000000,
  "owned_by": "your-gateway"
}

{
  "object": "list",
  "data": [
    {
      "id": "uuid",
      "model_id": "<model-id>",
      "model_type": "chat",
      "is_available": true,
      "health_status": "healthy",
      "last_health_latency_ms": 245
    }
  ],
  "total": 150, "healthy": 142, "down": 3, "unknown": 5
}

{
  "task": "transcribe",
  "language": "english",
  "duration": 42.5,
  "text": "Welcome to the API. This is a transcription test.",
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 4.2,
      "text": " Welcome to the API.",
      "avg_logprob": -0.21,
      "no_speech_prob": 0.003
    },
    {
      "id": 1,
      "start": 4.2,
      "end": 8.1,
      "text": " This is a transcription test.",
      "avg_logprob": -0.18,
      "no_speech_prob": 0.001
    }
  ]
}

from openai import OpenAI

client = OpenAI(
    base_url="https://llm.rooyai.com/v1",
    api_key="sk-your-api-key"
)

# verbose_json — includes duration for accurate billing
with open("/path/to/audio.mp3", "rb") as audio_file:
    transcript = client.audio.transcriptions.create(
        model="whisper-large-v3-turbo",
        file=audio_file,
        language="en",                   # optional — improves speed & accuracy
        response_format="verbose_json",  # recommended
    )

print(transcript.text)
print(f"Language : {transcript.language}")
print(f"Duration : {transcript.duration:.1f}s")
for seg in transcript.segments:
    print(f"  [{seg.start:.1f}s -> {seg.end:.1f}s] {seg.text}")

# Plain text (no duration field returned)
with open("/path/to/audio.mp3", "rb") as audio_file:
    text = client.audio.transcriptions.create(
        model="whisper-large-v3-turbo",
        file=audio_file,
        response_format="text",
    )
print(text)

from openai import OpenAI
from pathlib import Path

client = OpenAI(
    base_url="https://llm.rooyai.com/v1",
    api_key="sk-your-api-key"
)

# ── Option A: Save directly to a file (OpenAI SDK streaming helper) ───────
with client.audio.speech.with_streaming_response.create(
    model="rooyai-tts",
    voice="alloy",
    input="Hello! This is a test of the RooyaLLM text-to-speech API.",
    response_format="mp3",   # mp3 | opus | aac | flac | wav | pcm
    speed=1.0,               # 0.25 – 4.0
) as response:
    response.stream_to_file(Path("speech.mp3"))
print("Saved speech.mp3")

# ── Option B: Read into memory (small inputs only) ────────────────────────
audio = client.audio.speech.create(
    model="rooyai-tts",
    voice="nova",
    input="Short text for in-memory synthesis.",
    response_format="mp3",
)
audio_bytes = audio.read()
print(f"Received {len(audio_bytes):,} bytes of MP3 audio")

# ── Option C: Stream using requests (for custom handling) ─────────────────
import requests

with requests.post(
    f"https://llm.rooyai.com/v1/audio/speech",
    headers={
        "Authorization": "Bearer sk-your-api-key",
        "Content-Type": "application/json",
    },
    json={
        "model": "rooyai-tts",
        "input": "Streaming audio delivery with zero buffering.",
        "voice": "shimmer",
        "response_format": "opus",
        "speed": 1.1,
    },
    stream=True,
    timeout=90,
) as r:
    r.raise_for_status()
    with open("speech.opus", "wb") as f:
        for chunk in r.iter_content(chunk_size=4096):
            f.write(chunk)
print("Saved speech.opus")

import requests

BASE_URL = "https://llm.rooyai.com"
API_KEY  = "sk-your-api-key"

headers = {"Authorization": f"Bearer {API_KEY}"}

# ── Option A: OCR a PDF from a URL ──────────────────────────────────────────
response = requests.post(
    f"{BASE_URL}/v1/ocr",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "model": "mistral-ocr-latest",
        "document": {
            "type": "document_url",
            "document_url": "https://example.com/document.pdf",
        },
        "table_format": "markdown",      # optional
    },
    timeout=300,
)
data = response.json()
print(f"Pages processed: {data['usage_info']['pages_processed']}")
for page in data["pages"]:
    print(f"\n--- Page {page['index'] + 1} ---")
    print(page["markdown"])             # full Markdown for this page

# ── Option B: Upload a local file and OCR ───────────────────────────────────
with open("/path/to/document.pdf", "rb") as f:
    upload_response = requests.post(
        f"{BASE_URL}/v1/ocr/upload",
        headers=headers,
        files={"file": ("document.pdf", f, "application/pdf")},
        data={
            "model": "mistral-ocr-latest",
            "pages": "0-9",              # first 10 pages only (optional)
        },
        timeout=300,
    )
upload_data = upload_response.json()
full_text = "\n\n".join(p["markdown"] for p in upload_data["pages"])
print(full_text)

import base64
import requests
from pathlib import Path
from openai import OpenAI

BASE_URL = "https://llm.rooyai.com"
API_KEY  = "sk-your-api-key"

client = OpenAI(base_url=f"{BASE_URL}/v1", api_key=API_KEY)

# ── Option A: Standard PNG via OpenAI SDK ────────────────────────────────────
response = client.images.generate(
    model="flux-schnell",
    prompt="a majestic mountain at golden hour, photorealistic, 8k",
    n=1,                      # integer — NOT a string
    size="1024x1024",
    response_format="b64_json",
)
Path("output.png").write_bytes(base64.b64decode(response.data[0].b64_json))
print("Saved output.png")

# ── Option B: JPEG with quality control (via requests — OpenAI SDK strips
#             unknown fields like output_format / output_quality) ────────────
resp = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers={"Authorization": f"Bearer {API_KEY}",
             "Content-Type": "application/json"},
    json={
        "model": "flux-schnell",
        "prompt": "aerial view of a tropical island, turquoise water, cinematic",
        "n": 1,               # integer
        "size": "1792x1024",
        "response_format": "b64_json",
        "output_format": "jpeg",
        "output_quality": 80, # integer 1–100
    },
    timeout=120,
)
resp.raise_for_status()
data = resp.json()
img_bytes = base64.b64decode(data["data"][0]["b64_json"])
Path("output.jpg").write_bytes(img_bytes)
print(f"Saved output.jpg ({len(img_bytes) // 1024} KB)")

# ── Option C: WebP (smallest for web delivery) ────────────────────────────
resp = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers={"Authorization": f"Bearer {API_KEY}",
             "Content-Type": "application/json"},
    json={
        "model": "flux-schnell",
        "prompt": "futuristic city skyline at night, neon lights, ultra detailed",
        "n": 1,
        "size": "1024x1024",
        "response_format": "b64_json",
        "output_format": "webp",
        "output_quality": 90,
    },
    timeout=120,
)
resp.raise_for_status()
data = resp.json()
Path("output.webp").write_bytes(base64.b64decode(data["data"][0]["b64_json"]))
print("Saved output.webp")

# ── Option D: Generate multiple images concurrently (asyncio + httpx) ────────
# The gateway supports up to 20 concurrent image gen requests per API key.
# Use asyncio to fire them in parallel — total wall time ≈ 1 image time.
import asyncio, httpx

async def generate_image(client: httpx.AsyncClient, prompt: str, index: int):
    resp = await client.post(
        f"{BASE_URL}/v1/images/generations",
        json={
            "model": "flux-schnell",
            "prompt": prompt,
            "n": 1,
            "size": "1024x1024",
            "response_format": "b64_json",
            "output_format": "jpeg",
            "output_quality": 80,
        },
        timeout=120,
    )
    resp.raise_for_status()
    data = resp.json()
    Path(f"batch_{index}.jpg").write_bytes(
        base64.b64decode(data["data"][0]["b64_json"])
    )
    print(f"Saved batch_{index}.jpg")

async def main():
    prompts = [
        "a red rose in the rain, macro photography",
        "a golden desert dune at sunrise, epic scale",
        "a futuristic Tokyo street at night, neon rain",
    ]
    headers = {"Authorization": f"Bearer {API_KEY}",
               "Content-Type": "application/json"}
    async with httpx.AsyncClient(headers=headers) as client:
        await asyncio.gather(*[
            generate_image(client, p, i) for i, p in enumerate(prompts)
        ])
    print("All images saved!")

asyncio.run(main())

{
  "status": "ok",
  "timestamp": "2026-04-25T02:00:00.000Z",
  "uptime": 86400,
  "memory": { "rss": 128, "heap": 64 }
}

from openai import OpenAI
import json

client = OpenAI(
    base_url="https://llm.rooyai.com/v1",
    api_key="sk-your-api-key"
)

# -- Step 1: Define your tools ----------------------------
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "City name"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                },
                "required": ["city"]
            }
        }
    }
]

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user",   "content": "What is the weather in Cairo?"}
]

# -- Step 2: First call - model returns tool_calls --------
response = client.chat.completions.create(
    model="<your-chat-model>",
    messages=messages,
    tools=tools,
    tool_choice="auto"
)

assistant_msg = response.choices[0].message
print(f"finish_reason: {response.choices[0].finish_reason}")
# Output: finish_reason: tool_calls

# -- Step 3: Execute your real function ------------------
def get_weather(city, unit="celsius"):
    return {"city": city, "temperature": 32, "unit": unit, "condition": "sunny"}

tool_results = []
for tc in assistant_msg.tool_calls:
    args = json.loads(tc.function.arguments)
    result = get_weather(**args)
    tool_results.append({
        "role": "tool",
        "tool_call_id": tc.id,
        "content": json.dumps(result)
    })

# -- Step 4: Second call - send results back --------------
messages.append(assistant_msg)
messages.extend(tool_results)

final = client.chat.completions.create(
    model="<your-chat-model>",
    messages=messages,
    tools=tools
)

print(final.choices[0].message.content)
# Output: "The current weather in Cairo is 32degC and sunny."

from openai import OpenAI
import base64

client = OpenAI(
    base_url="https://llm.rooyai.com/v1",
    api_key="sk-your-api-key"
)

# ── Option A: Image URL ──────────────────────────────────────────
response = client.chat.completions.create(
    model="<your-chat-model>",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What is in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png",
                        "detail": "auto"  # "auto", "low", or "high"
                    }
                }
            ]
        }
    ],
    max_tokens=300
)
print(response.choices[0].message.content)

# ── Option B: Local file as base64 ──────────────────────────────
with open("image.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

response = client.chat.completions.create(
    model="<your-chat-model>",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe this image."},
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/jpeg;base64,{image_data}"}
                }
            ]
        }
    ]
)
print(response.choices[0].message.content)

from openai import OpenAI
import base64

client = OpenAI(
    base_url="https://llm.rooyai.com/v1",
    api_key="sk-your-api-key"
)

# Read the image file and encode it to a base64 data URL
with open("image.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

# Build the data URL — the gateway accepts any image MIME type
data_url = f"data:image/jpeg;base64,{image_data}"

response = client.chat.completions.create(
    model="<your-chat-model>",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What is in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": data_url,
                        "detail": "auto"  # "auto" | "low" | "high"
                    }
                }
            ]
        }
    ],
    max_tokens=300
)

print(response.choices[0].message.content)
# usage.prompt_tokens will include the image token cost
print(f"Tokens used: {response.usage.prompt_tokens} prompt / {response.usage.completion_tokens} completion")