Open API

Image OCR API Docs

The docs are public, but image OCR calls are reserved for professional-tier members. The current flow supports local uploads, remote image URLs, and work URLs, then returns a shared polling path for every task.

POST /api/open/image/extractGET /api/open/video/queryGET /api/public/runtime-healthPOST /api/open/video/extract

Image OCR access is for professional-tier members

You can inspect the fields and flow publicly first, but live requests still enforce account checks, API credentials, rate limits, and OCR quota.

API Key / Secret pairs can only be created or deleted after sign-in.

Image OCR consumes quota by the number of successfully processed images.

Invalid credentials, exhausted quota, or unauthorized access return 401 / 403 responses.

Create and manage API keys

After sign-in, use the My API page to create Key / Secret pairs, review plan entitlements, filter request logs, and manage integration records.

Each Key is paired with one Secret that is fully shown only once at creation time.

Store credentials on the server side only, never in browser code or public repos.

Image OCR, video extraction, and AI rewrite all reuse the same polling and management flow.

Python Example Download

Download a runnable Python sample package with local upload, remote image list, and workUrl OCR examples for the current deployment API.

Download Python ZIP

My API

Review public plan entitlements and the sign-in path first, then create keys, inspect quota, and manage request logs.

Video Copy API Docs

If you need public video or post URL extraction instead, continue to the video copy API docs.

Local runtime preflight

If you plan to upload local images, review the runtime preflight guide first so you can confirm OCR and Whisper dependencies on the current instance.

Access and limits

The docs are public, but real OCR requests still validate the account, API credentials, rate limits, and OCR quota.

API Key / Secret pairs can only be created or deleted after sign-in.

Image OCR checks the account's monthly OCR quota for real and returns 403 when credits are exhausted.

Open API requests still follow the current plan's per-minute rate limit.

If your flow includes local image uploads, call `GET /api/public/runtime-health` first so you can verify that RapidOCR is ready on the current machine.

Base Information

Replace the sample origin below with the real domain of your self-hosted deployment.

Base URL: `https://your-open-instance.example.com`

Image OCR upload: `POST /api/open/image/extract`

Shared task polling: `GET /api/open/video/query`

Public runtime preflight: `GET /api/public/runtime-health`

The current API supports local uploads, remote `imageUrls` list OCR, and `workUrl` parsing before OCR runs against the resolved images.

Authentication And Request Headers

Use `FormData` for local uploads. Use JSON for `imageUrl`, `imageUrls`, and `workUrl`. The authentication headers stay the same in every mode.

x-api-key

YOUR_API_KEY

The Key created from the signed-in My API page.

x-api-secret

YOUR_API_SECRET

The Secret paired with that Key and fully shown only when it is created.

Content-Type

multipart/form-data | application/json

Let the client or SDK generate the `FormData` boundary for local uploads, or switch to JSON when sending a remote `imageUrl`.

Local Runtime Health

This live panel reads the current instance through `GET /api/public/runtime-health`, so you can verify RapidOCR and the local Whisper runtime before wiring image uploads into the same deployment.

Loading the local runtime health status...

Runtime Repair Toolkit

Download a runnable toolkit for `GET /api/public/runtime-health`, `WHISPER_MODEL` checks, and local Whisper cache warmup, especially for `cache-required` and cached snapshot folder errors.

Download Runtime Toolkit ZIP

POST /api/open/image/extract

You can upload a local image file, submit remote `imageUrl` / `imageUrls`, or pass a `workUrl` so the server resolves the images from that public page first. Every mode eventually enters the same `image-extract` OCR task flow.

# curl: upload a local image
curl -X POST "https://your-open-instance.example.com/api/open/image/extract" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -F "file=@./sample-ocr.png;type=image/png" \
  -F "locale=en"

# curl: submit one remote image URL
curl -X POST "https://your-open-instance.example.com/api/open/image/extract" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "imageUrl",
    "imageUrl": "https://cdn.example.com/sample-ocr.png",
    "locale": "en"
  }'

# curl: submit a remote image URL list
curl -X POST "https://your-open-instance.example.com/api/open/image/extract" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "imageUrl",
    "imageUrls": [
      "https://cdn.example.com/sample-ocr-1.png",
      "https://cdn.example.com/sample-ocr-2.png"
    ],
    "locale": "en"
  }'

# curl: submit a workUrl
curl -X POST "https://your-open-instance.example.com/api/open/image/extract" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "workUrl",
    "workUrl": "https://www.example.com/posts/123456",
    "locale": "en"
  }'

GET /api/open/video/query

