Saltar al contenido principal
Este documento presentará una descripción de la integración de la API de creación de fotos de identificación con IA, que permite crear fotos de identificación de varios estilos mediante la entrada de la URL de una foto de retrato y la plantilla que prefieras.

​
Proceso de solicitud

Para utilizar la API, primero debes ir a la página correspondiente de la API de creación de fotos de identificación con IA para solicitar el servicio correspondiente. Una vez en la página, haz clic en el botón “Acquire”, como se muestra en la imagen: Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión para invitarte a registrarte e iniciar sesión. Después de registrarte e iniciar sesión, serás redirigido automáticamente a la página actual. En la primera solicitud, se te otorgará un crédito gratuito, lo que te permitirá utilizar la API de forma gratuita.

​
Uso básico

Primero, debes entender la forma básica de uso, que consiste en ingresar la imagen de retrato que deseas procesar y la plantilla de foto de identificación de IA que prefieras, para obtener el resultado procesado. Primero, necesitas pasar un campo image_urls, que es un array de enlaces a las imágenes de retrato que deseas procesar, como se muestra en la imagen:

Luego, también necesitamos ingresar la plantilla que prefieras. Este documento proporciona ocho plantillas populares, las plantillas específicas se pueden consultar a continuación: 
{
   "male_portrait":  Foto de retrato masculino,
   "male_portrait2":  Foto de retrato masculino (otra versión),
   "kindergarten":  Foto de entrada a la guardería,
   "logo_tshirt": Foto de camiseta con logo de empresa,
   "wedding":  Foto de registro de matrimonio,
   "business_photo":  Foto de estilo empresarial,
   "bob_suit": Foto con traje negro y corte bob,
   "female_portrait":  Foto de retrato femenino
}
Después, también podemos especificar el parámetro de velocidad de generación mode, que generalmente se divide en dos tipos: lento relax y rápido fast, el contenido específico es el siguiente:

Como puedes ver, aquí configuramos los Request Headers, que incluyen:
  • accept: el formato de respuesta que deseas recibir, aquí se establece como application/json, es decir, formato JSON.
  • authorization: la clave para llamar a la API, que puedes seleccionar directamente después de solicitarla.
Además, configuramos el Request Body, que incluye:
  • mode: el canal para generar la foto de identificación, que principalmente tiene dos tipos: rápido fast y lento relax. Cuando uses relax, se recomienda encarecidamente usar el siguiente parámetro callback_url.
  • template: el estilo de la plantilla de la foto de identificación.
  • image_urls: los enlaces de las imágenes de retrato que necesitas subir.
  • callback_url: la URL donde se necesita devolver el resultado.
Después de seleccionar, puedes ver que también se generó el código correspondiente a la derecha, como se muestra en la imagen:

Haz clic en el botón “Try” para realizar una prueba, como se muestra en la imagen anterior, y obtendrás el siguiente resultado: 
{
  "success": true,
  "task_id": "ae1e4948-dba1-4a6f-87af-67961b647428",
  "data": [
    {
      "id": "202411031951124776",
      "image_url": "https://platform.cdn.acedata.cloud/headshots/ae1e4948-dba1-4a6f-87af-67961b647428.png",
      "template": "Foto de retrato masculino"
    },
    {
      "id": "202411031951128490",
      "image_url": "https://platform.cdn.acedata.cloud/headshots/ae1e4948-dba1-4a6f-87af-67961b647428.png",
      "template": "Foto de retrato masculino"
    }
  ]
}
El resultado devuelto tiene varios campos, que se describen a continuación:
  • success: el estado de la tarea de generación de la foto de identificación en ese momento.
  • task_id: el ID de la tarea de generación de la foto de identificación en ese momento.
  • data: la lista de resultados de la tarea de generación de la foto de identificación en ese momento.
    • id: el ID de la foto de la tarea de generación de la foto de identificación en ese momento.
    • image_url: el enlace de la imagen de la tarea de generación de la foto de identificación en ese momento.
    • template: el nombre de la plantilla de la foto de identificación de la tarea de generación en ese momento.
