Automatizar el proceso de trabajo de posproducción con la API de Imagen

  • Actualización

Resumen de Imagen

Imagen es una solución basada en IA que ahorra horas de trabajo de posproducción a los fotógrafos profesionales. 

¿Cómo funciona? 

Los fotógrafos crean un perfil de IA o eligen un perfil de Talent IA o de Imagen AI. Luego, suben fotos a Imagen. Imagen edita las fotos con su perfil de IA en mucho menos de lo que se tardaría en hacerlo manualmente. Por último, exportan las fotos y se las entregan a los clientes.

La API de Imagen agiliza y automatiza el proceso de posproducción del fotógrafo de forma parecida a como lo hace la aplicación Imagen. Este documento explica el proceso y los puntos finales a los que hay que llamar. Algunas de las funciones de la aplicación Imagen aún no están disponibles en la API. Esta documentación cubre los puntos finales compatibles con la API de Imagen.

 

1. Antes de empezar

Configura tu entorno. Regístrate en Imagen y obtén tu clave API. Hemos incluido una colección de Postman y un ejemplo de código de Python para enseñarte a usar nuestra API. Revisa la información de esta sección para asegurarte de que tu entorno está listo y de que entiendes las cuestiones básicas para poder trabajar con la API.

Regístrate

Tienes que registrarte en Imagen para poder usar la API.  Una vez hecho, envía un correo electrónico al equipo de Éxito del Cliente de Imagen para solicitar una clave de API. En el correo electrónico, incluye la dirección que hayas usado para registrarte en Imagen.

URL base de Imagen

La URL base de la API de Imagen es https://api-beta.imagen-ai.com/v1/.

Documentos de la API de referencia

Aquí tienes la documentación de la API de referencia para la API de Imagen.

Colección Postman

Usa la colección de Postman para utilizar la API de Imagen.

  1. Descarga la colección de Postman en tu ordenador.
  2. Abre Postman.
  3. Ve a Archivo > Importar para abrir la colección en Postman.

Ejemplo de código de Python

Nuestro ejemplo de código Python te indica cómo llamar a los puntos finales de la API de Imagen para editar fotos. También muestra el subprocesamiento, que te permite procesar varios lotes de fotos al mismo tiempo en vez de esperar a que termine cada lote.

Autenticación

La API de Imagen utiliza una clave de API para la autenticación. Añádela en el encabezado de tus solicitudes con formato de texto. El nombre del encabezado es x-api-key. 

Aquí tienes un ejemplo:

curl --location ‘https://api-beta.imagen-ai.com/v1/profiles/’ \

--header ‘x-api-key: ’ \

--header ‘Content-Type: application/json’ 

Formatos de archivo compatibles para editar fotos

La API de Imagen admite estos formatos de archivo para editar fotos:

  • RAW: NEF, CR2, CR3, ARW, NRW, CRW, SRF, SR2, ORF, RW2, RAF, PTX, PEF, RWL, SRW, 3FR y FFF
  • DNG
  • JPEG 

2. Elige un perfil de IA

Los perfiles de IA predicen el estilo de edición de los fotógrafos y editan las fotos de manera acorde. Imagen ofrece muchos perfiles de IA de forma gratuita, pero también puedes crear uno basándote en tus fotos. 

Elige un perfil de IA compatible con las fotos que quieras editar. Asegúrate de que coincida con el formato de archivo y el estilo de edición de tus fotos. A continuación, llama al punto final /profiles/ para ver una lista de todos los perfiles disponibles. En la respuesta, verás la profile_key del que quieras usar.

  1. Edita tus fotos en línea para elegir un perfil de IA que te guste. Puedes subir hasta 10 fotos RAW y obtener resultados rápidamente.  Si no encuentras uno que te guste, utiliza la aplicación Imagen para crear un perfil personal de IA.
  2. Consulta una lista de los perfiles de IA y de sus claves. Llama a GET https://api-beta.imagen-ai.com/v1/profiles/ para obtener una lista de los perfiles de IA disponibles para editar tus fotos. 

La respuesta incluirá los perfiles personales de IA que hayas creado en la aplicación Imagen y todos los perfiles de IA de Talent y de Imagen disponibles. Cada perfil de IA tiene una profile_key para identificarlo. Necesitarás esta profile_key al editar las fotos de tu proyecto.

Ejemplo de respuesta con algunos de los perfiles de IA disponibles

{

    "data": {

        "profiles": [

            {

                "profile_key": ,

                "profile_name": "boda",

                "profile_type": "Personal",

                "image_type": "RAW"

            },

            {

                "profile_key": 14715,

                "profile_name": "AMOR Y LUZ",

                "profile_type": "Talent",

                "image_type": "RAW"

            },

            {

                "profile_key": 163322,

                "profile_name": "HOGAR ELEGANTE",

                "profile_type": "Talent",

                "image_type": "RAW"

            }

        ]

    }

}



