Thêm lớp phủ văn bản vào GIF bằng REST trong Java

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

Thêm phụ đề động, tiêu đề phụ hoặc thông điệp quảng cáo vào các tệp GIF động là một nhu cầu phổ biến cho các ứng dụng web và di động hiện đại. GroupDocs.Watermark Cloud SDK for Java cung cấp một thư viện mạnh mẽ dựa trên REST giúp công việc này trở nên đơn giản. Trong hướng dẫn này, bạn sẽ học cách thêm lớp phủ văn bản vào GIF bằng REST trong Java, xem một triển khai Java đầy đủ, khám phá các lệnh cURL tương đương và hiểu các bước thiết lập cần thiết.

Thêm Lớp Văn Bản lên GIF bằng REST trong Java - Mã mẫu

Ví dụ này minh họa cách cấu hình một watermark dạng văn bản và áp dụng nó cho mỗi khung của tệp 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();
        }
    }
}

Lưu ý: Ví dụ mã này minh họa chức năng cốt lõi. Trước khi sử dụng trong dự án của bạn, hãy chắc chắn cập nhật mọi đường dẫn tệp và giá trị cấu hình để phù hợp với môi trường thực tế của bạn, xác minh rằng tất cả các phụ thuộc cần thiết đã được cài đặt đúng cách, và kiểm tra kỹ lưỡng trong môi trường phát triển. Nếu bạn gặp bất kỳ vấn đề nào, vui lòng tham khảo tài liệu chính thức hoặc liên hệ với đội hỗ trợ để được trợ giúp.

Chồng Văn Bản lên GIF bằng REST API sử dụng cURL

Dưới đây là các lệnh cURL thực hiện cùng một thao tác từ terminal. Chúng minh họa quy trình REST đầy đủ: xác thực, tải lên, thêm watermark và tải xuống.

# 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"}'

Thay thế YOUR_ACCESS_TOKEN trong các lời gọi sau bằng token đã trả về ở trên.

# 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

Để biết thêm chi tiết về nội dung yêu cầu và định dạng phản hồi, xem tài liệu API chính thức.

Phân tích Thêm Văn bản Overlay vào GIF bằng REST trong Java - Cách hoạt động

Khởi tạo client API - new Configuration("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET") tạo một đối tượng cấu hình chứa thông tin xác thực của bạn. WatermarkApi sử dụng cấu hình này để ký mỗi yêu cầu.

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

Chỉ định tệp nguồn và tệp đích - FileInfo và OutputFileInfo cho dịch vụ biết nơi đọc GIF gốc và nơi ghi kết quả. Cả hai có thể tham chiếu tới một tên lưu trữ tùy chỉnh.
```
FileInfo inputFile = new FileInfo();
inputFile.setFilePath("input.gif");
inputFile.setStorageName("MyStorage");
```
Cấu hình dấu nước văn bản - TextWatermarkOptions chứa tất cả các thuộc tính hiển thị: văn bản, phông chữ, kích thước, màu sắc, độ trong suốt, góc quay và căn chỉnh. Đặt pageRange thành "1-" đảm bảo mỗi khung của GIF hoạt hình đều nhận được lớp phủ.

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-");

Xây dựng và gửi yêu cầu - AddWatermarkRequest gói thông tin tệp và các tùy chọn. Gọi watermarkApi.addWatermark(request) thực hiện thao tác trên máy chủ và trả về đường dẫn của tệp đã xử lý.

AddWatermarkRequest request = new AddWatermarkRequest();
request.setFileInfo(inputFile);
request.setOutputFileInfo(outputFile);
request.setOptions(textOptions);
AddWatermarkResponse response = watermarkApi.addWatermark(request);

Xử lý phản hồi - Phản hồi chứa đường dẫn tệp đầu ra. Trong một ứng dụng thực tế, bạn thường sẽ tải xuống tệp hoặc truyền đường dẫn cho một dịch vụ khác.

Để xem danh sách đầy đủ các lớp và thuộc tính, tham khảo API reference.

Cài đặt và cấu hình GroupDocs.Watermark Cloud SDK for Java

Thêm phụ thuộc Maven vào pom.xml của bạn (hoặc mục nhập Gradle tương đương). Điều này sẽ kéo về phiên bản 23.8 của SDK.


    com.groupdocs
    groupdocs-watermark-cloud
    23.8

Yêu cầu

Java 8 hoặc cao hơn
Một tài khoản GroupDocs Cloud đang hoạt động
Client ID và Client Secret (có sẵn trong bảng điều khiển GroupDocs Cloud)

Ví dụ cấu hình

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

Tải xuống các tệp JAR mới nhất từ trang tải xuống. Đối với việc sử dụng trong môi trường sản xuất, hãy áp dụng giấy phép hợp lệ được lấy từ trang giấy phép tạm thời.

Kết luận

Thêm lớp phủ văn bản lên GIF bằng REST trong Java trở thành một thao tác lặp lại, chạy phía máy chủ nhờ sự hỗ trợ của GroupDocs.Watermark Cloud SDK for Java. SDK trừu tượng hóa các phức tạp khi xử lý các khung ảnh động, cho phép bạn tập trung vào nội dung của phụ đề hoặc thông điệp quảng cáo. Sau khi tích hợp mã mẫu hoặc quy trình cURL, bạn có thể tinh chỉnh kiểu chữ, màu sắc và độ trong suốt để phù hợp với thương hiệu của mình. Hãy nhớ mua giấy phép sản xuất; thông tin giá cả có sẵn trên trang sản phẩm, và bạn có thể nhận giấy phép tạm thời để thử nghiệm qua trang giấy phép tạm thời. Chúc lập trình vui vẻ!

Câu hỏi thường gặp

Làm thế nào để thêm lớp phủ văn bản lên GIF bằng REST trong Java khi văn bản thay đổi theo người dùng?
Tạo đối tượng TextWatermarkOptions tại thời gian chạy với chuỗi cụ thể cho người dùng, sau đó gọi lại phương thức addWatermark giống như trước. API xử lý mỗi yêu cầu một cách độc lập, vì vậy nội dung động được hỗ trợ hoàn toàn.
Tôi có thể thêm phụ đề vào GIF hoạt hình mà không ảnh hưởng đến tốc độ hoạt hình không?
Có. Đánh dấu nước được áp dụng cho mỗi khung hình trong khi vẫn giữ nguyên độ trễ khung gốc. Chỉ cần đặt pageRange thành "1-" để mỗi khung nhận cùng một lớp phủ.
Các định dạng nào được hỗ trợ cho màu văn bản overlay?
SDK chấp nhận mã màu HEX (ví dụ, #FF0000) và các tên màu chuẩn HTML. Xem tài liệu tham chiếu API để có danh sách đầy đủ.
Tôi có cần giấy phép cho việc phát triển và kiểm thử không?
Giấy phép tạm thời là đủ cho việc đánh giá và kiểm thử. Đối với triển khai sản xuất, mua giấy phép đầy đủ từ trang sản phẩm và áp dụng nó bằng API cấp phép của SDK.

gif text overlay on Document Processing REST APIs | GroupDocs Cloud