Додати текстове накладання до GIF за допомогою REST у Java

Wed, 23 Sep 2026 13:04:19 +0000

Додавання динамічних підписів, субтитрів або рекламних повідомлень до анімованих GIF‑зображень є поширеною потребою для сучасних веб‑ та мобільних застосунків. GroupDocs.Watermark Cloud SDK for Java надає потужну бібліотеку на базі REST, яка спрощує виконання цього завдання. У цьому посібнику ви дізнаєтеся, як додати текстове накладання до GIF за допомогою REST у Java, переглянути повну реалізацію на Java, вивчити еквівалентні команди cURL та зрозуміти необхідні кроки налаштування.

Додати текстову накладку до GIF за допомогою REST у Java - приклад коду

Цей приклад демонструє, як налаштувати текстовий водяний знак і застосувати його до кожного кадру GIF‑файлу.

import com.groupdocs.watermark.cloud.api.WatermarkApi;
import com.groupdocs.watermark.cloud.client.ApiException;
import com.groupdocs.watermark.cloud.client.Configuration;
import com.groupdocs.watermark.cloud.model.AddWatermarkRequest;
import com.groupdocs.watermark.cloud.model.AddWatermarkResponse;
import com.groupdocs.watermark.cloud.model.FileInfo;
import com.groupdocs.watermark.cloud.model.OutputFileInfo;
import com.groupdocs.watermark.cloud.model.TextWatermarkOptions;
import com.groupdocs.watermark.cloud.model.HorizontalAlignment;
import com.groupdocs.watermark.cloud.model.VerticalAlignment;