3. Selecciona tus fotos sin la API

Selecciona tus fotos antes de subirlas para editarlas. La selección no forma parte de la API de Imagen.

 

4. Elige herramientas de IA para mejorar la edición

Las herramientas de IA incorporan funciones de procesamiento adicionales que mejoran la edición de las fotos del proyecto. Puedes mezclar y combinar las herramientas de IA en función de tus necesidades. Algunas herramientas de IA son mutuamente excluyentes, por lo que deberás elegir una u otra. Otras están orientadas a un tipo de fotografía concreto, como la inmobiliaria o la deportiva. 

En esta sección, te explicamos cómo elegir las herramientas de IA. Más adelante, añadirás las herramientas de IA a la solicitud de edición.

Herramientas de IA de Imagen

Excepto en el caso de crop_aspect_ratio y sky_replacement_template_id, el valor de las herramientas de IA es booleano, es decir, verdadero o falso.

Parámetro de herramienta de IA Descripción
crop Recorta las imágenes a una relación de aspecto de 2 x 3 para garantizar una composición óptima en muchos tipos de fotografía. No se puede usar con headshot_crop ni con portrait_crop.
crop_aspect_ratio

Cambia la relación de aspecto predeterminada para crop, headshot_crop y portrait_crop.

Ejemplo: "crop_aspect_ratio": "2 x 3"
headshot_crop

Ajusta el tamaño de todos los retratos y los alinea de manera consistente, por lo que es ideal para los anuarios y los retratos profesionales. Centra a la persona y alinea los ojos en la misma línea horizontal en todas las fotos. No se puede usar con crop ni con portrait_crop.

Utiliza crop_aspect_ratio para cambiar la relación de aspecto a 2 x 3 o 5 x 7.
hdr_merge Combina varias fotos con diferentes exposiciones en una sola foto para que la exposición para el exterior y el interior sea la correcta. Se utiliza principalmente para la fotografía inmobiliaria. Consulta Fusión HDR para conocer los requisitos.
perspective_correction Corrige las distorsiones en la fotografía inmobiliaria causadas por lentes gran angular o ángulos de disparo imperfectos, para que las líneas verticales y horizontales queden rectas. No se puede usar junto con straighten (enderezar).
portrait_crop

Centra el sujeto principal de cada foto y luego la recorta con una relación de aspecto de 4 x 5. Mantiene un espaciado óptimo por encima de la cabeza y otros detalles clave. Se recomienda para los retratos y las fotos de estudio, así como para las escuelas y los deportes. No se puede usar con crop ni con headshot_crop.

Utiliza crop_aspect_ratio para cambiar la relación de aspecto a 5 x 7.
straighten Gira cada foto en función de su horizonte. No se puede usar junto con perspective_correction (corrección de la perspectiva).
subject_mask Selecciona el tema principal de la foto de manera similar a Lightroom, aplica una máscara con pinceles y, a continuación, aplica una edición de IA local a esa máscara.
smooth_skin Minimiza las imperfecciones de la piel, como las líneas de expresión y las manchas, para lograr un cutis más uniforme y radiante.
sky_replacement

Elige entre diferentes cielos para tus fotos. Se utiliza con sky_replacement_template_id para elegir el cielo.

Estos cambios en el cielo se guardan en los metadatos XMP. Al revisar las fotos, puedes ajustar el cielo en el software de edición de Adobe. Accede a Descarga y revisa las fotos editadas en el software de Adobe para obtener más información.
sky_replacement_template_id

Identificador para el cielo. Para ver las opciones para cambiar el cielo, abre la aplicación, crea un proyecto y elige la herramienta de IA Sustitución de cielo.

Aquí tienes la leyenda:

1: Azul claro (nubes bajas)

2: Azul luminoso (nubes bajas)

3: Azul claro (nublado)

Ejemplo: "sky_replacement_template_id": "1"
window_pull Optimiza la exposición para equilibrar la iluminación interior y exterior. Funciona con tomas HDR combinadas y fusionadas en posproducción, por lo que te evitarás horas de trabajo manual enmascarando ventanas. Se recomienda para la fotografía inmobiliaria.

 

Herramientas de IA mutuamente excluyentes

Algunas herramientas de IA similares son excluyentes entre sí. Puedes seleccionar una de estas opciones:

  • crop, headshot_crop o portrait_crop;
  • perspective_correction o straighten.

Herramientas de IA para diferentes tipos de fotografía

Inmobiliaria

Para la fotografía inmobiliaria, usa hdr_merge, perspective_correction, sky_replacement y window_pull. Asegúrate de no utilizar la herramienta de IA Enderezar.

Escolar y deportiva

Para la fotografía escolar y deportiva, usa portrait_crop o headshot_crop.

En general para todos los tipos

