Chesslord

API de reconhecimento

Leia uma posição de xadrez a partir de uma imagem plana e receba-a de volta em notação. Uma requisição, uma resposta e nenhum modelo para treinar ou hospedar.

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

Pedir uma chave

Ainda não está aberta. As chaves são liberadas por combinação, e não há nada a pagar enquanto ela estiver fechada.

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

NomeTipoObrigatórioPadrãoDescrição
imagefileSim—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_hintwhite | black | autoNãoautoQual cor fica na parte de baixo do tabuleiro, quando você já sabe. Se ficar em auto, o leitor descobre pela imagem.
side_to_movew | bNãowDe 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.

CampoTipoDescrição
fenstringA 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.

Erro
{
  "code": "unsupported_format"
}
StatusCódigoSignificado
400invalid_bodyNão foi possível ler o corpo multipart.
401unauthenticatedSem chave, ou com uma chave que não é mais válida.
413too_largeMais de 5 MB.
415no_fileNenhuma parte de imagem no corpo.
415unsupported_formatNão é um PNG nem um JPEG.
415unreadable_imageNão foi possível interpretar o cabeçalho.
415dimensions_out_of_rangeUm lado menor que 16 ou maior que 12000 pixels.
422not_recognisedNão foi possível ler nenhuma posição da imagem. Este é sobre a sua imagem.
429rate_limitedSua chave passou da cota, ou tem requisições demais em andamento. Veja Retry-After.
502recogniser_unavailableO problema é nosso, não seu. Não conseguimos uma resposta do leitor. Tente de novo com a mesma imagem.
503at_capacityO 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.