Especificaciones de integración de la API de localización de rasgos faciales

Face Transformation 集成指南 - Ace Data Cloud

Este documento presentará una especificación de integración de la API de localización de rasgos faciales, que puede localizar los rasgos faciales (también conocido como localización de puntos clave de la cara) a través de la entrada de una imagen, calculando 90 puntos que forman el contorno de la cara, incluyendo cejas (8 puntos a cada lado), ojos (8 puntos a cada lado), nariz (13 puntos), boca (22 puntos), contorno de la cara (21 puntos) y pupilas (2 puntos).

​

Proceso de solicitud

Para utilizar la API, primero debe ir a la página correspondiente de la API de localización de rasgos faciales para solicitar el servicio correspondiente. Una vez en la página, haga clic en el botón “Acquire”, como se muestra en la imagen:

Si aún no ha iniciado sesión o registrado, será redirigido automáticamente a la página de inicio de sesión que le invita a registrarse e iniciar sesión. Después de registrarse e iniciar sesión, volverá automáticamente a la página actual.

En la primera solicitud, se le otorgará un límite gratuito que le permitirá utilizar la API de forma gratuita.

​

Uso básico

Primero, comprenda la forma básica de uso, que consiste en ingresar el enlace de la imagen para obtener la imagen de resultado procesada. Primero, necesita pasar un campo image_url, la imagen de la cara se muestra a continuación:

A continuación, podemos completar el contenido correspondiente en la interfaz, como se muestra en la imagen:

Aquí podemos ver que hemos configurado los encabezados de la solicitud, que incluyen:

• accept: el formato de respuesta que desea recibir, aquí se establece como application/json, es decir, formato JSON.
• authorization: la clave para llamar a la API, que puede seleccionar directamente después de solicitarla.

Además, se configuró el cuerpo de la solicitud, que incluye:

• image_url: el enlace de la imagen de la cara que necesita ser procesada.
• mode: modo de detección. 0 para detectar todas las caras que aparecen, 1 para detectar la cara de mayor área. El valor predeterminado es 0.
• face_model_version: la versión del modelo de algoritmo utilizado por el servicio de reconocimiento facial, el valor predeterminado es 3.0.
• need_rotate_detection: si se habilita el soporte de detección de rotación de imágenes. 0 para no habilitar, 1 para habilitar. El valor predeterminado es 0.

Después de seleccionar, se puede observar que también se generó el código correspondiente a la derecha, como se muestra en la imagen:

Haga clic en el botón “Try” para realizar la prueba, como se muestra en la imagen anterior, aquí obtuvimos el siguiente resultado:

{
  "image_width": 690,
  "image_height": 920,
  "face_model_version": "3.0",
  "face_shape_set": [
    {
      "face_profile": [
        {
          "x": 294,
          "y": 207
        },
        {
          "x": 289,
          "y": 216
        },
        {
          "x": 286,
          "y": 226
        },
        {
          "x": 284,
          "y": 236
        },
        {
          "x": 283,
          "y": 246
        },
        {
          "x": 283,
          "y": 256
        },
        {
          "x": 284,
          "y": 266
        },
        {
          "x": 286,
          "y": 276
        },
        {
          "x": 289,
          "y": 285
        },
        {
          "x": 294,
          "y": 294
        },
        {
          "x": 301,
          "y": 301
        },
        {
          "x": 314,
          "y": 306
        },
        {
          "x": 327,
          "y": 307
        },
        {
          "x": 340,
          "y": 306
        },
        {
          "x": 353,
          "y": 302
        },
        {
          "x": 365,
          "y": 296
        },
        {
          "x": 374,
          "y": 287
        },
        {
          "x": 382,
          "y": 276
        },
        {
          "x": 387,
          "y": 264
        },
        {
          "x": 392,
          "y": 251
        },
        {
          "x": 396,
          "y": 238
        }
      ],
      "left_eye": [
        {
          "x": 298,
          "y": 208
        },
        {
          "x": 301,
          "y": 212
        },
        {
          "x": 305,
          "y": 214
        },
        {
          "x": 309,
          "y": 215
        },
        {
          "x": 314,
          "y": 216
        },
        {
          "x": 313,
          "y": 210
        },
        {
          "x": 309,
          "y": 207
        },
        {
          "x": 303,
          "y": 206
        }
      ],
      "right_eye": [
        {
          "x": 363,
          "y": 229
        },
        {
          "x": 358,
          "y": 230
        },
        {
          "x": 353,
          "y": 229
        },
        {
          "x": 347,
          "y": 227
        },
        {
          "x": 342,
          "y": 224
        },
        {
          "x": 348,
          "y": 221
        },
        {
          "x": 354,
          "y": 221
        },
        {
          "x": 360,
          "y": 223
        }
      ],
      "left_eye_brow": [
        {
          "x": 296,
          "y": 196
        },
        {
          "x": 302,
          "y": 197
        },
        {
          "x": 308,
          "y": 198
        },
        {
          "x": 313,
          "y": 200
        },
        {
          "x": 319,
          "y": 202
        },
        {
          "x": 315,
          "y": 195
        },
        {
          "x": 309,
          "y": 192
        },
        {
          "x": 302,
          "y": 192
        }
      ],
      "right_eye_brow": [
        {
          "x": 377,
          "y": 221
        },
        {
          "x": 369,
          "y": 217
        },
        {
          "x": 360,
          "y": 213
        },
        {
          "x": 350,
          "y": 211
        },
        {
          "x": 341,
          "y": 208
        },
        {
          "x": 351,
          "y": 204
        },
        {
          "x": 362,
          "y": 206
        },
        {
          "x": 372,
          "y": 211
        }
      ],
      "mouth": [
        {
          "x": 296,
          "y": 262
        },
        {
          "x": 297,
          "y": 269
        },
        {
          "x": 299,
          "y": 276
        },
        {
          "x": 305,
          "y": 281
        },
        {
          "x": 315,
          "y": 283
        },
        {
          "x": 326,
          "y": 282
        },
        {
          "x": 335,
          "y": 277
        },
        {
          "x": 325,
          "y": 269
        },
        {
          "x": 315,
          "y": 262
        },
        {
          "x": 309,
          "y": 261
        },
        {
          "x": 305,
          "y": 258
        },
        {
          "x": 300,
          "y": 259
        },
        {
          "x": 299,
          "y": 265
        },
        {
          "x": 303,
          "y": 269
        },
        {
          "x": 307,
          "y": 272
        },
        {
          "x": 316,
          "y": 275
        },
        {
          "x": 325,
          "y": 276
        },
        {
          "x": 326,
          "y": 272
        },
        {
          "x": 317,
          "y": 269
        },
        {
          "x": 308,
          "y": 265
        },
        {
          "x": 304,
          "y": 263
        },
        {
          "x": 300,
          "y": 262
        }
      ],
      "nose": [
        {
          "x": 311,
          "y": 242
        },
        {
          "x": 325,
          "y": 220
        },
        {
          "x": 319,
          "y": 226
        },
        {
          "x": 313,
          "y": 231
        },
        {
          "x": 307,
          "y": 236
        },
        {
          "x": 302,
          "y": 243
        },
        {
          "x": 306,
          "y": 249
        },
        {
          "x": 311,
          "y": 252
        },
        {
          "x": 318,
          "y": 254
        },
        {
          "x": 329,
          "y": 253
        },
        {
          "x": 327,
          "y": 243
        },
        {
          "x": 326,
          "y": 235
        },
        {
          "x": 326,
          "y": 228
        }
      ],
      "left_pupil": [
        {
          "x": 310,
          "y": 211
        }
      ],
      "right_pupil": [
        {
          "x": 357,
          "y": 225
        }
      ]
    }
  ]
}

Se puede ver que en este momento hemos obtenido la información relacionada con la cara de la persona en la imagen, incluyendo la ubicación de las características faciales (puntos clave de la cara) y la versión del modelo de algoritmo utilizado para el reconocimiento facial.

La descripción de los campos es la siguiente:

• image_width ：ancho de la imagen solicitado.
• image_height ：altura de la imagen solicitada.
• face_model_version：versión del modelo de algoritmo utilizado para el reconocimiento facial.
• face_shape_set：información específica sobre la localización de los rasgos faciales (puntos clave de la cara).
  • face_profile ：21 puntos que describen el contorno de la forma de la cara.
    • x ：coordenada x
    • y ：coordenada y
  • left_eye ：8 puntos que describen el contorno del ojo izquierdo.
    • x ：coordenada x
    • y ：coordenada y
  • right_eye ：8 puntos que describen el contorno del ojo derecho.
    • x ：coordenada x
    • y ：coordenada y
  • left_eye_brow ：8 puntos que describen el contorno de la ceja izquierda.
    • x ：coordenada x
    • y ：coordenada y
  • right_eye_brow ：8 puntos que describen el contorno de la ceja derecha.
    • x ：coordenada x
    • y ：coordenada y
  • mouth ：22 puntos que describen el contorno de la boca.
    • x ：coordenada x
    • y ：coordenada y
  • nose ：13 puntos que describen el contorno de la nariz.
    • x ：coordenada x
    • y ：coordenada y
  • left_pupil ：1 punto que describe el contorno de la pupila izquierda.
    • x ：coordenada x
    • y ：coordenada y
  • right_pupil ：1 punto que describe el contorno de la pupila derecha.
    • x ：coordenada x
    • y ：coordenada y

Además, si desea generar el código correspondiente para la integración, puede copiarlo directamente, por ejemplo, el código de CURL es el siguiente:

curl -X POST 'https://api.acedata.cloud/face/analyze' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "image_url": "https://cdn.acedata.cloud/lrbtcn.jpg"
}'

El código de integración en Python es el siguiente:

import requests

url = "https://api.acedata.cloud/face/analyze"

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

payload = {
    "image_url": "https://cdn.acedata.cloud/lrbtcn.jpg"
}

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

​

Manejo de errores

Al llamar a la API, si se encuentra con un error, la API devolverá el código de error y la información correspondiente. 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": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

Conclusión

A través de este documento, ha aprendido cómo utilizar la API de localización de rasgos faciales para realizar la localización de rasgos en la imagen de entrada. 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.