Version: 1.0
Last Updated: 2021.10.26

Get started

This is e-book translation API of Booken.ru service.
Use this API to translate EPUB, FB2, TEXT e-books to one of 107 supported languages.
For example: English, French, German, Spanish, Italian, Russian etc.
Up to 100% guaranteed to save e-book structure.

To use this API, you need to deposit your personal account balance.
Please contact us at booken.ru@yandex.ru to deposit your account balance.

API endpoint

To access to API you should use GET or POST request to this endpoint: https://booken.ru/api

To call any API method you should use method parameter, for example: https://booken.ru/api/?method=server_health

Almost all API methods return JSON structure with response code 200 on success or 400 on error.

On success example: {"data":"OK"}

On error example: {"error":"Method not allowed"}

Public methods

  • server_health
  • supported_doc_formats
  • supported_input_languages
  • supported_output_languages
  • max_file_upload_in_bytes
  • create_new_api_key
  • check_api_key
  • get_currency_rate

Private methods

To call any private method you should use your personal API key. Create an API key you can with create_new_api_key method.

  • get_account_balance
  • translate_book
  • check_translation_status
  • download_translated_document

server_health

Recommended to use this method to determine an API availability.

On success response

Field Value
data "OK"

supported_doc_formats

Returns the supported document formats that can be translated.

On success response

Field Value
data.extension [array]
data.mime_type [array]

supported_input_languages

Returns the supported languages of the input document that can be translated.

On success response

Field Value
data [array]

supported_output_languages

Returns the supported languages of the output document that can be translated.

On success response

Field Value
data [array]

max_file_upload_in_bytes

Returns the maximum size of the uploaded file, in bytes, that can be translated.

On success response

Field Value
data integer

create_new_api_key

Creates new API key (or updates old). API key will be send to your email.

Input parameters

Field Type Description
email string Your email address.

On success response

Field Value
data.status "OK"
data.info string

check_api_key

Allows to debug a server connection with your API key.

Input parameters

Field Type Description
email string Your email address.
md5_of_api_key string Hash of your API key. For example: $md5_of_api_key=md5("87fe06f55b1a60c54bcb01e66070da29");

On success response

Field Value
data "OK"

get_currency_rate

Return actual currency rates used in products price.

On success response

Field Value Description
data.USD_RUB float USD_RUB rate

get_account_balance PRIVATE

Show your account balance. Should be used before uploading a book for translation.

Input parameters

Field Type Description
email string Your email address.
md5_of_api_key string Hash of your API key.

On success response

Field Value Description
data.status "OK"
data.balance integer Your account balance (in Russian rubles).
data.recommended_endpoint_price integer Official price recommended for one book translation.
data.your_personal_profit_per_sale integer Your personal profit per one sale.
data.can_translate_book_amount integer Shows amount of book translation that available for your current account balance.

translate_book PRIVATE

Allows to upload an ebook for translation. To upload a document you should use multipart/form-data enctype and POST request.

Input parameters

Field Type Description
email string Your email address.
md5_of_api_key string Hash of your API key.
translate_to_language string Language for translated e-book. See supported languages with supported_output_languages
book_file_name file Uploaded file for translation.

On success response

Field Value Description
order_id integer Requires to save an 'order_id' value. It allow to download translated book with download_translated_document
book_file_name string Original file name of ebook.
file_size integer Size of ebook file in bytes.
info string Additional information.

Example of HTML-form for upload ebook for translation

<form id="upload-book-form" method="post" enctype="multipart/form-data" action="https://booken.ru/api/">
	<input type="file" name="book_file_name" required="">
	<button type="submit">Translate book</button>
	<input type="hidden" name="method" value="translate_book">
	<input type="hidden" name="email" value="youremail@example.com">
	<input type="hidden" name="md5_of_api_key" value="4c501e8937759f54d3cbd8d0f655453a">
	<input type="hidden" name="translate_to_language" value="ru">
</form>

JAVA example:

HttpPost httpPost = new HttpPost("https://booken.ru/api/");
    HttpEntity entity = MultipartEntityBuilder.create()
        .addTextBody("method", "translate_book")
        .addTextBody("email", accountEmail)
        .addTextBody("md5_of_api_key", md5ApiKey)
        .addTextBody("translate_to_language", translateToLanguage)
        .addBinaryBody("book_file_name", streamToTranslate, ContentType.APPLICATION_OCTET_STREAM, uploadedFileName)
        .build();

    try (CloseableHttpClient httpClient = HttpClientBuilder.create().build();
         CloseableHttpResponse response = httpClient.execute(httpPost)) {
        //handle response
    }

check_translation_status PRIVATE

Allows to determine the status of the document translation. If status is READY then can download translated ebook with download_translated_document

Input parameters

Field Type Description
email string Your email address.
md5_of_api_key string Hash of your API key.
order_id integer The translation order number returned by translate_book method.

On success response

Field Value Description
data.status "IN_PROGRESS" or "READY" Translation status.
data.order_id integer The translation order number.
data.info string Additional information.

download_translated_document PRIVATE

Allows to download the translated ebook.

Input parameters

Field Type Description
email string Your email address.
md5_of_api_key string Hash of your API key.
order_id integer The translation order number.

On success response

Return translated files by HTTPS protocol.
General HTML headers:
Content-Description: File Transfer
Content-Type: application/octet-stream