# 快速开始

本页创建 API 密钥，并使用所有已注册账户都可调用的 `ppocr-v6` 发送一次文字识别请求。

## 创建 API 密钥

1. 打开[控制台](https://stack.foldbun.com/console/keys)并登录。新账户需先验证邮箱；验证前，调用会返回 `403 email_unverified`。
2. 打开 **API 密钥**，选择 **创建密钥**。
3. 输入名称，然后选择有效期（永不过期、7 天、30 天、90 天、1 年或自定义日期）和模型范围（全部模型或所选模型）。
4. 复制密钥并妥善保存。密钥以 `fbs_` 开头，仅显示一次。

将密钥保存在环境变量中。密钥不应出现在客户端代码或代码仓库中。

```bash
export FOLDBUN_API_KEY="fbs_..."
```

## 检查密钥

`GET /v1/models` 免费且不计量。它列出模型、价格，以及账户当前是否可使用各模型。

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

## 第一个请求

接受 JPEG、PNG 和静态 WebP 图片。图片以 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` 为 GNU coreutils 的写法，输出为单行编码。

### 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"])
```

## 响应

响应列出识别出的文本行及其置信度、外接框和四边形，之后是每个成功推理响应都包含的字段。以下示例有删减。

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

示例中的调用由公共池的每日额度覆盖，因此 `cost` 为 0，`billing` 明细显示的是标价。详见[计费](https://stack.foldbun.com/zh/docs/billing/)。

## 后续步骤

- [图片](https://stack.foldbun.com/zh/docs/images/)：上传一次图片，并在多次调用中复用。
- [用例](https://stack.foldbun.com/zh/docs/#用例)：每个任务的场景、模型选择和调用示例。
- [文字识别](https://stack.foldbun.com/zh/docs/use-cases/text-recognition/)：本快速开始中使用的接口。
- [错误](https://stack.foldbun.com/zh/docs/errors/)：处理失败和重试。