使用 REST 在 Java 中向 GIF 添加文字覆盖

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

向动画 GIF 添加动态标题、字幕或宣传信息是现代网页和移动应用的常见需求。 GroupDocs.Watermark Cloud SDK for Java 提供了一个强大的基于 REST 的库，使此任务变得简单直观。在本指南中，您将学习如何 使用 REST 在 Java 中为 GIF 添加文本覆盖，查看完整的 Java 实现，探索等效的 cURL 命令，并了解所需的设置步骤。

在 Java 中使用 REST 为 GIF 添加文字覆盖 - 示例代码

本示例演示如何配置文本水印并将其应用于 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();
        }
    }
}

注意： 此代码示例演示了核心功能。在将其用于项目之前，请确保更新所有文件路径和配置值以匹配实际环境，验证已正确安装所有必需的依赖项，并在开发环境中进行彻底测试。如果遇到任何问题，请参阅官方文档或联系支持团队获取帮助。

使用 cURL 的 REST API 在 GIF 上叠加文本

下面是从终端执行相同操作的 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 文档。

拆解使用 REST 在 Java 中为 GIF 添加文本覆盖的工作原理

初始化 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 reference。

安装和配置 GroupDocs.Watermark Cloud SDK for Java

将 Maven 依赖添加到您的 pom.xml（或等效的 Gradle 条目）。这将引入 SDK 的 23.8 版本。


    com.groupdocs
    groupdocs-watermark-cloud
    23.8

先决条件

Java 8 或更高
有效的 GroupDocs Cloud 账户
客户端 ID 和客户端密钥（可在 GroupDocs Cloud 仪表板中获取）

配置示例

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

从下载页面下载最新的 JAR。对于生产环境，请使用从临时许可证页面获取的有效许可证。

结论

使用 REST 在 Java 中为 GIF 添加文字覆盖，借助 GroupDocs.Watermark Cloud SDK for Java 可实现可重复的服务器端操作。该 SDK 抽象了处理动画帧的复杂性，让您专注于字幕或宣传信息的内容。集成示例代码或 cURL 工作流后，您可以微调字体样式、颜色和不透明度，以匹配您的品牌。请记得获取生产许可证，产品页面上提供了定价详情，您也可以通过临时许可证页面获取用于测试的临时许可证。祝编码愉快！

常见问题

如何在 Java 中使用 REST 向 GIF 添加文本覆盖，并且文本随用户变化？
在运行时使用用户特定的字符串构建 TextWatermarkOptions 对象，然后调用相同的 addWatermark 方法。API 会独立处理每个请求，因此完全支持动态内容。
我可以在不影响动画速度的情况下为动画 GIF 添加字幕吗？
是的。水印会应用于每一帧，同时保留原始帧延迟。只需将 pageRange 设置为 "1-"，即可让每一帧都收到相同的覆盖。
支持哪些格式的覆盖文本颜色？
SDK 接受十六进制颜色代码（例如 #FF0000）和标准的 HTML 颜色名称。请参阅 API 参考获取完整列表。
我需要为开发和测试获取许可证吗？
临时许可证足以用于评估和测试。对于生产部署，请从产品页面购买完整许可证，并使用 SDK 的授权 API 应用它。

image watermarking on Document Processing REST APIs | GroupDocs Cloud