> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Integração e Uso da API Face Swap > Face Transformation 集成指南 - XHuoAPI A principal função da API Face Swap é trocar o rosto da imagem alvo pelo rosto da imagem fonte, através da entrada de uma imagem fonte e uma imagem alvo. Este documento irá detalhar as instruções de integração da API Face Swap, ajudando você a integrar facilmente e aproveitar ao máximo as poderosas funcionalidades dessa API. Com a API Face Swap, você pode facilmente realizar a troca do rosto da imagem alvo pelo rosto da imagem fonte. ## Processo de Solicitação Para usar a API Face Swap, você precisa primeiro ir à página de solicitação [Face Swap API](https://api.xhuoapi.ai/documents/d10df07a-66a6-4c37-b114-3a003fc9bd55) para solicitar o serviço correspondente. Após entrar na página, clique no botão "Acquire", conforme mostrado na imagem: ![Página de Solicitação](https://cdn.xhuoapi.ai/rci31i.png) Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a [página de login](https://api.xhuoapi.ai), convidando você a se registrar e fazer login. 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 que você use a API sem custo. ## Exemplo de Solicitação Usaremos duas imagens como exemplo para demonstrar como usar a API. Suponha que a imagem fonte seja a mostrada abaixo:

A imagem alvo é:

A seguir, demonstraremos como trocar o rosto da imagem alvo pelo rosto da imagem fonte. ### Configurando Cabeçalhos e Corpo da Solicitação **Request Headers** incluem: * `accept`: especifica que a resposta deve ser no formato JSON, preenchido como `application/json`. * `authorization`: a chave para chamar a API, que pode ser selecionada diretamente após a solicitação. **Request Body** inclui: * `source_image_url`: link da imagem fonte carregada. * `target_image_url`: link da imagem alvo carregada. * `timeout`: opcional, tempo limite de processamento (segundos), o que exceder o tempo limite retornará diretamente. 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 ```bash theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/face/swap' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "source_image_url": "https://cdn.xhuoapi.ai/n1lmd8.png", "target_image_url": "https://cdn.xhuoapi.ai/3np95r.png" }' ``` #### Python ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/face/swap" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "source_image_url": "https://cdn.xhuoapi.ai/n1lmd8.png", "target_image_url": "https://cdn.xhuoapi.ai/3np95r.png" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ### Exemplo de Resposta Após uma solicitação bem-sucedida, a API retornará informações sobre a imagem resultante da troca de rostos. Por exemplo: ```json theme={null} { "image_url": "https://platform.cdn.xhuoapi.ai/face/4b13bdeb-1b19-4ea5-bddf-c2da14ba72e3.png", "image_width": 2008, "image_height": 1942, "image_size": 4006213, "task_id": "4b13bdeb-1b19-4ea5-bddf-c2da14ba72e3" } ``` Pode-se observar que o resultado contém um campo `image_url`, que inclui o link da imagem resultante da troca do rosto da imagem alvo pela imagem fonte, e outras informações conforme mostrado na imagem abaixo: * `image_url`, link da imagem gerada. * `image_width`, largura da imagem gerada. * `image_height`, altura da imagem gerada. * `image_size`, tamanho da imagem gerada. * `task_id`, ID da tarefa de geração. O resultado da imagem gerada é:

É claramente visível que a imagem já trocou com sucesso o rosto da imagem alvo pelo rosto da imagem fonte. ## Callback Assíncrono Devido ao tempo relativamente longo para gerar a troca de rostos, que leva cerca de 1-2 minutos, se a API não responder por um longo período, a solicitaçã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 `callback_url` adicional. Após a solicitação da API, a API retornará imediatamente um resultado, contendo um campo `task_id`, representando o ID da tarefa atual. Quando a tarefa for concluída, o resultado da geração da troca de rostos será enviado para o `callback_url` especificado pelo cliente, também incluindo o campo `task_id`, permitindo que o resultado da tarefa seja associado pelo ID. A seguir, vamos entender como operar isso através de um exemplo. Primeiro, o callback Webhook é um serviço que pode receber solicitações HTTP, e o desenvolvedor deve substituí-lo pela URL do servidor HTTP que ele configurou. Para facilitar a demonstração, usaremos um site de exemplo de Webhook público [https://webhook.site/](https://webhook.site/), onde ao abrir o site você obterá uma URL de Webhook, conforme mostrado na imagem: ![](https://cdn.xhuoapi.ai/r8wyb7.png) Copie esta URL para usá-la como Webhook; o exemplo aqui é [https://webhook.site/3b76eba5-4573-432a-b607-3000b87afc06](https://webhook.site/3b76eba5-4573-432a-b607-3000b87afc06). Em seguida, podemos configurar o campo `callback_url` para a URL do Webhook acima, ao mesmo tempo preenchendo os parâmetros correspondentes, conforme mostrado na imagem:

Ao clicar em executar, você pode notar que receberá imediatamente um resultado, como abaixo: ```json theme={null} { "task_id": "9cba9d36-3b14-43c9-85b6-86f6dfc3b096" } ``` Após alguns instantes, podemos observar o resultado da geração da troca de rostos em [https://webhook.site/3b76eba5-4573-432a-b607-3000b87afc06](https://webhook.site/3b76eba5-4573-432a-b607-3000b87afc06), conforme mostrado na imagem: ![](https://cdn.xhuoapi.ai/col42s.png) O conteúdo é o seguinte: ```json theme={null} { "success": true, "task_id": "9cba9d36-3b14-43c9-85b6-86f6dfc3b096", "image_url": "https://platform.cdn.xhuoapi.ai/face/9cba9d36-3b14-43c9-85b6-86f6dfc3b096.png", "image_width": 2008, "image_height": 1942, "image_size": 4006481 } ``` Pode-se ver que o resultado contém um campo `task_id`, e os outros campos são semelhantes aos mencionados anteriormente, permitindo a associação da tarefa através desse campo. ## Tratamento de Erros Ao chamar a API, se ocorrer um erro, a API retornará o código de erro e a mensagem correspondente. 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 Face Swap para trocar o rosto da imagem alvo pelo rosto da imagem fonte. 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.