BatchIn

BatchIn Developer Documentation

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

Runtime contract

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, llms.txt, and agents.md are exposed together.

Traffic policy

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

Public addresses and 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 and settlement semantics

Global and China entry points serve their audiences with a stable API experience.
Scoped rate limits and timeout controls apply by key, workspace, lane, and region, with explicit customer-visible failure semantics.
Ordinary enterprise traffic uses the shared core, while larger contracts, dedicated capacity, and 8+ GPU delivery move into private lanes.
Human funding and agent settlement stay separated: USDC and x402 are payment rails, ERC-8004 is receipt verification, and Alipay stays on the Chinese storefront.

Global Access, Unified Ingress

Providing consistent performance and reliability across global and domestic markets.

BatchIn coordinates API gateways, security controls, and compute availability to support localized delivery with unified engineering standards.

Open docs

Global entry

BatchIn serves global developers and enterprise buyers through the English storefront and global API.

Use this path for USD pricing, public MCP discovery, OpenAI-compatible access, and global-facing sales delivery.

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

Production posture

Built for stable production-scale traffic.

Traffic mix

Text plus vision, audio, image, and video workloads.

Streaming path

Regional ingress, stable streaming, and request continuity.

Control guardrails

Scoped limits, request isolation, and backpressure controls.

Public contract and readiness

OpenAI-compatible endpoints stay stable across chat, responses, embeddings, images, audio, and video.
Public MCP transport and tool discovery stay on the BatchIn contract instead of exposing execution details.
Traffic policy is designed for stable production text and multimodal workloads, not only demo-scale traffic.
Capability availability follows aligned usage, cost, billing, trace, and verification records.

Shared core

Self-serve developers and ordinary enterprise traffic run on the shared BatchIn control core.

This is where public Model API, batch, usage, billing, and public MCP contract stay consistent.

Private lanes

Reserved inference, dedicated endpoints, and larger enterprise traffic move into stricter capacity lanes.

Customer UI keeps one product truth while delivery, quota, and isolation can vary by contract.

Compute truth

Dedicated 8+ GPU delivery and smaller hourly rental both resolve against the same compute and capacity truth.

Public pages show inventory and availability only from the verified compute registry.

Edge ingress

Global traffic enters through a regional edge designed for resilient access and stable session continuity.

Latency work starts at the customer-facing edge before requests enter the primary execution path.

Streaming delivery

BatchIn maintains stable streaming behavior across cross-region and mixed-media workloads.

Connection reuse and consumer isolation are tuned to reduce jitter and long-tail failures.

Traffic policy

Traffic policy stays explicit through scoped protection, retry discipline, and graceful overload handling.

Customers see a simple API and clear limits while BatchIn handles traffic protection behind the scenes.

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="qwen3-32b",
  messages=[{"role": "user", "content": "Hello from BatchIn"}]
)
print(resp.choices[0].message.content)

3) Streaming

stream = client.chat.completions.create(
  model="qwen3-32b",
  messages=[{"role": "user", "content": "Write a haiku about latency"}],
  stream=True
)

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

Platform Playbooks

Dedicated Endpoints & GPU Rental

See the self-serve path for dedicated endpoints, card-hour GPU 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/meBearer

Current User Profile

Get current user profile for authenticated API key.

Request Example

{}

Response Example

