Automatize seu fluxo de trabalho de pós-produção com a API do Imagen

  • Atualizado

Visão geral do Imagen

Imagen é uma solução com tecnologia de IA que reduz horas de trabalho intenso de pós-produção para fotógrafos profissionais. 

Como ele funciona? 

Fotógrafos criam um Perfil de IA ou escolhem um Talento ou Perfil de IA do Imagen. Em seguida, fazem upload das fotos no Imagen. O Imagen edita as fotos com seu Perfil de IA em uma fração do tempo que seria necessário para realizar esse processo manualmente. Por fim, eles exportam as fotos e as entregam aos clientes.

A API do Imagen otimiza e automatiza o fluxo de trabalho de edição na pós-produção do fotógrafo, assim como o aplicativo Imagen. Este documento apresenta mais detalhes sobre o fluxo e os endpoints que você precisa chamar.

Confira as principais etapas ao usar a API do Imagen: 

  1. Escolha um perfil de IA: experimente os Perfis de IA e encontre um para usar na edição com a API do Imagen.
  2. Selecione suas fotos antes de enviá-las para edição. A API do Imagen não inclui a seleção.
  3. Editar fotos: envie as fotos para o bucket S3 do Imagen na AWS para editá-las com um Perfil de IA e ferramentas de IA.
  4. Exportar fotos para entrega: exporte as fotos editadas em um projeto para o formato JPEG. Esta etapa não é obrigatória. Algumas empresas preferem ajustar as edições e exportar fotos com seu software de edição.

Antes de começar

Pré-requisitos

Você precisa se inscrever no Imagen antes de poder usar a API do Imagen.  Em seguida, envie um e-mail para a equipe de sucesso do cliente do Imagen para solicitar uma chave de API. No seu e-mail, inclua o endereço de e-mail que você usou para se inscrever no Imagen.

URL base do Imagem

O URL base para a API do Imagen é https://api-beta.imagen-ai.com/v1/.

Documentação de referência da API

Confira a documentação de referência da API para a API do Imagen.

Autenticação

A API do Imagen usa uma chave de API para realizar a autenticação. Adicione a chave como um cabeçalho nas suas solicitações em formato de texto. O nome do cabeçalho é x-api-key. 

Veja este exemplo:

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

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

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

Formatos de arquivo compatíveis para edição de fotos

A API do Imagen oferece suporte para os seguintes formatos de arquivo para edição de fotos:

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

Escolha um perfil de IA

Os perfis de IA aprendem com o estilo de edição de um fotógrafo e editam as fotos conforme esse estilo. O Imagen oferece muitos Perfis de IA gratuitamente ou você pode criar um perfil a partir das suas fotos. 

Você escolhe um Perfil de IA que será compatível com as fotos que você deseja editar. Certifique-se de que o formato do arquivo corresponde ao estilo de edição das suas fotos. Em seguida, chame o endpoint /perfis/ para obter uma lista de todos os perfis disponíveis. Na resposta, você encontrará o profile_key do perfil que você deseja usar.

  1. Edite suas fotos online para escolher um Perfil de IA que você goste. Você pode fazer upload de até 10 fotos no formato RAW e receber os resultados rapidamente.  Se você não encontrar um que você goste, use o aplicativo Imagen para crie um Perfil de IA Pessoal.
  2. Obtenha uma lista de Perfis de IA e suas chaves.

Faça a chamada GET https://api-beta.imagen-ai.com/v1/profiles/ para obter uma lista com os Perfis de IA disponíveis para editar suas fotos. 

A resposta inclui os Perfis de IA Pessoais que você criou no aplicativo Imagen e todos os Perfis de Talentos e da Imagen IA disponíveis. Cada perfil de IA é identificado por um profile_key. Você vai precisar deste profile_key quando for editar as fotos no seu projeto.

Exemplo de resposta com uma amostra dos Perfis de IA disponíveis

{

    "data": {

        "profiles": [

            {

                "profile_key": ,

                "profile_name": "casamento",

                "profile_type": "Pessoal",

                "image_type": "RAW"

            },

            {

                "profile_key": 14715,

                "profile_name": "AMOR E LUZ",

                "profile_type": "Talento",

                "image_type": "RAW"

            },

            {

                "profile_key": 163322,

                "profile_name": "CASA ELEGANTE",

                "profile_type": "Talento",

                "image_type": "RAW"

            }

        ]

    }

}



Escolha ferramentas de IA para melhorar a edição

As ferramentas de IA oferecem processamento de fotos adicional com IA que melhora a edição das fotos no projeto. Você pode combinar as ferramentas de IA de diferentes formas, conforme as suas necessidades. Algumas ferramentas de IA são mutuamente exclusivas. Por isso, você terá que escolher uma ou outra. Outras são voltadas para tipos de fotografia específicos, como imóveis ou esportes. 