Image OCR reuses the same `GET /api/open/video/query` endpoint as URL extraction. Once you have a `taskId`, polling works the same way.

curl "https://your-open-instance.example.com/api/open/video/query?taskId=YOUR_TASK_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET"

GET /api/public/runtime-health

This public preflight endpoint does not require API credentials. Whenever your page flow or script is about to upload local images, read `imageOcr` and `localTranscription` here first, then use `cacheLookupScopes` and `nextSteps` to verify RapidOCR, Whisper cache, the `WHISPER_MODEL` path, the `WHISPER_ALLOW_DOWNLOAD` switch, and ffmpeg before the upload starts.

curl "https://your-open-instance.example.com/api/public/runtime-health"

{
  "msg": "操作成功",
  "code": 200,
  "data": {
    "checkedAt": "2026-07-18T15:41:52.660Z",
    "localTranscription": {
      "ready": false,
      "dependencyStatus": "ready",
      "ffmpegStatus": "ready",
      "whisperReadiness": "cache-required",
      "allowDownload": false,
      "model": "small",
      "source": "huggingface-cache",
      "cacheLookupScopes": [
        "HOME_CACHE_HUGGINGFACE_HUB",
        "LOCALAPPDATA_HUGGINGFACE_HUB"
      ],
      "nextSteps": [
        {
          "code": "prepare-local-whisper-model",
          "severity": "critical",
          "commands": [
            "python -c \"from huggingface_hub import snapshot_download; snapshot_download(repo_id='Systran/faster-whisper-small')\"",
            "python -c \"from faster_whisper import WhisperModel; WhisperModel('small', device='cpu', compute_type='int8', local_files_only=True)\"",
            "curl \"<部署地址>/api/public/runtime-health\""
          ]
        }
      ]
    },
    "imageOcr": {
      "ready": true,
      "dependencyStatus": "ready",
      "nextSteps": []
    }
  }
}

curl / TypeScript / Python Examples

These snippets cover local uploads, remote image URL lists, `workUrl`, polling, and the minimum field access pattern for a successful OCR task.

# TypeScript: submit a remote image URL list and poll the aggregated result
const createResponse = await fetch("https://your-open-instance.example.com/api/open/image/extract", {
  method: "POST",
  headers: {
    "x-api-key": process.env.ATC_API_KEY!,
    "x-api-secret": process.env.ATC_API_SECRET!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "imageUrl",
    imageUrls: [
      "https://cdn.example.com/sample-ocr-1.png",
      "https://cdn.example.com/sample-ocr-2.png",
    ],
    locale: "en",
  }),
});
const createPayload = await createResponse.json();
const taskId = createPayload.data.taskId;

let queryPayload = null;
for (let attempt = 0; attempt < 20; attempt += 1) {
  const queryResponse = await fetch(
    "https://your-open-instance.example.com/api/open/video/query?taskId=" + encodeURIComponent(taskId),
    {
      headers: {
        "x-api-key": process.env.ATC_API_KEY!,
        "x-api-secret": process.env.ATC_API_SECRET!,
      },
    },
  );
  queryPayload = await queryResponse.json();
  if (queryPayload.data?.status === "SUCCESS" || queryPayload.data?.status === "FAILURE") {
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 3000));
}

const batchItems = Array.isArray(queryPayload?.data?.batchItems) ? queryPayload.data.batchItems : [];
const successfulItems = batchItems.filter((item) => item.status === "SUCCESS");
console.log(queryPayload?.data?.textContent ?? "");
console.log(successfulItems.map((item) => item.cover));

# Python: submit a workUrl and read the OCR batch result
import requests
import time

headers = {
    "x-api-key": "YOUR_API_KEY",
    "x-api-secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
}

create_response = requests.post(
    "https://your-open-instance.example.com/api/open/image/extract",
    headers=headers,
    json={
        "type": "workUrl",
        "workUrl": "https://www.example.com/posts/123456",
        "locale": "en",
    },
    timeout=30,
)

task_id = create_response.json()["data"]["taskId"]
query_payload = None
for _ in range(20):
    query_response = requests.get(
        "https://your-open-instance.example.com/api/open/video/query",
        headers=headers,
        params={"taskId": task_id},
        timeout=30,
    )
    query_payload = query_response.json()
    if query_payload["data"]["status"] in ("SUCCESS", "FAILURE"):
        break
    time.sleep(3)

batch_items = query_payload["data"].get("batchItems") or []
print(query_payload["data"].get("textContent", ""))
print(len(batch_items))
print(query_payload["data"].get("meta", {}).get("ocrCountUsed"))

