Resumen
Envía una imagen plana de una posición de ajedrez y la respuesta te dice dónde están las piezas. Eso es un diagrama impreso en un libro o una revista, una página exportada de un PDF, o una captura de pantalla de un stream, una aplicación o un tablero de análisis.
Lo que recibes es un FEN. No entrenas nada, no alojas nada, y no mantienes ninguna GPU caliente.
Autenticación
Una clave bearer en la cabecera Authorization en cada petición. No hay otro esquema, ni parámetro de consulta, ni cookie.
Las claves se conceden por acuerdo y no por registro, así que no hay nada que generar por tu cuenta. Acceso dice cómo pedirla.
Reconocer una posición
Un comando, y esa es toda la API. El cuerpo es multipart/form-data con la imagen dentro. La petición es síncrona: la posición vuelve por la misma conexión, y no hay ningún trabajo que consultar.
La imagen se conserva exactamente como la enviaste — metadatos incluidos, de modo que una fotografía conserva todo lo que registró tu cámara, la ubicación incluida. La guardamos junto a la colocación que devolvió el lector, mientras exista la cuenta: una lectura que salió mal es imposible de examinar de otro modo, y el lector no se puede medir contra imágenes reales. Eliminar la cuenta elimina ambas cosas.
Parámetros
| Nombre | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
| image | file | Sí | — | La imagen de la posición. PNG o JPEG, hasta 5 MB, sin ningún lado por debajo de 16 ni por encima de 12000 píxeles. Más abajo se explica qué pasa con ella después de responder. |
| orientation_hint | white | black | auto | No | auto | Qué color queda en la parte baja del tablero, cuando ya lo sabes. Si se deja en auto, el lector lo deduce de la imagen. |
| side_to_move | w | b | No | w | A quién le toca mover. No está en la imagen, así que no se lee: es el valor que se compone en el campo fen de abajo. |
Respuesta
200 con un objeto JSON que lleva un solo campo. Una imagen de la que no sale ninguna posición no es un 200 en absoluto: es un 422 not_recognised, porque con un solo campo no hay sitio en el cuerpo para decirlo.
Un solo campo es deliberado. Es la notación, y todo lo demás que un lector podría contar sobre una posición — de qué casillas dudó, qué seguridad tenía, hacia qué lado estaba el tablero — se deja fuera hasta que un cliente lo necesite, en vez de enviarse porque existe.
| Campo | Tipo | Descripción |
|---|---|---|
| fen | string | La posición, en la notación que lee cualquier programa de ajedrez. Solo su primer campo — la colocación de las piezas — se leyó de tu imagen. El turno, los derechos de enroque, la captura al paso y ambos contadores no se ven en una imagen, así que son los valores por defecto w - - 0 1 y deberías sobrescribir los que conozcas. |
Errores
Cada error lleva un code legible por máquina. Esa cadena es la parte que prometemos no cambiar dentro de v1; la frase que la acompaña es libre de reescribirse o traducirse.
{
"code": "unsupported_format"
}| Estado | Código | Significado |
|---|---|---|
| 400 | invalid_body | El cuerpo multipart no se pudo leer. |
| 401 | unauthenticated | Sin clave, o con una clave que ya no es válida. |
| 413 | too_large | Más de 5 MB. |
| 415 | no_file | No hay parte de imagen en el cuerpo. |
| 415 | unsupported_format | No es un PNG ni un JPEG. |
| 415 | unreadable_image | La cabecera no se puede analizar. |
| 415 | dimensions_out_of_range | Un lado por debajo de 16 o por encima de 12000 píxeles. |
| 422 | not_recognised | No se pudo leer ninguna posición de la imagen. Este es cosa de tu imagen. |
| 429 | rate_limited | Tu clave ha superado su cuota, o tiene demasiadas peticiones en curso. Consulta Retry-After. |
| 502 | recogniser_unavailable | Nuestro, no tuyo. No conseguimos respuesta del lector. Reintenta con la misma imagen. |
| 503 | at_capacity | Nuestro, no tuyo. Hay demasiado en curso ahora mismo. Consulta Retry-After. |
Qué no va a leer
Imágenes planas de una posición, y eso es todo. El límite no es una restricción que se levantará más adelante: es aquello para lo que sirve el lector.
- Fotografías de un tablero real, desde cualquier ángulo
- Vídeo, o una posición que todavía se mueve
- Planillas y listas de jugadas escritas a mano
Un tablero en tres dimensiones fotografiado es un problema más difícil con una respuesta peor, así que Chesslord no finge resolverlo. Con los diagramas planos sí se le puede exigir.
Acceso
Escribe a [email protected] y cuenta qué estás construyendo y aproximadamente cuántas imágenes al mes enviaría. Esas dos respuestas son lo que necesitamos, y no hay ningún formulario que rellenar.