Nesta seção, abordaremos como escolher ferramentas de IA. Posteriormente durante o processo, você adicionará as ferramentas de IA à solicitação de edição.

Ferramentas de IA do Imagen

Parâmetro da ferramenta de IA Descrição
crop Realiza o corte com uma proporção de 2x3 para atingir uma composição adequada em diferentes tipos de fotografia. Não pode ser usado junto com headshot_crop ou portrait_crop.
headshot_crop Alinha e dimensiona todas as suas fotos de rosto de modo consistente, sendo uma opção ideal para anuários e fotos de rosto profissionais. Centraliza o assunto e alinha os olhos na mesma linha horizontal, em todas as fotos. Não pode ser usado junto com crop ou portrait_crop.
hdr_merge Combina várias fotos com exposições diferentes em uma única foto para que a exposição do ambiente externo e do ambiente interno estejam corretas. É usado principalmente para fotografia imobiliária. Confira Mesclagem HDR para saber os requisitos.
perspective_correction Corrige distorções em fotografias imobiliárias causadas por lentes grande-angulares ou ângulos de captura incorretos para que as linhas verticais e horizontais fiquem retas. Não pode ser usado junto com endireitar.
portrait_crop Centraliza o objeto principal de cada foto e corta com uma proporção de 4x5. Mantém o espaçamento ideal acima da cabeça, além de outros detalhes importantes. Recomendado para retratos e sessões em estúdio, assim como para escolas e esportes. Não pode ser usado junto com crop ou headshot_crop.
straighten Gira cada foto de acordo com seu horizonte. Não pode ser usado junto com perspective_correction.
subject_mask Seleciona o objeto principal da foto de forma semelhante ao Lightroom, aplica uma máscara usando pincéis e, em seguida, aplica uma edição de IA local a essa máscara.
smooth_skin Torna imperfeições na pele menos evidentes, como linhas finas e manchas, resultando em uma pele mais lisa e visualmente atraente.

 

Ferramentas de IA mutuamente exclusivas

Algumas ferramentas de IA semelhantes se excluem mutuamente. Escolha entre:

  • crop, headshot_crop ou portrait_crop
  • perspective_correction ou straighten.

Ferramentas de IA para diferentes tipos de fotografia

Imóveis

Para fotografia imobiliária, use hdr_merge e perspective_correction. Lembre-se de não usar a ferramenta de IA straighten.

Escola e esportes

Para fotografia escolar e esportiva, use portrait_crop.

Geral para todos os tipos

Estas ferramentas de IA são boas para a maioria dos tipos de fotografia.

  • crop
  • straighten
  • subject_mask
  • smooth_skin

 

Editar fotos

1. Criar um projeto

Faça a chamada POST https://api-beta.imagen-ai.com/v1/projects/ para criar um projeto.

Recomendamos que você crie um projeto para cada sessão de fotos. O projeto organiza suas fotos com o Perfil de IA que você escolheu para editá-las. A resposta é o project_uuid usado para identificar este projeto. Use este project_uuid até você exportar suas fotos como JPEG.

Exemplo de resposta

{

    "data": {

        "project_uuid": ""

    }

}

 

2. Tenha acesso a links de upload temporários para enviar fotos

Faça a chamada POST https://api-beta.imagen-ai.com/v1/projects//get_temporary_upload_links.

Na solicitação, no parâmetro files_list, inclua os nomes dos arquivos das fotos que serão enviadas. Use o formato de lista.

A resposta inclui um link temporário para cada foto no bucket S3 do Imagen na AWS. Este link é o URL pré-assinado da AWS.

Exemplo de solicitação

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”}

    ]

}’

 

Exemplo de resposta

