API Reference v1.0

Video OCR & Entity Extraction API

SightAPI provides high-throughput developer endpoints for running frame-by-frame text extraction, bounding box detection, and timecoded metadata tracking on video files.

Manage API Keys Jump to Quickstart

Rate limits

Each API key has a token-bucket allowance of 20 requests per 10 seconds. Every authenticated response includes RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. A 429 response also includes Retry-After; wait that many seconds before retrying.

Authentication

Every API request must include your secret API key in an Authorization header formatted as Bearer <prefix>.<secret>.

HTTP Header Formathttp

Authorization: Bearer prefix_1234.secret_5678

Quickstart Workflow

4 Step Pipeline

Create Input Asset & Get Presigned Upload URL

Post video metadata to initialize an asset record and obtain a signed upload target.

1. Create Assetbash

curl -X POST https://www.sightapi.work/api/v1/assets \
  -H "Authorization: Bearer <prefix>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{"filename":"sample.mp4","content_type":"video/mp4"}'

Upload Video Payload

Upload raw video bytes directly to the returned presigned upload_url.

2. Upload Video Binarybash

curl -X PUT "<upload_url>" --upload-file sample.mp4

Choose and Dispatch a Video Operation

Select OCR, ENTITY_EXTRACTION, OCR_RENDER, or ENTITY_RENDER.

3. Create Jobbash

curl -X POST https://www.sightapi.work/api/v1/jobs \
  -H "Authorization: Bearer <prefix>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "input_asset_id":"123e4567-e89b-12d3-a456-426614174000",
    "operation":"ENTITY_RENDER",
    "entities":["EMAIL","PERSON"],
    "render":{"type":"redact","blur_strength":75},
    "idempotency_key":"sample-upload-1"
  }'

Fetch Frame OCR & Bounding Box Output

JSON operations return only their requested tracks. Render operations return a hardware-encoded MP4.

4. Get Job Resultsbash

curl -X GET https://www.sightapi.work/api/v1/jobs/<job_id>/result \
  -H "Authorization: Bearer <prefix>.<secret>"

Supported entity categories

The entities array accepts only the 10 uppercase, case-sensitive values below. It is required for ENTITY_EXTRACTION and ENTITY_RENDER, accepts 1–10 values, and must not be sent with either OCR operation. Slight OCR corruption may be repaired during classification, but the returned track remains aligned to the text detected in the video.

Value	What it matches	Example	Not matched
PERSON	A specific person’s full or partial name.	Ada Lovelace	Generic roles such as “Admin” or “Manager”
COMPANY	A named business, brand, or commercial organization.	Acme Inc.	Generic phrases such as “the bank”
EMAIL	An email address in username@domain format.	ada@example.com	Usernames without a domain
CURRENCY	A monetary amount with a symbol, ISO code, or clear financial context.	USD 1,250.00	Unlabelled numbers
PASSWORD	A value explicitly identified by the surrounding text as a password.	Password: hunter2	Unlabelled arbitrary strings
API_KEY	A high-entropy key, secret, or token explicitly identified as such.	API key: sk_live_…	Unlabelled IDs
DATE	A date, timestamp, or specific time value.	2026-06-18 3:45 PM	Vague phrases such as “next week”
ADDRESS	A physical or postal address, including meaningful locality and postal information.	123 Main St, New York, NY 10001	Generic words such as “office”
PHONE	A telephone or mobile number in a recognizable format.	+91 98765 43210	Unlabelled numeric identifiers
URL	A web address with a protocol, www prefix, or recognizable domain.	https://example.com/path	Ordinary text containing a dot

Job request examples

Every job needs an uploaded input_asset_id. An optional idempotency_key (1–255 characters) safely identifies a create request for retry. The four valid request shapes are shown below.

OCR — return all text tracks as JSON

Do not include entities or render.

Create an OCR jobbash

curl -X POST https://www.sightapi.work/api/v1/jobs \
  -H "Authorization: Bearer <prefix>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "input_asset_id":"123e4567-e89b-12d3-a456-426614174000",
    "operation":"OCR",
    "idempotency_key":"video-42-ocr"
  }'

