Überblick
Schicke ein flaches Bild einer Schachstellung, und die Antwort sagt dir, wo die Figuren stehen. Das ist ein in einem Buch oder einer Zeitschrift gedrucktes Diagramm, eine aus einem PDF exportierte Seite oder ein Screenshot aus einem Stream, einer App oder einem Analysebrett.
Zurück bekommst du ein FEN. Du trainierst nichts, hostest nichts und hältst keine GPU warm.
Authentifizierung
Ein Bearer-Schlüssel im Authorization-Header bei jeder Anfrage. Es gibt kein anderes Verfahren, keinen Query-Parameter und kein Cookie.
Schlüssel werden nach Absprache vergeben statt per Registrierung, es gibt also nichts selbst zu erzeugen. Zugang sagt, wie man fragt.
Eine Stellung erkennen
Ein Befehl, und das ist die ganze API. Der Body ist multipart/form-data mit dem Bild darin. Die Anfrage ist synchron: die Stellung kommt auf derselben Verbindung zurück, und es gibt keinen Auftrag abzufragen.
Das Bild wird genau so behalten, wie du es geschickt hast — Metadaten eingeschlossen, sodass ein Foto alles behält, was deine Kamera darin festgehalten hat, Ort inklusive. Wir speichern es neben der Aufstellung, die der Leser zurückgegeben hat, solange das Konto besteht: eine falsch zurückgegebene Lesung lässt sich sonst unmöglich untersuchen, und der Leser lässt sich nicht an echten Bildern messen. Das Konto zu löschen löscht beides.
Parameter
| Name | Typ | Pflicht | Vorgabe | Beschreibung |
|---|---|---|---|---|
| image | file | Ja | — | Das Bild der Stellung. PNG oder JPEG, bis zu 5 MB, mit keiner Seite unter 16 oder über 12000 Pixeln. Unten steht, was danach damit geschieht. |
| orientation_hint | white | black | auto | Nein | auto | Welche Farbe unten am Brett sitzt, wenn du es schon weißt. Auf auto belassen, rechnet der Leser es aus dem Bild aus. |
| side_to_move | w | b | Nein | w | Wer am Zug ist. Nicht im Bild, also nicht gelesen: das ist der Wert, der unten in das Feld fen eingesetzt wird. |
Antwort
200 mit einem JSON-Objekt, das ein Feld trägt. Ein Bild, aus dem keine Stellung wird, ist überhaupt keine 200: es ist eine 422 not_recognised, denn bei einem Feld ist im Body kein Platz, das zu sagen.
Ein Feld ist Absicht. Es ist die Notation, und alles andere, was ein Leser über eine Stellung berichten könnte — welche Felder er bezweifelt hat, wie sicher er war, wie herum das Brett lag — bleibt weg, bis ein Aufrufer es braucht, statt ausgeliefert zu werden, weil es existiert.
| Feld | Typ | Beschreibung |
|---|---|---|
| fen | string | Die Stellung, als die Notation, die jedes Schachprogramm liest. Nur ihr erstes Feld — die Figurenaufstellung — wurde von deinem Bild gelesen. Zugrecht, Rochaderechte, en passant und beide Zähler sind auf einem Bild nicht zu sehen, also sind sie die Vorgaben w - - 0 1, und du solltest jene überschreiben, die du kennst. |
Fehler
Jeder Fehler trägt einen maschinenlesbaren code. Diese Zeichenkette ist der Teil, den wir innerhalb von v1 nicht zu ändern versprechen; der Satz daneben darf umformuliert oder übersetzt werden.
{
"code": "unsupported_format"
}| Status | Code | Bedeutung |
|---|---|---|
| 400 | invalid_body | Der Multipart-Body konnte nicht gelesen werden. |
| 401 | unauthenticated | Kein Schlüssel, oder ein Schlüssel, der nicht mehr gültig ist. |
| 413 | too_large | Über 5 MB. |
| 415 | no_file | Kein Bildteil im Body. |
| 415 | unsupported_format | Kein PNG und kein JPEG. |
| 415 | unreadable_image | Der Header lässt sich nicht auswerten. |
| 415 | dimensions_out_of_range | Eine Seite unter 16 oder über 12000 Pixeln. |
| 422 | not_recognised | Aus dem Bild konnte keine Stellung gelesen werden. Dieser hier liegt an deinem Bild. |
| 429 | rate_limited | Dein Schlüssel ist über seinem Kontingent, oder hat zu viele Anfragen gleichzeitig offen. Siehe Retry-After. |
| 502 | recogniser_unavailable | Unserer, nicht deiner. Wir haben keine Antwort aus dem Leser bekommen. Versuche dasselbe Bild erneut. |
| 503 | at_capacity | Unserer, nicht deiner. Gerade ist zu viel gleichzeitig offen. Siehe Retry-After. |
Was es nicht lesen wird
Flache Bilder einer Stellung, und das ist alles. Die Grenze ist keine Einschränkung, die später fällt, sie ist das, wofür der Leser da ist.
- Fotos eines echten Bretts, aus jedem Winkel
- Video, oder eine Stellung, die sich noch bewegt
- Handgeschriebene Partieformulare und Zuglisten
Ein fotografiertes 3D-Brett ist ein schwierigeres Problem mit einer schlechteren Antwort, also gibt Chesslord nicht vor, es zu lösen. An flachen Diagrammen lässt es sich messen.
Zugang
Schreibe an [email protected] und sage, was du baust und ungefähr wie viele Bilder im Monat es schicken würde. Diese beiden Antworten sind, was wir brauchen, und es gibt kein Formular auszufüllen.