{

    "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. Envie cada foto no seu link de upload temporário

Envie fotos ao bucket S3 do Imagen na AWS com os links de upload temporários da resposta da etapa anterior. Use o método da sua preferência.

Para obter mais informações sobre como enviar arquivos com um URL pré-assinado, consulte este guia na documentação da AWS.

Como realizar testes no Postman

  • Exclua o Content-Type do cabeçalho.
  • Na guia Parâmetros, adicione um novo parâmetro chamado Content-Type usando uma string vazia ("") como valor.

Requisitos para o cabeçalho da solicitação

Se você incluiu md5 no parâmetro files_list na solicitação de links de upload temporários, certifique-se de incluir MD5 no cabeçalho da solicitação para enviar as fotos. Para obter um código de exemplo em Python, consulte api_client.py no projeto da API do Imagen no Github.

Requisitos para o corpo da solicitação

No corpo da solicitação, adicione Content-Type como um parâmetro de consulta usando uma string vazia ("") como o valor.

4. Inicie a edição 

Faça a chamada POST https://api-beta.imagen-ai.com/v1/projects//edit para dar início à edição com o Perfil de IA que você escolheu. 

No corpo da solicitação, inclua:

Exemplo do corpo da solicitação

{

  "profile_key": ,

  "hdr_merge": true,

  "photography_type": "NO_TYPE",

  "callback_url": "string",

  "perspective_correction": true

}

A resposta é uma mensagem de que o projeto foi editado com sucesso. Se houver um erro, envie um e-mail para nossa equipe de sucesso do cliente.

Chave de perfil

O profile_key é um identificador para o Perfil de IA que você usará para editar seu projeto. Use números inteiros. Confira a resposta em Escolha um perfil de IA para obter o seu profile_key.

Ferramentas de IA

Uma ferramenta de IA é uma ferramenta adicional para o processamento de fotos com IA que você pode incluir ao editar as fotos no projeto. 

Tipo de fotografia

O photography_type indica o tipo de sessão fotográfica no projeto. Este parâmetro é opcional. 

Confira os valores de photography_type:

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

URL de retorno

O callback_url é um endpoint POST que o Imagen pode usar para enviar mensagens de status para sua API. Este parâmetro é opcional. Se você usá-lo, não será necessário verificar o status da edição. Este endpoint deve estar aberto para o Imagen. 

Os status que podem ser enviados na solicitação são:

Exemplo de resposta

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



5. Verifique o status da edição

Faça a chamada GET https://api-beta.imagen-ai.com/v1/projects//edit/status para obter o status atual do processo de edição. Continue chamando este endpoint com uma consulta longa até que o status seja Concluído.

Se você quiser ignorar essa verificação de status, inclua o callback_url na solicitação de /projects//edit/. Consulte URL de retorno de chamada para mais informações.

Confira os status na resposta:

 

6. Obtenha links de download temporários para baixar fotos editadas

Depois que o status passar para CONCLUÍDO, faça a chamada GET https://api-beta.imagen-ai.com/v1/projects//edit/get_temporary_download_link. 

Na solicitação, inclua no parâmetro files_list as fotos que você fará download. Use o formato de lista.

A resposta inclui um link temporário para cada foto no bucket S3 do Imagen na AWS. Esse link é o URL pré-assinado da AWS.

Exemplo de resposta

{

    "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. Baixe as fotos localmente

Estes são os respectivos formatos quando o Imagen retorna os arquivos editados: 

Formato do arquivo antes da edição Formato do arquivo que retornou após a edição
RAW XMP
Observação: ao editar fotos usando Mesclagem HDR, o formato no retorno será sempre DNG, mesmo que o formato do arquivo antes da edição fosse RAW.
DNG DNG com XMP incorporado
JPEG JPEG com XMP incorporado


Baixe fotos do bucket S3 do Imagen na AWS com os links de download temporários da resposta da etapa anterior. Use qualquer método da sua preferência. Para obter um código de exemplo em Python, consulte api_client.py no projeto da API do Imagen no Github.

Para obter mais informações sobre como baixar arquivos da AWS, consulte este guia na documentação da AWS.

Exportar fotos para entrega

A API do Imagen exporta todas as fotos de um projeto para o formato JPEG. Esta etapa é opcional. Alguns fotógrafos ajustam as edições e as exportam com seus softwares de edição. Após exportar as fotos, você pode fazer a entrega ou enviá-las para uma galeria.

1. Exporte as fotos no projeto

Faça a chamada POST https://api-beta.imagen-ai.com/v1/projects//export. A resposta inclui o project_uuid e uma mensagem de que a exportação foi bem-sucedida. Se houver um erro, envie um e-mail para nossa equipe de sucesso do cliente.

2. Verifique o status da exportação

Faça a chamada GET https://api-beta.imagen-ai.com/v1/projects//export/status. A resposta inclui o status da exportação. Os status possíveis são:

  • EM ANDAMENTO: a API do Imagen está editando as fotos.
  • FALHA: envie ume-mail para a equipe de sucesso do cliente.
  • CONCLUÍDO: a API do Imagen concluiu a exportação das fotos para JPEG. 

3. Baixe as fotos JPEG exportadas

Obtenha links de download temporários para baixar fotos JPEG exportadas

Após o retorno do status de exportação como CONCLUÍDO, faça a chamada GET https://api-beta.imagen-ai.com/v1/projects//export/get_temporary_download_links. 

Na solicitação, inclua no parâmetro files_list as fotos exportadas que você fará download. Use o formato de lista.

A resposta inclui um link temporário para cada foto no bucket S3 do Imagen na AWS. Esse link é o URL pré-assinado da AWS.

Exemplo de resposta

{

    "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": ""

            }

        ]

    }

}

 

Baixe as fotos JPEG exportadas localmente

Baixe fotos do bucket S3 do Imagen na AWS com os links de download temporários da resposta da etapa anterior. Use qualquer método da sua preferência. Para obter um código de exemplo em Python, consulte api_client.py no projeto da API do Imagen no Github.

Para obter mais informações sobre como baixar arquivos da AWS, consulte este guia na documentação da AWS.

Esse artigo foi útil?

Tem mais dúvidas? Envie uma solicitação