Partner API documentation

Novo Translator B2B API

Novo Translator exposes long-form novel translation as async API tasks. Partners create a task with an action, poll status, then download outputs. The same task model supports pricing estimates, glossary extraction, preview generation, and full translation.

Base URL

https://xsfyj.com/api/b2b/v1

OpenAPI JSON

/api/b2b/v1/openapi.json

Version

1.0.0-draft

Quick start

1Store your issued API key on the server side and send it as a bearer token.
2Call GET /usage to verify the key, remaining prepaid credits, and RPM limit.
3Create POST /tasks with action=token_estimate or action=preview_metadata before quoting a client.
4Use action=glossary_extraction or action=translation with char_limit to create a limited preview.
5For a paid full run, omit char_limit and provide estimated_chars for file uploads.
6Poll GET /tasks/{task_id}; download completed files with GET /tasks/{task_id}/download.

Authentication and account mapping

Each API key maps to one managed Novo Translator partner account. Billing and quotas are controlled by that mapped account, so partners do not need browser login for API use.

Header	Authorization	Bearer nt_live_xxxxxxxxxxxxxxxxx
Credits	1 credit	1 source character processed
Pilot balance	Plan-specific	Use /usage to read the current balance. Example pilot pool: 1000000 credits.
Rate limit	Per key	Use /usage to read the configured requests-per-minute limit.

Action recipes

Goal	action	Result
Full translation	translation	Translate the whole text or uploaded file.
Preview translation	preview_translation	Translate an opening sample with char_limit.
Cost estimate	token_estimate	Return system-side character/token estimate for pricing.
Glossary extraction	glossary_extraction	Extract names, terms, and preferred translations.
Metadata preview	preview_metadata	Detect language and inspect source metadata without a full run.

char_limit for previews and scoped work

char_limit controls how much source content the task processes. Partners can use it to generate a preview or quote a client without processing the full file.

For translation, omit char_limit for the full file; include it for a partial translation preview.
For glossary_extraction, include char_limit to extract terms only from the opening range.
For token_estimate and preview_metadata, include char_limit when the client only wants a scoped estimate.
For file uploads, provide estimated_chars unless char_limit is present, so the gateway can reserve prepaid credits.

Partner glossary control

Send glossary as a JSON object and choose glossary_strategy to define how partner terms interact with extracted terms.

merge

Default

Combine extracted and supplied terms; supplied terms win conflicts.

override

Authoritative terms

Use supplied terms as authoritative for conflicts.

append

Hints only

Add supplied terms only where extracted terms do not conflict.

none

No supplied glossary

Ignore supplied terms.

Check balance and RPM

curl https://xsfyj.com/api/b2b/v1/usage \
  -H "Authorization: Bearer nt_live_xxxxxxxxxxxxxxxxx"

{
  "success": true,
  "data": {
    "api_key_prefix": "nt_live_ab12",
    "balance_credits": 10000000,
    "period_used_credits": 0,
    "period_start": "2026-06-01T00:00:00Z",
    "period_end": null,
    "rate_limit_per_minute": 120
  }
}

Core operations

1. Count characters and estimate cost from an uploaded file

Use action=token_estimate before quoting or accepting a full run. For pilot file uploads, send estimated_chars as the prepaid-credit guard; the completed task returns system-side statistics such as source characters and estimated tokens.

Poll https://xsfyj.com/api/b2b/v1/tasks/{task_id}. Completed estimate tasks may include total_characters, estimated_tokens, detected_language, and estimated credits depending on file type.

Request

curl https://xsfyj.com/api/b2b/v1/tasks \
  -H "Authorization: Bearer nt_live_xxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: partner-estimate-001" \
  -F "action=token_estimate" \
  -F "target_lang=en" \
  -F "estimated_chars=120000" \
  -F "[email protected]"

Typical response

{
  "success": true,
  "data": {
    "task_id": "TSK_EST_01HV8W...",
    "status": "pending",
    "action": "token_estimate",
    "file_name": "novel.txt",
    "target_lang": "en",
    "char_count": 120000,
    "estimated_credits": 120000,
    "created_at": "2026-06-16T10:30:00Z"
  }
}

2. Extract glossary terms

Use action=glossary_extraction for a terminology-only task. Add char_limit when the partner only wants terms from the opening range for review or pricing.

Request

curl https://xsfyj.com/api/b2b/v1/tasks \
  -H "Authorization: Bearer nt_live_xxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: partner-glossary-001" \
  -F "action=glossary_extraction" \
  -F "target_lang=en" \
  -F "char_limit=20000" \
  -F "[email protected]"

