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. Alguns recursos do aplicativo Imagen ainda não estão na API. Esta documentação aborda os endpoints compatíveis com a API do Imagen.

 

1. Antes de começar

Configure seu ambiente antes de começar. Você precisa se inscrever no Imagen e obter sua chave de API. Incluímos uma coleção Postman e um exemplo de código Python para fornecer exemplos de como usar a nossa API. Revise as informações nesta seção para garantir que seu ambiente esteja pronto e que você entenda os conceitos básicos de como trabalhar com a API.

Inscreva-se

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 usado para se inscrever no Imagen.

URL de 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.

Coleção Postman

Use nossa coleção Postman como ajuda para usar a API Imagen.

  1. Baixe a coleção Postman para o seu computador.
  2. Abra o Postman.
  3. Acesse Arquivo > Importar para abrir a coleção no Postman.

Exemplo de código Python

Nosso exemplo de código Python mostra como chamar os endpoints da API do Imagen para editar fotos. Ele também demonstra o threading, que permite processar vários lotes de fotos ao mesmo tempo, em vez de esperar que cada lote seja concluído.

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: para realizar a mesclagem HDR, as fotos DNG devem conter dados RAW. Fotos DNG com dados JPEG não são compatíveis.
  • JPEG 

2. 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 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 goste, use o aplicativo Imagen para criar um Perfil de IA Pessoal.
  2. Obtenha uma lista de Perfis de IA e suas chaves. Chame 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"

            }

        ]

    }

}



3. Selecione suas fotos sem a API

Selecione suas fotos antes de enviá-las para edição. A API do Imagen não inclui a seleção.

 

4. 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

Exceto para crop_aspect_ratio e sky_replacement_template_id, o valor das ferramentas de IA é booleano, ou seja, verdadeiro ou falso.

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.
crop_aspect_ratio

Altera a proporção da proporção padrão para crop, headshot_crop e portrait_crop.

Exemplo: "crop_aspect_ratio": "2X3"
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.

Use crop_aspect_ratio para alterar a proporção para 1x1, 2x3 ou 5x7.
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.

Para realizar a mesclagem HDR, as fotos DNG devem conter dados RAW. Fotos DNG com dados JPEG não são compatíveis.
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 4 x 5. 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.

Use crop_aspect_ratio para alterar a proporção para 2x3 ou 5x7.
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 de expressão e manchas, resultando em uma pele mais lisa e visualmente atraente.
sky_replacement

Escolha entre diferentes céus para suas fotos. Usado com sky_replacement_template_id para escolher o céu.

Essas alterações no céu são salvas nos metadados XMP. Ao revisar as fotos, você pode ajustar o céu no software de edição da Adobe. Consulte Baixar e revisar fotos editadas no software Adobe para obter mais informações.
sky_replacement_template_id

Identificador para o céu. Para ver as opções de um novo céu, você precisa abrir o app, criar um projeto e escolher a ferramenta de IA de substituição de céu.

Aqui está a chave:

1: Azul claro — Nuvens baixas

2: Azul brilhante — Nuvens baixas

3: Azul claro — Nublado

Exemplo: "sky_replacement_template_id": "1"
window_pull Otimiza a exposição para equilibrar a iluminação interna e externa. Funciona com fotos entre colchetes HDR e fotos mescladas pós-HDR, eliminando horas de aplicação manual de máscaras em janelas. Recomendado para fotografia imobiliária.

 

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

Imobiliária

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

Escolar e esportiva

Para fotografia escolar e esportiva, use portrait_crop ou headshot_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

 

5. 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. Esse 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 apenas uma solicitação PUT.

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

Desative o Content-Type nos cabeçalhos.

Requisitos para o cabeçalho da solicitação no código

  • 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.

  • Adicione Content-Type ao cabeçalho usando uma string vazia ("") como 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 de corpo da solicitação

{

  "profile_key": ,

  "hdr_merge": true,

  "photography_type": "REAL_ESTATE",

  "callback_url": "string",

  "perspective_correction": true,

  "sky_replacement": true,

  "sky_replacement_template_id": “2”

}

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 de 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.

Revise as edições no software de edição da Adobe. Se você abrir as fotos com o visualizador de fotos padrão no seu computador, as edições não serão exibidas. Para obter ajuda, consulte:

6. 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 um e-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 de 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