Request Fields

file

File

Conditionally required for local-upload mode. The current public API handles one uploaded file per request and applies a hard 15 MB limit per image.

type

String

Optional. In JSON mode, explicitly sending `imageUrl` or `workUrl` makes the intent clearer for your integration.

imageUrl

String

Conditionally required in single-image JSON mode. Submit one publicly reachable remote image URL.

imageUrls

Array<String>

Conditionally required in multi-image JSON mode. Submit one or more publicly reachable remote image URLs.

workUrl

String

Conditionally required in work-link mode. Submit a publicly reachable post or content URL and the server will resolve image assets before OCR.

locale

String

Optional. Preferred message locale. Supports `zh-CN`, `zh-TW`, and `en`.

x-api-key

Header

Required. The API Key created after sign-in.

x-api-secret

Header

Required. The Secret paired with that API Key.

Suggested Call Flow

1. Create an API Key / Secret from a signed-in account first.

2. Call `POST /api/open/image/extract` with a local upload, an `imageUrls` list, or a `workUrl`, then store the returned `taskId`.

3. Poll `GET /api/open/video/query` every 3 to 5 seconds until the task reaches `SUCCESS` or `FAILURE`.

4. After success, read `textContent`, `cover`, `imageUrlList`, `batchItems`, `meta.ocrCountUsed`, and `meta.imageOcrSourceType`.

Response Status Codes

200

Task creation succeeded, or task polling succeeded and returned the current state.

400

The uploaded file was missing, exceeded the size limit, or the upload payload was malformed.

401

API credentials are missing, or the API Key / Secret pair is invalid.

403

Monthly OCR credits are exhausted, or the task does not belong to the current account.

404

The requested task does not exist, or it has already been deleted.

429

Open API requests are too frequent and exceed the current plan's per-minute limit.

Task States

WAITING

The image task has been created and is still queued.

RUNNING

The OCR worker is already processing the file. Keep polling.

SUCCESS

OCR completed successfully and the result fields can be consumed.

FAILURE

OCR failed. Inspect `errorMessage` together with the original file.

Core Response Fields

data.taskId

String

The unique task identifier returned by both creation and query endpoints.

data.status

String

Shared task state: `WAITING`, `RUNNING`, `SUCCESS`, or `FAILURE`.

data.kind

String

The original task kind that was actually stored when the task was created.

data.displayKind

String

The effective display kind after result resolution. Image OCR tasks currently return `image-extract` here.

data.displayKindTitle

String

The localized task-kind title for the current response language, ready to show in your UI.

data.textContent

String

The main OCR text extracted by RapidOCR.

data.imageUrlList

Array<String>

Accessible file URLs for the OCR source images. Multi-image tasks return multiple previews.

data.cover

String

Usually the same image preview URL, useful for showing the OCR source directly.

data.localFiles

Array<String>

Safe basenames only; absolute server paths are never exposed.

data.batchItems

Array<Object>

When `imageUrls` or `workUrl` produces an aggregated OCR task, each image result is returned here.

data.platform

String

Local uploads are usually `local-image`; remote list mode is `remote-image`; `workUrl` tries to keep the upstream platform label.

data.workType

String

Currently fixed to `image`.

data.meta.ocrEngine

String

Currently defaults to `RapidOCR`.

data.meta.originalFileName

String

The original uploaded filename for UI echo-back or audit needs.

data.meta.imageOcrSourceType

String

The OCR source type for this task: `upload`, `image-url`, or `work-url`.

data.meta.ocrCountUsed

Number

The real OCR quota consumed by this task, accumulated by the number of successfully processed images.

data.errorMessage

String

Human-readable status text or failure reason. Start troubleshooting here.

data.runtimeRepairActions

Array<Object>

Optional. If the queried task is blocked by a local Whisper runtime problem such as a missing cache, model path, or dependency, the response also carries the help anchor and the runtime-toolkit download entry so your client can surface direct repair steps.

Image OCR Success Response Example

When an image OCR task finishes, the shared query endpoint returns a payload like this:

{
  "msg": "Success",
  "code": 200,
  "data": {
    "taskId": "c32fce2c-bc94-46e6-a91f-9f4636444d7e",
    "kind": "image-extract",
    "displayKind": "image-extract",
    "displayKindTitle": "Image Copy Extraction Tool",
    "title": "Remote Image OCR (2 images)",
    "content": "https://cdn.example.com/sample-ocr-1.png\nhttps://cdn.example.com/sample-ocr-2.png",
    "textContent": "#1 [SUCCESS] Image Item 1\nOpen\nOCR\nTask 123\n\n#2 [SUCCESS] Image Item 2\nOpen\nOCR\nTask 123",
    "videoUrlList": [],
    "imageUrlList": [
      "https://your-open-instance.example.com/api/files/c32fce2c-bc94-46e6-a91f-9f4636444d7e-img-1/sample-ocr-1.png?ownerTaskId=c32fce2c-bc94-46e6-a91f-9f4636444d7e",
      "https://your-open-instance.example.com/api/files/c32fce2c-bc94-46e6-a91f-9f4636444d7e-img-2/sample-ocr-2.png?ownerTaskId=c32fce2c-bc94-46e6-a91f-9f4636444d7e"
    ],
    "cover": "https://your-open-instance.example.com/api/files/c32fce2c-bc94-46e6-a91f-9f4636444d7e-img-1/sample-ocr-1.png?ownerTaskId=c32fce2c-bc94-46e6-a91f-9f4636444d7e",
    "platform": "remote-image",
    "workType": "image",
    "status": "SUCCESS",
    "errorMessage": "Task completed successfully",
    "createTime": "2026-07-16T12:00:00.000Z",
    "sourceUrl": "https://cdn.example.com/sample-ocr-1.png",
    "batchItems": [
      {
        "taskId": "c32fce2c-bc94-46e6-a91f-9f4636444d7e-img-1",
        "title": "Image Item 1",
        "content": "",
        "textContent": "Open\nOCR\nTask 123",
        "videoUrlList": [],
        "imageUrlList": [
          "https://your-open-instance.example.com/api/files/c32fce2c-bc94-46e6-a91f-9f4636444d7e-img-1/sample-ocr-1.png?ownerTaskId=c32fce2c-bc94-46e6-a91f-9f4636444d7e"
        ],
        "localFiles": ["sample-ocr-1.png"],
        "cover": "https://your-open-instance.example.com/api/files/c32fce2c-bc94-46e6-a91f-9f4636444d7e-img-1/sample-ocr-1.png?ownerTaskId=c32fce2c-bc94-46e6-a91f-9f4636444d7e",
        "platform": "remote-image",
        "workType": "image",
        "status": "SUCCESS",
        "errorMessage": "Task completed successfully",
        "createTime": "2026-07-16T12:00:00.000Z",
        "sourceUrl": "https://cdn.example.com/sample-ocr-1.png",
        "meta": {
          "ocrEngine": "RapidOCR",
          "ocrLineCount": 3,
          "originalFileName": "sample-ocr-1.png",
          "imageOcrSourceType": "image-url",
          "batchIndex": 1
        }
      },
      {
        "taskId": "c32fce2c-bc94-46e6-a91f-9f4636444d7e-img-2",
        "title": "Image Item 2",
        "content": "",
        "textContent": "Open\nOCR\nTask 123",
        "videoUrlList": [],
        "imageUrlList": [
          "https://your-open-instance.example.com/api/files/c32fce2c-bc94-46e6-a91f-9f4636444d7e-img-2/sample-ocr-2.png?ownerTaskId=c32fce2c-bc94-46e6-a91f-9f4636444d7e"
        ],
        "localFiles": ["sample-ocr-2.png"],
        "cover": "https://your-open-instance.example.com/api/files/c32fce2c-bc94-46e6-a91f-9f4636444d7e-img-2/sample-ocr-2.png?ownerTaskId=c32fce2c-bc94-46e6-a91f-9f4636444d7e",
        "platform": "remote-image",
        "workType": "image",
        "status": "SUCCESS",
        "errorMessage": "Task completed successfully",
        "createTime": "2026-07-16T12:00:00.000Z",
        "sourceUrl": "https://cdn.example.com/sample-ocr-2.png",
        "meta": {
          "ocrEngine": "RapidOCR",
          "ocrLineCount": 3,
          "originalFileName": "sample-ocr-2.png",
          "imageOcrSourceType": "image-url",
          "batchIndex": 2
        }
      }
    ],
    "meta": {
      "imageOcrSourceType": "image-url",
      "requestedImageCount": 2,
      "successCount": 2,
      "failureCount": 0,
      "ocrCountUsed": 2,
      "sourceUrlCount": 2
    }
  }
}

Business Rules And Notes

0. If your flow uses local image uploads, query `GET /api/public/runtime-health` first so you do not finish uploading files before discovering that RapidOCR is still unavailable on the current instance.

1. The public image OCR API supports local uploads, `imageUrls` lists, and `workUrl` image resolution. `batchItems` expands one child result per processed image.

