Developer Documentation & API

BatchIn Developer Documentation

Complete docs organized around quick start, API reference, tutorials, and cookbook content.

Get API Key Explore Models

Runtime Contract & Specifications

Production posture

Built for stable production-scale text and multimodal traffic.

Capability mix

Text and multimodal traffic share one Model API contract.

Agent protocols

OpenAI-compatible access, MCP, and llms.txt are exposed together.

Traffic policy

TTFT, backpressure, slow-consumer isolation, and regional rate limits.

Public Addresses & Protocols

OpenAPI

https://api.batchin.tech/openapi.json

API base

https://api.batchin.tech/v1

MCP

https://api.batchin.tech/v1/mcp

Public endpoints

/v1/chat/completions · /v1/responses · /v1/embeddings · /v1/images · /v1/audio/* · /v1/videos

Concurrency & Billing Semantics

Global and regional endpoints serve their audiences with a unified API experience.

Scoped rate limits and timeout controls apply by key, workspace, and region with clear failure classification.

Standard enterprise traffic uses the high-performance shared core; dedicated capacity routes to isolated pools.

Human billing and agent settlement stay separated, backed by Ed25519 cryptographic receipts.

Quickstart Guide

Quick Start (3 Languages)

1) Install

pip install openai

2) First Request

from openai import OpenAI

client = OpenAI(
  base_url="https://api.batchin.tech/v1",
  api_key="YOUR_API_KEY"
)

resp = client.chat.completions.create(
  model="deepseek-v4-pro",
  messages=[{"role": "user", "content": "Hello from BatchIn"}]
)
print(resp.choices[0].message.content)

3) Streaming

stream = client.chat.completions.create(
  model="deepseek-v4-pro",
  messages=[{"role": "user", "content": "Write a fast python async worker"}],
  stream=True
)

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

Platform Playbooks

Dedicated Endpoints & Concurrency Pools

See the self-serve path for dedicated endpoints, private throughput usage, billing, and settlement.

Open

Dedicated Capacity Path

Understand dedicated endpoints, private deployment boundaries, key formats, and usage separation before you start a capacity rollout.

Open

Route Control + Failover Path

Review how BatchIn positions route control, batch lanes, and fallback behavior before moving production traffic.

Open

Audit Trace Verification Path

Open the public verification flow, inspect a signed evidence pack, and reproduce the trust check in the browser.

Open

OTLP Observability Path

Review the reserved OTLP ingest/export surface and the planned bridge from native traces into external observability tools.

Open

API Reference

GET/v1/users/me

Bearer

Code Samples

curl -X GET https://api.batchin.tech/v1/users/me \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \

Open Try it

POST/v1/keys

Bearer

Code Samples

curl -X POST https://api.batchin.tech/v1/keys \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Production Key",
  "rate_limit_rpm": 120,
  "monthly_budget_cents": 500000
}'

Parameters

Name	Type	Required
name	string	No
rate_limit_rpm	number	No
monthly_budget_cents	number	No

Open Try it

GET/v1/keys

Bearer

Code Samples

curl -X GET https://api.batchin.tech/v1/keys \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \

Open Try it

DELETE/v1/keys/{id}

Bearer

Code Samples

curl -X DELETE https://api.batchin.tech/v1/keys/{id} \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \

Parameters

Name	Type	Required	Description
id	path:uuid	Yes

Open Try it

POST/v1/chat/completions

Bearer

Code Samples

curl -X POST https://api.batchin.tech/v1/chat/completions \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen3.8-max",
  "messages": [{"role":"user","content":"Explain attention in 3 bullets"}],
  "temperature": 0.7,
  "stream": false
}'

Parameters

Name	Type	Required
model	string	Yes
messages	array	Yes
temperature	number	No
max_tokens	number	No
stream	boolean	No

Open Try it

POST/v1/responses

Bearer

Code Samples

curl -X POST https://api.batchin.tech/v1/responses \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen3.8-max",
  "input": "Explain batch inference in 3 bullets",
  "max_output_tokens": 256
}'

Parameters

Name	Type	Required
model	string	Yes
input	string\|array	Yes
max_output_tokens	number	No
stream	boolean	No

Open Try it

POST/v1/completions

Bearer

Code Samples

curl -X POST https://api.batchin.tech/v1/completions \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen3.8-max",
  "prompt": "Complete this sentence: Batch processing helps",
  "suffix": "for large workloads.",
  "max_tokens": 128
}'

Parameters

Name	Type	Required
model	string	Yes
prompt	string\|array	Yes
suffix	string	No
max_tokens	number	No

Open Try it

POST/v1/embeddings

Bearer

Code Samples

curl -X POST https://api.batchin.tech/v1/embeddings \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "bge-m3",
  "input": ["batch inference", "retrieval augmented generation"]
}'

Parameters

Name	Type	Required	Description
model	string	Yes
input	string\|array	Yes

Open Try it

POST/v1/audio/speech

Bearer

Code Samples

curl -X POST https://api.batchin.tech/v1/audio/speech \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "tts-1",
  "input": "Welcome to BatchIn",
  "voice": "alloy",
  "response_format": "mp3"
}'

Parameters

Name	Type	Required
model	string	Yes
input	string	Yes
voice	string	No
response_format	string	No

Open Try it

POST/v1/audio/transcriptions

Bearer

Code Samples

curl -X POST https://api.batchin.tech/v1/audio/transcriptions \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \
  -F "file=@meeting.wav" \
  -F "model=whisper-large-v3-turbo" \
  -F "response_format=verbose_json" \
  -F "language=en"

Parameters

Name	Type	Required
file	binary	Yes
model	string	Yes
language	string	No
prompt	string	No
response_format	string	No
temperature	number\|string	No

Open Try it

POST/v1/videos

Bearer

Code Samples

curl -X POST https://api.batchin.tech/v1/videos \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Cyberpunk city night drone tracking shot, neon reflections",
  "model": "wan3.0-video",
  "duration_seconds": 5,
  "resolution": "1080p"
}'

Parameters

Name	Type	Required
prompt	string	Yes
model	string	No
duration_seconds	integer	No
resolution	string	No

Open Try it

POST/v1/images/generations

Bearer

Code Samples

curl -X POST https://api.batchin.tech/v1/images/generations \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Minimalist geometric architectural rendering, dusk light",
  "model": "doubao-seedream-5-0-260128",
  "n": 1,
  "size": "1024x1024"
}'

Parameters

Name	Type	Required
prompt	string	Yes
model	string	No
n	integer	No
size	string	No

Open Try it

GET/v1/models

Bearer

Code Samples

curl -X GET https://api.batchin.tech/v1/models \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \

Open Try it

POST/v1/batches

Bearer

Code Samples

curl -X POST https://api.batchin.tech/v1/batches \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "priority": "fill",
  "webhook_url": "https://your-domain.com/webhooks/batchin",
  "tasks": [
    {"custom_id":"task-1","model":"qwen3.8-max","request_body":{"messages":[{"role":"user","content":"translate this"}]}},
    {"custom_id":"task-2","model":"glm-5.3","request_body":{"messages":[{"role":"user","content":"summarize this"}]}}
  ]
}'

Parameters

Name	Type	Required
tasks	array	Yes
priority	string(high\|low\|fill)	No
webhook_url	string(url)	No

Open Try it

GET/v1/batches

Bearer

Code Samples

curl -X GET https://api.batchin.tech/v1/batches \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \

Open Try it

GET/v1/batches/{id}

Bearer

Code Samples

curl -X GET https://api.batchin.tech/v1/batches/{id} \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \

Parameters

Name	Type	Required	Description
id	path:uuid	Yes

Open Try it

POST/v1/batches/{id}/cancel

Bearer

Code Samples

curl -X POST https://api.batchin.tech/v1/batches/{id}/cancel \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \

Parameters

Name	Type	Required	Description
id	path:uuid	Yes

Open Try it

POST/v1/topup/alipay/checkout

Bearer

Code Samples

curl -X POST https://api.batchin.tech/v1/topup/alipay/checkout \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "amount_cents": 5000,
  "currency": "cny",
  "locale": "zh-CN"
}'

Parameters

Name	Type	Required	Description
amount_cents	number	Yes
locale	string	No

Open Try it

GET/v1/topup/history

Bearer

Code Samples

curl -X GET https://api.batchin.tech/v1/topup/history \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \

Open Try it

GET/v1/usage/logs?limit=50&offset=0

Bearer

Code Samples

curl -X GET https://api.batchin.tech/v1/usage/logs?limit=50&offset=0 \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \

Parameters

Name	Type	Required	Description
limit	query:number	No
offset	query:number	No

Open Try it

GET/v1/usage/summary

Bearer

Code Samples

curl -X GET https://api.batchin.tech/v1/usage/summary \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \

Open Try it

GET/v1/usage/by-model

Bearer

Code Samples

curl -X GET https://api.batchin.tech/v1/usage/by-model \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \

Open Try it

POST/v1/vaas

Bearer

Code Samples

curl -X POST https://api.batchin.tech/v1/vaas \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input_text": "What is a zero-knowledge proof?",
  "output_text": "A cryptographic method...",
  "model_id": "qwen3.8-max",
  "node_id": "execution-a19c-42ef"
}'

Parameters

Name	Type	Required
input_text	string	Yes
output_text	string	Yes
model_id	string	Yes
node_id	string	No

Open Try it

GET/v1/vaas/{id}

Public

Code Samples

curl -X GET https://api.batchin.tech/v1/vaas/{id} \

Parameters

Name	Type	Required	Description
id	path:uuid	Yes

Open Try it

GET/v1/vaas/{id}/verify

Public

Code Samples

curl -X GET https://api.batchin.tech/v1/vaas/{id}/verify \

Parameters

Name	Type	Required	Description
id	path:uuid	Yes

Open Try it

GET/v1/vaas/{id}/evidence

Public

Code Samples

curl -X GET https://api.batchin.tech/v1/vaas/{id}/evidence \

Parameters

Name	Type	Required	Description
id	path:uuid	Yes

Open Try it

GET/v1/vaas/pubkey/current

Public

Code Samples

curl -X GET https://api.batchin.tech/v1/vaas/pubkey/current \

Open Try it

GET/v1/traces?limit=20

Bearer

Code Samples

curl -X GET https://api.batchin.tech/v1/traces?limit=20 \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \

Parameters

Name	Type	Required	Description
limit	query:number	No

Open Try it

GET/v1/traces/{trace_id}

Bearer

Code Samples

curl -X GET https://api.batchin.tech/v1/traces/{trace_id} \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \

Parameters

Name	Type	Required	Description
trace_id	path:string	Yes

Open Try it

GET/v1/prompts

Bearer

Code Samples

curl -X GET https://api.batchin.tech/v1/prompts \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \

Open Try it

GET/v1/prompt-regressions

Bearer

Code Samples

curl -X GET https://api.batchin.tech/v1/prompt-regressions \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \

Open Try it

GET/v1/experiments

Bearer

Code Samples

curl -X GET https://api.batchin.tech/v1/experiments \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \

Open Try it

POST/v1/otlp/traces

Bearer

Code Samples

curl -X POST https://api.batchin.tech/v1/otlp/traces \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "resourceSpans": []
}'

Open Try it

GET/v1/otlp/export

Bearer

Code Samples

curl -X GET https://api.batchin.tech/v1/otlp/export \
  -H "Authorization: Bearer $BATCHIN_API_KEY" \

Open Try it

GET/health

Public

Code Samples

curl -X GET https://api.batchin.tech/health \

Open Try it

Tutorials

Batch Tutorial

Upload a JSONL input file (one task per line).
Create a batch job and store batch_id.
Poll status, then download output file.

Responses Tutorial

Send a single input to /v1/responses when you want a lighter response object instead of Chat Completions.
Inspect traceparent and X-BatchIn-* receipt headers to capture route, prompt, and run context.
Follow the trace into /console/traces and open the linked audit proof in /verify.

VaaS Tutorial

Send text to /v1/vaas.
Define policy thresholds using risk_score.
Connect final decisions to audit logs.