Vue d’ensemble
Envoyez une image plate d’une position d’échecs et la réponse vous dit où sont les pièces. C’est un diagramme imprimé dans un livre ou une revue, une page exportée d’un PDF, ou une capture d’écran d’un stream, d’une application ou d’un échiquier d’analyse.
Ce que vous récupérez est un FEN. Vous n’entraînez rien, n’hébergez rien, et ne gardez aucun GPU au chaud.
Authentification
Une clé bearer dans l’en-tête Authorization à chaque requête. Il n’y a pas d’autre schéma, pas de paramètre de requête et pas de cookie.
Les clés sont délivrées sur arrangement plutôt que par inscription : il n’y a donc rien à générer soi-même. Accès explique comment demander.
Reconnaître une position
Une commande, et c’est toute l’API. Le corps est en multipart/form-data avec l’image dedans. La requête est synchrone : la position revient sur la même connexion, et il n’y a aucune tâche à interroger.
L’image est conservée exactement telle que vous l’avez envoyée — métadonnées comprises, de sorte qu’une photographie garde tout ce que votre appareil y a enregistré, localisation incluse. Nous la stockons à côté du placement renvoyé par le lecteur, aussi longtemps que le compte existe : une lecture revenue fausse est autrement impossible à examiner, et le lecteur ne peut pas être mesuré sur de vraies images. Supprimer le compte supprime les deux.
Paramètres
| Nom | Type | Requis | Par défaut | Description |
|---|---|---|---|---|
| image | file | Oui | — | L’image de la position. PNG ou JPEG, jusqu’à 5 Mo, sans côté inférieur à 16 ni supérieur à 12000 pixels. Voir plus bas ce qu’elle devient après notre réponse. |
| orientation_hint | white | black | auto | Non | auto | Quelle couleur se trouve en bas de l’échiquier, quand vous le savez déjà. Laissé sur auto, le lecteur le déduit de l’image. |
| side_to_move | w | b | Non | w | À qui de jouer. Absent de l’image, donc non lu : c’est la valeur composée dans le champ fen ci-dessous. |
Réponse
200 avec un objet JSON portant un seul champ. Une image dont ne sort aucune position n’est pas du tout un 200 : c’est un 422 not_recognised, car avec un seul champ il n’y a nulle part dans le corps pour le dire.
Un seul champ, et c’est délibéré. C’est la notation, et tout ce qu’un lecteur pourrait rapporter d’autre sur une position — quelles cases il a mises en doute, à quel point il était sûr, dans quel sens était l’échiquier — est laissé de côté jusqu’à ce qu’un appelant en ait besoin, plutôt que livré parce que cela existe.
| Champ | Type | Description |
|---|---|---|
| fen | string | La position, dans la notation que lit tout programme d’échecs. Seul son premier champ — le placement des pièces — a été lu sur votre image. Le trait, les droits de roque, la prise en passant et les deux compteurs ne sont pas visibles sur une image : ce sont donc les valeurs par défaut w - - 0 1, et vous devriez écraser celles que vous connaissez. |
Erreurs
Chaque erreur porte un code lisible par une machine. Cette chaîne est la partie que nous promettons de ne pas changer à l’intérieur de v1 ; la phrase à côté est libre d’être reformulée ou traduite.
{
"code": "unsupported_format"
}| Statut | Code | Signification |
|---|---|---|
| 400 | invalid_body | Le corps multipart n’a pas pu être lu. |
| 401 | unauthenticated | Pas de clé, ou une clé qui n’est plus valide. |
| 413 | too_large | Plus de 5 Mo. |
| 415 | no_file | Aucune partie image dans le corps. |
| 415 | unsupported_format | Ni un PNG ni un JPEG. |
| 415 | unreadable_image | L’en-tête ne s’analyse pas. |
| 415 | dimensions_out_of_range | Un côté inférieur à 16 ou supérieur à 12000 pixels. |
| 422 | not_recognised | Aucune position n’a pu être lue dans l’image. Celle-ci concerne votre image. |
| 429 | rate_limited | Votre clé dépasse son quota, ou a trop de requêtes en cours. Voir Retry-After. |
| 502 | recogniser_unavailable | La nôtre, pas la vôtre. Nous n’avons pas obtenu de réponse du lecteur. Réessayez avec la même image. |
| 503 | at_capacity | La nôtre, pas la vôtre. Trop de requêtes en cours en ce moment. Voir Retry-After. |
Ce qu’elle ne lira pas
Des images plates d’une position, et c’est tout. La limite n’est pas une restriction à lever plus tard, c’est ce à quoi le lecteur sert.
- Les photographies d’un échiquier réel, sous n’importe quel angle
- La vidéo, ou une position encore en mouvement
- Les feuilles de partie et les listes de coups manuscrites
Un échiquier en trois dimensions photographié est un problème plus difficile pour une réponse moins bonne, alors Chesslord ne prétend pas le résoudre. Sur les diagrammes plats, on peut le tenir pour responsable.
Accès
Écrivez à [email protected] et dites ce que vous construisez et à peu près combien d’images par mois cela enverrait. Ces deux réponses sont ce qu’il nous faut, et il n’y a aucun formulaire à remplir.