# 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](https://stack.foldbun.com/console/keys) 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.

```bash
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.

```bash
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

```bash
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

```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.

```json
{
  "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](https://stack.foldbun.com/docs/billing/).

## Next steps

- [Images](https://stack.foldbun.com/docs/images/): upload an image once and reuse it in several calls.
- [Use cases](https://stack.foldbun.com/docs/#use-cases): scenarios, model choice and an example call per task.
- [Text recognition](https://stack.foldbun.com/docs/use-cases/text-recognition/): the endpoint used in this quickstart.
- [Errors](https://stack.foldbun.com/docs/errors/): handling failures and retries.