快速开始

开始使用开发者 API——获取 API 密钥、发起首次 OCR 请求，了解认证和计费方式。

前提条件

使用开发者 API 之前，您需要：

一个 Image to Text 账号
一个带有所需权限范围的 开发者 API 密钥
账号中可用的 处理积分

第一步：创建 API 密钥

前往 设置 → API 密钥，点击 创建 API 密钥。选择一个或多个权限范围：

OCR — 访问 POST /api/v1/ocr
Image — 访问 POST /api/v1/images/convert 和 POST /api/v1/images/compress

完整密钥仅在创建时显示一次，请安全保存。

重要提示： API 密钥属于服务端机密，请勿在客户端代码、公共仓库或移动应用中暴露。

第二步：发起首次请求

使用 Authorization: Bearer <key> 请求头（或 x-api-key 请求头）进行认证：

curl -X POST https://image-to-text.org/api/v1/ocr \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/sample.png",
    "mode": "formatted"
  }'

image_url 和 base64 均可通过 JSON 提交。文件上传使用 multipart/form-data：

curl -X POST https://image-to-text.org/api/v1/ocr \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "mode=formatted"

第三步：理解响应

成功的 OCR 响应如下：

{
  "success": true,
  "request_id": "abc123...",
  "elapsed_ms": 1500,
  "data": {
    "markdown": "# Document Title\n\n...",
    "text": "Document Title\n\n...",
    "pages": [...],
    "usage": {
      "credits": 10,
      "pages": 3,
      "mode": "formatted"
    }
  }
}

错误响应遵循标准格式：

{
  "success": false,
  "request_id": "abc123...",
  "error": {
    "code": "credits_insufficient",
    "message": "积分不足。此 OCR API 请求需要 10 积分。",
    "retryable": false
  }
}

认证

所有端点支持两种认证方式：

方式	请求头	示例
Bearer token	`Authorization`	`Bearer YOUR_API_KEY`
API key header	`x-api-key`	`YOUR_API_KEY`

两种方式等效，选择对您的 HTTP 客户端更方便的一种即可。

幂等性

对于计费请求，可以提供 Idempotency-Key 请求头来安全重试，避免重复扣费：

curl -X POST https://image-to-text.org/api/v1/ocr \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-key-2024-001" \
  -F "[email protected]"

幂等键有效期为 24 小时。后续使用相同键和相同输入的请求会返回缓存结果，不再扣费。

下一步

阅读 API 概述了解错误码、限流和计费
查看 OCR API 参考了解完整端点详情
查看图片处理 API 了解转换和压缩端点

快速开始

前提条件

第一步：创建 API 密钥

第二步：发起首次请求

第三步：理解响应

认证

幂等性

下一步

On this page