Chesslord

API di riconoscimento

Leggi una posizione di scacchi da un’immagine piatta e ricevila come notazione. Una richiesta, una risposta, e nessun modello da addestrare o da ospitare.

POST https://api.chesslord.app/v1/positions/recognize

Richiedi una chiave

Non è ancora aperta. Le chiavi vengono concesse su accordo, e finché resta chiusa non c’è niente da pagare.

Panoramica

Invia un’immagine piatta di una posizione di scacchi e la risposta ti dice dove sono i pezzi. Cioè un diagramma stampato in un libro o in una rivista, una pagina esportata da un PDF, o uno screenshot di uno stream, di un’app o di una scacchiera di analisi.

Quello che ricevi è una FEN. Non addestri niente, non ospiti niente e non tieni calda nessuna GPU.

Autenticazione

Una chiave bearer nell’header Authorization di ogni richiesta. Non c’è nessun altro schema, nessun parametro di query e nessun cookie.

Le chiavi vengono concesse su accordo e non con la registrazione, quindi non c’è niente da generare da solo. Accesso spiega come chiederla.

Riconoscere una posizione

Un solo comando, ed è tutta l’API. Il corpo è multipart/form-data con dentro l’immagine. La richiesta è sincrona: la posizione torna sulla stessa connessione, e non c’è nessun job da interrogare.

L’immagine viene conservata esattamente come l’hai inviata, metadati compresi, quindi una fotografia conserva tutto quello che la tua fotocamera ci ha registrato, posizione geografica inclusa. La archiviamo insieme alla disposizione dei pezzi restituita dal lettore, finché esiste l’account: altrimenti una lettura venuta male sarebbe impossibile da esaminare, e il lettore non si potrebbe misurare su immagini reali. Eliminare l’account elimina entrambe.

Parametri

NomeTipoObbligatorioPredefinitoDescrizione
imagefileSì—L’immagine della posizione. PNG o JPEG, fino a 5 MB, senza lati sotto i 16 o sopra i 12000 pixel. Più sotto trovi cosa succede all’immagine dopo la nostra risposta.
orientation_hintwhite | black | autoNoautoQuale colore sta in basso sulla scacchiera, quando lo sai già. Se lo lasci su auto, il lettore lo ricava dall’immagine.
side_to_movew | bNowA chi tocca muovere. Non è nell’immagine, quindi non viene letto: è il valore inserito nel campo fen qui sotto.

Risposta

200 con un oggetto JSON che contiene un solo campo. Un’immagine da cui non esce nessuna posizione non è affatto un 200: è un 422 not_recognised, perché con un solo campo non c’è posto nel corpo per dirlo.

Un solo campo è una scelta. È la notazione, e tutto il resto che un lettore potrebbe dire su una posizione (di quali case ha dubitato, quanto era sicuro, da che verso stava la scacchiera) resta fuori finché a qualcuno non serve, invece di essere spedito solo perché esiste.

CampoTipoDescrizione
fenstringLa posizione, nella notazione che ogni programma di scacchi sa leggere. Solo il suo primo campo, la disposizione dei pezzi, è stato letto dalla tua immagine. Il tratto, i diritti di arrocco, l’en passant ed entrambi i contatori non si vedono in un’immagine, quindi hanno i valori predefiniti w - - 0 1 e dovresti sovrascrivere quelli che conosci.

Errori

Ogni errore ha un code leggibile dalle macchine. Quella stringa è la parte che promettiamo di non cambiare dentro v1; la frase accanto può essere riformulata o tradotta.

Errore
{
  "code": "unsupported_format"
}
StatoCodiceSignificato
400invalid_bodyNon è stato possibile leggere il corpo multipart.
401unauthenticatedNessuna chiave, o una chiave non più valida.
413too_largeOltre 5 MB.
415no_fileNel corpo non c’è nessuna parte con l’immagine.
415unsupported_formatNon è né un PNG né un JPEG.
415unreadable_imageL’header non si riesce ad analizzare.
415dimensions_out_of_rangeUn lato sotto i 16 o sopra i 12000 pixel.
422not_recognisedDall’immagine non è stato possibile leggere nessuna posizione. Questo dipende dalla tua immagine.
429rate_limitedLa tua chiave ha superato la sua quota, o ha troppe richieste in corso. Vedi Retry-After.
502recogniser_unavailableColpa nostra, non tua. Non siamo riusciti a ottenere una risposta dal lettore. Riprova con la stessa immagine.
503at_capacityColpa nostra, non tua. Troppe richieste in corso in questo momento. Vedi Retry-After.

Cosa non legge

Immagini piatte di una posizione, e nient’altro. Questo confine non è un limite da togliere più avanti: è lo scopo per cui esiste il lettore.

  • Fotografie di una scacchiera reale, da qualsiasi angolazione
  • Video, o una posizione ancora in movimento
  • Formulari e liste di mosse scritti a mano

Una scacchiera 3D fotografata è un problema più difficile con una risposta peggiore, quindi Chesslord non finge di risolverlo. Sui diagrammi piatti, invece, puoi chiedergliene conto.

Accesso

Scrivi a contact@chesslord.app e racconta cosa stai costruendo e più o meno quante immagini al mese invierebbe. Ci servono queste due risposte, e non c’è nessun modulo da compilare.