{
  "id": "f6e2c67b-90cf-4f4e-b1e5-31d45f3b1b0a",
  "email": "hello@luminapath.ai",
  "name": "BatchIn Team",
  "credit_balance_cents": 10000
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/users/me",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
No parameters

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
POST/v1/keysBearer

Create API Key

Create a new API key with optional rate limit and monthly budget.

Request Example

{
  "name": "Production Key",
  "rate_limit_rpm": 120,
  "monthly_budget_cents": 500000
}

Response Example

{
  "id": "f40cf8b0-c367-4764-92e3-cbd358fa3d76",
  "key": "batchin_api_xxx",
  "key_prefix": "batchin_api",
  "name": "Production Key",
  "rate_limit_rpm": 120,
  "monthly_budget_cents": 500000,
  "created_at": "2026-04-08T18:00:00Z"
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.batchin.tech/v1/keys",
    headers=headers,
    json={
  "name": "Production Key",
  "rate_limit_rpm": 120,
  "monthly_budget_cents": 500000
}
)

print(response.json())

Parameters

NameTypeRequiredDescription
namestringNoKey name
rate_limit_rpmnumberNoRequests per minute limit
monthly_budget_centsnumberNoMonthly budget in cents

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
GET/v1/keysBearer

List API Keys

List all API keys for current user.

Request Example

{}

Response Example

[
  {
    "id": "f40cf8b0-c367-4764-92e3-cbd358fa3d76",
    "key_prefix": "batchin_api",
    "name": "Production Key",
    "rate_limit_rpm": 120,
    "is_active": true,
    "created_at": "2026-04-08T18:00:00Z"
  }
]

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/keys",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
No parameters

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
DELETE/v1/keys/{id}Bearer

Delete API Key

Delete one API key by id.

Request Example

{}

Response Example

204 No Content

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "DELETE",
    "https://api.batchin.tech/v1/keys/{id}",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
idpath:uuidYesAPI key id

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
not_found404API key not foundVerify key id and retry.
Open Try it
POST/v1/chat/completionsBearer

Chat Completions

Text and multi-turn chat completion with SSE streaming support.

Request Example

{
  "model": "qwen3.5-27b",
  "messages": [{"role":"user","content":"Explain attention in 3 bullets"}],
  "temperature": 0.7,
  "stream": false
}

Response Example

{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "model": "qwen3.5-27b",
  "choices": [{"index":0,"message":{"role":"assistant","content":"..."}}],
  "usage": {"prompt_tokens": 22, "completion_tokens": 90, "total_tokens": 112}
}

Response Headers

HeaderDescription
traceparentW3C trace context for linking the request into external tracing systems.
X-Request-IdRequest correlation id for support and audit troubleshooting.
X-BatchIn-Run-IdBatchIn run id for this execution.
X-BatchIn-Prompt-VersionPrompt version bound to this run.
X-VaaS-Record-IdAudit evidence record id.
X-VaaS-SignatureAudit evidence signature.
X-VaaS-PublicKeyAudit verification public key.

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.batchin.tech/v1/chat/completions",
    headers=headers,
    json={
  "model": "qwen3.5-27b",
  "messages": [{"role":"user","content":"Explain attention in 3 bullets"}],
  "temperature": 0.7,
  "stream": false
}
)

print(response.json())

Parameters

NameTypeRequiredDescription
modelstringYesModel ID
messagesarrayYesChat message array
temperaturenumberNoSampling temperature
max_tokensnumberNoMax output tokens
streambooleanNoEnable streaming

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
payment_required402Insufficient balance or budget exceededTop up balance or increase monthly budget.
Open Try it
POST/v1/responsesBearer

Responses API

Responses API compatibility layer with non-streaming response objects, SSE streaming events, and runtime receipt headers.

Request Example

{
  "model": "qwen3.5-27b",
  "input": "Explain batch inference in 3 bullets",
  "max_output_tokens": 256
}

Response Example

{
  "id": "resp_chatcmpl_xxx",
  "object": "response",
  "model": "qwen3.5-27b",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{"type":"output_text","text":"..."}]
    }
  ],
  "usage": {"input_tokens": 12, "output_tokens": 10, "total_tokens": 22}
}

Response Headers

HeaderDescription
traceparentW3C trace context for linking the request into external tracing systems.
X-Request-IdRequest correlation id for support and audit troubleshooting.
X-BatchIn-Run-IdBatchIn run id for this execution.
X-BatchIn-Prompt-VersionPrompt version bound to this run.
X-VaaS-Record-IdAudit evidence record id.
X-VaaS-SignatureAudit evidence signature.
X-VaaS-PublicKeyAudit verification public key.

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.batchin.tech/v1/responses",
    headers=headers,
    json={
  "model": "qwen3.5-27b",
  "input": "Explain batch inference in 3 bullets",
  "max_output_tokens": 256
}
)

print(response.json())

Parameters

NameTypeRequiredDescription
modelstringYesModel ID
inputstring|arrayYesInput text or message array
max_output_tokensnumberNoMax output tokens
streambooleanNoReturn Responses events as text/event-stream.

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
responses_streaming_disabled409Responses streaming is not enabled for this API keyDisable stream or contact support to enable streaming access.
Open Try it
POST/v1/completionsBearer

