Let's Build: Transloadit による AI 名刺スキャナー
名刺の画像や PDF から連絡先情報を抽出し、ローカルの JSON ファイルに保存します。この TypeScript のサンプルでは、名刺を一枚 Transloadit にアップロードし、AI モデルに見えている項目の抽出を依頼して結果を保存します。CRM に連絡先を追加する前に、元の名刺と比較できます。
作成するもの
- PNG/JPEG の名刺画像または PDF の受け付け
- 🤖 /image/optimize による画像の最適化。PDF は抽出用の Step に直接送信
- 🤖 /ai/chat による連絡先項目の抽出と JSON 結果のダウンロード
これはローカルで実行するコマンドラインのサンプルで、カメラアプリではありません。Transloadit Workspace の Auth Key と Auth Secret、AI 認証情報の明示的な選択、名刺を Transloadit と Anthropic に送信する許可が必要です。AI テスト認証情報を使う場合も含め、処理は課金対象です。まずは個人情報を含まない架空の名刺を使ってください。
スキーマから始める(zod)
サンプルスクリプト は businessCardSchema をエクスポートします。別の項目リストを管理せずに、同じデータ契約を再利用できます。省略可能な項目は、full_name、title、company、email、phones、address、website、socials、notes です。電話番号は文字列のまま扱うため、先頭の + が保持されます。不明な項目は省略するものとします。
以下のセットアップを終えたら、次のコードをプロジェクトディレクトリ内に
schema.ts として保存し、node schema.ts を実行すると、モデルに送信するスキーマを確認できます。
import { zodToJsonSchema } from 'zod-to-json-schema'
import { businessCardSchema } from './business-card-scanner/run.ts'
console.log(JSON.stringify(zodToJsonSchema(businessCardSchema), null, 2))
スキーマで検証できるのは項目の型であり、名前やメールアドレスの読み取りが正しいかどうかは判断できません。実行プログラムは、不正な JSON、スキーマに適合しない出力、認識対象の項目がないオブジェクトを拒否します。空でなく、スキーマに適合する結果であっても、名刺との照合が必要です。
パイプラインの概要
| 入力 | 処理経路 |
|---|---|
| PDF の名刺 | /ai/chat |
| PNG/JPEG の名刺 | /image/optimize → /ai/chat |
ファイルフィルターにより、PDF と画像を別々の経路に振り分けます。PDF フィルターの名前は pdf_verified ですが、報告された MIME タイプに基づいて選択するだけです。文書が破損していないことや、読み取り可能なことを証明するものではありません。
Assembly のコード例
アプリがエクスポートする処理設定には、フィルター、プロンプト、スキーマ、anthropic/claude-sonnet-4-6 モデルが含まれます。その Assembly Instructions を確認するには、次のコードを instructions.ts として schema.ts と同じディレクトリに保存し、node instructions.ts を実行します。
import { example } from './business-card-scanner/run.ts'
const steps = example.steps({ test_credentials: true })
console.log(JSON.stringify({ steps }, null, 2))
このコードは処理設定を表示するだけです。以下の CLI では設定を送信し、完了を待って結果をダウンロードし、検証したうえで連絡先の各項目をローカルに保存します。保持するのはローカルファイルです。処理結果の URL は一時的なものです。
サンプルアプリの実行
Node.js 26.12.1、別途インストールした
Corepack、cURL と、既存プロジェクトの外にある新しい空のディレクトリを用意します。セットアップ手順に従い、Yarn 4.12.0、@transloadit/node 4.14.0、Zod 3.25.76、zod-to-json-schema 3.25.2 をインストールし、business-card-scanner/run.ts と shared/runtime.ts の両方をダウンロードしてください。アプリが共有ランタイムをインポートするため、ディレクトリ構成はそのまま維持してください。非公開リポジトリのチェックアウトは不要です。
これらは動作確認済みのバージョンです。このサンプルでは Zod 3 とそのコンバーターを引き続き使用します。zod-to-json-schema は非推奨です。Zod 4 は JSON Schema をネイティブにサポートしています。このデータ契約のアップグレードは、アプリに対する別の変更として行います。
プログラムを実行するシェルで、次のプレースホルダーを Workspace の値に置き換えてください。
export TRANSLOADIT_AUTH_KEY='YOUR_AUTH_KEY'
export TRANSLOADIT_AUTH_SECRET='YOUR_AUTH_SECRET'
シークレットはバージョン管理やブラウザー用コードに含めないでください。プログラムはプロセスの環境変数を読み取ります。環境ファイルの読み込みや認証情報の作成は行いません。
プロジェクトディレクトリ内の card.png に名刺を配置するか、入力パスを置き換えます。まだ存在しない出力先を選び、課金対象の AI テスト認証情報の使用を明示的に許可してください。
node business-card-scanner/run.ts --input ./card.png --output ./result.json --test-credentials
または、TRANSLOADIT_AI_CREDENTIALS に既存の Anthropic の AI 認証情報の名前を設定し、--test-credentials を省略します。モードは必ずどちらか一方だけを選んでください。独自のプロバイダー認証情報を設定する方法は、アプリの実行前にセットアップ手順で確認してください。
成功したら result.json を開き、抽出された名前、メールアドレス、電話番号を名刺と比較してください。省略可能な項目は欠けていても問題ありません。アプリは入力を変更せず、処理を送信する前に既存の出力先を拒否するため、再実行時には新しい出力先を使ってください。入力とダウンロードする出力はそれぞれ 20 MiB までに制限し、処理の完了を最大五分間待ちます。結果のダウンロードには、これとは別に 30 秒の制限時間を設けています。これらはサンプルの制限であり、製品の制限ではありません。
Assembly ID が表示された後に実行が失敗した場合は、再試行する前に Console でその Assembly を確認してください。タイムアウトや中断が起きても、リモートの処理が停止したとは限らず、処理が課金されることもあります。スクリプトは Assembly を自動的に再試行しません。
入力例
名前、会社名、メールアドレス、電話番号を照合できる、読み取りやすい架空の名刺を使ってください。ファイルごとに一枚の名刺を処理します。PDF の場合は一ページから始めてください。PDF の経路を試すには、同じコマンドに PDF のファイル名を渡し、別の JSON 出力先を選びます。画像からの抽出に成功しても、特定の PDF が読み取り可能だと判断することはできません。また、画像の最適化によって認識精度の向上が保証されるわけではありません。
次のステップ
CRM に連絡先を登録する前に、抽出結果を毎回確認してください。このスキーマは信頼度スコアを返さないため、「信頼度の低い」連絡先を選別することはできません。確認後、ロケールに合わせて電話番号と住所を正規化し、CRM のルールに従って連絡先の重複を排除してください。