2. Both local uploads and remote images are limited to 15 MB per image. Remote images are downloaded locally before OCR, and only `http` / `https` URLs are accepted.

3. `workUrl` depends on the open-source URL extraction pipeline to resolve image assets first. If the public page exposes no recognizable images, the task fails.

4. Image OCR validates the account's OCR quota for real. Remote lists and `workUrl` consume quota by the number of successfully processed images.

5. `localFiles` only contains safe filenames and never exposes absolute server paths. Aggregated task files are attached to child results inside `batchItems`.

6. This page documents the real endpoints already available on the site, and the downloadable example ZIP can be wired up directly after you replace the credentials.

7. Image OCR and local video / audio transcription share the same polling endpoint. When the returned task is actually blocked by the local Whisper runtime, the payload now also includes `runtimeRepairActions` so your own client can surface the help entry and toolkit download immediately.

Image OCR API Docs

POST /api/open/image/extractGET /api/open/video/queryGET /api/public/runtime-healthPOST /api/open/video/extract

Image OCR access is for professional-tier members

You can inspect the fields and flow publicly first, but live requests still enforce account checks, API credentials, rate limits, and OCR quota.

API Key / Secret pairs can only be created or deleted after sign-in.

Image OCR consumes quota by the number of successfully processed images.

Invalid credentials, exhausted quota, or unauthorized access return 401 / 403 responses.

Create and manage API keys

After sign-in, use the My API page to create Key / Secret pairs, review plan entitlements, filter request logs, and manage integration records.

Each Key is paired with one Secret that is fully shown only once at creation time.

Store credentials on the server side only, never in browser code or public repos.

Image OCR, video extraction, and AI rewrite all reuse the same polling and management flow.

Python Example Download

Download a runnable Python sample package with local upload, remote image list, and workUrl OCR examples for the current deployment API.

Download Python ZIP

Access and limits

The docs are public, but real OCR requests still validate the account, API credentials, rate limits, and OCR quota.

API Key / Secret pairs can only be created or deleted after sign-in.

Image OCR checks the account's monthly OCR quota for real and returns 403 when credits are exhausted.

Open API requests still follow the current plan's per-minute rate limit.

If your flow includes local image uploads, call `GET /api/public/runtime-health` first so you can verify that RapidOCR is ready on the current machine.

Base Information

Replace the sample origin below with the real domain of your self-hosted deployment.

Base URL: `https://your-open-instance.example.com`

Image OCR upload: `POST /api/open/image/extract`

Shared task polling: `GET /api/open/video/query`

Public runtime preflight: `GET /api/public/runtime-health`

The current API supports local uploads, remote `imageUrls` list OCR, and `workUrl` parsing before OCR runs against the resolved images.

Authentication And Request Headers

Use `FormData` for local uploads. Use JSON for `imageUrl`, `imageUrls`, and `workUrl`. The authentication headers stay the same in every mode.

x-api-key

YOUR_API_KEY

The Key created from the signed-in My API page.

x-api-secret

YOUR_API_SECRET

The Secret paired with that Key and fully shown only when it is created.

Content-Type

multipart/form-data | application/json

Let the client or SDK generate the `FormData` boundary for local uploads, or switch to JSON when sending a remote `imageUrl`.

Local Runtime Health

This live panel reads the current instance through `GET /api/public/runtime-health`, so you can verify RapidOCR and the local Whisper runtime before wiring image uploads into the same deployment.

Loading the local runtime health status...

Runtime Repair Toolkit

Download a runnable toolkit for `GET /api/public/runtime-health`, `WHISPER_MODEL` checks, and local Whisper cache warmup, especially for `cache-required` and cached snapshot folder errors.

Download Runtime Toolkit ZIP

POST /api/open/image/extract

# curl: upload a local image
curl -X POST "https://your-open-instance.example.com/api/open/image/extract" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -F "file=@./sample-ocr.png;type=image/png" \
  -F "locale=en"

# curl: submit one remote image URL
curl -X POST "https://your-open-instance.example.com/api/open/image/extract" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "imageUrl",
    "imageUrl": "https://cdn.example.com/sample-ocr.png",
    "locale": "en"
  }'

# curl: submit a remote image URL list
curl -X POST "https://your-open-instance.example.com/api/open/image/extract" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "imageUrl",
    "imageUrls": [
      "https://cdn.example.com/sample-ocr-1.png",
      "https://cdn.example.com/sample-ocr-2.png"
    ],
    "locale": "en"
  }'

# curl: submit a workUrl
curl -X POST "https://your-open-instance.example.com/api/open/image/extract" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "workUrl",
    "workUrl": "https://www.example.com/posts/123456",
    "locale": "en"
  }'

