API de Integração para Criação de Fotos de Identidade com IA

Este documento apresentará uma API de criação de fotos de identidade com IA, que pode ser utilizada para gerar diversos estilos de fotos de identidade através da URL de uma foto de retrato e de um modelo de sua preferência.

Processo de Solicitação

Para usar a API, você precisa primeiro acessar a página correspondente da API de Criação de Fotos de Identidade com IA e solicitar o serviço desejado. Após acessar a página, clique no botão “Acquire”, conforme mostrado na imagem:

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e logar. Após o registro e login, você será redirecionado de volta para a página atual. Na primeira solicitação, haverá um crédito gratuito disponível, permitindo o uso gratuito da API.

Uso Básico

Primeiro, é importante entender a forma básica de uso, que consiste em inserir a imagem de retrato a ser processada e o modelo de foto de identidade desejado, para obter o resultado processado. É necessário passar um campo image_urls, que é um array de links da imagem de retrato a ser processada, conforme mostrado na imagem:

Em seguida, precisamos inserir o modelo de sua preferência. Este documento fornece oito modelos populares, que podem ser consultados abaixo:

{
   "male_portrait":  "Foto de Retrato Masculino",
   "male_portrait2":  "Foto de Retrato Masculino (Outra Versão)",
   "kindergarten":  "Foto de Entrada na Creche",
   "logo_tshirt": "Foto com Logo da Empresa na Camiseta",
   "wedding":  "Foto de Registro de Casamento",
   "business_photo":  "Foto de Estilo Empresarial",
   "bob_suit": "Foto com Terno Preto e Cabelo Bob",
   "female_portrait":  "Foto de Retrato Feminino"
}

Depois, podemos especificar o parâmetro de velocidade de geração mode, que geralmente é dividido em duas opções: lenta relax e rápida fast, conforme descrito abaixo:

Podemos ver que aqui configuramos os Headers da Requisição, incluindo:

accept: o formato de resposta desejado, que deve ser preenchido como application/json, ou seja, formato JSON.
authorization: a chave de acesso à API, que pode ser selecionada diretamente após a solicitação.

Além disso, configuramos o Corpo da Requisição, que inclui:

mode: o canal para geração da foto de identidade, que pode ser fast (rápido) ou relax (lento). Quando usar relax, é altamente recomendável usar o parâmetro callback_url abaixo.
template: o estilo do modelo da foto de identidade.
image_urls: os links das imagens de retrato a serem enviadas.
callback_url: a URL para onde os resultados devem ser enviados.

Após a seleção, podemos ver que o código correspondente também foi gerado à direita, conforme mostrado na imagem:

Clique no botão “Try” para realizar um teste, como mostrado na imagem acima, e você receberá o seguinte resultado:

{
  "success": true,
  "task_id": "ae1e4948-dba1-4a6f-87af-67961b647428",
  "data": [
    {
      "id": "202411031951124776",
      "image_url": "https://platform.cdn.xhuoapi.ai/headshots/ae1e4948-dba1-4a6f-87af-67961b647428.png",
      "template": "Foto de Retrato Masculino"
    },
    {
      "id": "202411031951128490",
      "image_url": "https://platform.cdn.xhuoapi.ai/headshots/ae1e4948-dba1-4a6f-87af-67961b647428.png",
      "template": "Foto de Retrato Masculino"
    }
  ]
}

O resultado retornado contém vários campos, descritos a seguir:

success: o status da tarefa de geração da foto de identidade.
task_id: o ID da tarefa de geração da foto de identidade.
data: a lista de resultados da tarefa de geração da foto de identidade.
- id: o ID da foto gerada na tarefa de geração da foto de identidade.
- image_url: o link da imagem gerada na tarefa de geração da foto de identidade.
- template: o nome do modelo da foto de identidade gerada na tarefa.

Podemos ver que recebemos informações satisfatórias sobre a foto de identidade com base no modelo e na imagem de retrato. Precisamos apenas acessar o link da imagem no campo data para obter a foto de identidade. Além disso, se você quiser gerar o código de integração correspondente, pode copiá-lo diretamente, como no exemplo do código CURL abaixo:

curl -X POST 'https://api.xhuoapi.ai/v1/headshots/generate' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "mode": "fast",
  "template": "male_portrait",
  "image_urls": ["https://cdn.zhishuyun.com/2024-11-03-d23744954ca4819503469f04f2268aa0.jpg"]
}'

Callback Assíncrono

Como a geração da foto de identidade com IA pode levar um tempo relativamente longo, cerca de 1-2 minutos, se a API não responder por um longo período, a requisição HTTP manterá a conexão, resultando em consumo adicional de recursos do sistema. Portanto, esta API também oferece suporte a callbacks assíncronos. O fluxo geral é: quando o cliente faz a solicitação, deve especificar um campo adicional callback_url. Após a solicitação da API, a API retornará imediatamente um resultado contendo um campo task_id, que representa o ID da tarefa atual. Quando a tarefa for concluída, o resultado da geração da foto de identidade será enviado para o callback_url especificado pelo cliente, em formato JSON POST, incluindo também o campo task_id, permitindo que o resultado da tarefa seja associado pelo ID. Abaixo, vamos entender como operar isso através de um exemplo. Primeiro, o callback Webhook é um serviço que pode receber requisições HTTP, e o desenvolvedor deve substituí-lo pela URL do servidor HTTP que ele configurou. Para facilitar a demonstração, usaremos um site público de exemplo de Webhook, https://webhook.site/, onde você pode abrir o site e obter uma URL de Webhook, conforme mostrado na imagem:

Copie esta URL para usá-la como Webhook. O exemplo aqui é https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a. Em seguida, podemos definir o campo callback_url como a URL do Webhook acima, ao mesmo tempo que inserimos o link da imagem de retrato e o modelo. Este documento recomenda usar o callback assíncrono quando o parâmetro mode estiver definido como relax, conforme mostrado na imagem:

Clique em executar e você verá que receberá imediatamente um resultado, como abaixo:

{
  "task_id": "763b1450-8804-434f-acc7-d713be73a28f"
}

Após alguns instantes, você poderá observar o resultado da geração da foto em https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a, conforme mostrado na imagem:

O conteúdo é o seguinte:

{
    "success": true,
    "task_id": "763b1450-8804-434f-acc7-d713be73a28f",
    "data": [
        {
            "id": "202411032010131366",
            "image_url": "https://platform.cdn.xhuoapi.ai/headshots/763b1450-8804-434f-acc7-d713be73a28f.png",
            "template": "foto de perfil masculino"
        },
        {
            "id": "202411032010132420",
            "image_url": "https://platform.cdn.xhuoapi.ai/headshots/763b1450-8804-434f-acc7-d713be73a28f.png",
            "template": "foto de perfil masculino"
        }
    ]
}

Pode-se ver que o resultado contém um campo task_id, os outros campos são semelhantes ao texto anterior, e através desse campo é possível realizar a associação da tarefa.

Tratamento de Erros

Ao chamar a API, se encontrar um erro, a API retornará o respectivo código de erro e informações. Por exemplo:

400 token_mismatched: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
400 api_not_implemented: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
401 invalid_token: Não autorizado, token de autorização inválido ou ausente.
429 too_many_requests: Muitas solicitações, você excedeu o limite de taxa.
500 api_error: Erro interno do servidor, algo deu errado no servidor.

Exemplo de Resposta de Erro

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "falha na busca"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusão

Através deste documento, você já entendeu como usar a API de criação de fotos de identificação com IA, que pode criar vários estilos de fotos de identificação através da URL da foto de retrato e do template de sua preferência. Esperamos que este documento possa ajudá-lo a integrar e usar melhor essa API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico.

Documentation Index

​Processo de Solicitação

​Uso Básico

​Callback Assíncrono

​Tratamento de Erros

​Exemplo de Resposta de Erro

​Conclusão