Typical response

{
  "success": true,
  "data": {
    "task_id": "TSK_GLO_01HV8W...",
    "action": "glossary_extraction",
    "status": "completed",
    "progress": 1,
    "terms": [
      { "source": "玄天宗", "target": "Xuantian Sect", "confidence": 0.93 },
      { "source": "灵石", "target": "spirit stone", "confidence": 0.9 }
    ],
    "char_count": 20000,
    "credits_charged": 20000
  }
}

3. Translate a full file or a preview range

Use action=translation for the main translation task. Omit char_limit for the full file; include char_limit to translate only the opening range and use it as a preview.

To generate a translation preview with the same task type, replace estimated_chars with char_limit, for example char_limit=12000.

Request

curl https://xsfyj.com/api/b2b/v1/tasks \
  -H "Authorization: Bearer nt_live_xxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: partner-file-001" \
  -F "action=translation" \
  -F "target_lang=en" \
  -F "glossary_strategy=merge" \
  -F "estimated_chars=120000" \
  -F "[email protected]" \
  -F 'glossary={"玄天宗":"Xuantian Sect"}'

Typical response

{
  "success": true,
  "data": {
    "task_id": "TSK_01HV8W...",
    "status": "pending",
    "action": "translation",
    "file_name": "novel.txt",
    "source_lang": "auto",
    "target_lang": "en",
    "char_count": 120000,
    "estimated_credits": 120000,
    "created_at": "2026-06-16T10:30:00Z"
  }
}

4. Inspect metadata before processing

Use action=preview_metadata when the partner wants detected language, title/file metadata, or source statistics before deciding which downstream task to run.

Request

curl https://xsfyj.com/api/b2b/v1/tasks \
  -H "Authorization: Bearer nt_live_xxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: partner-metadata-001" \
  -F "action=preview_metadata" \
  -F "target_lang=en" \
  -F "char_limit=8000" \
  -F "[email protected]"

Typical response

{
  "success": true,
  "data": {
    "task_id": "TSK_META_01HV8W...",
    "action": "preview_metadata",
    "status": "completed",
    "progress": 1,
    "source_lang": "zh",
    "char_count": 8000,
    "detected_language": "zh",
    "metadata": {
      "file_name": "novel.txt",
      "sample_characters": 8000
    }
  }
}

Poll task status

Tasks are asynchronous. Poll every 5-15 seconds for normal jobs and back off for long files. A completed task returns outputs inline for lightweight actions or download file descriptors for file outputs.

curl https://xsfyj.com/api/b2b/v1/tasks/{task_id} \
  -H "Authorization: Bearer nt_live_xxxxxxxxxxxxxxxxx"

{
  "success": true,
  "data": {
    "task_id": "TSK_01HV8W...",
    "action": "translation",
    "status": "completed",
    "progress": 1,
    "stage": "completed",
    "file_name": "novel.txt",
    "source_lang": "zh",
    "target_lang": "en",
    "char_count": 120000,
    "credits_charged": 120000,
    "download_files": [
      {
        "file_id": "translated",
        "file_name": "novel_translated.txt",
        "url": "/api/tasks/download-file/TSK_01HV8W...",
        "file_size": 348200,
        "type": "translated"
      }
    ]
  }
}

Download completed output

curl https://xsfyj.com/api/b2b/v1/tasks/{task_id}/download \
  -H "Authorization: Bearer nt_live_xxxxxxxxxxxxxxxxx"

{
  "success": true,
  "data": {
    "download_url": "https://...",
    "expires_in": 3600,
    "file_name": "novel_translated.txt",
    "file_size": 348200
  }
}

Errors and retries

HTTP	Code	Partner action
400	BAD_REQUEST	Fix invalid parameters, missing input, or malformed glossary JSON.
401	UNAUTHORIZED	Check the bearer API key. Revoked or unknown keys cannot access tasks.
402	PAYMENT_REQUIRED	Top up the mapped account or lower char_limit before retrying.
409	IDEMPOTENCY_CONFLICT	Reuse the same idempotency key only for the same logical request.
429	RATE_LIMITED	Retry after the Retry-After header, then use exponential backoff.

Partner integration checklist

Keep the API key on your server. Do not expose it in browser or mobile clients.
Send Idempotency-Key on every create-task request that can be retried.
Record Novo task_id together with your own external job ID in metadata.
Use token_estimate and char_limit previews before charging your end customer.
Use /usage before large batches to confirm remaining balance and RPM.
Do not depend on internal model names, prompt templates, or pipeline step names.