Adicionar legendas dinâmicas, subtítulos ou mensagens promocionais a GIFs animados é uma necessidade comum para aplicações web e móveis modernas. GroupDocs.Watermark Cloud SDK for Java fornece uma poderosa biblioteca baseada em REST que torna essa tarefa simples. Neste guia você aprenderá como adicionar sobreposição de texto a GIF usando REST em Java, ver uma implementação completa em Java, explorar comandos cURL equivalentes e entender as etapas de configuração necessárias.

Adicionar Sobreposição de Texto a GIF Usando REST em Java - Código de Exemplo

Este exemplo demonstra como configurar uma marca d’água de texto e aplicá‑la a cada quadro de um arquivo 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();
        }
    }
}

Nota: Este exemplo de código demonstra a funcionalidade principal. Antes de usá‑lo em seu projeto, certifique‑se de atualizar quaisquer caminhos de arquivos e valores de configuração para corresponder ao seu ambiente real, verifique se todas as dependências necessárias estão devidamente instaladas e teste minuciosamente em seu ambiente de desenvolvimento. Se encontrar algum problema, consulte a documentação oficial ou entre em contato com a equipe de suporte para obter assistência.

Sobrepor Texto em GIF com API REST Usando cURL

Abaixo estão os comandos cURL que executam a mesma operação a partir de um terminal. Eles ilustram o fluxo de trabalho completo da API REST: autenticação, upload, marca d’água e download.

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

Substitua YOUR_ACCESS_TOKEN nas chamadas a seguir pelo token retornado acima.

# 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

Para mais detalhes sobre os corpos de requisição e formatos de resposta, veja a documentação oficial da API.

Desmembrando a Adição de Sobreposição de Texto a GIF Usando REST em Java - Como Funciona

  1. Inicializar o cliente da API - new Configuration("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET") cria um objeto de configuração que contém suas credenciais. A instância WatermarkApi usa essa configuração para assinar cada solicitação.
Configuration config = new Configuration("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
WatermarkApi watermarkApi = new WatermarkApi(config);

  1. Especifique os arquivos de origem e destino - FileInfo e OutputFileInfo informam ao serviço onde ler o GIF original e onde gravar o resultado. Ambos podem referenciar um nome de armazenamento personalizado.

    FileInfo inputFile = new FileInfo();
inputFile.setFilePath("input.gif");
inputFile.setStorageName("MyStorage");

  2. Configure a marca d’água de texto - TextWatermarkOptions contém todas as propriedades visuais: texto, fonte, tamanho, cor, opacidade, rotação e alinhamento. Definir pageRange como "1-" garante que cada quadro do GIF animado receba a sobreposição.

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-");
  1. Construa e envie a solicitação - AddWatermarkRequest agrupa as informações do arquivo e as opções. Chamando watermarkApi.addWatermark(request) executa a operação no servidor e retorna o caminho do arquivo processado.
AddWatermarkRequest request = new AddWatermarkRequest();
request.setFileInfo(inputFile);
request.setOutputFileInfo(outputFile);
request.setOptions(textOptions);
AddWatermarkResponse response = watermarkApi.addWatermark(request);
  1. Manipular a resposta - A resposta contém o caminho do arquivo de saída. Em uma aplicação real, você normalmente faria o download do arquivo ou passaria o caminho para outro serviço.

Para obter uma lista completa de classes e propriedades, consulte a referência da API.

Instalando e Configurando GroupDocs.Watermark Cloud SDK for Java

Adicione a dependência Maven ao seu pom.xml (ou a entrada equivalente do Gradle). Isso traz a versão 23.8 do SDK.

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-watermark-cloud</artifactId>
    <version>23.8</version>
</dependency>

Pré-requisitos

  • Java 8 ou superior
  • Uma conta ativa do GroupDocs Cloud
  • Client ID e Client Secret (disponíveis no painel do GroupDocs Cloud)

Exemplo de Configuração

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

Baixe os JARs mais recentes na página de download. Para uso em produção, aplique uma licença válida obtida na página de licença temporária.

Conclusão

Adicionar sobreposição de texto a GIF usando REST em Java se torna uma operação repetível, do lado do servidor, com a ajuda do GroupDocs.Watermark Cloud SDK for Java. O SDK abstrai as complexidades de manipular quadros animados, permitindo que você se concentre no conteúdo de suas legendas ou mensagens promocionais. Após integrar o código de exemplo ou o fluxo de trabalho cURL, você pode ajustar finamente estilos de fonte, cores e opacidade para combinar com sua marca. Lembre‑se de garantir uma licença de produção; detalhes de preços estão disponíveis na página do produto, e uma licença temporária pode ser obtida para testes através da página de licença temporária. Feliz codificação!

Perguntas Frequentes

  • Como adiciono sobreposição de texto a um GIF usando REST em Java quando o texto muda por usuário?
    Construa o objeto TextWatermarkOptions em tempo de execução com a string específica do usuário e, em seguida, invoque a mesma chamada addWatermark. A API processa cada solicitação de forma independente, portanto, o conteúdo dinâmico é totalmente suportado.

  • Posso adicionar legendas a um GIF animado sem afetar a velocidade da animação?
    Sim. A marca d’água é aplicada a cada quadro enquanto preserva o atraso original do quadro. Basta definir pageRange como "1-" para que cada quadro receba a mesma sobreposição.

  • Quais formatos são suportados para a cor do texto sobreposto?
    O SDK aceita códigos de cores HEX (por exemplo, #FF0000) e nomes de cores padrão do HTML. Consulte a referência da API para a lista completa.

  • Preciso de uma licença para desenvolvimento e teste?
    Uma licença temporária é suficiente para avaliação e teste. Para implantações de produção, adquira uma licença completa na página do produto e aplique‑a usando a API de licenciamento do SDK.

Read More