Bucepha Intelligence API

One photograph

curl -X POST https://mainbucephaai-production.up.railway.app/v1/images/process \
  -H "Authorization: Bearer $BUCEPHA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "image": {
    "url": "https://example.com/photos/front-left.jpg"
  },
  "vehicle": {
    "year": 2019,
    "make": "Honda",
    "model": "Civic"
  },
  "reference": "stock-1042"
}'

Several photographs in parallel, each its own image

curl -X POST https://mainbucephaai-production.up.railway.app/v1/images/batch \
  -H "Authorization: Bearer $BUCEPHA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "images": [
    {
      "url": "https://example.com/photos/front.jpg"
    },
    {
      "url": "https://example.com/photos/driver-side.jpg"
    },
    {
      "url": "https://example.com/photos/rear.jpg"
    }
  ],
  "vehicle": {
    "year": 2018,
    "make": "Ford",
    "model": "F-150",
    "notes": [
      "tailgate replaced"
    ]
  },
  "reference": "stock-77"
}'

Credits left

curl https://mainbucephaai-production.up.railway.app/v1/credits -H "Authorization: Bearer $BUCEPHA_API_KEY"

Node

const response = await fetch('https://mainbucephaai-production.up.railway.app/v1/images/process', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BUCEPHA_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'stock-1042-front-left', // optional: a retry returns the first image, not a second charge
  },
  body: JSON.stringify({
    image: { url: 'https://example.com/photos/front-left.jpg' },
    vehicle: { year: 2019, make: 'Honda', model: 'Civic' },
    reference: 'stock-1042',
  }),
})

let image = await response.json()
if (!response.ok) throw new Error(`${image.error.code}: ${image.error.message} (${image.error.request_id})`)

// 202 means still reading: poll until it is complete.
while (image.status === 'processing') {
  await new Promise((resolve) => setTimeout(resolve, 2000))
  image = await (
    await fetch(`https://mainbucephaai-production.up.railway.app/v1/images/${image.id}`, {
      headers: { Authorization: `Bearer ${process.env.BUCEPHA_API_KEY}` },
    })
  ).json()
}

console.log(image.status, image.credits_charged, 'credits')
for (const defect of image.result?.damage ?? []) {
  console.log(defect.area, defect.kind, defect.severity, defect.bounding_box)
}

Python

import os, time, requests

BASE = "https://mainbucephaai-production.up.railway.app/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['BUCEPHA_API_KEY']}"}

response = requests.post(
    f"{BASE}/images/process",
    headers=HEADERS,
    json={
        "image": {"url": "https://example.com/photos/front-left.jpg"},
        "vehicle": {"year": 2019, "make": "Honda", "model": "Civic"},
        "reference": "stock-1042",
    },
    timeout=60,
)
image = response.json()
if response.status_code >= 400:
    raise SystemExit(f"{image['error']['code']}: {image['error']['message']} ({image['error']['request_id']})")

while image["status"] == "processing":  # 202: still reading
    time.sleep(2)
    image = requests.get(f"{BASE}/images/{image['id']}", headers=HEADERS, timeout=30).json()

print(image["status"], image["credits_charged"], "credits")
for defect in image["result"]["damage"]:
    print(defect["area"], defect["kind"], defect["severity"], defect["bounding_box"])

1. 1. Get a key, signed in. Open the account's API tab, name a key and press Create key. It is shown once; copy it then. One key per environment, so a key for your laptop and another for production, and revoking one never stops the other.
2. 2. Keep it in your environment, never in code. Two variables, in a .env file your process reads or in the host's settings:

   BUCEPHA_API_KEY=bk_live_...
   BUCEPHA_API_URL=https://mainbucephaai-production.up.railway.app/v1

   Add .env to .gitignore before the first commit. Point BUCEPHA_API_URL at a local API when developing. If a key reaches a repository, a browser bundle or a log, rotate it on the API tab.
3. 3. Every request carries the key and JSON.

   POST {BUCEPHA_API_URL}/images/process
   Authorization: Bearer {BUCEPHA_API_KEY}
   Content-Type: application/json
   Idempotency-Key: {your unique id for this attempt}   # optional
   
   { ...the JSON below... }