Text Completions / FIM

OpenAI-compatible text completions with prefix/suffix FIM-style passthrough.

Request Example

{
  "model": "qwen3.5-27b",
  "prompt": "Complete this sentence: Batch processing helps",
  "suffix": "for large workloads.",
  "max_tokens": 128
}

Response Example

{
  "id": "cmpl_xxx",
  "object": "text_completion",
  "choices": [{"index":0,"text":"reduce manual toil at scale.","finish_reason":"stop"}],
  "usage": {"prompt_tokens": 24, "completion_tokens": 12, "total_tokens": 36}
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.batchin.tech/v1/completions",
    headers=headers,
    json={
  "model": "qwen3.5-27b",
  "prompt": "Complete this sentence: Batch processing helps",
  "suffix": "for large workloads.",
  "max_tokens": 128
}
)

print(response.json())

Parameters

NameTypeRequiredDescription
modelstringYesCompletion model id
promptstring|arrayYesPrompt or prefix content
suffixstringNoFIM suffix
max_tokensnumberNoMax completion tokens

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
POST/v1/embeddingsBearer

Embeddings

Convert text into embeddings.

Request Example

{
  "model": "bge-m3",
  "input": ["batch inference", "retrieval augmented generation"]
}

Response Example

{
  "object": "list",
  "data": [
    {"index":0,"embedding":[0.012,-0.043,...]},
    {"index":1,"embedding":[0.021,-0.011,...]}
  ]
}

Response Headers

HeaderDescription
traceparentW3C trace context.
X-BatchIn-Run-IdRun id for this embedding request.
X-BatchIn-Prompt-VersionPrompt version bound to this run.
X-VaaS-Record-IdAudit evidence record id.

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.batchin.tech/v1/embeddings",
    headers=headers,
    json={
  "model": "bge-m3",
  "input": ["batch inference", "retrieval augmented generation"]
}
)

print(response.json())

Parameters

NameTypeRequiredDescription
modelstringYesEmbedding model id
inputstring|arrayYesText input to embed

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
POST/v1/audio/speechBearer

Audio Speech

Convert text into synthesized speech with CosyVoice / TTS-compatible models.

Request Example

{
  "model": "cosyvoice",
  "input": "Welcome to BatchIn",
  "voice": "alloy",
  "response_format": "mp3"
}

Response Example

Binary audio payload (audio/mpeg)

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.batchin.tech/v1/audio/speech",
    headers=headers,
    json={
  "model": "cosyvoice",
  "input": "Welcome to BatchIn",
  "voice": "alloy",
  "response_format": "mp3"
}
)

print(response.content)

Parameters

NameTypeRequiredDescription
modelstringYesSpeech model id
inputstringYesText to synthesize
voicestringNoVoice preset
response_formatstringNoAudio response format

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
POST/v1/audio/transcriptionsBearer

Audio Transcriptions

Transcribe speech or audio files into text, with compact or verbose segment-aware output.

Request Example

multipart/form-data
  file=@meeting.wav
  model=whisper-large-v3-turbo
  response_format=verbose_json
  language=en

Response Example

{
  "text": "BatchIn transcription output",
  "language": "en",
  "duration": 3.42,
  "segments": [{"id":0,"start":0.0,"end":3.42,"text":"BatchIn transcription output"}]
}

Code Samples

import os
import requests

with open("meeting.wav", "rb") as audio_file:
    response = requests.request(
        "POST",
        "https://api.batchin.tech/v1/audio/transcriptions",
        headers={"Authorization": f"Bearer {os.environ['BATCHIN_API_KEY']}"},
        files={"file": audio_file},
        data={
            "model": "whisper-large-v3-turbo",
            "response_format": "verbose_json",
            "language": "en",
        },
    )

print(response.json())

Parameters

NameTypeRequiredDescription
filebinaryYesAudio file upload
modelstringYesTranscription model id
languagestringNoLanguage code
promptstringNoTranscription prompt
response_formatstringNoResponse format
temperaturenumber|stringNoSampling temperature

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
POST/v1/videosBearer

Videos

Submit video generation jobs through the unified Model API video entry.

Request Example

{
  "model": "wan-2.2",
  "prompt": "Create a product teaser for an AI cloud launch",
  "duration_seconds": 6
}

Response Example