GET /api/open/video/query

Image OCR reuses the same `GET /api/open/video/query` endpoint as URL extraction. Once you have a `taskId`, polling works the same way.

curl "https://your-open-instance.example.com/api/open/video/query?taskId=YOUR_TASK_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET"

GET /api/public/runtime-health

curl "https://your-open-instance.example.com/api/public/runtime-health"

{
  "msg": "操作成功",
  "code": 200,
  "data": {
    "checkedAt": "2026-07-18T15:41:52.660Z",
    "localTranscription": {
      "ready": false,
      "dependencyStatus": "ready",
      "ffmpegStatus": "ready",
      "whisperReadiness": "cache-required",
      "allowDownload": false,
      "model": "small",
      "source": "huggingface-cache",
      "cacheLookupScopes": [
        "HOME_CACHE_HUGGINGFACE_HUB",
        "LOCALAPPDATA_HUGGINGFACE_HUB"
      ],
      "nextSteps": [
        {
          "code": "prepare-local-whisper-model",
          "severity": "critical",
          "commands": [
            "python -c \"from huggingface_hub import snapshot_download; snapshot_download(repo_id='Systran/faster-whisper-small')\"",
            "python -c \"from faster_whisper import WhisperModel; WhisperModel('small', device='cpu', compute_type='int8', local_files_only=True)\"",
            "curl \"<部署地址>/api/public/runtime-health\""
          ]
        }
      ]
    },
    "imageOcr": {
      "ready": true,
      "dependencyStatus": "ready",
      "nextSteps": []
    }
  }
}

curl / TypeScript / Python Examples

These snippets cover local uploads, remote image URL lists, `workUrl`, polling, and the minimum field access pattern for a successful OCR task.

# TypeScript: submit a remote image URL list and poll the aggregated result
const createResponse = await fetch("https://your-open-instance.example.com/api/open/image/extract", {
  method: "POST",
  headers: {
    "x-api-key": process.env.ATC_API_KEY!,
    "x-api-secret": process.env.ATC_API_SECRET!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "imageUrl",
    imageUrls: [
      "https://cdn.example.com/sample-ocr-1.png",
      "https://cdn.example.com/sample-ocr-2.png",
    ],
    locale: "en",
  }),
});
const createPayload = await createResponse.json();
const taskId = createPayload.data.taskId;

let queryPayload = null;
for (let attempt = 0; attempt < 20; attempt += 1) {
  const queryResponse = await fetch(
    "https://your-open-instance.example.com/api/open/video/query?taskId=" + encodeURIComponent(taskId),
    {
      headers: {
        "x-api-key": process.env.ATC_API_KEY!,
        "x-api-secret": process.env.ATC_API_SECRET!,
      },
    },
  );
  queryPayload = await queryResponse.json();
  if (queryPayload.data?.status === "SUCCESS" || queryPayload.data?.status === "FAILURE") {
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 3000));
}

const batchItems = Array.isArray(queryPayload?.data?.batchItems) ? queryPayload.data.batchItems : [];
const successfulItems = batchItems.filter((item) => item.status === "SUCCESS");
console.log(queryPayload?.data?.textContent ?? "");
console.log(successfulItems.map((item) => item.cover));

# Python: submit a workUrl and read the OCR batch result
import requests
import time

headers = {
    "x-api-key": "YOUR_API_KEY",
    "x-api-secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
}

create_response = requests.post(
    "https://your-open-instance.example.com/api/open/image/extract",
    headers=headers,
    json={
        "type": "workUrl",
        "workUrl": "https://www.example.com/posts/123456",
        "locale": "en",
    },
    timeout=30,
)

task_id = create_response.json()["data"]["taskId"]
query_payload = None
for _ in range(20):
    query_response = requests.get(
        "https://your-open-instance.example.com/api/open/video/query",
        headers=headers,
        params={"taskId": task_id},
        timeout=30,
    )
    query_payload = query_response.json()
    if query_payload["data"]["status"] in ("SUCCESS", "FAILURE"):
        break
    time.sleep(3)

batch_items = query_payload["data"].get("batchItems") or []
print(query_payload["data"].get("textContent", ""))
print(len(batch_items))
print(query_payload["data"].get("meta", {}).get("ocrCountUsed"))

Request Fields

file

File

Conditionally required for local-upload mode. The current public API handles one uploaded file per request and applies a hard 15 MB limit per image.

type

String

Optional. In JSON mode, explicitly sending `imageUrl` or `workUrl` makes the intent clearer for your integration.

