POST /api/recognize

Envie uma imagem JPEG ou PNG e receba os dados de todas as placas detectadas. Cada chamada bem-sucedida consome 1 crédito.

Autenticação

Scope necessário: recognitions:write

Inclua o header Authorization: Bearer <api-key> ou use cookie de sessão.

Requisição

POST /api/recognize?mode=scene|closeup
Content-Type: application/octet-stream
Body: bytes da imagem

Parâmetros de query

scene (padrão) — para frames de câmeras de monitoramento, onde a placa ocupa uma parte pequena da imagem. A imagem é processada sem modificações.

closeup — para fotos tiradas de perto, onde a placa preenche a maior parte do quadro (celular, app, leitor móvel, foto da traseira de um veículo). A imagem passa por normalização de escala antes da detecção, o que melhora drasticamente a taxa de detecção nesses casos. A orientação EXIF é aplicada automaticamente (fotos de celular em retrato).

Headers

Body

O corpo da requisição deve conter os bytes brutos da imagem (JPEG ou PNG).

Exemplos

curl

curl -X POST "https://api.placaflow.com.br/api/recognize" \
  -H "Content-Type: application/octet-stream" \
  -H "Authorization: Bearer pk_a1b2c3d4e5f6g7h8i9j0..." \
  --data-binary @foto.jpg

curl — foto tirada de perto (placa preenche o quadro)

curl -X POST "https://api.placaflow.com.br/api/recognize?mode=closeup" \
  -H "Content-Type: application/octet-stream" \
  -H "Authorization: Bearer pk_a1b2c3d4e5f6g7h8i9j0..." \
  --data-binary @foto-celular.jpg

Node.js

const fs = require('fs');

const image = fs.readFileSync('foto.jpg');

const res = await fetch('https://api.placaflow.com.br/api/recognize', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/octet-stream',
    'Authorization': 'Bearer pk_a1b2c3d4e5f6g7h8i9j0...',
  },
  body: image,
});

const data = await res.json();
console.log(`Placas encontradas: ${data.plates.length}`);
console.log(`Tempo de processamento: ${data.processingTimeMs}ms`);
console.log(`Créditos restantes: ${data.creditsRemaining}`);

for (const plate of data.plates) {
  console.log(`${plate.plate} — ${plate.conf.toFixed(1)}%`);
}

Python

import requests

with open('foto.jpg', 'rb') as f:
    image = f.read()

res = requests.post(
    'https://api.placaflow.com.br/api/recognize',
    headers={
        'Content-Type': 'application/octet-stream',
        'Authorization': 'Bearer pk_a1b2c3d4e5f6g7h8i9j0...',
    },
    data=image,
)

data = res.json()
print(f"Placas encontradas: {len(data['plates'])}")
print(f"Tempo: {data['processingTimeMs']}ms")
print(f"Créditos restantes: {data['creditsRemaining']}")

for plate in data['plates']:
    print(f"{plate['plate']} — {plate['conf']:.1f}%")

Resposta 200

{
  "plates": [
    {
      "plate": "ABC1D23",
      "conf": 95.2,
      "charConfs": "0.98;0.95;0.92;0.96;0.94;0.97;0.93",
      "coordinateLeft": 100,
      "coordinateTop": 200,
      "coordinateRight": 300,
      "coordinateBottom": 250,
      "plateType": "car",
      "time": "2026-03-22T14:30:00.000-03:00",
      "createdAt": "2026-03-22T14:30:00.000-03:00"
    },
    {
      "plate": "XYZ9K87",
      "conf": 88.7,
      "charConfs": "0.91;0.87;0.90;0.85;0.92;0.88;0.86",
      "coordinateLeft": 520,
      "coordinateTop": 310,
      "coordinateRight": 710,
      "coordinateBottom": 365,
      "plateType": "car",
      "time": "2026-03-22T14:30:00.000-03:00",
      "createdAt": "2026-03-22T14:30:00.000-03:00"
    }
  ],
  "processingTimeMs": 45,
  "imageWidth": 1920,
  "imageHeight": 1080,
  "creditsRemaining": 499
}

Campos da resposta (raiz)

Campos de cada placa (plates[n])

Créditos

Cada chamada processada com sucesso consome 1 crédito — mesmo quando nenhuma placa é detectada (o custo é do processamento, não do resultado). Chamadas que falham (erros 4xx ou 5xx) não consomem crédito: em falhas do servidor de reconhecimento, o crédito é estornado automaticamente.

Erros