Добавление динамических подписей, субтитров или рекламных сообщений к анимированным 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.
<dependency>
<groupId>com.groupdocs</groupId>
<artifactId>groupdocs-watermark-cloud</artifactId>
<version>23.8</version>
</dependency>
Требования
- 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‑процесса вы можете точно настроить стили шрифтов, цвета и непрозрачность в соответствии с вашим брендом. Не забудьте оформить производственную лицензию — детали ценообразования доступны на странице продукта, а временную лицензию можно получить для тестирования через страницу временной лицензии. Приятного кодинга!
Часто задаваемые вопросы
Как добавить текстовый наложение на GIF с помощью REST в Java, когда текст меняется для каждого пользователя?
Создайте объектTextWatermarkOptionsво время выполнения с пользовательской строкой, затем вызовите тот же методaddWatermark. API обрабатывает каждый запрос независимо, поэтому динамический контент полностью поддерживается.Могу ли я добавить субтитры к анимированному GIF без изменения скорости анимации?
Да. Водяной знак применяется к каждому кадру, сохраняя исходную задержку кадра. Просто установитеpageRangeв"1-", чтобы каждый кадр получил одинаковое наложение.Какие форматы поддерживаются для цвета наложенного текста?
SDK принимает HEX‑коды цветов (например,#FF0000) и стандартные названия цветов HTML. См. справку API для полного списка.Нужна ли лицензия для разработки и тестирования?
Временная лицензия достаточна для оценки и тестирования. Для развертывания в продакшн приобретите полную лицензию на странице продукта и примените её с помощью API лицензирования SDK.