Step 1
Add credits
API requests use your CircuitNotion credit balance. Top up with MoMo or card on Pricing & credits in the Developer Platform.
Open Pricing & creditsCircuitNotion AI API
Your first successful request
OpenAI SDK-compatible interface for CircuitNotion, OpenAI, DeepSeek, Anthropic, and Moonshot. Fund credits, create a server-side key, then call the live catalog.
Livehttps://api.circuitnotion.com/v1
1curl "https://api.circuitnotion.com/v1/chat/completions" \
2 -H "Authorization: Bearer $CIRCUITNOTION_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "model": "gpt-4o-mini",
6 "messages": [
7 {"role": "user", "content": "Write a friendly welcome message."}
8 ]
9 }'Quickstart
Start in three steps
The platform, billing, and API work together.
Step 2
Create an API key
Sign in, open Generate API Key, name the key, and store it server-side only.
Generate API KeyStep 3
Send a request
Point the OpenAI SDK at our base URL, or use curl above. Check GET /v1/models for live IDs.
Requests return HTTP 402 Payment Required when no usable credit balance remains. Add credits before running production workloads.
Python quickstart
Store the key in CIRCUITNOTION_API_KEY, then run:
1import os
2from openai import OpenAI
3
4client = OpenAI(
5 base_url="https://api.circuitnotion.com/v1",
6 api_key=os.environ["CIRCUITNOTION_API_KEY"],
7)
8
9response = client.chat.completions.create(
10 model="circuit-2-turbo",
11 messages=[
12 {"role": "user", "content": "Explain APIs in one short paragraph."}
13 ],
14)
15
16print(response.choices[0].message.content)
17print(response.usage)Stream responses
Always check chunk.choices. The final token-accounting chunk can contain an empty choices array.
1stream = client.chat.completions.create(
2 model="circuit-2-turbo",
3 messages=[
4 {"role": "user", "content": "Give me five practical productivity tips."}
5 ],
6 stream=True,
7)
8
9for chunk in stream:
10 # The final usage-only chunk can have an empty choices array.
11 if chunk.choices and chunk.choices[0].delta.content:
12 print(chunk.choices[0].delta.content, end="", flush=True)
13
14print()JavaScript
Install with npm install openai.
1import OpenAI from "openai";
2
3const client = new OpenAI({
4 baseURL: "https://api.circuitnotion.com/v1",
5 apiKey: process.env.CIRCUITNOTION_API_KEY,
6});
7
8const response = await client.chat.completions.create({
9 model: "deepseek-v4-flash",
10 messages: [
11 { role: "user", content: "Summarize why API timeouts are important." },
12 ],
13});
14
15console.log(response.choices[0].message.content);cURL
Send a direct chat-completions request.
1curl "https://api.circuitnotion.com/v1/chat/completions" \
2 -H "Authorization: Bearer $CIRCUITNOTION_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "model": "gpt-4o-mini",
6 "messages": [
7 {"role": "user", "content": "Write a friendly welcome message."}
8 ]
9 }'Choose a model
Aliases can route to different upstream providers. Use the live catalog for current availability and prices — reference rows are not yet available.
curl "https://api.circuitnotion.com/v1/models" \
-H "Authorization: Bearer $CIRCUITNOTION_API_KEY"| Model ID | Provider | Status | Recommended use |
|---|---|---|---|
| auto | CircuitNotion router | Live | Automatically select an available route |
| circuit-2-turbo | CircuitNotion router | Live | General chat with a speed-focused route |
| circuit-1-mini | CircuitNotion router | Live | Lightweight, cost-sensitive work |
| circuit-3 | CircuitNotion router | Live | More advanced tasks |
| gpt-4o | OpenAI | Live | Multimodal and general-purpose work |
| gpt-4o-mini | OpenAI | Live | Economical OpenAI workloads |
| gpt-4.1 | OpenAI | Live | Instruction following and coding |
| gpt-4.1-mini | OpenAI | Live | Balanced performance and cost |
| gpt-4.1-nano | OpenAI | Live | Classification and extraction tasks |
| deepseek-v4-flash | DeepSeek | Live | Low-latency, high-volume workloads |
| deepseek-v4-pro | DeepSeek | Live | Reasoning and coding |
| kimi | Moonshot | Live | Kimi alias → Kimi K3 |
| kimi-k3 | Moonshot | Live | Kimi K3 flagship (1M context) |
| kimi-k2.7-code | Moonshot | Live | Dedicated coding model |
| kimi-k2.7-code-highspeed | Moonshot | Live | High-speed coding model |
| kimi-k2.6 | Moonshot | Live | General-purpose multimodal Kimi |
| claude | Anthropic | Live | Claude alias → Sonnet 5 |
| claude-fable-5 | Anthropic | Live | Mythos-class flagship |
| claude-mythos-5 | Anthropic | Live | Mythos 5 (Glasswing / limited upstream) |
| claude-opus-5 | Anthropic | Live | Claude Opus 5 |
| claude-sonnet-5 | Anthropic | Live | Claude Sonnet 5 |
| claude-haiku-4-5 | Anthropic | Live | Claude Haiku 4.5 |
Billing
How credits are charged
- Input and output tokens use separate provider rates.
- Standard and streamed requests are both billed.
- CircuitNotion applies a 15% platform and routing fee.
- Charges are converted to Rwandan francs.
- Routed aliases use the rate of the model that handled the request.
- The
/v1/modelsresponse is authoritative for current prices.
Common errors
Handle failures explicitly
400Invalid request
401Missing, invalid, or revoked API key
402Insufficient credits
404Unknown model or endpoint
429Request rate limit reached
500Internal processing error
503Selected provider is unavailable or not configured
Error handling example
1from openai import APIConnectionError, APIStatusError, RateLimitError
2
3try:
4 response = client.chat.completions.create(
5 model="circuit-2-turbo",
6 messages=[{"role": "user", "content": "Hello"}],
7 )
8except RateLimitError:
9 print("Too many requests. Retry with exponential backoff.")
10except APIConnectionError:
11 print("Could not reach the CircuitNotion API.")
12except APIStatusError as error:
13 print(f"API error {error.status_code}: {error.response}")Production checklist
- Store API keys in a server-side environment variable or secret manager.
- Set connection and request timeouts.
- Retry only transient 429, 500, and 503 responses with exponential backoff.
- Check choices before reading a streaming chunk.
- Set max_tokens to control latency and cost.
- Use the live model catalog instead of hardcoding availability or prices.
- Monitor credits on Pricing & credits in the Developer Platform.
- Revoke and replace exposed API keys immediately.
Start building
Use the CircuitNotion AI API
Fund credits, generate a server-side API key, and use the live model catalog for current availability and rates.