{
  "id": "video_xxx",
  "object": "video.generation",
  "status": "queued",
  "duration_seconds": 6,
  "output_url": "https://api.batchin.tech/v1/files/file_video_xxx/content"
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.batchin.tech/v1/videos",
    headers=headers,
    json={
  "model": "wan-2.2",
  "prompt": "Create a product teaser for an AI cloud launch",
  "duration_seconds": 6
}
)

print(response.json())

Parameters

NameTypeRequiredDescription
modelstringYesVideo model id
promptstringYesVideo prompt
duration_secondsnumberNoVideo duration in seconds
aspect_ratiostringNoAspect ratio

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
POST/v1/imagesBearer

Image Generation

Generate images from text prompts through the unified Model API image entry.

Request Example

{
  "model": "flux-schnell",
  "prompt": "A futuristic city at sunrise",
  "size": "1024x1024"
}

Response Example

{
  "created": 1775671200,
  "data": [{"url":"https://batchin.tech/images/generated/abc.png"}]
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.batchin.tech/v1/images",
    headers=headers,
    json={
  "model": "flux-schnell",
  "prompt": "A futuristic city at sunrise",
  "size": "1024x1024"
}
)

print(response.json())

Parameters

NameTypeRequiredDescription
modelstringYesImage model id
promptstringYesImage prompt
sizestringNoOutput size

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
GET/v1/modelsPublic

List Models

Returns model status, pricing, context length, and license metadata.

Request Example

{}

Response Example

{
  "object": "list",
  "data": [
    {
      "id":"qwen3.5-27b",
      "status":"always_on",
      "context_length":131072,
      "pricing":{"std_input":0.02,"std_output":0.08}
    }
  ]
}

Code Samples

import os
import requests

headers = {}
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/models",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
No parameters

Error Codes

CodeHTTPMessageResolution
service_unavailable503Model service unavailableCheck status page and retry later.
Open Try it
POST/v1/batchesBearer

Create Batch

Submit batch jobs with mixed-model tasks and priorities.

Request Example

{
  "priority": "fill",
  "webhook_url": "https://your-domain.com/webhooks/batchin",
  "tasks": [
    {"custom_id":"task-1","model":"qwen3.5-27b","request_body":{"messages":[{"role":"user","content":"translate this"}]}},
    {"custom_id":"task-2","model":"glm-5.1","request_body":{"messages":[{"role":"user","content":"summarize this"}]}}
  ]
}

Response Example

{
  "id":"0b0db2a6-0baf-4ec4-a5e7-bce60da57db6",
  "status":"pending",
  "priority":"fill",
  "total_tasks":2,
  "completed_tasks":0,
  "failed_tasks":0
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.batchin.tech/v1/batches",
    headers=headers,
    json={
  "priority": "fill",
  "webhook_url": "https://your-domain.com/webhooks/batchin",
  "tasks": [
    {"custom_id":"task-1","model":"qwen3.5-27b","request_body":{"messages":[{"role":"user","content":"translate this"}]}},
    {"custom_id":"task-2","model":"glm-5.1","request_body":{"messages":[{"role":"user","content":"summarize this"}]}}
  ]
}
)

print(response.json())

Parameters

NameTypeRequiredDescription
tasksarrayYesTask array (each task can set its own model)
prioritystring(high|low|fill)NoScheduling priority
webhook_urlstring(url)NoWebhook callback URL

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
payload_too_large413Batch JSON payload exceeds 2MBSplit into smaller batches.
Open Try it
GET/v1/batchesBearer

List Batches

List batch jobs for current user.

Request Example

{}

Response Example

[
  {
    "id":"0b0db2a6-0baf-4ec4-a5e7-bce60da57db6",
    "status":"completed",
    "priority":"fill",
    "total_tasks":2,
    "completed_tasks":2,
    "failed_tasks":0
  }
]

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/batches",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
No parameters

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
GET/v1/batches/{id}Bearer

Get Batch Detail

Get batch detail including task results.

Request Example

{}

Response Example