4. 4. From a website, call the API from your server. The browser talks to a route of your own; that route holds the key in its environment and forwards the JSON. A key in a page's JavaScript is a key everyone has.

   your page  →  your server route (has BUCEPHA_API_KEY)  →  {BUCEPHA_API_URL}/images/process
   your page  ←  the response JSON, as is, or the parts your page shows  ←

5. 5. Check the balance first, then send. GET /credits says whether a call would be accepted today, so a batch stops before the first 402 rather than after it.

{
  "image": {
    "url": "https://example.com/photos/front-left.jpg"
  },
  "vehicle": {
    "year": 2019,
    "make": "Honda",
    "model": "Civic",
    "trim": "EX",
    "body_style": "sedan",
    "color": "blue",
    "mileage": 48000,
    "mileage_unit": "mi",
    "vin": "2HGFC2F69KH512345",
    "notes": [
      "rear bumper repainted"
    ]
  },
  "reference": "stock-1042",
  "metadata": {
    "lane": 7,
    "inspector": "rk"
  }
}

{
  "image": {
    "base64": "/9j/4AAQSkZJRgABAQ...",
    "content_type": "image/jpeg"
  },
  "reference": "stock-1042"
}

{
  "id": "img_3kT9xQ2vLm8R0pZa1bYc4dEf",
  "object": "image",
  "status": "complete",
  "created_at": "2026-09-24T15:04:05.000Z",
  "completed_at": "2026-09-24T15:04:11.000Z",
  "reference": "stock-1042",
  "vehicle": {
    "year": 2019,
    "make": "Honda",
    "model": "Civic"
  },
  "metadata": {
    "lane": 7
  },
  "result": {
    "readable": true,
    "unread_reason": null,
    "viewpoint": "front left three-quarter",
    "confidence": {
      "percent": 82,
      "band": "high"
    },
    "overall_damage": "moderate",
    "damage": [
      {
        "area": "front_bumper",
        "kind": "scratch",
        "severity": "moderate",
        "confidence": 0.86,
        "description": "Scuffing across the lower left corner of the bumper cover.",
        "bounding_box": {
          "x": 0.12,
          "y": 0.61,
          "width": 0.2,
          "height": 0.09
        },
        "point": {
          "x": 0.2,
          "y": 0.65
        }
      }
    ],
    "panels_visible": [
      "front_bumper",
      "hood",
      "driver_front_door",
      "wheels"
    ],
    "estimated_repair": {
      "low": 280,
      "high": 520,
      "currency": "USD"
    }
  },
  "credits_charged": 5,
  "demonstration": false
}

{
  "images": [
    {
      "url": "https://example.com/photos/front.jpg"
    },
    {
      "url": "https://example.com/photos/driver-side.jpg"
    },
    {
      "base64": "/9j/4AAQSkZJRgABAQ...",
      "content_type": "image/jpeg"
    }
  ],
  "vehicle": {
    "year": 2018,
    "make": "Ford",
    "model": "F-150",
    "notes": [
      "tailgate replaced"
    ]
  },
  "reference": "stock-77",
  "metadata": {
    "lot": "B-12"
  }
}

{
  "object": "batch",
  "data": [
    {
      "index": 0,
      "image": {
        "...": "an image, as above"
      },
      "error": null
    },
    {
      "index": 1,
      "image": {
        "...": "an image, as above"
      },
      "error": null
    },
    {
      "index": 2,
      "image": null,
      "error": {
        "code": "insufficient_credits",
        "message": "Not enough credits to process an image. Top up to continue."
      }
    }
  ],
  "images_sent": 3,
  "images_read": 2,
  "images_unread": 0,
  "images_processing": 0,
  "images_refused": 1,
  "credits_charged": 10
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "The request is not valid. See details for what to correct.",
    "request_id": "req_Zm9vYmFyYmF6cXV4",
    "param": "vehicle.year",
    "details": [
      {
        "field": "vehicle.year",
        "message": "Too small: expected number to be >=1900"
      }
    ]
  }
}

Response