public class AddTextOverlayToGif {
    public static void main(String[] args) {
        // Initialize API configuration (replace with your actual clientId and clientSecret)
        Configuration config = new Configuration("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
        WatermarkApi watermarkApi = new WatermarkApi(config);

// Prepare input file information
        FileInfo inputFile = new FileInfo();
        inputFile.setFilePath("input.gif");          // Path to the source GIF in the storage
        inputFile.setStorageName("MyStorage");       // Optional: name of the storage

// Prepare output file information
        OutputFileInfo outputFile = new OutputFileInfo();
        outputFile.setFilePath("output.gif");        // Desired path for the watermarked GIF
        outputFile.setStorageName("MyStorage");      // Optional: name of the storage

// Configure text watermark options
        TextWatermarkOptions textOptions = new TextWatermarkOptions();
        textOptions.setText("Sample Watermark");
        textOptions.setFontFamily("Arial");
        textOptions.setFontSize(24.0);
        textOptions.setColor("#FF0000");             // Red color in HEX
        textOptions.setOpacity(0.5);                 // 50% opacity
        textOptions.setRotationAngle(0.0);
        textOptions.setHorizontalAlignment(HorizontalAlignment.CENTER);
        textOptions.setVerticalAlignment(VerticalAlignment.MIDDLE);
        textOptions.setPageRange("1-");               // Apply to all frames/pages

// Build the request
        AddWatermarkRequest request = new AddWatermarkRequest();
        request.setFileInfo(inputFile);
        request.setOutputFileInfo(outputFile);
        request.setOptions(textOptions);

try {
            // Execute the request
            AddWatermarkResponse response = watermarkApi.addWatermark(request);
            System.out.println("Watermark added successfully. Output file: " + response.getPath());
        } catch (ApiException e) {
            System.err.println("Error while adding watermark: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Примітка: Цей приклад коду демонструє основну функціональність. Перш ніж використовувати його у вашому проєкті, переконайтеся, що оновили всі шляхи до файлів та значення конфігурації відповідно до вашого реального середовища, перевірте, що усі необхідні залежності правильно встановлені, і ретельно протестуйте у вашому середовищі розробки. Якщо ви зіткнетеся з будь‑якими проблемами, будь ласка, зверніться до офіційної документації або звʼяжіться з командою підтримки для отримання допомоги.

Накласти текст на GIF за допомогою REST API з використанням cURL

Нижче наведено команди cURL, які виконують ту ж операцію з терміналу. Вони ілюструють повний процес REST: автентифікація, завантаження, додавання водяного знака та завантаження.

# 1. Obtain an access token
curl -X POST "https://api.groupdocs.cloud/v2.0/auth/token" \
     -H "Content-Type: application/json" \
     -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'

Замініть YOUR_ACCESS_TOKEN у наведених нижче викликах на токен, отриманий вище.

# 2. Upload the source GIF to storage
curl -X PUT "https://api.groupdocs.cloud/v2.0/storage/file/input.gif" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/octet-stream" \
     --data-binary @path/to/local/input.gif

# 3. Add text overlay to the GIF
curl -X POST "https://api.groupdocs.cloud/v2.0/watermark/add" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "fileInfo": { "filePath": "input.gif", "storageName": "MyStorage" },
           "outputFileInfo": { "filePath": "output.gif", "storageName": "MyStorage" },
           "options": {
               "text": "Sample Watermark",
               "fontFamily": "Arial",
               "fontSize": 24,
               "color": "#FF0000",
               "opacity": 0.5,
               "horizontalAlignment": "Center",
               "verticalAlignment": "Middle",
               "pageRange": "1-"
           }
         }'

# 4. Download the watermarked GIF
curl -X GET "https://api.groupdocs.cloud/v2.0/storage/file/output.gif" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o path/to/local/output.gif

Для отримання докладнішої інформації про тіла запитів та формати відповідей, перегляньте офіційну документацію API.

Розбір процесу додавання текстового накладання до GIF за допомогою REST у Java - Як це працює

Ініціалізуйте клієнт API - new Configuration("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET") створює об’єкт конфігурації, який містить ваші облікові дані. Екземпляр WatermarkApi використовує цю конфігурацію для підписання кожного запиту.

Configuration config = new Configuration("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
WatermarkApi watermarkApi = new WatermarkApi(config);

Вкажіть вихідний та цільовий файли - FileInfo та OutputFileInfo повідомляють сервісу, де читати оригінальний GIF і куди записати результат. Обидва можуть посилатися на власну назву сховища.
```
FileInfo inputFile = new FileInfo();
inputFile.setFilePath("input.gif");
inputFile.setStorageName("MyStorage");
```
Налаштуйте текстовий водяний знак - TextWatermarkOptions містить усі візуальні властивості: текст, шрифт, розмір, колір, прозорість, обертання та вирівнювання. Встановлення pageRange в "1-" забезпечує, що кожен кадр анімованого GIF отримує накладення.

TextWatermarkOptions textOptions = new TextWatermarkOptions();
textOptions.setText("Sample Watermark");
textOptions.setFontFamily("Arial");
textOptions.setFontSize(24.0);
textOptions.setColor("#FF0000");
textOptions.setOpacity(0.5);
textOptions.setHorizontalAlignment(HorizontalAlignment.CENTER);
textOptions.setVerticalAlignment(VerticalAlignment.MIDDLE);
textOptions.setPageRange("1-");

Створіть і надішліть запит - AddWatermarkRequest об’єднує інформацію про файл та параметри. Виклик watermarkApi.addWatermark(request) виконує операцію на сервері та повертає шлях до обробленого файлу.
```
AddWatermarkRequest request = new AddWatermarkRequest();
request.setFileInfo(inputFile);
request.setOutputFileInfo(outputFile);
request.setOptions(textOptions);
AddWatermarkResponse response = watermarkApi.addWatermark(request);
```
Обробка відповіді - Відповідь містить шлях до вихідного файлу. У реальному застосунку ви зазвичай завантажуєте файл або передаєте шлях іншій службі.

Для повного списку класів і властивостей зверніться до довідки API.

Встановлення та налаштування GroupDocs.Watermark Cloud SDK for Java

Додайте залежність Maven у ваш pom.xml (або відповідний запис Gradle). Це підключає версію 23.8 SDK.


    com.groupdocs
    groupdocs-watermark-cloud
    23.8

Вимоги

Java 8 або вище
Активний обліковий запис GroupDocs Cloud
Client ID та Client Secret (доступні в панелі управління GroupDocs Cloud)

Приклад конфігурації

Configuration config = new Configuration("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");

Завантажте останні JAR‑файли зі сторінки завантаження. Для використання у продакшені застосуйте дійсну ліцензію, отриману зі сторінки тимчасової ліцензії.

Висновок

Додавання текстового накладання до GIF за допомогою REST у Java стає повторюваною сервер‑сторонньою операцією завдяки GroupDocs.Watermark Cloud SDK for Java. SDK абстрагує складність обробки анімованих кадрів, дозволяючи вам зосередитися на вмісті ваших субтитрів або рекламних повідомлень. Після інтеграції зразкового коду або cURL‑процесу ви можете точно налаштувати стилі шрифтів, кольори та прозорість, щоб відповідати вашому бренду. Не забудьте отримати ліцензію для продакшн; деталі ціноутворення доступні на сторінці продукту, а тимчасову ліцензію можна отримати для тестування через temporary license page. Щасливого кодування!

Питання та відповіді

Як додати текстове накладання до GIF за допомогою REST у Java, коли текст змінюється для кожного користувача?
Створіть об’єкт TextWatermarkOptions під час виконання з рядком, специфічним для користувача, а потім викличте той самий метод addWatermark. API обробляє кожен запит незалежно, тому динамічний вміст повністю підтримується.
Чи можу я додати субтитри до анімованого GIF, не впливаючи на швидкість анімації?
Так. Водяний знак застосовується до кожного кадру, зберігаючи оригінальну затримку кадру. Просто встановіть pageRange у "1-", щоб кожен кадр отримав однакове накладання.
Які формати підтримуються для кольору накладеного тексту?
SDK приймає HEX‑коди кольорів (наприклад, #FF0000) та стандартні назви кольорів HTML. Перегляньте довідку API для повного списку.
Чи потрібна мені ліцензія для розробки та тестування?
Тимчасова ліцензія достатня для оцінки та тестування. Для розгортання у продакшн придбайте повну ліцензію зі сторінки продукту та застосуйте її за допомогою API ліцензування SDK.

image watermarking on Document Processing REST APIs | GroupDocs Cloud