imageUrl

String

Conditionally required in single-image JSON mode. Submit one publicly reachable remote image URL.

imageUrls

Array<String>

Conditionally required in multi-image JSON mode. Submit one or more publicly reachable remote image URLs.

workUrl

String

Conditionally required in work-link mode. Submit a publicly reachable post or content URL and the server will resolve image assets before OCR.

locale

String

Optional. Preferred message locale. Supports `zh-CN`, `zh-TW`, and `en`.

x-api-key

Header

Required. The API Key created after sign-in.

x-api-secret

Header

Required. The Secret paired with that API Key.

Suggested Call Flow

1. Create an API Key / Secret from a signed-in account first.

2. Call `POST /api/open/image/extract` with a local upload, an `imageUrls` list, or a `workUrl`, then store the returned `taskId`.

3. Poll `GET /api/open/video/query` every 3 to 5 seconds until the task reaches `SUCCESS` or `FAILURE`.

4. After success, read `textContent`, `cover`, `imageUrlList`, `batchItems`, `meta.ocrCountUsed`, and `meta.imageOcrSourceType`.

Response Status Codes

200

Task creation succeeded, or task polling succeeded and returned the current state.

400

The uploaded file was missing, exceeded the size limit, or the upload payload was malformed.

401

API credentials are missing, or the API Key / Secret pair is invalid.

403

Monthly OCR credits are exhausted, or the task does not belong to the current account.

404

The requested task does not exist, or it has already been deleted.

429

Open API requests are too frequent and exceed the current plan's per-minute limit.

Task States

WAITING

The image task has been created and is still queued.

RUNNING

The OCR worker is already processing the file. Keep polling.

SUCCESS

OCR completed successfully and the result fields can be consumed.

FAILURE

OCR failed. Inspect `errorMessage` together with the original file.

Core Response Fields

data.taskId

String

The unique task identifier returned by both creation and query endpoints.

data.status

String

Shared task state: `WAITING`, `RUNNING`, `SUCCESS`, or `FAILURE`.

data.kind

String

The original task kind that was actually stored when the task was created.

data.displayKind

String

The effective display kind after result resolution. Image OCR tasks currently return `image-extract` here.

data.displayKindTitle

String

The localized task-kind title for the current response language, ready to show in your UI.

data.textContent

String

The main OCR text extracted by RapidOCR.

data.imageUrlList

Array<String>

Accessible file URLs for the OCR source images. Multi-image tasks return multiple previews.

data.cover

String

Usually the same image preview URL, useful for showing the OCR source directly.

data.localFiles

Array<String>

Safe basenames only; absolute server paths are never exposed.

data.batchItems

Array<Object>

When `imageUrls` or `workUrl` produces an aggregated OCR task, each image result is returned here.

data.platform

String

Local uploads are usually `local-image`; remote list mode is `remote-image`; `workUrl` tries to keep the upstream platform label.

data.workType

String

Currently fixed to `image`.

data.meta.ocrEngine

String

Currently defaults to `RapidOCR`.

data.meta.originalFileName

String

The original uploaded filename for UI echo-back or audit needs.

data.meta.imageOcrSourceType

String

The OCR source type for this task: `upload`, `image-url`, or `work-url`.

data.meta.ocrCountUsed

Number

The real OCR quota consumed by this task, accumulated by the number of successfully processed images.

data.errorMessage

String

Human-readable status text or failure reason. Start troubleshooting here.

data.runtimeRepairActions

Array<Object>

Image OCR Success Response Example

When an image OCR task finishes, the shared query endpoint returns a payload like this:

