API v1

RanoAI API Reference

The RanoAI API provides OpenAI-compatible inference for Gemma 4 and Qwen 3.5 models, served on NPU hardware (Furiosa RNGD).

If you already use the OpenAI SDK, migration is a one-line change — swap base_url to https://api.ranoai.com/v1.

Authentication

All API requests require a Bearer token in the Authorization header. Get your API key from the Console.

http

Authorization: Bearer rno-xxxxxxxxxxxxxxxxxxxxxxxx

Keep your API key secret. Do not expose it in client-side code or public repositories. Use environment variables to manage keys.

Quick Start

Make your first request in under a minute.

python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.ranoai.com/v1",
    api_key="rno-xxxxxxxxxxxxxxxxxxxxxxxx",
)

response = client.chat.completions.create(
    model="gemma-4-12b",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain NPU vs GPU in one paragraph."},
    ],
)

print(response.choices[0].message.content)

Chat Completions

POST/v1/chat/completions

Creates a model response for the given conversation. Compatible with the OpenAI Chat Completions API.

Request Body

modelstringrequired

ID of the model to use. See the Models section for available options.

messagesarrayrequired

A list of messages comprising the conversation. Each message has a role (system, user, or assistant) and content.

max_tokensinteger

Maximum number of tokens to generate. Defaults to 4096.

temperaturenumber

Sampling temperature between 0 and 2. Higher values produce more random output. Defaults to 1.

top_pnumber

Nucleus sampling: consider only tokens with cumulative probability >= top_p. Defaults to 1.

streamboolean

If true, returns a stream of server-sent events. Defaults to false.

stopstring | array

Up to 4 sequences where the API will stop generating further tokens.

Example Request

python

response = client.chat.completions.create(
    model="gemma-4-31b",
    messages=[
        {"role": "system", "content": "You are a coding assistant."},
        {"role": "user", "content": "Write a binary search in Python."},
    ],
    max_tokens=1024,
    temperature=0.7,
)

Response

json

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1751234567,
  "model": "gemma-4-31b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "def binary_search(arr, target):\n    ..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 312,
    "total_tokens": 340
  }
}

Streaming

Set stream=True to receive tokens as server-sent events (SSE) as they are generated, reducing time-to-first-token latency.

python

stream = client.chat.completions.create(
    model="gemma-4-26b",
    messages=[{"role": "user", "content": "Write a short story."}],
    stream=True,
)

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

SSE Format

text

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"delta":{"content":"Once"},"index":0}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"delta":{"content":" upon"},"index":0}]}

data: [DONE]

Models

All models support a 128K context window and multimodal input.

Model ID	Family	Params	Context	Input	Output
gpt-oss-120b	GPT-OSS	120B	128K	$0.60/1M	$1.80/1M
gemma-4-31b	Gemma 4	31B	128K	$0.25/1M	$0.75/1M
gemma-4-26b	Gemma 4	26B	128K	$0.20/1M	$0.60/1M
gemma-4-12b	Gemma 4	12B	128K	$0.08/1M	$0.25/1M
qwen-3.5-35b	Qwen 3.5	35B	128K	$0.28/1M	$0.85/1M
qwen-3.5-27b	Qwen 3.5	27B	128K	$0.18/1M	$0.55/1M

Python SDK

Install the official OpenAI Python library.

bash

pip install openai

python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.ranoai.com/v1",
    api_key=os.environ["RANOAI_API_KEY"],
)

response = client.chat.completions.create(
    model="qwen-3.5-35b",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

Node.js SDK

Install the official OpenAI Node.js library.

bash

npm install openai

javascript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.ranoai.com/v1",
  apiKey: process.env.RANOAI_API_KEY,
});

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

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

cURL

bash

curl https://api.ranoai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RANOAI_API_KEY" \
  -d '{
    "model": "gemma-4-12b",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Error Codes

Status	Error	Description
400	invalid_request_error	Malformed request or missing required parameters.
401	authentication_error	Invalid or missing API key.
429	rate_limit_error	You have exceeded your rate limit. Retry after the indicated period.
500	server_error	Internal server error. Contact support if this persists.
503	overloaded_error	The NPU cluster is temporarily at capacity. Retry with exponential backoff.

Rate Limits

Plan	Requests / min	Tokens / min	Monthly quota
Free	10	40,000	1M tokens
Pay-as-you-go	600	2,000,000	Unlimited
Enterprise	Custom	Custom	Unlimited

Rate limits are applied per API key. Exceeding limits returns a 429 response with a Retry-After header.