API Reference
OpenAI-compatible API. Use any OpenAI SDK client - just change the base URL and access token.
Authentication
All API requests require a Bearer token in the Authorization header. The Yin/Yang catalog serves managed accounts (every new registration is managed); developer-policy accounts keep the raw model registry and raw model ids.
Header
Authorization: Bearer YOUR_ACCESS_TOKEN
The token is issued when you sign in to your Instachat account. Self-serve API keys are not available yet and new accounts are reviewed before activation. To request API access, write to [email protected].
Base URL
API base
https://brain.intch.cc
Reference
Endpoints
POST
/v1/chat/completions
Create a chat completion. Streaming and non-streaming; tools (function calling) and image input pass through; unknown parameters are refused with a 400 naming the supported set.
Request Body
Parameter
Type
Required
Description
Parameter
messages
Type
array
Required
Yes
Description
Array of message objects with role and content
Parameter
model
Type
string
Required
No
Description
yin or yang. Defaults to yin
Parameter
stream
Type
boolean
Required
No
Description
Enable SSE streaming. Default: false
Parameter
tools
Type
array
Required
No
Description
OpenAI function calling; your client executes the tools
Parameter
reasoning
Type
object
Required
No
Description
{"effort": "..."}. Yin defaults to minimal reasoning for speed
POST
/v1/audio/transcriptions
Speech to text: multipart file upload (up to 10 MB), answers {text}.
POST
/v1/audio/speech
Text to speech: input up to 2000 characters; ogg, wav, pcm or m4a out; pcm and wav stream as sentences are synthesized.
POST
/v1/search
Web search for agents: a query in, ranked results with title, url and snippet out. 429 carries Retry-After.
GET
/v1/realtime
Realtime voice over WebSocket with an OpenAI Realtime shaped event vocabulary (PCM16 audio deltas at 24 kHz). For production use, write to [email protected].
POST
/mcp
A Model Context Protocol server over streamable HTTP, same Bearer token; currently exposes a chat tool.
Quickstart
Code examples
cURL
curl -X POST https://brain.intch.cc/v1/chat/completions \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "yin",
"messages": [
{"role": "user", "content": "Explain quantum computing in one paragraph"}
]
}'Python
from openai import OpenAI
client = OpenAI(
base_url="https://brain.intch.cc/v1",
api_key="YOUR_ACCESS_TOKEN",
)
response = client.chat.completions.create(
model="yin",
messages=[
{"role": "user", "content": "Explain quantum computing in one paragraph"}
],
)
print(response.choices[0].message.content)Response
JSON
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1713200000,
"model": "yin",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Quantum computing harnesses ..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 85,
"total_tokens": 97
}
}TypeScript
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://brain.intch.cc/v1",
apiKey: "YOUR_ACCESS_TOKEN",
});
const response = await client.chat.completions.create({
model: "yang",
messages: [
{ role: "user", content: "Refactor this function to be pure." },
],
});
console.log(response.choices[0].message.content);Streaming (Python)
from openai import OpenAI
client = OpenAI(
base_url="https://brain.intch.cc/v1",
api_key="YOUR_ACCESS_TOKEN",
)
stream = client.chat.completions.create(
model="yin",
messages=[{"role": "user", "content": "Write a haiku about coding"}],
stream=True,
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")
print()GET
/v1/models
List all available models.
cURL
curl https://brain.intch.cc/v1/models \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response
{
"object": "list",
"data": [
{
"id": "yin",
"object": "model",
"owned_by": "soulful",
"display_name": "Yin",
"description": "Fast tasks",
"context_window": 1048576,
"max_output_tokens": 65536,
"capabilities": { "tools": true, "images": true, "reasoning": true }
},
{
"id": "yang",
"object": "model",
"owned_by": "soulful",
"display_name": "Yang",
"description": "Coding",
"context_window": 1048576,
"max_output_tokens": 393216,
"capabilities": { "tools": true, "images": true, "reasoning": true }
}
]
}Models
Two models
Pick by the shape of the task: both support streaming, tools and image input, with context windows in the million-token range.
Model ID
Name
Best for
Model ID
yin
Name
Yin
Best for
Fast tasks: chat, summarization, extraction. Lowest latency, streaming-first.
Model ID
yang
Name
Yang
Best for
Coding and deep work: larger answers, tool-heavy agent loops.
Model versions: what serves Yin and Yang advances over time under the same names, the way other providers move the model behind an alias. Query GET /v1/models for the current context window, max output tokens and capabilities instead of hardcoding them.
Errors
Error handling
The API returns standard OpenAI-compatible error responses.
Status
Meaning
Status
400
Meaning
Invalid request (missing messages, bad JSON, unsupported parameter)
Status
401
Meaning
Invalid, expired or missing access token
Status
403
Meaning
Account not yet approved, or model not available to this account
Status
404
Meaning
Model not found
Status
429
Meaning
Rate limit exceeded; the response carries a Retry-After header
Status
500
Meaning
Server error (model timeout, provider issue)
Error response
{
"error": {
"message": "That model is not available on this account. Available models: yin, yang.",
"type": "invalid_request_error",
"code": "model_not_allowed"
}
}Limits
Rate limits
When a limit is reached the API answers 429 with a Retry-After header saying how many seconds to wait. Limits can change during early access.
Surface
Limit
Surface
Chat completions
Limit
1000 requests per hour per account
Surface
Search
Limit
30 requests per 10 minutes, 200 per day
Surface
Audio (each endpoint)
Limit
30 requests per minute
Plans offered inside the Instachat Telegram bot apply to the bot, not to this API.