{
  "id": "img_3kT9xQ2vLm8R0pZa1bYc4dEf",
  "object": "image",
  "status": "complete",
  "created_at": "2026-09-24T15:04:05.000Z",
  "completed_at": "2026-09-24T15:04:11.000Z",
  "reference": "stock-1042",
  "vehicle": {
    "year": 2019,
    "make": "Honda",
    "model": "Civic"
  },
  "metadata": {
    "lane": 7
  },
  "result": {
    "readable": true,
    "unread_reason": null,
    "viewpoint": "front left three-quarter",
    "confidence": {
      "percent": 82,
      "band": "high"
    },
    "overall_damage": "moderate",
    "damage": [
      {
        "area": "front_bumper",
        "kind": "scratch",
        "severity": "moderate",
        "confidence": 0.86,
        "description": "Scuffing across the lower left corner of the bumper cover.",
        "bounding_box": {
          "x": 0.12,
          "y": 0.61,
          "width": 0.2,
          "height": 0.09
        },
        "point": {
          "x": 0.2,
          "y": 0.65
        }
      }
    ],
    "panels_visible": [
      "front_bumper",
      "hood",
      "driver_front_door",
      "wheels"
    ],
    "estimated_repair": {
      "low": 280,
      "high": 520,
      "currency": "USD"
    }
  },
  "credits_charged": 5,
  "demonstration": false
}

Response

{
  "object": "batch",
  "data": [
    {
      "index": 0,
      "image": {
        "...": "an image, as above"
      },
      "error": null
    },
    {
      "index": 1,
      "image": {
        "...": "an image, as above"
      },
      "error": null
    },
    {
      "index": 2,
      "image": null,
      "error": {
        "code": "insufficient_credits",
        "message": "Not enough credits to process an image. Top up to continue."
      }
    }
  ],
  "images_sent": 3,
  "images_read": 2,
  "images_unread": 0,
  "images_processing": 0,
  "images_refused": 1,
  "credits_charged": 10
}

Response

{
  "object": "credits",
  "credits_remaining": 1240,
  "credits_per_image": 5,
  "images_remaining": 248,
  "credits_used_this_period": 260,
  "period_starts_at": "2026-09-10T14:02:11.000Z",
  "period_ends_at": "2026-10-10T14:02:11.000Z",
  "can_process": true
}

Response

{
  "object": "usage",
  "period": {
    "starts_at": "2026-09-10T14:02:11.000Z",
    "ends_at": "2026-10-10T14:02:11.000Z"
  },
  "requests": 52,
  "images_processed": 52,
  "credits_used": 260,
  "credits_remaining": 1240,
  "images_remaining": 248
}

area Where on the car. unknown when the model could not place it.

• front_bumper
• rear_bumper
• hood
• roof
• driver_front_door
• driver_rear_door
• passenger_front_door
• passenger_rear_door
• driver_quarter_panel
• passenger_quarter_panel
• wheels
• glass
• lights
• interior
• engine_bay
• undercarriage
• unknown

kind What the defect is.

• dent
• scratch
• paint_mismatch
• panel_gap
• rust
• crack
• missing_part
• tire_wear
• glass_damage
• interior_wear
• other

severity How bad, in the same four words everywhere. none is a photograph with nothing found.

• none
• minor
• moderate
• severe

Canvas

// The photograph drawn at any size; the coordinates are fractions of it.
const scaleX = canvas.width
const scaleY = canvas.height
for (const defect of image.result.damage) {
  const box = defect.bounding_box
  if (box) ctx.strokeRect(box.x * scaleX, box.y * scaleY, box.width * scaleX, box.height * scaleY)
  const point = defect.point ?? (box && { x: box.x + box.width / 2, y: box.y + box.height / 2 })
  if (point) ctx.fillText(defect.kind, point.x * scaleX, point.y * scaleY)
}

An error

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "The request is not valid. See details for what to correct.",
    "request_id": "req_Zm9vYmFyYmF6cXV4",
    "param": "vehicle.year",
    "details": [
      {
        "field": "vehicle.year",
        "message": "Too small: expected number to be >=1900"
      }
    ]
  }
}