---
name: epubtranslator-api
description: Operate epubtranslator translation APIs with API key. Use when translating EPUB files via API, automating EPUB translation, or when the user mentions epubtranslator API, EPUB translation API, or translating books programmatically.
---

# EPUB Translator API Skill

## User Interaction

- **Response language:** Reply to the user in the same language they use. If the user asks in Chinese, respond in Chinese; if in English, respond in English; and so on.
- **Tone:** Be polite and friendly. Avoid technical jargon (e.g. API, fileId, preSignedUrl). Explain progress and results in plain, accessible language.
- **Ask target language first:** Before starting the translation flow, always ask: "What language would you like to translate this book into?" (or equivalent in the user's language). Only after the user specifies the target language (Chinese, English, Japanese, etc.) should you call the translation API. Convert to ISO 639-1 codes (e.g. zh, en, ja) when calling the API.
- **Insufficient balance:** Politely inform the user that their balance is insufficient and provide the link https://epubtranslator.app so they can top up.
- **Missing or invalid API key:** If the user has no API key configured or the key is invalid (401 response), prompt them to log in at epubtranslator.app, bind a payment method, and purchase a credit package.
- **Translation complete/failed:** Use friendly wording (e.g. "Translation is done, you can download it now" or "Sorry, something went wrong. Please try again later").
- **Manual proofreading:** When translation fails and requires manual proofreading (status `failed` with `reason: "manual_proofing"` in the status response), inform the user: "Our team is now manually reviewing your translation. We'll notify you when it's ready."

## Authentication

All requests must include the API key. Use one of:

- Header: `Authorization: Bearer <api_key>`
- Header: `X-Api-Key: <api_key>`

Users obtain API keys from https://epubtranslator.app/settings/api-keys (after logging in).

## Base URL

- Production: `https://gateway.meside.com` (or the configured epubtranslator API host)
- Development: `http://localhost:3000`

## Translation Flow (execute in order)

0. **Ask target language** — After the user expresses interest in translating, politely ask what language they want to translate into. Proceed only after they answer.
1. **Pre-upload** `POST /apis/file/pre-upload` — Get fileId and preSignedUploadUrl
2. **Upload file** — If preSignedUploadUrl exists: `PUT` the file to that URL. Otherwise: `POST /apis/file/upload` with multipart/form-data (fileId, file)
3. **Check upload** `POST /apis/file/check` — Parse EPUB, returns cost (charCount, wordCount)
4. **Show user cost** — Tell the user in plain language (e.g. "This book has about X characters/words, and the translation will use that amount of credits" or "The file has been parsed; it contains about X characters"). Ask if they want to continue.
5. **Check balance** `POST /apis/epub-translation/check-balance` — Verify user has sufficient balance
6. **Start translation** `POST /apis/epub-translation/start` — Body: `{ fileId, targetLanguage }` (e.g. targetLanguage: "zh", "en", "ja")
7. **Poll status** `POST /apis/epub-translation/status` — Poll every 60 seconds until status is `completed` or `failed`. Use setInterval or setTimeout; clear when done.
8. **Get download URL** `POST /apis/file/download-url` — After translation completes, get pre-signed download URL

## Polling Reminder

Set a timer to poll status every 60 seconds. When status becomes `completed` or `failed`, clear the timer and proceed (download if completed, report error if failed).

## Additional Resources

See [reference.md](reference.md) for detailed request/response formats and error handling.