Tutorial: How to Send DjVu Files for Conversion

Learning Objectives

In this tutorial, you’ll learn:

How to authenticate with the Aspose.OCR Cloud API
How to prepare a DjVu file for submission
How to structure a proper API request
How to send the DjVu file to the conversion queue
How to handle the API response

Prerequisites

Before starting this tutorial, you should have:

An Aspose Cloud account (sign up for free)
Your Client ID and Client Secret from the Aspose Cloud dashboard
Basic understanding of REST APIs
A development environment with tools for making HTTP requests (cURL, Postman, or your preferred programming language)
A DjVu file for testing

Authentication Process

All requests to the Aspose.OCR Cloud API require authorization via an access token. Let’s start by obtaining this token.

Step 1: Get Access Token

To get an access token, you need to send a POST request to the Aspose.OCR Cloud authorization endpoint with your Client ID and Client Secret.

curl -X POST "https://api.aspose.cloud/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

The response will contain your access token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "bearer"
}

This token remains valid for 1 hour (3600 seconds). Store this token securely and use it in all subsequent API calls.

Try It Yourself

Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual credentials
Execute the request using cURL or Postman
Verify you receive a valid access token
Make note of this token for use in the next steps

Preparing DjVu for Conversion

Before sending a DjVu file to the API, you need to:

Read the file content: Access the DjVu file from your file system
Encode to Base64: Convert the binary data to a Base64 string

Converting a File to Base64

Here’s how to convert a file to Base64 in different environments:

Command Line (Linux/macOS)

base64 -i your-file.djvu

PowerShell (Windows)

[Convert]::ToBase64String([IO.File]::ReadAllBytes("your-file.djvu"))

Programming Languages

Python

import base64

with open("your-file.djvu", "rb") as file:
    encoded_string = base64.b64encode(file.read()).decode("utf-8")

JavaScript (Node.js)

const fs = require('fs');

const file = fs.readFileSync('your-file.djvu');
const encodedFile = Buffer.from(file).toString('base64');

using System;
using System.IO;

string filePath = "your-file.djvu";
byte[] fileBytes = File.ReadAllBytes(filePath);
string encodedFile = Convert.ToBase64String(fileBytes);

Try It Yourself

Choose one of the methods above to encode your DjVu file
Verify the output is a valid Base64 string (it should contain only letters, numbers, ‘+’, ‘/’ and possibly ‘=’ for padding)
Keep this encoded string for the next step

Sending DjVu for Conversion

Now that you have an access token and a Base64-encoded DjVu file, you can send the file for conversion.

Step 2: Submit DjVu File

Send a POST request to the DjVu to PDF conversion endpoint with your DjVu file:

curl --request POST --location 'https://api.aspose.cloud/v5.0/ocr/djvu2pdf' \
--header 'Accept: text/plain' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data-raw '{
  "image": "YOUR_BASE64_ENCODED_DJVU_FILE"
}'

Replace:

YOUR_ACCESS_TOKEN with the token you obtained in Step 1
YOUR_BASE64_ENCODED_DJVU_FILE with your Base64-encoded DjVu file

Understanding the API Endpoint

Let’s break down the important components of this request:

Endpoint URL: https://api.aspose.cloud/v5.0/ocr/djvu2pdf
- This is the specific endpoint for DjVu to PDF conversion
HTTP Method: POST
- We’re sending data to the server
Headers:
- Accept: text/plain: Expects a plain text response
- Content-Type: application/json: Indicates we’re sending JSON data
- Authorization: Bearer YOUR_ACCESS_TOKEN: Authenticates the request
Request Body:
- A JSON object containing the image property with the Base64-encoded DjVu file

Response Handling

If successful, the API will return a unique task ID (GUID) as a plain text response:

a197aade-bba9-4c7a-92c7-46851b3dceaa

This ID is crucial as it’s used to retrieve the conversion results later.

Try It Yourself

Replace the placeholders in the cURL command with your actual access token and Base64-encoded DjVu file
Execute the request
Save the task ID returned in the response

Common Issues and Troubleshooting

When submitting DjVu files for conversion, you might encounter these common issues:

Authentication Issues

401 Unauthorized: Your access token may be invalid or expired
- Solution: Generate a new access token

File Issues

Invalid Base64 string: The encoding might be incorrect
- Solution: Ensure your Base64 string doesn’t contain line breaks or invalid characters
File too large: Very large files might cause timeout issues
- Solution: Consider splitting large documents into smaller files

Request Issues

400 Bad Request: Your JSON structure might be incorrect
- Solution: Verify your JSON payload has the correct format
Connection Issues: Network problems can interrupt the request
- Solution: Implement retry logic in your application

Programming Examples

Here are complete examples for submitting DjVu files in popular programming languages:

Python Example

import requests
import base64
import json

# Authentication
auth_url = "https://api.aspose.cloud/connect/token"
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"

auth_data = {
    "grant_type": "client_credentials",
    "client_id": client_id,
    "client_secret": client_secret
}

auth_response = requests.post(auth_url, data=auth_data, headers={"Content-Type": "application/x-www-form-urlencoded"})
access_token = auth_response.json()["access_token"]

# Encode DjVu file
with open("sample.djvu", "rb") as file:
    encoded_file = base64.b64encode(file.read()).decode("utf-8")

# Send for conversion
conversion_url = "https://api.aspose.cloud/v5.0/ocr/djvu2pdf"
headers = {
    "Accept": "text/plain",
    "Content-Type": "application/json",
    "Authorization": f"Bearer {access_token}"
}

payload = {
    "image": encoded_file
}

response = requests.post(conversion_url, headers=headers, data=json.dumps(payload))
task_id = response.text

print(f"Conversion task ID: {task_id}")

C# Example

using System;
using System.IO;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        // Authentication
        var client = new HttpClient();
        var authContent = new FormUrlEncodedContent(new[]
        {
            new KeyValuePair<string, string>("grant_type", "client_credentials"),
            new KeyValuePair<string, string>("client_id", "YOUR_CLIENT_ID"),
            new KeyValuePair<string, string>("client_secret", "YOUR_CLIENT_SECRET")
        });

        var authResponse = await client.PostAsync("https://api.aspose.cloud/connect/token", authContent);
        var authResult = await JsonSerializer.DeserializeAsync<TokenResponse>(await authResponse.Content.ReadAsStreamAsync());
        
        // Encode DjVu file
        byte[] fileBytes = File.ReadAllBytes("sample.djvu");
        string encodedFile = Convert.ToBase64String(fileBytes);
        
        // Send for conversion
        var conversionClient = new HttpClient();
        conversionClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {authResult.access_token}");
        
        var payload = new
        {
            image = encodedFile
        };
        
        var jsonContent = new StringContent(
            JsonSerializer.Serialize(payload),
            Encoding.UTF8,
            "application/json"
        );
        
        var conversionResponse = await conversionClient.PostAsync(
            "https://api.aspose.cloud/v5.0/ocr/djvu2pdf",
            jsonContent
        );
        
        var taskId = await conversionResponse.Content.ReadAsStringAsync();
        Console.WriteLine($"Conversion task ID: {taskId}");
    }
}

class TokenResponse
{
    public string access_token { get; set; }
    public int expires_in { get; set; }
    public string token_type { get; set; }
}

JavaScript (Node.js) Example

const fs = require('fs');
const axios = require('axios');
const FormData = require('form-data');
const qs = require('querystring');

async function convertDjVuToPdf() {
    try {
        // Authentication
        const authResponse = await axios.post('https://api.aspose.cloud/connect/token', 
            qs.stringify({
                grant_type: 'client_credentials',
                client_id: 'YOUR_CLIENT_ID',
                client_secret: 'YOUR_CLIENT_SECRET'
            }),
            {
                headers: {
                    'Content-Type': 'application/x-www-form-urlencoded'
                }
            }
        );
        
        const accessToken = authResponse.data.access_token;
        
        // Encode DjVu file
        const fileBuffer = fs.readFileSync('sample.djvu');
        const encodedFile = fileBuffer.toString('base64');
        
        // Send for conversion
        const conversionResponse = await axios.post(
            'https://api.aspose.cloud/v5.0/ocr/djvu2pdf',
            {
                image: encodedFile
            },
            {
                headers: {
                    'Accept': 'text/plain',
                    'Content-Type': 'application/json',
                    'Authorization': `Bearer ${accessToken}`
                }
            }
        );
        
        const taskId = conversionResponse.data;
        console.log(`Conversion task ID: ${taskId}`);
        
    } catch (error) {
        console.error('Error:', error.response ? error.response.data : error.message);
    }
}

convertDjVuToPdf();

What You’ve Learned

In this tutorial, you’ve learned:

How to authenticate with the Aspose.OCR Cloud API
How to prepare DjVu files by encoding them to Base64
How to structure and send an API request for DjVu to PDF conversion
How to handle the API response and obtain a task ID
Common issues and their solutions
Implementation examples in popular programming languages

Next Steps

Now that you’ve successfully submitted a DjVu file for conversion, the next step is to learn how to retrieve the converted PDF document:

Tutorial: How to Fetch PDF Conversion Results

Further Practice

Try converting different sizes and types of DjVu files
Implement error handling and retry logic in your code
Create a simple application that automates the submission process
Experiment with batch processing multiple DjVu files

Helpful Resources

Have questions about this tutorial? Feel free to post on our support forum.