Agregar subtítulos dinámicos, leyendas o mensajes promocionales a GIFs animados es una necesidad común para aplicaciones web y móviles modernas. GroupDocs.Watermark Cloud SDK for Java proporciona una potente biblioteca basada en REST que hace que esta tarea sea sencilla. En esta guía aprenderá cómo agregar una superposición de texto a GIF usando REST en Java, ver una implementación completa en Java, explorar comandos cURL equivalentes y comprender los pasos de configuración necesarios.
Añadir superposición de texto a GIF usando REST en Java - Código de ejemplo
Este ejemplo muestra cómo configurar una marca de agua de texto y aplicarla a cada fotograma de un archivo 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 ejemplo de código demuestra la funcionalidad principal. Antes de usarlo en su proyecto, asegúrese de actualizar cualquier ruta de archivo y valores de configuración para que coincidan con su entorno real, verifique que todas las dependencias requeridas estén instaladas correctamente y pruebe exhaustivamente en su entorno de desarrollo. Si encuentra algún problema, consulte la documentación oficial o póngase en contacto con el equipo de soporte para obtener ayuda.
Superponer texto en GIF con API REST usando cURL
A continuación se presentan los comandos cURL que realizan la misma operación desde una terminal. Ilustran el flujo de trabajo completo de REST: autenticación, carga, marca de agua y descarga.
# 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"}'
Reemplace YOUR_ACCESS_TOKEN en las siguientes llamadas con el token devuelto arriba.
# 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 obtener más detalles sobre los cuerpos de solicitud y los formatos de respuesta, consulte la documentación oficial de la API.
Desglosando la adición de superposición de texto a GIF usando REST en Java - Cómo funciona
- Inicializar el cliente API -
new Configuration("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")crea un objeto de configuración que contiene sus credenciales. La instanciaWatermarkApiutiliza esta configuración para firmar cada solicitud.
Configuration config = new Configuration("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
WatermarkApi watermarkApi = new WatermarkApi(config);
Especifique los archivos de origen y destino -
FileInfoyOutputFileInfoindican al servicio dónde leer el GIF original y dónde escribir el resultado. Ambos pueden hacer referencia a un nombre de almacenamiento personalizado.FileInfo inputFile = new FileInfo(); inputFile.setFilePath("input.gif"); inputFile.setStorageName("MyStorage");Configurar la marca de agua de texto -
TextWatermarkOptionscontiene todas las propiedades visuales: texto, fuente, tamaño, color, opacidad, rotación y alineación. ConfigurarpageRangea"1-"garantiza que cada fotograma del GIF animado reciba la superposición.
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-");
Construir y enviar la solicitud -
AddWatermarkRequestagrupa la información del archivo y las opciones. Llamar awatermarkApi.addWatermark(request)realiza la operación en el servidor y devuelve la ruta del archivo procesado.AddWatermarkRequest request = new AddWatermarkRequest(); request.setFileInfo(inputFile); request.setOutputFileInfo(outputFile); request.setOptions(textOptions); AddWatermarkResponse response = watermarkApi.addWatermark(request);Manejar la respuesta - La respuesta contiene la ruta del archivo de salida. En una aplicación real, normalmente descargarías el archivo o pasarías la ruta a otro servicio.
Para obtener una lista completa de clases y propiedades, consulte la referencia de API.
Instalación y configuración de GroupDocs.Watermark Cloud SDK for Java
Agrega la dependencia de Maven a tu pom.xml (o la entrada equivalente de Gradle). Esto incluye la versión 23.8 del SDK.
<dependency>
<groupId>com.groupdocs</groupId>
<artifactId>groupdocs-watermark-cloud</artifactId>
<version>23.8</version>
</dependency>
Requisitos previos
- Java 8 o superior
- Una cuenta activa de GroupDocs Cloud
- Client ID y Client Secret (disponibles en el panel de GroupDocs Cloud)
Ejemplo de configuración
Configuration config = new Configuration("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
Descargue los últimos JARs desde la página de descarga. Para uso en producción, aplique una licencia válida obtenida de la página de licencia temporal.
Conclusión
Agregar superposición de texto a GIF usando REST en Java se convierte en una operación repetible del lado del servidor con la ayuda del GroupDocs.Watermark Cloud SDK for Java. El SDK abstrae la complejidad de manejar fotogramas animados, permitiéndote centrarte en el contenido de tus subtítulos o mensajes promocionales. Después de integrar el código de ejemplo o el flujo de trabajo cURL, puedes ajustar finamente los estilos de fuente, colores y opacidad para que coincidan con tu marca. Recuerda asegurar una licencia de producción; los detalles de precios están disponibles en la página del producto, y se puede obtener una licencia temporal para pruebas a través de la página de licencia temporal. ¡Feliz codificación!
Preguntas frecuentes
¿Cómo agrego una superposición de texto a un GIF usando REST en Java cuando el texto cambia por usuario?
Construya el objetoTextWatermarkOptionsen tiempo de ejecución con la cadena específica del usuario, luego invoque la misma llamadaaddWatermark. La API procesa cada solicitud de forma independiente, por lo que el contenido dinámico es totalmente compatible.¿Puedo añadir subtítulos a un GIF animado sin afectar su velocidad de animación?
Sí. La marca de agua se aplica a cada fotograma mientras se conserva el retraso original del fotograma. Simplemente establezcapageRangeen"1-"para que cada fotograma reciba la misma superposición.¿Qué formatos son compatibles para el color del texto superpuesto?
El SDK acepta códigos de color HEX (p. ej.,#FF0000) y nombres de color estándar de HTML. Consulte la referencia de API para la lista completa.¿Necesito una licencia para desarrollo y pruebas?
Una licencia temporal es suficiente para la evaluación y pruebas. Para implementaciones en producción, compre una licencia completa en la página del producto y aplíquela mediante la API de licencias del SDK.