Estas herramientas de IA son recomendables para la mayoría de los tipos de fotografía.

  • crop
  • straighten
  • subject_mask
  • smooth_skin

 

5. Edita las fotos

1. Crea un proyecto

Llama a POST https://api-beta.imagen-ai.com/v1/projects/ para crear un proyecto.

Recomendamos crear un proyecto para cada sesión de fotos. Los proyectos organizarán tus fotos con el perfil de IA que hayas elegido para editarlas. La respuesta es el project_uuid utilizado para identificar el proyecto. Usa este project_uuid hasta que exportes tus fotos a JPEG.

Ejemplo de respuesta

{

    "data": {

        "project_uuid": ""

    }

}

 

2. Obtén enlaces de subida temporales para subir fotos

Llama a POST https://api-beta.imagen-ai.com/v1/projects//get_temporary_upload_links.

En la solicitud, en el parámetro files_list, incluye los nombres de los archivos de las fotos que vayas a subir. Usa el formato de lista.

La respuesta incluye un enlace temporal para cada foto al contenedor S3 de Imagen en AWS. Este enlace es la URL prefirmada de AWS.

Ejemplo de solicitud

curl --location ‘https://api.dev.imagen-ai.com/v1/projects//get_temporary_upload_links’ \

--header ‘x-api-key: ’ \

--header ‘Content-Type: application/json’ \

--data ‘{

    “files_list”: [

        {“file_name”: “922A4846.CR2”},

        {“file_name”: “922A4832.CR2”},

        {“file_name”: “922A4818.CR2”},

        {“file_name”: “922A4809.CR2”}

    ]

}’

 

Ejemplo de respuesta

{

    "data": {

        "files_list": [

            {

                "file_name": "922A4846.raw",

                "upload_link": ""

            },

            {

                "file_name": "922A4832.raw",

                "upload_link": ""

            },

            {

                "file_name": "922A4818.raw",

                "upload_link": ""

            },

            {

                "file_name": "922A4809.raw",

                "upload_link": ""

            }

        ]

    }

}



3. Sube cada foto al enlace de subida que le corresponda

Sube las fotos al contenedor S3 de Imagen en AWS con los enlaces de subida temporales de la respuesta del paso anterior. Utiliza únicamente una solicitud PUT.

Para obtener más información sobre cómo subir archivos con una URL prefirmada, consulta esta guía en la documentación de AWS.

Pruebas en Postman

Desactiva Content-Type en los encabezados.

Requisitos del encabezado de la solicitud en el código

  • Si has incluido md5 en el parámetro files_list de la solicitud de los enlaces de subida temporales, asegúrate de incluir «MD5» en el encabezado de la solicitud para subir las fotos. Para ver un ejemplo de código en Python, consulta api_client.py en el proyecto de la API de Imagen en GitHub.

  • Añade Content-Type al encabezado con una cadena vacía ("") como valor.

4. Empieza a editar 

Llama a POST https://api-beta.imagen-ai.com/v1/projects//edit para editar con el perfil de IA que elijas. 

En el cuerpo de la solicitud, incluye lo siguiente:

Ejemplo de cuerpo de solicitud

{

  "profile_key": ,

  "hdr_merge": true,

  "photography_type": "REAL_ESTATE",

  "callback_url": "string",

  "perspective_correction": true,

  "sky_replacement": true,

  "sky_replacement_template_id": "2"

}

La respuesta es un mensaje que indica que el proyecto se ha editado correctamente. Si hay un error, envía un correo electrónico a nuestro equipo de Éxito del Cliente.

Clave de perfil

El profile_key es un identificador del perfil de IA que utilizas para editar tu proyecto. Usa el formato entero. Consulta la respuesta en Elegir un perfil de IA para obtener tu profile_key.

Herramientas de IA

Una herramienta de IA es una herramienta adicional de procesamiento fotográfico con IA que puedes añadir al editar las fotos del proyecto. 

Tipo de fotografía

El photography_type indica el tipo de sesión fotográfica del proyecto. Este parámetro es opcional. 

Estos son los valores photography_type :

  • WEDDING
  • REAL_ESTATE
  • SCHOOL
  • SPORTS
  • EVENTS
  • PORTRAITS
  • NO_TYPE
  • OTHER
  • LANDSCAPE_NATURE
  • FAMILY_NEWBORN
  • BOUDOIR

URL de devolución de llamada

El parámetro callback_url es un punto final POST que Imagen puede usar para enviar mensajes de estado a tu API. Es opcional. Si lo usas, no es necesario que compruebes el estado de la edición. Este punto final debe estar abierto para Imagen. 

Los posibles estados enviados en la solicitud son:

Ejemplo de respuesta

{“project_uuid”: “”, “status”: “Failed/Completed”, “action”: “edit/export”“}



5. Comprueba el estado de la edición

