Visão geral
Envie uma imagem plana de uma posição de xadrez e a resposta diz onde estão as peças. Isso vale para um diagrama impresso em um livro ou revista, uma página exportada de um PDF, ou uma captura de tela de uma live, de um aplicativo ou de um tabuleiro de análise.
O que volta é um FEN. Você não treina nada, não hospeda nada e não mantém nenhuma GPU ligada.
Autenticação
Uma chave bearer no cabeçalho Authorization em toda requisição. Não há outro esquema, nem parâmetro de query, nem cookie.
As chaves são liberadas por combinação, e não por cadastro, então não há nada para você gerar sozinho. Acesso explica como pedir.
Reconhecer uma posição
Um comando, e ele é a API inteira. O corpo é multipart/form-data com a imagem dentro. A requisição é síncrona: a posição volta na mesma conexão, e não há nenhum job para consultar.
A imagem é guardada exatamente como você a enviou — com os metadados, então uma fotografia mantém tudo o que a sua câmera registrou nela, inclusive a localização. Nós a armazenamos junto com a disposição das peças que o leitor devolveu, enquanto a conta existir: sem isso, seria impossível investigar uma leitura que veio errada, e o leitor não poderia ser medido contra imagens reais. Excluir a conta exclui as duas.
Parâmetros
| Nome | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
| image | file | Sim | — | A imagem da posição. PNG ou JPEG, até 5 MB, sem nenhum lado menor que 16 ou maior que 12000 pixels. Veja abaixo o que acontece com ela depois que respondemos. |
| orientation_hint | white | black | auto | Não | auto | Qual cor fica na parte de baixo do tabuleiro, quando você já sabe. Se ficar em auto, o leitor descobre pela imagem. |
| side_to_move | w | b | Não | w | De quem é a vez. Isso não está na imagem, então não é lido: é o valor usado para montar o campo fen abaixo. |
Resposta
200 com um objeto JSON que traz um único campo. Uma imagem da qual não sai nenhuma posição não é um 200: é um 422 not_recognised, porque com um único campo não há lugar no corpo para dizer isso.
Um único campo é proposital. É a notação, e todo o resto que um leitor poderia informar sobre uma posição — de quais casas ele duvidou, quão seguro estava, para que lado o tabuleiro estava virado — fica de fora até que alguém que chama a API precise, em vez de ser enviado só porque existe.
| Campo | Tipo | Descrição |
|---|---|---|
| fen | string | A posição, na notação que todo programa de xadrez lê. Só o primeiro campo dela — a disposição das peças — foi lido da sua imagem. A vez de jogar, os direitos de roque, o en passant e os dois contadores não aparecem numa imagem, então ficam com os valores padrão w - - 0 1, e você deve substituir os que souber. |
Erros
Todo erro traz um code legível por máquina. Essa string é a parte que prometemos não mudar dentro da v1; a frase ao lado dela pode ser reescrita ou traduzida.
{
"code": "unsupported_format"
}| Status | Código | Significado |
|---|---|---|
| 400 | invalid_body | Não foi possível ler o corpo multipart. |
| 401 | unauthenticated | Sem chave, ou com uma chave que não é mais válida. |
| 413 | too_large | Mais de 5 MB. |
| 415 | no_file | Nenhuma parte de imagem no corpo. |
| 415 | unsupported_format | Não é um PNG nem um JPEG. |
| 415 | unreadable_image | Não foi possível interpretar o cabeçalho. |
| 415 | dimensions_out_of_range | Um lado menor que 16 ou maior que 12000 pixels. |
| 422 | not_recognised | Não foi possível ler nenhuma posição da imagem. Este é sobre a sua imagem. |
| 429 | rate_limited | Sua chave passou da cota, ou tem requisições demais em andamento. Veja Retry-After. |
| 502 | recogniser_unavailable | O problema é nosso, não seu. Não conseguimos uma resposta do leitor. Tente de novo com a mesma imagem. |
| 503 | at_capacity | O problema é nosso, não seu. Coisa demais em andamento agora. Veja Retry-After. |
O que ela não lê
Imagens planas de uma posição, e só isso. Esse limite não é uma restrição a ser removida depois: é para isso que o leitor existe.
- Fotografias de um tabuleiro físico, de qualquer ângulo
- Vídeo, ou uma posição que ainda está em movimento
- Súmulas e listas de lances escritas à mão
Um tabuleiro 3D fotografado é um problema mais difícil, com uma resposta pior, então o Chesslord não finge resolvê-lo. Nos diagramas planos, dá para cobrar dele.
Acesso
Escreva para contact@chesslord.app e conte o que você está construindo e mais ou menos quantas imagens por mês ele enviaria. Essas duas respostas são o que precisamos, e não há formulário para preencher.