Como puedes ver, hemos obtenido información satisfactoria sobre la foto de identificación según la plantilla y la imagen de retrato. Solo necesitamos obtener la foto de identificación a partir de la dirección del enlace de la imagen en data. Además, si deseas generar el código de integración correspondiente, puedes copiarlo directamente, por ejemplo, el código de CURL es el siguiente: 
curl -X POST 'https://api.acedata.cloud/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 asíncrono

Debido a que el tiempo de generación de la foto de identificación con IA es relativamente largo, aproximadamente de 1 a 2 minutos, si la API no responde durante mucho tiempo, la solicitud HTTP mantendrá la conexión, lo que provocará un consumo adicional de recursos del sistema. Por lo tanto, esta API también ofrece soporte para callbacks asíncronos. El proceso general es: cuando el cliente inicia la solicitud, debe especificar un campo adicional callback_url. Después de que el cliente inicie la solicitud a la API, la API devolverá inmediatamente un resultado que incluye un campo task_id, que representa el ID de la tarea actual. Cuando la tarea se complete, el resultado de la generación de la foto de identificación se enviará al callback_url especificado por el cliente en formato JSON POST, que también incluirá el campo task_id, de modo que el resultado de la tarea se pueda asociar mediante el ID. A continuación, utilizaremos un ejemplo para entender cómo operar específicamente. Primero, el callback de Webhook es un servicio que puede recibir solicitudes HTTP, y el desarrollador debe reemplazarlo con la URL de su propio servidor HTTP. Para facilitar la demostración, utilizaremos un sitio web de ejemplo de Webhook público https://webhook.site/, al abrir este sitio obtendrás una URL de Webhook, como se muestra en la imagen: Copia esta URL y podrás usarla como Webhook. El ejemplo aquí es https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a. A continuación, podemos establecer el campo callback_url como la URL de Webhook anterior, al mismo tiempo que ingresamos el enlace de la imagen de retrato y la plantilla. Este documento recomienda usar el callback asíncrono cuando el parámetro mode es relax, el contenido específico se muestra en la imagen:

Haz clic en ejecutar y podrás ver que recibirás un resultado inmediato, como el siguiente: 
{
  "task_id": "763b1450-8804-434f-acc7-d713be73a28f"
}
Después de un momento, podrás observar el resultado de la generación de la canción en https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a, como se muestra en la imagen: El contenido es el siguiente: 
{
    "success": true,
    "task_id": "763b1450-8804-434f-acc7-d713be73a28f",
    "data": [
        {
            "id": "202411032010131366",
            "image_url": "https://platform.cdn.acedata.cloud/headshots/763b1450-8804-434f-acc7-d713be73a28f.png",
            "template": "Foto de perfil masculina"
        },
        {
            "id": "202411032010132420",
            "image_url": "https://platform.cdn.acedata.cloud/headshots/763b1450-8804-434f-acc7-d713be73a28f.png",
            "template": "Foto de perfil masculina"
        }
    ]
}
Se puede ver que en el resultado hay un campo task_id, los otros campos son similares a los anteriores, a través de este campo se puede realizar la asociación de tareas.

​
Manejo de errores

Al llamar a la API, si se encuentra con un error, la API devolverá el código de error correspondiente y la información. Por ejemplo:
  • 400 token_mismatched: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
  • 400 api_not_implemented: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
  • 401 invalid_token: No autorizado, token de autorización inválido o faltante.
  • 429 too_many_requests: Demasiadas solicitudes, ha superado el límite de tasa.
  • 500 api_error: Error interno del servidor, algo salió mal en el servidor.

​
Ejemplo de respuesta de error

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "la recuperación falló"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Conclusión

A través de este documento, ha comprendido cómo utilizar la API de creación de fotos de identificación AI, que puede crear varios estilos de fotos de identificación ingresando la URL de la foto de retrato y la plantilla que prefiera. Esperamos que este documento le ayude a integrar y utilizar mejor esta API. Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de soporte técnico.