Saltar para o conteúdo principal
A principal função da API de Tarefas de Foto de Identidade AI é consultar o status de execução de uma tarefa gerada pela API de criação de fotos de identidade AI, através da entrada do ID da tarefa. Este documento irá detalhar as instruções de integração da API de Tarefas de Foto de Identidade AI, ajudando você a integrar facilmente e aproveitar ao máximo as poderosas funcionalidades dessa API. Com a API de Tarefas de Foto de Identidade AI, você pode consultar facilmente o status de execução das tarefas da API de criação de fotos de identidade AI.

​
Processo de Solicitação

Para usar a API de Tarefas de Foto de Identidade AI, você precisa primeiro ir à página de solicitação API de Criação de Fotos de Identidade AI para solicitar o serviço correspondente, e então copiar o ID da tarefa da API de criação de fotos de identidade AI, conforme mostrado na imagem:

Por fim, acesse a página da API de Tarefas API de Tarefas de Foto de Identidade AI para solicitar o serviço correspondente. Após acessar a página, clique no botão “Adquirir”, conforme mostrado na imagem: Página de Solicitação Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login que o convida a se registrar e fazer login. Após o registro e login, você será redirecionado automaticamente de volta para a página atual. Na primeira solicitação, haverá um crédito gratuito disponível, permitindo que você use a API gratuitamente.

​
Exemplo de Solicitação

A API de Tarefas de Foto de Identidade AI pode ser usada para consultar os resultados da API de criação de fotos de identidade AI. Para saber como usar a API de criação de fotos de identidade AI, consulte o documento API de Criação de Fotos de Identidade AI. Usaremos um exemplo de ID de tarefa retornado pelo serviço da API de criação de fotos de identidade AI para demonstrar como usar essa API. Suponha que temos um ID de tarefa: 16f96e95-d95c-46ef-b183-139b9bd1aebd, a seguir, demonstraremos como passar um ID de tarefa.

​
Exemplo de Tarefa

​
Configurando Cabeçalhos e Corpo da Solicitação

Cabeçalhos da Solicitação incluem:
  • accept: especifica que a resposta deve ser no formato JSON, preenchido como application/json.
  • authorization: chave para chamar a API, que pode ser selecionada diretamente após a solicitação.
Corpo da Solicitação inclui:
  • id: ID da tarefa enviada.
  • action: modo de operação da tarefa.
Configuração conforme mostrado na imagem abaixo:

​
Exemplo de Código

Pode-se notar que, no lado direito da página, já foram gerados automaticamente códigos em várias linguagens, conforme mostrado na imagem:

Alguns exemplos de código são os seguintes:

​
CURL

curl -X POST 'https://api.xhuoapi.ai/v1/headshots/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
  "action": "retrieve"
}'

​
Python

import requests

url = "https://api.xhuoapi.ai/v1/headshots/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
    "action": "retrieve"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

​
Exemplo de Resposta

Após uma solicitação bem-sucedida, a API retornará as informações detalhadas da tarefa de foto de identidade. Por exemplo: 
{
  "_id": "67276ab6550a4144a53b6036",
  "id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
  "api_id": "53bcc3f7-12ec-4f04-8ca4-20f150dcde2a",
  "application_id": "1af53f80-c166-4f54-a8ea-0ffc24d8e2cd",
  "created_at": 1730636470.402,
  "credential_id": "3c253880-21ef-478a-9389-c09fa837ac7c",
  "request": {
    "mode": "relax",
    "template": "male_portrait",
    "image_urls": [
      "https://cdn.zhishuyun.com/2024-11-03-d23744954ca4819503469f04f2268aa0.jpg"
    ],
    "callback_url": "https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a"
  },
  "trace_id": "6eded0e2-274d-4cde-a567-d6b0decb9a97",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "success": true,
    "task_id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
    "data": [
      {
        "id": "202411032022077381",
        "image_url": "https://platform.cdn.xhuoapi.ai/headshots/16f96e95-d95c-46ef-b183-139b9bd1aebd.png",
        "template": "男形象照"
      },
      {
        "id": "202411032022079194",
        "image_url": "https://platform.cdn.xhuoapi.ai/headshots/16f96e95-d95c-46ef-b183-139b9bd1aebd.png",
        "template": "男形象照"
      }
    ]
  }
}
O resultado retornado contém vários campos, o campo request é o corpo da solicitação enviado ao iniciar a tarefa, enquanto o campo response é o corpo da resposta retornada após a conclusão da tarefa. A descrição dos campos é a seguinte.
  • id, ID da tarefa de foto de identidade gerada, usado para identificar exclusivamente esta tarefa de geração de foto de identidade.
  • request, informações da solicitação na tarefa de foto de identidade.
  • response, informações da resposta na tarefa de foto de identidade.

