Gibt es eine API, die Pokémon-Karten auf einem Foto erkennt?

Was du schickst

Eine POST-Anfrage an https://europe-west1-neosatoshi.cloudfunctions.net/detectApi mit dem Header Authorization: Bearer <key> und einem JSON-Body mit entweder image (ein JPEG oder PNG als Base64, bis 12 MB) oder image_url (ein öffentlicher https-Link darauf). Pokémon ist das Standardspiel, "tcg" brauchst du also nicht. Diese Anfrage nutzt unser Beispielfoto einer Ordnerseite und den öffentlichen Demo-Schlüssel und funktioniert so, wie sie ist:

curl -X POST https://europe-west1-neosatoshi.cloudfunctions.net/detectApi \
  -H "Authorization: Bearer nsk_live_9c253fbed995042a98280ad13e5c47d3c4a59c9b4f0f7274" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://neosatoshi.com/static/images/example_api_multi.jpg"}'

Was pro Karte zurückkommt

{
  "name": "Charizard ex",
  "name_ja": null,
  "language": "en",
  "set": { "id": "sv3pt5", "ptcgo_code": "MEW", "name": "151", "number": "006" },
  "rarity": "Illustration Rare",
  "cardmarket_id": 746497,
  "reverse_holo": false,
  "first_edition": false,
  "prices": {
    "cardmarket": { "trend": 3.93, "low": 2.50, "avg7": 4.05, "avg30": 4.21, "currency": "EUR" }
  },
  "confidence": 0.97,
  "alternatives": [
    { "name": "Charizard", "set": "Base", "number": "004", "score": 0.81 }
  ]
}

• name: der Kartenname in der gedruckten Sprache. Bei japanischen, koreanischen und chinesischen Karten ist es der englische Name, der Originalname steht in name_ja, name_ko oder name_zh.
• language: die erkannte Kartensprache, zum Beispiel "en", "de", "ja" oder "zh".
• set: die Set-ID, ptcgo_code (das kurze Kürzel auf modernen Karten, etwa MEW für 151), der Set-Name und die Kartennummer.
• rarity: die gedruckte Seltenheit.
• reverse_holo und first_edition: true, wenn das Foto einen Reverse-Holo- oder einen 1st-Edition-Druck zeigt. Reverse Holo kommt nur in Frage, wo Seltenheit und Ära es zulassen.
• cardmarket_id: die Cardmarket-Produkt-ID (idProduct). Bei wenigen Karten ist sie null.
• prices.cardmarket: trend, low, avg7 und avg30 in EUR, täglich aktualisiert.
• possible_variants: bekannte Katalogversionen der Karte (zum Beispiel gestempelte Versionen), mit eigener Cardmarket-ID und eigenem Preis, wo bekannt. Das sind Optionen, die dein Nutzer bestätigt, nichts, was aus dem Foto gelesen wird. Null heisst, es gibt keine Variantendaten, nicht, dass es keine Varianten gibt.
• is_energy_card und is_card_back: Flags, damit deine App Basis-Energien und Kartenrückseiten überspringen kann.
• images: Referenzbilder in zwei Grössen.
• confidence (0 bis 1) und image_quality (unscharf, ungewöhnliche Masse).
• alternatives: Kandidaten mit tieferem Score, mit Name, Set, Nummer und Score, damit deine Nutzer die richtige Karte von Hand wählen können, wenn der erste Treffer falsch ist.

Das vollständige Schema steht in der OpenAPI-Spezifikation und in der Dokumentation (auf Englisch).

Mehrere Karten pro Foto und Ordnerseiten

Ein Foto kann viele Pokémon-Karten enthalten: auf dem Tisch ausgelegte Karten, ein Raster oder eine ganze Ordnerseite. Jede Karte kommt als eigenes Objekt in cards zurück, mit eigener Konfidenz, und count sagt, wie viele Karten sicher erkannt wurden. Am besten klappt es mit bis zu etwa 20 Karten pro Foto bei gutem, gleichmässigem Licht. Eine harte Grenze gibt es nicht, aber mehr Karten pro Foto heisst kleinere Karten und schwierigere Erkennung. Vermeide Spiegelungen von Hüllen und Ordnertaschen.

Japanische, koreanische und chinesische Karten

Japanische, koreanische und vereinfacht chinesische Karten werden an der Karte selbst erkannt. name enthält den englischen Namen, damit du über Sprachen hinweg suchen und sortieren kannst, der Originalname kommt in name_ja, name_ko oder name_zh. Japanische Karten werden ihrem japanischen Set und Cardmarket-Produkt zugeordnet. Traditionell chinesische Karten werden noch nicht unterstützt.

Kosten, Limits und Tempo

• Ein Karten-Scan pro erkannter Karte: Eine Ordnerseite mit neun Karten braucht neun. Eine Karte, bei der sich das Modell nicht sicher ist, wird nicht berechnet, und ein Foto ganz ohne Karte gibt HTTP 422 zurück und kostet nichts.
• Der öffentliche Demo-Schlüssel erlaubt 10 Anfragen pro Tag und Netzwerk, egal wie viele Karten auf jedem Foto sind. Jede Demo-Antwort zeigt demo.remaining_today.
• Für einen eigenen Schlüssel brauchst du einen bezahlten Plan. Start-Up, der kleinste bezahlte Plan, kostet 19 pro Monat (15 pro Monat bei jährlicher Zahlung, derselbe Betrag in EUR, USD oder CHF) und enthält 1.000 Karten-Scans pro Monat, aus demselben Guthaben wie die NeoSatoshi-App. Aktuelle Pläne: Preise.
• Die Anfrage ist synchron: Eine warme Anfrage dauert etwa 5 Sekunden, eine kalte 10 bis 15 Sekunden. Setz das Timeout im Client auf 120 Sekunden.

Was die API nicht macht

• Sie bewertet keinen Zustand. Zentrierung, Ecken, Kanten und Oberfläche werden nie beurteilt; den Zustand setzt dein Nutzer.
• Sie prüft nicht, ob eine Karte echt ist.
• Sie liest keine Stempel oder anderen Sonderversionen aus dem Foto; possible_variants listet die bekannten Optionen zur Auswahl.
• Sie liest noch keine traditionell chinesischen Karten.

Häufige Fragen

Kann die API eine ganze Ordnerseite lesen?

Ja. Schick das Foto der Seite als ein Bild; jede Karte kommt als eigener Eintrag zurück. Am besten klappt es mit bis zu etwa 20 Karten pro Foto, bei gleichmässigem Licht und ohne Spiegelungen.

Welchen Cardmarket-Preis sollte ich nutzen?

trend ist der Trendpreis von Cardmarket, low das günstigste aktuelle Angebot, avg7 und avg30 die durchschnittlichen Verkaufspreise der letzten 7 und 30 Tage. Viele Verkäufer starten mit avg30, weil er weniger schwankt. Ein Wert kann 0 sein oder fehlen, wenn Cardmarket keine Daten dazu hat, nimm dann ein anderes Feld.

Wie unterscheide ich ein Reverse Holo von der normalen Karte?

Prüf reverse_holo. Auf Cardmarket ist ein Reverse Holo dasselbe Produkt wie die normale Karte, verkauft mit eigenem Reverse-Holo-Merkmal und eigenem Preis, behalte das Merkmal also beim Listen und Bepreisen.

Gibt es ein Python-Beispiel?

Ja, mit einem einzelnen Foto, einem Ordner als CSV und Fehlerbehandlung: wie du eine Kartenscanner-App baust. Für die anderen Spiele siehe die API für Magic, Lorcana, Yu-Gi-Oh! und One Piece.