Quickstart

Your first scan in three steps: create a key, send a photo, read the parts.

Using an AI coding agent? Give it /llms-full.txt: the whole integration — calls, answers, errors, billing — in one plain-text file.

1. Create a key

Sign in to the console with your phone number and create a secret key under API keys. It is shown once — keep it on your server, never in a browser. New accounts start with 1,000 free credits.

2. Send a photo

curl -X POST https://spoken.fyi/api/v1/scan \
  -H "Authorization: Bearer $SPOKEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "photos": ["https://your-cdn.example/bike.jpg"] }'

The request stays open while the scan runs, about a minute. To start a scan and collect the result later, run it as a job.

3. Read the parts

{
  "build_id": "bb9ff821-1ca0-414d-8508-9f108dade19f",
  "parts": [
    {
      "index": 0,
      "brand": "Cannondale",
      "model": "SuperSix EVO LAB71 Frameset",
      "category": "frame",
      "price": 6000,
      "url": "https://…",
      "pin": { "x": 48.2, "y": 39.5 },
      "box": { "x": 25.5, "y": 23.8, "w": 52.6, "h": 51.7 }
    }
  ],
  "job": "bom",
  "credits_charged": 103
}

• • pin and box are percentages of the photo, so they land on the part at any size.
• • The build page on spoken.fyi opens for anyone with the link; the rest of Spoken is in its private beta, and the API answer is complete regardless.
• • Have the photo as a file? Ask for an upload slot first (POST /api/v1/uploads), PUT the bytes to its upload_url, then scan with its photo_url. A request carrying base64 is limited to about 4 MB; a phone photo is bigger than that.
• • Keep the build_id. Posters and films made from it later skip the identification you already paid for.