REST を使用して Java で GIF にテキストオーバーレイを追加する

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

アニメーションGIFに動的なキャプション、字幕、またはプロモーションメッセージを追加することは、現代のウェブやモバイルアプリケーションで一般的なニーズです。 GroupDocs.Watermark Cloud SDK for Java は、このタスクを簡単に実行できる強力なRESTベースのライブラリを提供します。このガイドでは、JavaでRESTを使用してGIFにテキストオーバーレイを追加する方法を学び、完全なJava実装を確認し、同等のcURLコマンドを探り、必要なセットアップ手順を理解します。

REST を使用した Java での 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 リファレンスをご参照ください。

GroupDocs.Watermark Cloud SDK for Java のインストールと構成

Maven の依存関係を pom.xml に追加します（または同等の Gradle エントリ）。これにより SDK のバージョン 23.8 が取得されます。


    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 をダウンロードページから取得してください。本番環境で使用する場合は、一時ライセンスページから取得した有効なライセンスを適用してください。

結論

Java の REST を使用して GIF にテキストオーバーレイを追加することは、GroupDocs.Watermark Cloud SDK for Java の助けにより、繰り返し可能なサーバーサイド操作になります。SDK はアニメーションフレームの処理の複雑さを抽象化し、字幕やプロモーションメッセージの内容に集中できるようにします。サンプルコードまたは cURL ワークフローを統合した後、フォントスタイル、色、透明度をブランドに合わせて微調整できます。製品ページで価格情報が確認できる本番ライセンスを取得することを忘れずに、テスト用には一時ライセンスページから一時ライセンスを取得できます。ハッピーコーディング！

よくある質問

ユーザーごとにテキストが変わる場合、REST を使用して Java で GIF にテキストオーバーレイを追加するにはどうすればよいですか？
TextWatermarkOptions オブジェクトを実行時にユーザー固有の文字列で構築し、同じ addWatermark 呼び出しを実行します。API は各リクエストを独立して処理するため、動的コンテンツが完全にサポートされます。
アニメーションGIFに字幕を追加しても、アニメーション速度に影響を与えませんか？
はい。ウォーターマークは各フレームに適用され、元のフレーム遅延は保持されます。pageRange を "1-" に設定すれば、すべてのフレームが同じオーバーレイを受け取ります。
オーバーレイテキストの色にサポートされている形式は何ですか？
SDK は HEX カラーコード（例: #FF0000）および標準の HTML カラー名を受け入れます。完全な一覧は API リファレンスを参照してください。
開発およびテストにライセンスは必要ですか？
評価およびテストには一時ライセンスで十分です。本番環境へのデプロイでは、製品ページからフルライセンスを購入し、SDK のライセンス API を使用して適用してください。

image watermarking on Document Processing REST APIs | GroupDocs Cloud