ENTITY_EXTRACTION — return selected entity tracks as JSON

Include one or more supported entity values. Do not include render.

Extract email, phone, and API-key tracksbash

curl -X POST https://www.sightapi.work/api/v1/jobs \
  -H "Authorization: Bearer <prefix>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "input_asset_id":"123e4567-e89b-12d3-a456-426614174000",
    "operation":"ENTITY_EXTRACTION",
    "entities":["EMAIL","PHONE","API_KEY"]
  }'

OCR_RENDER — render every OCR track into an MP4

Include render and omit entities. Rectangle thickness is 1–20 pixels and defaults to 4 when omitted.

Draw rectangles around all detected textbash

curl -X POST https://www.sightapi.work/api/v1/jobs \
  -H "Authorization: Bearer <prefix>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "input_asset_id":"123e4567-e89b-12d3-a456-426614174000",
    "operation":"OCR_RENDER",
    "render":{"type":"rectangle","color":"#5B5FEF","thickness":4}
  }'

ENTITY_RENDER — render only selected entities into an MP4

Include both entities and render. Redaction blur strength is an integer from 10–100 and defaults to 50 when omitted.

Redact people, email addresses, and phone numbersbash

curl -X POST https://www.sightapi.work/api/v1/jobs \
  -H "Authorization: Bearer <prefix>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "input_asset_id":"123e4567-e89b-12d3-a456-426614174000",
    "operation":"ENTITY_RENDER",
    "entities":["PERSON","EMAIL","PHONE"],
    "render":{"type":"redact","blur_strength":75}
  }'

API Endpoints Overview

POST/api/v1/assets

Create an asset record and receive a signed upload URL for raw video payload.

Body parameters: filename (string), content_type (optional string)

POST/api/v1/jobs

Enqueue one of four GPU video operations for an uploaded asset.

Required: input_asset_id and operation. Entity operations also require entities; render operations require render.

GET/api/v1/jobs

List historic and active OCR processing jobs with status, frame progress, and credit charges.

Query parameters: status, limit, offset

GET/api/v1/jobs/{id}

Get details, progress stage, and metadata for a specific job by UUID. Failed jobs include a structured error with a stable code, human-readable message, and user/system classification.

DELETE/api/v1/jobs/{id}

Cancel a queued or dispatching job and release its reserved credits. Jobs already processing or in a terminal state return 409 job_not_cancellable. This does not delete job history or results.

GET/api/v1/jobs/{id}/result

Stream the requested JSON track data or the rendered video/mp4.

Operations, rendering, and billing

OCR returns OCR tracks only. ENTITY_EXTRACTION returns boxes only for the requested entity categories. OCR_RENDER renders all OCR tracks, while ENTITY_RENDER renders only requested entities. Rectangle rendering accepts a #RRGGBB colour and optional thickness; redaction accepts a blur strength from 10–100.

Successful jobs cost 2 credits per second of measured GPU-worker processing time. Partial credits round up to the next whole credit; the job response reports both processing_seconds and charged_credits.

Failed jobs are never charged. Input errors such as a corrupt file or unsupported codec are returned immediately with error.type = "user". Transient worker failures are retried automatically; if all attempts fail, the terminal response uses error.type = "system". In both cases, reserved credits are released.

Failed job responsejson

{
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "failed",
  "charged_credits": null,
  "error": {
    "code": "bad_codec",
    "message": "The video uses a codec that is not supported.",
    "type": "user"
  }
}

DELETE

/api/v1/jobs/{id}

Cancels a job only while its status is queued, pending, or dispatching. Cancellation is atomic: if processing starts first, the request is rejected. A successful cancellation releases reserved credits and retains the job as an auditable cancelled record; no job data is hard-deleted.

Cancel a Jobbash

curl -X DELETE https://www.sightapi.work/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer <prefix>.<secret>"

200 — Cancelledjson

{
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "cancelled",
  "current_stage": "cancelled",
  "reserved_credits": 14,
  "charged_credits": null
}

404 — not found

The job does not exist or belongs to another organization. The response does not reveal cross-tenant resource existence.

409 — job_not_cancellable

The job is already processing, completed, failed, or cancelled. The response includes its current status.