Llama a GET https://api-beta.imagen-ai.com/v1/projects//edit/status para obtener el estado actual del proceso de edición. Sigue llamando a este punto final con sondeo largo hasta que el estado sea Completado.

Si quieres omitir esta comprobación de estado, incluye la solicitud callback_url in the /projects//edit/. Consulta URL de devolución de llamada para obtener más información.

Estos son los estados de la respuesta:

 

6. Obtén enlaces de descarga temporales para conseguir las fotos editadas

Después de recibir un estado COMPLETADO, llama a GET https://api-beta.imagen-ai.com/v1/projects//edit/get_temporary_download_link. 

En la solicitud, incluye las fotos que vayas a descargar en el parámetro files_list. Usa el formato de lista.

La respuesta incluye un enlace temporal para cada foto al contenedor S3 de Imagen en AWS. Este enlace es la URL prefirmada de AWS.

Ejemplo de respuesta

{

    "data": {

        "files_list": [

            {

                "file_name": "922A4846.DNG",

                "upload_link": ""

            },

            {

                "file_name": "922A4832.DNG",

                "upload_link": ""

            },

            {

                "file_name": "922A4818.DNG",

                "upload_link": ""

            },

            {

                "file_name": "922A4809.DNG",

                "upload_link": ""

            }

        ]

    }

}

 

7. Descarga las fotos localmente

Cuando Imagen devuelva los archivos editados, tendrán estos formatos: 

Formato de archivo antes de editarlo Formato de archivo devuelto después de editarlo
RAW XMP
Nota: Al editar fotos con «Fusión HDR», el formato devuelto siempre será DNG, aunque el formato de archivo antes de la edición fuese RAW.
DNG DNG con XMP integrado
JPEG JPEG con XMP integrado


Descarga las fotos del contenedor S3 de Imagen en AWS con los enlaces de descarga temporales de la respuesta del paso anterior. Utiliza el método que prefieras. Para ver un código de muestra en Python, consulta api_client.py en el proyecto de la API de Imagen en GitHub.

Para obtener más información sobre cómo descargar archivos de AWS, consulta esta guía en la documentación de AWS.

Revisa las ediciones en el software de edición de Adobe. Si abres las fotos con el visor de fotos predeterminado de tu ordenador, no verás las ediciones. Para obtener ayuda, consulta:

6. Exporta las fotos para entregarlas

La API de imagen exporta todas las fotos de un proyecto al formato JPEG. Este paso es opcional. Algunos fotógrafos modifican las ediciones y las exportan con su software de edición. Después de exportar las fotos, las entregas o las subes a una galería.

1. Exporta las fotos del proyecto

Llama a POST https://api-beta.imagen-ai.com/v1/projects//export. La respuesta incluye el project_uuid y un mensaje que indica que la exportación se ha realizado correctamente. Si hay un error, envía un correo electrónico a nuestro equipo de Éxito del Cliente.

2. Comprueba el estado de la exportación

Llama a GET https://api-beta.imagen-ai.com/v1/projects//export/status. La respuesta incluirá el estado de la exportación. Los estados que pueden darse son:

  • EN CURSO: la API de Imagen está editando las fotos.
  • ERROR: envía un correo electrónico al equipo de Éxito del Cliente.
  • COMPLETADO: la API de Imagen ha terminado de exportar las fotos a JPEG. 

3. Descarga las fotos JPEG exportadas

Obtén enlaces de descarga temporales para descargar las fotos JPEG exportadas

Cuando el estado de la exportación sea COMPLETADO, llama a GET https://api-beta.imagen-ai.com/v1/projects//export/get_temporary_download_links. 

En la solicitud, incluye las fotos exportadas que vayas a descargar en el parámetro files_list. Usa el formato de lista.

La respuesta incluye un enlace temporal para cada foto al contenedor S3 de Imagen en AWS. Este enlace es la URL prefirmada de AWS.

Ejemplo de respuesta

{

    "data": {

        "files_list": [

            {

                "file_name": "922A4846.JPG",

                "upload_link": ""

            },

            {

                "file_name": "922A4832.JPG",

                "upload_link": ""

            },

            {

                "file_name": "922A4818.JPG",

                "upload_link": ""

            },

            {

                "file_name": "922A4809.JPG",

                "upload_link": ""

            }

        ]

    }

}

 

Descargar las fotos JPEG exportadas localmente

Descarga las fotos del contenedor S3 de Imagen en AWS con los enlaces de descarga temporales de la respuesta del paso anterior. Utiliza el método que prefieras. Para ver un código de muestra en Python, consulta api_client.py en el proyecto de la API de Imagen en GitHub.

Para obtener más información sobre cómo descargar archivos de AWS, consulta esta guía en la documentación de AWS.

¿Fue útil este artículo?

¿Tiene más preguntas? Enviar una solicitud