API 레퍼런스

Workflow

A complete translation lifecycle has 5 steps. Step 3 only queues the work (it returns 202 immediately); use step 5 to wait until a chapter turns done, then read the translation in step 4.

1. 1

   Create a book

   POST /books — get back bookId

2. 2

   Add a chapter

   POST /books/{id}/chapters — get back chapterId

3. 3

   Translate chapters

   POST /translation/books/{id}/translate — queued

4. 4

   Get the translation

   GET /books/{id}/chapters/{chapterId} — read translatedText

5. 5

   Translation status

   GET /books/{id} — watch chapters[].status

Book Bible

The Book Bible is the per-book consistency layer — the glossary of terms, characters, relationships and idioms the translator applies to every chapter. The endpoints below read and edit it; every path sits under /books/{id} and uses the same API key.

curl "$BASE/books/$BOOK_ID/export" \
  -H "Authorization: Bearer $KEY"

Webhook

Instead of polling /books/:id/chapters to learn whether a translation has finished, register an endpoint and let 2Novel call you. Create it in Settings → Webhook (Pro plan); each endpoint gets its own signing secret, shown only once at creation.

A workspace can register several endpoints — typically one for production and one for staging, or to migrate to a new receiver without missing an event.

Events

What gets sent

The body is a doorbell, not a parcel — it carries no chapter content. Once you receive it, call the API above to fetch the translations. Note: sending content along would mean one request per chapter, and a large batch would become thousands.

X-2Novel-Signature: 9f2b…            (hex, HMAC-SHA256)
X-2Novel-Timestamp: 1787760000        (unix seconds)
Content-Type: application/json

{
  "schema_version": 1,
  "event": "book.chapters_translated",
  "book_id": "8f14e45f-ceea-467a-9fd9-9f2b0e4f7f10",
  "title": "凡人修仙传",
  "pending_since": "2026-08-27T03:12:44.512Z"
}

Verifying the signature

The signature is the HMAC-SHA256 of the string <timestamp>.<raw body> with the endpoint’s signing secret. Compare over the raw body — parsing then re-serializing changes every byte and the signature will never match. Reject requests whose timestamp is off by more than 5 minutes to block replays.

import crypto from 'node:crypto'

app.post('/2novel/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const raw = req.body.toString('utf8')          // raw, not yet parsed
  const ts = req.get('X-2Novel-Timestamp')
  const sig = req.get('X-2Novel-Signature')

  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(401)

  const expected = crypto
    .createHmac('sha256', process.env.LITRANS_WEBHOOK_SECRET)
    .update(`${ts}.${raw}`)
    .digest('hex')

  const a = Buffer.from(sig, 'hex')
  const b = Buffer.from(expected, 'hex')
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401)

  const { event, book_id } = JSON.parse(raw)
  if (event === 'book.chapters_translated') void pullChapters(book_id)
  res.sendStatus(200)                             // ack fast, work later
})

What you return

The endpoint must be https:// on a public server. Addresses pointing into a private network are rejected both at registration and at send time — checked twice because a public hostname can still be redirected afterwards.

Receiving the same event twice is normal (a retry after you already processed it). Make the receiver idempotent; use pending_since to tell a new window apart from a resend of an old one.

Rate limits and quotas

An API key has no rate limit in requests per minute (RPM) and no Retry-After header to watch. Translation is a queue: POST /translation/books/{id}/translate accepts up to 1000 chapter ids per call (none means every chapter) and returns at once; chapters are translated in the background and you follow them with GET /books/{id} or a webhook.

Error codes

Errors come back as JSON { "error": "<code>", "message"?: "..." } with the matching HTTP status.