{
  "msg": "Success",
  "code": 200,
  "data": {
    "taskId": "c32fce2c-bc94-46e6-a91f-9f4636444d7e",
    "kind": "image-extract",
    "displayKind": "image-extract",
    "displayKindTitle": "Image Copy Extraction Tool",
    "title": "Remote Image OCR (2 images)",
    "content": "https://cdn.example.com/sample-ocr-1.png\nhttps://cdn.example.com/sample-ocr-2.png",
    "textContent": "#1 [SUCCESS] Image Item 1\nOpen\nOCR\nTask 123\n\n#2 [SUCCESS] Image Item 2\nOpen\nOCR\nTask 123",
    "videoUrlList": [],
    "imageUrlList": [
      "https://your-open-instance.example.com/api/files/c32fce2c-bc94-46e6-a91f-9f4636444d7e-img-1/sample-ocr-1.png?ownerTaskId=c32fce2c-bc94-46e6-a91f-9f4636444d7e",
      "https://your-open-instance.example.com/api/files/c32fce2c-bc94-46e6-a91f-9f4636444d7e-img-2/sample-ocr-2.png?ownerTaskId=c32fce2c-bc94-46e6-a91f-9f4636444d7e"
    ],
    "cover": "https://your-open-instance.example.com/api/files/c32fce2c-bc94-46e6-a91f-9f4636444d7e-img-1/sample-ocr-1.png?ownerTaskId=c32fce2c-bc94-46e6-a91f-9f4636444d7e",
    "platform": "remote-image",
    "workType": "image",
    "status": "SUCCESS",
    "errorMessage": "Task completed successfully",
    "createTime": "2026-07-16T12:00:00.000Z",
    "sourceUrl": "https://cdn.example.com/sample-ocr-1.png",
    "batchItems": [
      {
        "taskId": "c32fce2c-bc94-46e6-a91f-9f4636444d7e-img-1",
        "title": "Image Item 1",
        "content": "",
        "textContent": "Open\nOCR\nTask 123",
        "videoUrlList": [],
        "imageUrlList": [
          "https://your-open-instance.example.com/api/files/c32fce2c-bc94-46e6-a91f-9f4636444d7e-img-1/sample-ocr-1.png?ownerTaskId=c32fce2c-bc94-46e6-a91f-9f4636444d7e"
        ],
        "localFiles": ["sample-ocr-1.png"],
        "cover": "https://your-open-instance.example.com/api/files/c32fce2c-bc94-46e6-a91f-9f4636444d7e-img-1/sample-ocr-1.png?ownerTaskId=c32fce2c-bc94-46e6-a91f-9f4636444d7e",
        "platform": "remote-image",
        "workType": "image",
        "status": "SUCCESS",
        "errorMessage": "Task completed successfully",
        "createTime": "2026-07-16T12:00:00.000Z",
        "sourceUrl": "https://cdn.example.com/sample-ocr-1.png",
        "meta": {
          "ocrEngine": "RapidOCR",
          "ocrLineCount": 3,
          "originalFileName": "sample-ocr-1.png",
          "imageOcrSourceType": "image-url",
          "batchIndex": 1
        }
      },
      {
        "taskId": "c32fce2c-bc94-46e6-a91f-9f4636444d7e-img-2",
        "title": "Image Item 2",
        "content": "",
        "textContent": "Open\nOCR\nTask 123",
        "videoUrlList": [],
        "imageUrlList": [
          "https://your-open-instance.example.com/api/files/c32fce2c-bc94-46e6-a91f-9f4636444d7e-img-2/sample-ocr-2.png?ownerTaskId=c32fce2c-bc94-46e6-a91f-9f4636444d7e"
        ],
        "localFiles": ["sample-ocr-2.png"],
        "cover": "https://your-open-instance.example.com/api/files/c32fce2c-bc94-46e6-a91f-9f4636444d7e-img-2/sample-ocr-2.png?ownerTaskId=c32fce2c-bc94-46e6-a91f-9f4636444d7e",
        "platform": "remote-image",
        "workType": "image",
        "status": "SUCCESS",
        "errorMessage": "Task completed successfully",
        "createTime": "2026-07-16T12:00:00.000Z",
        "sourceUrl": "https://cdn.example.com/sample-ocr-2.png",
        "meta": {
          "ocrEngine": "RapidOCR",
          "ocrLineCount": 3,
          "originalFileName": "sample-ocr-2.png",
          "imageOcrSourceType": "image-url",
          "batchIndex": 2
        }
      }
    ],
    "meta": {
      "imageOcrSourceType": "image-url",
      "requestedImageCount": 2,
      "successCount": 2,
      "failureCount": 0,
      "ocrCountUsed": 2,
      "sourceUrlCount": 2
    }
  }
}

Business Rules And Notes

1. The public image OCR API supports local uploads, `imageUrls` lists, and `workUrl` image resolution. `batchItems` expands one child result per processed image.

2. Both local uploads and remote images are limited to 15 MB per image. Remote images are downloaded locally before OCR, and only `http` / `https` URLs are accepted.

3. `workUrl` depends on the open-source URL extraction pipeline to resolve image assets first. If the public page exposes no recognizable images, the task fails.

4. Image OCR validates the account's OCR quota for real. Remote lists and `workUrl` consume quota by the number of successfully processed images.

5. `localFiles` only contains safe filenames and never exposes absolute server paths. Aggregated task files are attached to child results inside `batchItems`.

6. This page documents the real endpoints already available on the site, and the downloadable example ZIP can be wired up directly after you replace the credentials.