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();
        }
    }
}

Note: 이 코드 예제는 핵심 기능을 보여줍니다. 프로젝트에서 사용하기 전에 파일 경로와 구성 값을 실제 환경에 맞게 업데이트하고, 모든 필수 종속성이 올바르게 설치되었는지 확인하며, 개발 환경에서 충분히 테스트하십시오. 문제가 발생하면 공식 문서를 참조하거나 지원 팀에게 문의하십시오.

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

Handle the response - 응답에는 출력 파일 경로가 포함됩니다. 실제 애플리케이션에서는 일반적으로 파일을 다운로드하거나 경로를 다른 서비스에 전달합니다.

전체 클래스 및 속성 목록은 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 계정
Client ID 및 Client Secret (GroupDocs Cloud 대시보드에서 확인 가능)

구성 예시

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

최신 JAR를 다운로드 페이지에서 받으세요. 프로덕션 사용을 위해서는 임시 라이선스 페이지에서 얻은 유효한 라이선스를 적용하십시오.

결론

REST를 사용하여 Java에서 GIF에 텍스트 오버레이를 추가하는 작업은 GroupDocs.Watermark Cloud SDK for Java의 도움으로 반복 가능한 서버‑사이드 작업이 됩니다. SDK는 애니메이션 프레임 처리를 추상화하여 자막이나 홍보 메시지의 내용에 집중할 수 있게 합니다. 샘플 코드 또는 cURL 워크플로를 통합한 후에는 글꼴 스타일, 색상 및 투명도를 브랜드에 맞게 미세 조정할 수 있습니다. 프로덕션 라이선스를 확보해야 하며, 가격 세부 정보는 제품 페이지에서 확인할 수 있고, 테스트용 임시 라이선인은 temporary license page에서 얻을 수 있습니다. 코딩 즐겁게 하세요!

FAQs

사용자마다 텍스트가 변경될 때 Java에서 REST를 사용하여 GIF에 텍스트 오버레이를 추가하려면 어떻게 해야 하나요?
TextWatermarkOptions 객체를 런타임에 사용자별 문자열로 생성한 다음 동일한 addWatermark 호출을 수행합니다. API는 각 요청을 독립적으로 처리하므로 동적 콘텐츠가 완전히 지원됩니다.
애니메이션 GIF에 자막을 추가하면서 애니메이션 속도에 영향을 주지 않을 수 있나요?
예. 워터마크는 원본 프레임 지연을 유지하면서 각 프레임에 적용됩니다. pageRange를 "1-"으로 설정하면 모든 프레임에 동일한 오버레이가 적용됩니다.
오버레이 텍스트 색상에 대해 지원되는 형식은 무엇입니까?
SDK는 HEX 색상 코드(예: #FF0000)와 표준 HTML 색상 이름을 허용합니다. 전체 목록은 API 참조에서 확인하십시오.
개발 및 테스트에 라이선스가 필요합니까?
평가 및 테스트에는 임시 라이선스로 충분합니다. 프로덕션 배포의 경우 제품 페이지에서 정식 라이선스를 구매하고 SDK의 라이선스 API를 사용하여 적용하십시오.

image watermarking on Document Processing REST APIs | GroupDocs Cloud