​
Operação de Consulta em Lote

Esta operação é para consultar os detalhes da tarefa de foto de identidade para vários IDs de tarefa, diferindo do anterior, onde a ação deve ser selecionada como retrieve_batch. Corpo da Solicitação inclui:
  • ids: array de IDs de tarefa enviados.
  • action: modo de operação da tarefa.
Configuração conforme mostrado na imagem abaixo:

​
Exemplo de Código

Pode-se notar que, no lado direito da página, já foram gerados automaticamente códigos em várias linguagens, conforme mostrado na imagem:

Alguns exemplos de código são os seguintes:

​
Exemplo de Resposta

Após uma solicitação bem-sucedida, a API retornará as informações detalhadas de todas as tarefas de foto de identidade em lote. Por exemplo: 
{
  "items": [
    {
      "_id": "67276ab6550a4144a53b6036",
      "id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
      "api_id": "53bcc3f7-12ec-4f04-8ca4-20f150dcde2a",
      "application_id": "1af53f80-c166-4f54-a8ea-0ffc24d8e2cd",
      "created_at": 1730636470.402,
      "credential_id": "3c253880-21ef-478a-9389-c09fa837ac7c",
      "request": {
        "mode": "relaxar",
        "template": "retrato_masculino",
        "image_urls": [
          "https://cdn.zhishuyun.com/2024-11-03-d23744954ca4819503469f04f2268aa0.jpg"
        ],
        "callback_url": "https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a"
      },
      "trace_id": "6eded0e2-274d-4cde-a567-d6b0decb9a97",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
        "data": [
          {
            "id": "202411032022077381",
            "image_url": "https://platform.cdn.xhuoapi.ai/headshots/16f96e95-d95c-46ef-b183-139b9bd1aebd.png",
            "template": "男形象照"
          },
          {
            "id": "202411032022079194",
            "image_url": "https://platform.cdn.xhuoapi.ai/headshots/16f96e95-d95c-46ef-b183-139b9bd1aebd.png",
            "template": "男形象照"
          }
        ]
      }
    },
    {
      "_id": "67276c52550a4144a53b995b",
      "id": "5213468b-6b96-4ad4-9c6a-657bd438d299",
      "api_id": "53bcc3f7-12ec-4f04-8ca4-20f150dcde2a",
      "application_id": "1af53f80-c166-4f54-a8ea-0ffc24d8e2cd",
      "created_at": 1730636882.359,
      "credential_id": "3c253880-21ef-478a-9389-c09fa837ac7c",
      "request": {
        "mode": "relaxar",
        "template": "retrato_masculino",
        "image_urls": [
          "https://cdn.zhishuyun.com/2024-11-03-d23744954ca4819503469f04f2268aa0.jpg"
        ],
        "callback_url": "https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a"
      },
      "trace_id": "50b2b4a8-6c1c-4b95-ac0b-46e5b97c7b18",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "task_id": "5213468b-6b96-4ad4-9c6a-657bd438d299",
        "status": "desconhecido",
        "data": []
      }
    }
  ],
  "count": 2
}

​
CURL

curl -X POST 'https://api.xhuoapi.ai/v1/headshots/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["16f96e95-d95c-46ef-b183-139b9bd1aebd","5213468b-6b96-4ad4-9c6a-657bd438d299"],
  "action": "recuperar_lote"
}'

​
Python

import requests

url = "https://api.xhuoapi.ai/v1/headshots/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "ids": ["16f96e95-d95c-46ef-b183-139b9bd1aebd","5213468b-6b96-4ad4-9c6a-657bd438d299"],
    "action": "recuperar_lote"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

​
Erro de tratamento

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 ao buscar"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Conclusão

Através deste documento, você já entendeu como usar a API de Task de fotos de identificação AI para consultar detalhes de tarefas de fotos de identificação individuais ou em lote. 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.