Quickstart

This page creates an API key and sends a text recognition request with ppocr-v6, a model that every registered account can call.

Create an API key

1. Open the console and sign in. A new account must verify an email address first; until then, calls fail with 403 email_unverified.
2. Open API keys and select Create key.
3. Enter a name, then choose an expiration (never, 7, 30 or 90 days, 1 year, or a custom date) and a model scope (all models or selected models).
4. Copy the secret and store it securely. The secret starts with fbs_ and is shown only once.

Store the key in an environment variable. Keys never belong in client-side code or in a repository.

export FOLDBUN_API_KEY="fbs_..."

Check the key

GET /v1/models is free and not metered. It lists the models and prices, and whether the account may use each model now.

curl https://api.stack.foldbun.com/v1/models \
  -H "Authorization: Bearer $FOLDBUN_API_KEY"

First request

JPEG, PNG and static WebP images are accepted. The image is sent inline as base64.

curl

curl https://api.stack.foldbun.com/v1/ocr \
  -H "Authorization: Bearer $FOLDBUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"image\": {\"base64\": \"$(base64 -w0 screenshot.png)\"}}"

base64 -w0 is the GNU coreutils form; it writes the encoding on a single line.

Python

import base64
import os

import requests

with open("screenshot.png", "rb") as f:
    image = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://api.stack.foldbun.com/v1/ocr",
    headers={"Authorization": f"Bearer {os.environ['FOLDBUN_API_KEY']}"},
    json={"image": {"base64": image}},
    timeout=60,
)
response.raise_for_status()
result = response.json()

for line in result["lines"]:
    print(line["text"])
print("request id:", response.headers["X-Request-Id"])

Response

The response lists the recognised lines with confidence, a bounding box and a quadrilateral, followed by the fields present in every successful inference response. The example is abridged.

{
  "id": "call_01a1913d-55cd-7bee-ba86-bbbef2aa9bae",
  "model": "ppocr-v6",
  "image": {
    "id": "img_2dedd0716bfd46ec29b286a279d18b6fc80631e5d90fedb5c63eb36f231622e6",
    "width": 1100,
    "height": 760,
    "bytes": 83478,
    "contentType": "image/jpeg"
  },
  "lines": [
    {
      "text": "Account settings",
      "confidence": 0.982,
      "bbox": [270, 33, 483, 60],
      "quad": [[270, 33], [483, 33], [483, 60], [270, 60]],
      "words": [
        { "text": "Account", "confidence": 0.982, "bbox": [279, 33, 374, 60] },
        { "text": "settings", "confidence": 0.982, "bbox": [387, 33, 478, 60] }
      ]
    }
  ],
  "cost": 0,
  "balance": 0,
  "timing": { "queueMs": 0, "processingMs": 753 },
  "billing": {
    "lines": [
      { "unit": "image", "quantity": 1, "unitPrice": 0.25, "amount": 0.25, "waived": false }
    ],
    "total": 0.25,
    "charged": false,
    "pool": "public",
    "allowance": { "used": 1, "limit": 100 }
  }
}

In the example, the call is covered by the public pool’s daily allowance, so cost is 0 and the billing lines show the list price. See Billing.

Next steps

• Images: upload an image once and reuse it in several calls.
• Use cases: scenarios, model choice and an example call per task.
• Text recognition: the endpoint used in this quickstart.
• Errors: handling failures and retries.