{
  "id":"0b0db2a6-0baf-4ec4-a5e7-bce60da57db6",
  "status":"completed",
  "tasks":[{"custom_id":"task-1","status":"completed"}]
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/batches/{id}",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
idpath:uuidYesBatch id

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
not_found404Batch not foundVerify batch id.
Open Try it
POST/v1/batches/{id}/cancelBearer

Cancel Batch

Cancel a pending or running batch job.

Request Example

{}

Response Example

{
  "id":"0b0db2a6-0baf-4ec4-a5e7-bce60da57db6",
  "status":"cancelled"
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "POST",
    "https://api.batchin.tech/v1/batches/{id}/cancel",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
idpath:uuidYesBatch id

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
POST/v1/topup/alipay/checkoutBearer

Create Alipay Checkout

Create an Alipay checkout session for Chinese-site credit top-up.

Request Example

{
  "amount_cents": 5000,
  "currency": "cny",
  "locale": "zh-CN"
}

Response Example

{
  "object": "topup.alipay.checkout",
  "session_id": "alipay_xxx",
  "checkout_url": "https://openapi.alipay.com/gateway.do?..."
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.batchin.tech/v1/topup/alipay/checkout",
    headers=headers,
    json={
  "amount_cents": 5000,
  "currency": "cny",
  "locale": "zh-CN"
}
)

print(response.json())

Parameters

NameTypeRequiredDescription
amount_centsnumberYesTop-up amount in CNY cents
localestringNoChinese locale, zh-CN or zh-HK

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
POST/v1/topup/stripe/checkoutBearer

Create Stripe Checkout

Create Stripe checkout session for credit top-up.

Request Example

{
  "amount_cents": 5000
}

Response Example

{
  "checkout_url":"https://buy.stripe.com/9B65kD4US2fLeEF4zweME00",
  "session_id":"cs_test_xxx"
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.batchin.tech/v1/topup/stripe/checkout",
    headers=headers,
    json={
  "amount_cents": 5000
}
)

print(response.json())

Parameters

NameTypeRequiredDescription
amount_centsnumberYesTop-up amount in cents

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
GET/v1/topup/historyBearer

Top-up History

Get top-up transaction history.

Request Example

{}

Response Example

[
  {
    "id":"1544d6df-8fca-46f3-9091-95f81dc37efa",
    "amount_cents":5000,
    "source":"stripe",
    "reference_id":"cs_test_xxx"
  }
]

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/topup/history",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
No parameters

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
GET/v1/topup/usdc/chainsBearer

USDC Chain Info

Get supported USDC chains and deposit addresses.

Request Example

{}

Response Example

{
  "chains":[
    {"chain":"ethereum","deposit_address":"0x...","required_confirmations":12},
    {"chain":"polygon","deposit_address":"0x...","required_confirmations":12}
  ]
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/topup/usdc/chains",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
No parameters

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
GET/v1/usage/logs?limit=50&offset=0Bearer

Usage Logs

List request-level usage logs.

Request Example

{}

Response Example

[
  {
    "id":"e73f9476-00ea-491f-ba6f-899602247a15",
    "model":"qwen3.5-27b",
    "input_tokens":120,
    "output_tokens":88,
    "cost_cents":2
  }
]

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/usage/logs?limit=50&offset=0",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
limitquery:numberNoPage size (1-500)
offsetquery:numberNoOffset

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
GET/v1/usage/summaryBearer

Usage Summary

Get total requests, tokens, and cost summary.

Request Example

{}

Response Example

{
  "total_requests": 1304,
  "total_input_tokens": 2341122,
  "total_output_tokens": 1111400,
  "total_cost_cents": 18640
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/usage/summary",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
No parameters

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
payment_required402API key monthly budget exceededIncrease key budget or rotate key.
Open Try it
GET/v1/usage/by-modelBearer

Usage by Model

Aggregate usage by model dimension.

Request Example

{}

Response Example

[
  {
    "model":"qwen3.5-27b",
    "total_requests": 880,
    "total_input_tokens": 1620012,
    "total_output_tokens": 801202,
    "total_cost_cents": 9900
  }
]

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/usage/by-model",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
No parameters

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
POST/v1/vaasBearer

Create Audit Record

Create verifiable audit record and signature.

Request Example

{
  "input_text": "What is a zero-knowledge proof?",
  "output_text": "A cryptographic method...",
  "model_id": "qwen3.5-27b",
  "gpu_id": "execution-a19c-42ef"
}

Response Example

{
  "audit_id":"ee3cc19e-710d-4a2d-bf01-0edca0c5fdf4",
  "input_hash":"9a5f...",
  "output_hash":"2f1b...",
  "carbon_grams_co2e":0.0126,
  "energy_wh":0.2107,
  "energy_source":"Renewable grid mix",
  "carbon_offset_vs_us_cloud":0.0717,
  "signature":"bfc4..."
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.batchin.tech/v1/vaas",
    headers=headers,
    json={
  "input_text": "What is a zero-knowledge proof?",
  "output_text": "A cryptographic method...",
  "model_id": "qwen3.5-27b",
  "gpu_id": "execution-a19c-42ef"
}
)

print(response.json())

Parameters

NameTypeRequiredDescription
input_textstringYesInput text
output_textstringYesOutput text
model_idstringYesModel id
gpu_idstringNoMasked execution environment identifier

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
GET/v1/vaas/{id}Public

Get Audit Record

Fetch audit details by audit_id.

Request Example

{}

Response Example

{
  "audit_id":"ee3cc19e-710d-4a2d-bf01-0edca0c5fdf4",
  "input_hash":"9a5f...",
  "output_hash":"2f1b...",
  "carbon_grams_co2e":0.0126,
  "energy_wh":0.2107,
  "energy_source":"Renewable grid mix",
  "carbon_offset_vs_us_cloud":0.0717,
  "signature":"bfc4..."
}

Code Samples

import os
import requests

headers = {}
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/vaas/{id}",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
idpath:uuidYesAudit id

Error Codes

CodeHTTPMessageResolution
not_found404Audit record not foundVerify audit_id.
Open Try it
GET/v1/vaas/{id}/verifyPublic

Verify Audit Signature

Verify audit signature validity.

Request Example

{}

Response Example

{
  "audit_id":"ee3cc19e-710d-4a2d-bf01-0edca0c5fdf4",
  "valid": true
}

Code Samples

import os
import requests

headers = {}
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/vaas/{id}/verify",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
idpath:uuidYesAudit id

Error Codes

CodeHTTPMessageResolution
Open Try it
GET/v1/vaas/{id}/evidencePublic

Export Evidence Pack

Return the audit evidence pack used for browser verification and export workflows.

Request Example

{}

Response Example

{
  "record_id":"vaas_xxx",
  "run_id":"run_xxx",
  "customer_trace_id":"0123456789abcdef0123456789abcdef",
  "public_route_label":"managed-text",
  "environment":"development",
  "prompt_version_id":"default",
  "verification_method":"Ed25519Signature2020",
  "public_key":"ed25519:pk_xxx",
  "signature":"ed25519:xxx",
  "payload": {"record_id":"vaas_xxx","input_hash":"sha256:...","output_hash":"sha256:..."}
}

Response Headers

HeaderDescription
Content-TypeJSON evidence pack that can be saved directly or passed into /verify.

Code Samples

import os
import requests

headers = {}
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/vaas/{id}/evidence",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
idpath:uuidYesAudit id

Error Codes

CodeHTTPMessageResolution
Open Try it
GET/v1/vaas/pubkey/currentPublic

Get Current Verify Public Key

Get public key used for browser-side signature verification.

Request Example

{}

Response Example

{
  "verify_key_hex":"1fbd9285..."
}

Code Samples

import os
import requests

headers = {}
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/vaas/pubkey/current",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
No parameters

Error Codes

CodeHTTPMessageResolution
Open Try it
GET/v1/traces?limit=20Bearer

List Runtime Traces

List native runtime traces with route, prompt-version, and audit linkage.

Request Example

{}

Response Example

{
  "items": [
    {
      "customer_trace_id":"0123456789abcdef0123456789abcdef",
      "run_id":"run_xxx",
      "record_id":"vaas_xxx",
      "public_route_label":"managed-text",
      "environment":"development",
      "prompt_version_id":"default",
      "model_id":"qwen3.5-27b"
    }
  ]
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/traces?limit=20",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
limitquery:numberNoPage size (1-100)

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
GET/v1/traces/{trace_id}Bearer

Get Runtime Trace

Fetch one native runtime trace by trace_id.

Request Example

{}

Response Example

{
  "customer_trace_id":"0123456789abcdef0123456789abcdef",
  "run_id":"run_xxx",
  "record_id":"vaas_xxx",
  "public_route_label":"managed-text",
  "environment":"development",
  "prompt_version_id":"default",
  "model_id":"qwen3.5-27b"
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/traces/{trace_id}",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
trace_idpath:stringYesTrace ID

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
not_found404Trace not foundVerify the trace id and retry.
Open Try it
GET/v1/promptsBearer

Prompt Registry

Return prompt registries with promoted versions, latest observed versions, and version details.

Request Example

{}

Response Example

{
  "status":"ready",
  "docs":"/docs/prompts",
  "items":[
    {
      "registry_id":"support",
      "display_name":"support",
      "source":"auto_backfill",
      "latest_version_id":"support@v2",
      "promoted_version_id":"support@v2",
      "total_runs":4,
      "versions":[
        {
          "version_id":"support@v1",
          "status":"observed",
          "total_runs":2
        },
        {
          "version_id":"support@v2",
          "status":"promoted",
          "total_runs":2
        }
      ]
    }
  ]
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/prompts",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
No parameters

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
GET/v1/prompt-regressionsBearer

输入模板回归 Results

Return automatic sampled-replay regression runs with sample counts, similarity, and latency summaries.

Request Example

{}

Response Example

{
  "status":"ready",
  "docs":"/docs/experiments",
  "items":[
    {
      "regression_id":"preg_demo",
      "registry_id":"support",
      "baseline_prompt_version_id":"support@v1",
      "candidate_prompt_version_id":"support@v2",
      "status":"passed",
      "judge":"deterministic_replay",
      "sample_count":3,
      "pass_count":3,
      "fail_count":0,
      "avg_similarity":1,
      "baseline_avg_latency_ms":420,
      "candidate_avg_latency_ms":390
    }
  ]
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/prompt-regressions",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
No parameters

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
GET/v1/experimentsBearer

Experiments Control Plane

Return automatic experiments for candidate prompt versions, including replay state and auto-promotion results.

Request Example

{}

Response Example

{
  "status":"ready",
  "docs":"/docs/experiments",
  "items":[
    {
      "experiment_id":"pexp_demo",
      "registry_id":"support",
      "baseline_prompt_version_id":"support@v1",
      "candidate_prompt_version_id":"support@v2",
      "status":"passed",
      "promotion_status":"promoted",
      "sample_count":3,
      "pass_rate":1
    }
  ]
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/experiments",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
No parameters

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
POST/v1/otlp/tracesBearer

OTLP Trace Ingest

Accept OTLP/HTTP JSON or protobuf traces and merge spans into the unified trace view.

Request Example

{
  "resourceSpans": []
}

Response Example

{}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.batchin.tech/v1/otlp/traces",
    headers=headers,
    json={
  "resourceSpans": []
}
)

print(response.json())

Parameters

NameTypeRequiredDescription
No parameters

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
GET/v1/otlp/exportBearer

OTLP Trace Export

Export spans from the unified trace view as OTLP protobuf or JSON.

Request Example

{}

Response Example

{
  "resourceSpans":[]
}

Code Samples

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.batchin.tech/v1/otlp/export",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
No parameters

Error Codes

CodeHTTPMessageResolution
unauthorized401API key is invalid or missingVerify Authorization: Bearer <API_KEY>.
Open Try it
GET/healthPublic

Health Check

Service health probe endpoint.

Request Example

{}

Response Example

{
  "status":"ok"
}

Code Samples

import os
import requests

headers = {}
response = requests.request(
    "GET",
    "https://api.batchin.tech/health",
    headers=headers,
    
)

print(response.json())

Parameters

NameTypeRequiredDescription
No parameters

Error Codes

CodeHTTPMessageResolution
Open Try it

Tutorials

Batch Tutorial

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

Responses Tutorial

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

VaaS Tutorial

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

Cookbook

Batch Pipeline for 1M Documents

Split one million records into JSONL tasks, execute by priority tiers, and ingest callbacks automatically.

Production RAG Pipeline

Combine embeddings, retrieval, reranking, and generation with observability and rollback controls.

Audit Trace Integration

Capture verifiable audit evidence at input, output, and human-review checkpoints with Ed25519 verification.

Changelog

Release truth lives in the live model catalog, pricing surfaces, and verified route behavior. Use the public site and console evidence paths as the current changelog source of truth.