================================================================================ KIWIMG - API DE OPTIMIZACION DE IMAGENES ================================================================================ Base URL: https://kiwimg.nexir.es Token: kw1m4g3n-s3cr3t-2024-p3rs0n4l Autenticacion: Token via query parameter ?access=TOKEN ================================================================================ 1. OPTIMIZAR IMAGEN (Upload) ================================================================================ Endpoint: POST /api/optimize?access=TOKEN Content-Type: multipart/form-data PARAMETROS: --------------------------------------------------------------------------- | Campo | Tipo | Requerido | Descripcion | --------------------------------------------------------------------------- | image | File | Si | Archivo de imagen (JPEG, PNG, WebP) | | width | Number | * | Ancho de salida en pixeles | | height | Number | * | Alto de salida en pixeles | | format | String | No | jpeg, png, webp (default: jpeg) | | quality | Number | No | Calidad 1-100 (default: 90) | | seoMetadata | JSON | No | Metadatos EXIF (ver seccion 4) | | watermark | JSON | No | Configuracion watermark (ver sec. 6) | | preset_id | String | No | ID de preset a aplicar (ver sec. 5) | --------------------------------------------------------------------------- * DIMENSIONES FLEXIBLES: - Se requiere al menos width O height (no es necesario ambos) - Si solo se proporciona width: height se calcula automaticamente - Si solo se proporciona height: width se calcula automaticamente - El aspect ratio original se mantiene cuando falta una dimension - Si se proporcionan ambos: la imagen se recorta con fit "cover" EJEMPLO CURL (ambas dimensiones): curl -X POST "https://kiwimg.nexir.es/api/optimize?access=TOKEN" \ -F "image=@foto.jpg" \ -F "width=1200" \ -F "height=550" \ -F "format=webp" \ -F "quality=85" \ -o foto-optimized.webp EJEMPLO CURL (solo width - altura automatica): curl -X POST "https://kiwimg.nexir.es/api/optimize?access=TOKEN" \ -F "image=@foto.jpg" \ -F "width=800" \ -F "format=webp" \ -o foto-800w.webp EJEMPLO CURL (solo height - anchura automatica): curl -X POST "https://kiwimg.nexir.es/api/optimize?access=TOKEN" \ -F "image=@foto.jpg" \ -F "height=600" \ -F "format=jpeg" \ -o foto-600h.jpg RESPUESTA: - Content-Type: image/jpeg, image/png, o image/webp - Body: Archivo de imagen binario - Headers adicionales: - X-Original-Width: Ancho original - X-Original-Height: Alto original - X-Output-Width: Ancho de salida (calculado si no se especifico) - X-Output-Height: Alto de salida (calculado si no se especifico) - X-Output-Format: Formato de salida - X-Output-Quality: Calidad aplicada - X-Watermark-Applied: true/false LIMITES: - Tamano maximo: 50MB - Formatos aceptados: JPEG, PNG, WebP ================================================================================ 2. OPTIMIZAR IMAGEN (Base64) ================================================================================ Endpoint: POST /api/crop-optimize?access=TOKEN Content-Type: application/json Para optimizar imagenes enviadas como Base64 (util desde frontend). PARAMETROS JSON: --------------------------------------------------------------------------- | Campo | Tipo | Requerido | Descripcion | --------------------------------------------------------------------------- | image | String | Si | Imagen en formato Base64 (data:...) | | width | Number | * | Ancho de salida en pixeles | | height | Number | * | Alto de salida en pixeles | | format | String | No | jpeg, png, webp (default: jpeg) | | quality | Number | No | Calidad 1-100 (default: 90) | | seoMetadata | Object | No | Metadatos EXIF (ver seccion 4) | | watermark | Object | No | Configuracion watermark (ver sec. 6) | | preset_id | String | No | ID de preset a aplicar | --------------------------------------------------------------------------- * DIMENSIONES: Mismas reglas que /api/optimize (ver seccion 1) EJEMPLO: { "image": "data:image/jpeg;base64,/9j/4AAQ...", "width": 800, "format": "webp", "quality": 85 } RESPUESTA JSON: { "success": true, "image": "data:image/webp;base64,...", "dimensions": { "width": 800, "height": 450 }, "originalDimensions": { "width": 1920, "height": 1080 }, "format": "webp", "quality": 85 } ================================================================================ 3. GENERAR IMAGEN CON IA ================================================================================ Endpoint: POST /api/generate?access=TOKEN Content-Type: application/json Genera imagenes usando IA (Replicate) y las procesa automaticamente. PARAMETROS JSON: --------------------------------------------------------------------------- | Campo | Tipo | Requerido | Descripcion | --------------------------------------------------------------------------- | prompt | String | Si | Descripcion de la imagen a generar | | model | String | No | Modelo de IA a usar | | width | Number | * | Ancho de salida en pixeles | | height | Number | * | Alto de salida en pixeles | | format | String | No | jpeg, png, webp (default: jpeg) | | quality | Number | No | Calidad 1-100 (default: 90) | | seoMetadata | Object | No | Metadatos EXIF (ver seccion 4) | | watermark | Object | No | Configuracion watermark (ver sec. 6) | --------------------------------------------------------------------------- * DIMENSIONES FLEXIBLES: - Se requiere al menos width O height - Si solo width: se usa aspect ratio 16:9 (landscape) - Si solo height: se usa aspect ratio 9:16 (portrait) - La dimension faltante se calcula del resultado generado EJEMPLO: { "prompt": "A beautiful sunset over mountains", "width": 1200, "height": 630, "format": "webp", "quality": 90 } EJEMPLO (solo width - landscape automatico): { "prompt": "Professional product photo of a coffee cup", "width": 1200, "format": "webp" } RESPUESTA JSON: { "success": true, "image": "data:image/webp;base64,...", "originalImage": "data:image/webp;base64,...", "dimensions": { "width": 1200, "height": 630 }, "originalDimensions": { "width": 1024, "height": 1024 }, "format": "webp", "quality": 90, "model": "black-forest-labs/flux-schnell", "aspectRatio": "16:9", "watermarkApplied": false } ================================================================================ 4. METADATOS SEO (EXIF) ================================================================================ El parametro seoMetadata permite agregar metadatos EXIF a las imagenes. CAMPOS DISPONIBLES: --------------------------------------------------------------------------- | Campo | Tipo | Descripcion | --------------------------------------------------------------------------- | description | String | Descripcion de la imagen (EXIF ImageDescription)| | copyright | String | Copyright (EXIF Copyright) | | artist | String | Autor (EXIF Artist) | | latitude | Number | Latitud GPS (-90 a 90) | | longitude | Number | Longitud GPS (-180 a 180) | --------------------------------------------------------------------------- EJEMPLO: { "description": "Foto de producto para catalogo", "copyright": "2025 Mi Empresa", "artist": "Fotografo", "latitude": 40.4168, "longitude": -3.7038 } EJEMPLO CURL CON SEO: curl -X POST "https://kiwimg.nexir.es/api/optimize?access=TOKEN" \ -F "image=@foto.jpg" \ -F "width=1200" \ -F "format=webp" \ -F 'seoMetadata={"description":"Mi producto","copyright":"2025 MiEmpresa"}' \ -o foto-optimized.webp ================================================================================ 5. PRESETS (CONFIGURACIONES GUARDADAS) ================================================================================ Los presets permiten guardar y reutilizar configuraciones completas (dimensiones, formato, calidad, SEO, watermark). LISTAR PRESETS: --------------------------------------------------------------------------- Endpoint: GET /api/presets?access=TOKEN RESPUESTA: { "success": true, "presets": [ { "id": "preset-m5abc123", "name": "Banner Blog", "createdAt": "2025-12-21T12:00:00.000Z", "config": { "dimensions": { "width": 1200, "height": 630 }, "format": "webp", "quality": 85, "seo": { "copyright": "2025 Mi Empresa" }, "watermark": { "enabled": true, "type": "text", "text": "Mi Marca" } } } ] } CREAR PRESET: --------------------------------------------------------------------------- Endpoint: POST /api/presets?access=TOKEN Content-Type: application/json { "name": "Mi Preset", "config": { "dimensions": { "width": 1200 }, "format": "webp", "quality": 85 } } ACTUALIZAR PRESET: --------------------------------------------------------------------------- Endpoint: PUT /api/presets/:id?access=TOKEN ELIMINAR PRESET: --------------------------------------------------------------------------- Endpoint: DELETE /api/presets/:id?access=TOKEN USAR PRESET EN ENDPOINTS: --------------------------------------------------------------------------- Anadir preset_id a cualquier endpoint de optimizacion o generacion. Los parametros explicitos sobreescriben los del preset. curl -X POST "https://kiwimg.nexir.es/api/optimize?access=TOKEN" \ -F "image=@foto.jpg" \ -F "preset_id=preset-m5abc123" \ -o foto-optimized.webp ================================================================================ 6. MARCA DE AGUA (WATERMARK) ================================================================================ Configuracion de watermark disponible en presets o directamente en requests. CAMPOS DISPONIBLES: --------------------------------------------------------------------------- | Campo | Tipo | Descripcion | --------------------------------------------------------------------------- | enabled | Boolean | Activar/desactivar watermark | | type | String | "image" o "text" | | position | String | Posicion (ver opciones abajo) | | opacity | Number | Opacidad 0-100 | | scale | Number | Tamano % del ancho (solo type=image) | | margin | Number | Margen en pixeles | | text | String | Texto a mostrar (solo type=text) | | textColor | String | Color hex (solo type=text) | | textSize | Number | Tamano en pixeles (solo type=text) | | image | String | Base64 o URL de imagen (solo type=image) | --------------------------------------------------------------------------- POSICIONES DISPONIBLES: top-left, top-center, top-right, middle-left, center, middle-right, bottom-left, bottom-center, bottom-right EJEMPLO WATERMARK DE TEXTO: { "enabled": true, "type": "text", "text": "Mi Marca", "position": "bottom-right", "opacity": 50, "textColor": "#ffffff", "textSize": 24, "margin": 20 } ================================================================================ 7. CODIGOS DE ERROR ================================================================================ | Codigo | Descripcion | ------------------------------------------------------------------------ | 400 | Parametros invalidos o archivo no soportado | | 403 | Token de acceso invalido o faltante | | 404 | Preset no encontrado | | 413 | Archivo demasiado grande | | 429 | Rate limit excedido (Replicate) | | 500 | Error interno del servidor | ------------------------------------------------------------------------ EJEMPLOS DE ERROR: { "error": "Se requiere al menos width o height como numero positivo valido" } { "error": "Prompt is required" } { "error": "Preset not found" } ================================================================================ 8. DIMENSIONES RECOMENDADAS ================================================================================ | Uso | Dimensiones | Aspect Ratio | ------------------------------------------------------- | Wide Banner | 1200x550 | ~2.18:1 | | Wide Banner Small | 900x450 | 2:1 | | Social Media (OG) | 1200x630 | ~1.9:1 | | Instagram Square | 1080x1080 | 1:1 | | Instagram Stories | 1080x1920 | 9:16 | | Full HD | 1920x1080 | 16:9 | | 4K | 3840x2160 | 16:9 | | Twitter Header | 1500x500 | 3:1 | | YouTube Thumbnail | 1280x720 | 16:9 | ------------------------------------------------------- NOTA: Para mantener el aspect ratio original, especifica solo width o height. ================================================================================ FIN DE DOCUMENTACION ================================================================================