The Jokai API

Authentication

Requests are authenticated with a personal API key passed as a Bearer token. Create keys in Settings → API (or via the API itself). The full key is shown only once at creation — only a SHA-256 hash is stored, so a lost key cannot be recovered.

Authorization: Bearer jk_live_YOUR_KEY

• • Keys act as your account — keep them secret. Rotate by creating a new key and revoking the old one (zero downtime).
• • Optional expiry date per key, revocation is immediate.
• • API access requires a paid plan — free-plan requests get a 403 upgrade payload.
• • Every authenticated response carries X-Jokai-Credits (your remaining balance) and rate-limit headers.

The fastest way in: POST an image, receive the translated blocks (with bounding boxes), the original image, a cleaned (inpainted) image and timing/credit metadata — in a single synchronous response, typically within 10–60 seconds. Steer the output with a custom prompt and story context, or run your request live below.

# Translate one image — everything comes back in the response
curl -X POST https://your-jokai-host/api/v1/translate \
  -H "Authorization: Bearer jk_live_YOUR_KEY" \
  -F "file=@page_001.jpg" \
  -F "target_lang=en"

Every example on this page ships in 8 flavors — cURL, Node.js, Python, Go, Rust, PHP, C# and Java. Pick your language in the tabs above a block; every other block follows.

Cost: 1 credit (OCR) + translation (0 with your own API key — BYOK) + 1 credit if inpainted. Use a generous HTTP timeout.

For whole series: create a project, push chapters with their pages, and the pipeline runs automatically — OCR, translation, inpainting. Pages sharing a contextGroup keep rolling story context, so names and references stay consistent across pages (a Jokai strength).

# 1. Create a project with its languages
curl -X POST https://your-jokai-host/api/v1/projects \
  -H "Authorization: Bearer jk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My series", "sourceLanguageId": "…", "targetLanguageIds": ["…"]}'

# 2. Create a chapter and upload the pages
curl -X POST https://your-jokai-host/api/v1/projects/$PROJECT_ID/chapters \
  -H "Authorization: Bearer jk_live_YOUR_KEY" \
  -F "title=Chapter 1" -F "chapterNumber=1" -F "status=translation" \
  -F "pages[0][image]=@page_001.jpg" -F "pages[0][pageNumber]=1" \
  -F "pages[1][image]=@page_002.jpg" -F "pages[1][pageNumber]=2" \
  -F "pages[1][contextGroup]=1"
# → OCR starts automatically, translation follows, inpaint if autoInpaint

# 3. Follow the progress
curl -H "Authorization: Bearer jk_live_YOUR_KEY" \
  https://your-jokai-host/api/v1/chapters/$CHAPTER_ID/status

# 4. Fetch the results
curl -H "Authorization: Bearer jk_live_YOUR_KEY" \
  https://your-jokai-host/api/v1/chapters/$CHAPTER_ID/pages/$PAGE_ID/translations

Retrieve results as JSON (translations per block), a chapter export bundle, or a ZIP archive with cleaned page images and per-language translation files.

Endpoint reference

Every endpoint available with your key, grouped by purpose. All paths are relative to your Jokai host.

Other translation APIs stop at the text. Jokai returns the final composed page — cleaned artwork with the translated text typeset on top, exactly as it appears in the Jokai web editor. Fonts, strokes, outlines, vertical Japanese text, gradients and effects are rendered by the very same engine, on our servers.

# Queue server-side rendering (same engine as the web editor)
curl -X POST https://your-jokai-host/api/v1/chapters/$CHAPTER_ID/render \
  -H "Authorization: Bearer jk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pixelRatio": 2}'

# Poll the render status / get the image URL
curl -H "Authorization: Bearer jk_live_YOUR_KEY" \
  https://your-jokai-host/api/v1/chapters/$CHAPTER_ID/pages/$PAGE_ID/renders

# Download the final composed image
curl -o final_page.png "$RENDER_URL"

• • Rendering is asynchronous: queue it, then poll the render list or listen for the page.render.completed webhook.
• •pixelRatio upscales the output (2× default 1×), limited by your plan's export resolution.
• • Renders are free — you only paid for the pipeline that produced them.

Register an HTTPS endpoint and get notified when processing finishes — no polling. Deliveries are signed (Stripe-style X-Jokai-Signature: t=…,v1=…), retried with exponential backoff, and the endpoint is auto-disabled after 5 consecutive failures. URLs must be HTTPS on a public host (SSRF-hardened).

# Verify a Jokai webhook signature with openssl (bash)
# SIGNATURE is the value of the "X-Jokai-Signature" header: t=…,v1=…
# payload.json contains the RAW request body
TIMESTAMP=$(echo "$SIGNATURE" | cut -d, -f1 | cut -d= -f2)
GIVEN=$(echo "$SIGNATURE" | cut -d, -f2 | cut -d= -f2)

EXPECTED=$(printf '%s.%s' "$TIMESTAMP" "$(cat payload.json)" \
  | openssl dgst -sha256 -hmac "$JOKAI_WEBHOOK_SECRET" | awk '{print $NF}')

NOW=$(date +%s)
if [ "$EXPECTED" = "$GIVEN" ] && [ $((NOW - TIMESTAMP)) -lt 300 ]; then
  echo "Signature valid"
fi

Errors & rate limits

Rate limiting uses a per-key token bucket: 120 requests per minute of sustained throughput with the full budget available as an immediate burst (default; configurable server-side). Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

Credits & costs

API usage draws from the same credit balance as the web app — subscription credits first, purchased packs after. Check GET /api/v1/pricing for the exact costs applied to your account (translation is free if you use your own API key — BYOK).

File limits

• • Max size: 50 MB per image
• • Max side: 20 000 px
• • Max resolution: 100 megapixels
• • Formats: jpg, jpeg, png, webp