API Reference

OpenAI-compatible API. Use any OpenAI SDK client: set the base URL and your access token.

Authentication

All API requests require a Bearer token in the Authorization header. The token is issued when you sign in to your Instachat account. 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

API access: 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

https://brain.intch.cc

Models

The API serves two models. Pick by the shape of the task, not by vendor: both support streaming, tools (function calling) and image input, with context windows in the million-token range.

Model ID	Name	Best for
`yin`	Yin	Fast tasks: chat, summarization, extraction. Lowest latency, streaming-first.
`yang`	Yang	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.

Endpoints

POST/v1/chat/completions

Create a chat completion. Supports streaming and non-streaming responses, a client-owned tool loop (tools, tool_choice, assistant tool_calls and role: "tool" results pass through), and image input via image_url content parts.

Request Body

Parameter	Type	Required	Description
`model`	string	No	`yin` or `yang`. Defaults to `yin`
`messages`	array	Yes	Array of message objects with `role` and `content`
`stream`	boolean	No	Enable SSE streaming. Default: `false`
`stream_options`	object	No	`{"include_usage": true}` adds a usage event to the stream
`tools`, `tool_choice`	array, object	No	OpenAI function calling; your client executes the tools
`reasoning`	object	No	`{"effort": "..."}`. Yin defaults to minimal reasoning for speed; send your own value to override

Unknown top-level parameters are refused with a 400 that names the supported set, never silently dropped.

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)

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()

Response

JSON

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1789660000,
  "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
  }
}

GET/v1/models

List the available models with their current limits and capabilities. This is the source of truth for context window and max output tokens.

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 }
    }
  ]
}

POST/v1/audio/transcriptions

Speech to text. Multipart upload with a file field (up to 10 MB); answers {"text": "..."}.

curl

curl -X POST https://brain.intch.cc/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "[email protected]"

POST/v1/audio/speech

Text to speech. input up to 2000 characters; response_format one of ogg, wav, pcm, m4a; optional language. The pcm and wav formats stream as the sentences are synthesized.

curl

curl -X POST https://brain.intch.cc/v1/audio/speech \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello from Instachat.", "response_format": "wav"}' \
  --output hello.wav

POST/v1/search

Web search for agents: a query in, ranked results out, no model call in between.

Parameter	Type	Required	Description
`query`	string	Yes	Up to 400 characters
`limit`	number	No	1 to 10 results. Default: 5
`allowed_domains`, `blocked_domains`	array	No	Up to 10 domains each
`freshness`	string	No	`"auto"` (recency window for time-sensitive queries) or `"none"`

Response

{
  "results": [
    { "title": "...", "url": "https://...", "snippet": "..." }
  ],
  "searched_at": "2026-09-17T16:00:00Z"
}

GET/v1/realtime

Realtime voice over WebSocket, with an OpenAI Realtime shaped event vocabulary: session.*, input_audio_buffer.*, response.output_audio.delta (base64 PCM16 at 24 kHz), response.done. Authenticate with a Bearer header or the openai-insecure-api-key.YOUR_ACCESS_TOKEN WebSocket subprotocol. Signed-in accounts can use it today; for production or third-party use, write to [email protected].

POST/mcp

A Model Context Protocol server over streamable HTTP, using the same Bearer token. It currently exposes a chat tool. Point any MCP client at it:

MCP client config

{
  "mcpServers": {
    "instachat": {
      "type": "http",
      "url": "https://brain.intch.cc/mcp",
      "headers": { "Authorization": "Bearer YOUR_ACCESS_TOKEN" }
    }
  }
}

Errors

The API returns standard OpenAI-compatible error responses.

Status	Meaning
`400`	Invalid request (missing messages, bad JSON, unsupported parameter)
`401`	Invalid, expired or missing access token
`403`	Account not yet approved, or model not available to this account
`404`	Model not found
`429`	Rate limit exceeded; the response carries a `Retry-After` header
`500`	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"
  }
}

Rate Limits

Surface	Limit
Chat completions	1000 requests per hour per account
Search	30 requests per 10 minutes, 200 per day
Audio (each endpoint)	30 requests per minute

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.

Plans offered inside the Instachat Telegram bot apply to the bot, not to this API.

NextPrivacy policy