Overview

Send Japanese audio, get text back. Translation is always free on the server; transcription runs on your worker or the community pool.

What are GET and POST? Standard HTTP verbs used by every REST API. GET fetches data (health, account). POST sends data to process (upload audio, mint a key). The colored badges on each endpoint show which one to use — same as Stripe, GitHub, or OpenAI docs.

Base URL: https://api.jptranscribe.com
Browser proxy: https://jptranscribe.com/api

Community pool: run worker.py on your PC · 3 free server demos/day (30s) · GET /v1/account for credits.

Authentication

Most endpoints need a free API key in the Authorization header:

Header

Authorization: Bearer jpt_YOUR_API_KEY

Mint a key on /get-key/. Keep keys on your backend — not in public client apps.

Quick start

Mint a key (below)
Run worker.py on your PC
POST audio to transcribe

Transcribe + translate

curl -X POST https://api.jptranscribe.com/v1/transcribe \
  -H "Authorization: Bearer jpt_YOUR_KEY" \
  -F "file=@sample.wav" \
  -F "language=ja" \
  -F "translate=true"

POST /v1/keys Mint API key

Create a free API key instantly. No auth required. Limit: 5 keys per IP per day.

Request

curl -X POST https://api.jptranscribe.com/v1/keys \
  -H "Content-Type: application/json" \
  -d '{}'

GET /v1/account Account & balance

Worker online status, pool credits, and pool stats for your key.

Request

curl https://api.jptranscribe.com/v1/account \
  -H "Authorization: Bearer jpt_YOUR_KEY"

POST /v1/transcribe Transcribe audio

Upload Japanese audio. Routing depends on worker, credits, or demo quota — see routing.

Request (multipart/form-data)

Field	Type	Required	Description
`file`	file	file or url	WAV, MP3, M4A, FLAC, OGG
`url`	string	file or url	Public HTTPS URL to audio
`language`	string	No	Default `ja`
`translate`	boolean	No	Include English translation

Example response

200 OK

{
  "id": "tx_abc123",
  "language": "ja",
  "text": "こんにちは、今日は配信を始めます。",
  "translation": "Hello, starting the stream today.",
  "duration_seconds": 12.4,
  "processed_by": "self",
  "route_reason": "Your worker is online — job runs on your CPU",
  "model": "vosk-small-ja"
}

POST /v1/translate Translate text

Japanese → English without audio. Always runs on the server — no worker needed.

Request JSON

{
  "text": "今日はいい天気ですね。",
  "source": "ja",
  "target": "en"
}

200 OK

{
  "text": "It's nice weather today, isn't it?",
  "source": "ja",
  "target": "en"
}

GET /v1/health Health check

Public status + pool stats. No authentication.

{
  "status": "ok",
  "version": "1.3.0",
  "backend": {
    "mode": "coordinator",
    "pool": { "workers_online": 1, "jobs_queued": 0 }
  }
}

Run worker.py

Transcribe on your CPU with Vosk. Required for full access beyond server demos.

pip install -r requirements.txt
python worker.py --key jpt_YOUR_KEY

Full setup: /worker/

Worker endpoints

Used internally by worker.py — skip these unless building a custom worker.

Method	Path	Description
POST	`/v1/worker/heartbeat`	Register worker (~15 min TTL)
POST	`/v1/pool/claim`	Claim next job
GET	`/v1/pool/jobs/{id}/audio`	Download job audio
POST	`/v1/pool/jobs/{id}/complete`	Submit result
POST	`/v1/pool/jobs/{id}/fail`	Report failure

How routing works

When you call POST /v1/transcribe, the server picks one path:

Route	When	`processed_by`
`pool_self`	Your worker is online	`self`
`server_demo`	No worker · ≤30s · demos left today	`server_demo`
`pool_credit`	Enough pool credits	`pool`
403 error	None of the above	`worker_required`

Error codes

HTTP	Code	Meaning
400	`invalid_request`	Bad parameters
400	`invalid_audio`	Unsupported or corrupt audio
401	`unauthorized`	Missing or invalid API key
403	`worker_required`	Run worker or use demo / credits
413	`file_too_large`	Over 10 MB
429	`rate_limited`	Too many requests
500	`internal_error`	Server error — retry

All errors use: {"error": {"code": "…", "message": "…"}}

Rate limits

Limit	Value
Requests per minute	30 per API key
Server demo	3 clips / IP / day (max 30s)
Max clip with worker	90 seconds
Max file size	10 MB
Keys per IP / day	5
Pool credits	1 sec earned per 1 sec audio processed for others

Headers: X-RateLimit-Limit, X-RateLimit-Remaining. Live stats: /status/

SDKs

Coming soon. Until then, use curl or generate a client from openapi.yaml.

pip install jptranscribe — Python
npm install @jptranscribe/sdk — TypeScript

API reference