Processors | EZGH Cloud

Create, list, update, disable, enable and delete OCR processors, and pin or follow model versions.

A processor is a saved OCR configuration in a project: the model and version to use, the document languages, the output format and the detail level. You process documents by sending them to a processor. By default, a project can have up to 50 processors.

Processor fields

Field	Description
`id`	The processor’s ID, a UUID. API paths use it.
`slug`	A short ID such as `prc_4k2m9x0a7qpe`.
`resourceName`	The processor’s resource name, used in IAM policies and Trails: `ezgh:us-west-1:org_…:prj_…:prc_…`. It never changes.
`organizationId`, `projectId`, `region`	Where the processor is. `region` is `us-west-1`.
`name`	1 to 100 characters, without control characters. Names don’t have to be unique.
`description`	Up to 2,000 characters. Default: empty.
`model`	A model ID from the catalog, such as `unlimited-ocr`.
`modelVersion`	An exact version, such as `1.0.0`, or `latest`. See Model versions.
`resolvedModelVersion`	The version `modelVersion` resolves to now.
`languages`	Language codes from the model’s `capabilities.languages`, without duplicates. Default: none.
`outputFormat`	`text` or `json-layout`, from the model’s `capabilities.outputFormats`. See Output formats.
`options.detail`	A detail level from the model’s `capabilities.details`. Default and only value: `high`.
`tags`	Up to 50 key-value pairs. Keys are 1 to 128 characters and can’t start with `ezgh:`; values are up to 256 characters.
`state`	`active` or `disabled`. `status` has the same value.
`createdAt`, `updatedAt`	Times, RFC 3339 with milliseconds.
`warnings`	Problems with the configured model version, as `{ "code", "message" }`. Usually empty.

Create a processor

You need ocr.processors.create on the project.

In the console, choose the project, open OCR, and select Processors.
Select Create processor.
Model: enter a Name, an optional Description, and choose a model.
Version: choose Latest or a specific version.
Output: choose the Languages, the Output format (Text or JSON layout), and the Detail: High.
Review: check the settings and select Create processor.

ezgh ocr processors create --name receipts --language en --project web
ezgh ocr processors create --name forms --output-format json-layout --version 1.0.0 --project web

Flag	Sets	Default
`--name`	`name` (required)
`--description`	`description`
`--model`	`model`	`unlimited-ocr`
`--version`	`modelVersion`	`latest`
`--language`	`languages` (repeat, or separate with commas)	none
`--output-format`	`outputFormat`	`text`
`--detail`	`options.detail`	`high`

--project takes a project ID, slug or name. Without it, ezgh uses EZGH_PROJECT or the profile’s project.

Call CreateProcessor. name, model, modelVersion and outputFormat are required.

curl -X POST \
  -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "Receipts", "model": "unlimited-ocr", "modelVersion": "latest", "languages": ["en"], "outputFormat": "text", "options": {"detail": "high"}}' \
  "https://ocr.ezghcloud.com/v1/organizations/$ORG_ID/projects/$PROJECT_ID/ocr/processors"

The response is 201 Created, with the processor’s path in Location and its version in ETag:

{
  "id": "0199a3d0-2b3c-7d4e-9f50-6b7c8d9e0f1a",
  "slug": "prc_4k2m9x0a7qpe",
  "resourceName": "ezgh:us-west-1:org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2:prc_4k2m9x0a7qpe",
  "organizationId": "0199a3c2-5b1e-7d40-9f3a-2c8e6b1d4f70",
  "projectId": "0199a3c2-6c2f-7e51-8a4b-3d9f7c2e5a81",
  "region": "us-west-1",
  "name": "Receipts",
  "description": "",
  "model": "unlimited-ocr",
  "modelVersion": "latest",
  "languages": ["en"],
  "outputFormat": "text",
  "options": { "detail": "high", "detectTables": false, "detectHandwriting": false },
  "tags": {},
  "state": "active",
  "status": "active",
  "createdAt": "2026-09-30T17:02:11.408Z",
  "updatedAt": "2026-09-30T17:02:11.408Z",
  "resolvedModelVersion": "1.0.0",
  "warnings": []
}

List and view processors

OCR > Processors lists the current project’s processors with their Model, Output format, Detail, State and Created time. Select a processor to open its page, which shows its IDs and state, its Configuration, and Try it, where you can process a document.

ezgh ocr processors list --project web
ezgh ocr processors get receipts --project web

get takes a processor’s ID, slug or name.

curl -H "Authorization: Bearer $EZGH_API_KEY" \
  "https://ocr.ezghcloud.com/v1/organizations/$ORG_ID/projects/$PROJECT_ID/ocr/processors?limit=20"

curl -H "Authorization: Bearer $EZGH_API_KEY" \
  "https://ocr.ezghcloud.com/v1/organizations/$ORG_ID/projects/$PROJECT_ID/ocr/processors/$PROCESSOR_ID"

ListProcessors returns { "processors": [...], "nextCursor": ... }, newest first. It takes limit (1 to 100, default 20) and cursor (the previous page’s nextCursor). GetProcessor returns one processor, with an ETag header.

Update a processor

UpdateProcessor (PATCH) changes the fields you send and leaves the others unchanged.

languages, tags and options are replaced whole. Sending options replaces all options: any option you leave out returns to its default.
Changing model requires modelVersion in the same request.
null values and unknown fields are refused with 400 invalid_request.
The configuration (model, modelVersion, languages, outputFormat, options) is checked against the catalog only when one of those fields is in the request. You can rename a processor whose configuration is no longer valid.

On the processor’s page, open Configuration and select Edit configuration. Change the Name, Description, Model, Version or output settings, and select Save.

ezgh ocr processors update receipts --name "Receipts (EU)" --language en,zh --project web

Flags are the same as create. --language replaces the languages. ezgh sends the ETag it just read; if the processor changed in between, nothing is changed and you run the command again.

curl -X PATCH \
  -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "If-Match: $ETAG" \
  -d '{"languages": ["en", "zh"]}' \
  "https://ocr.ezghcloud.com/v1/organizations/$ORG_ID/projects/$PROJECT_ID/ocr/processors/$PROCESSOR_ID"

The response is 200 with the updated processor and its new ETag.

Disable, enable and delete

A disabled processor refuses documents (409 processor_disabled) until you enable it. You can still read, update and delete it. Enabling checks the configuration against the catalog again and refuses a retired model version or an option the model no longer offers.

Deleting a processor is permanent. It stops counting toward the project’s processor quota. When a project is deleted, its processors are deleted too.

On the processor’s page, select Disable, Enable or Delete, and confirm.

ezgh ocr processors disable receipts --project web
ezgh ocr processors enable receipts --project web
ezgh ocr processors delete receipts --project web

delete asks for confirmation; --yes skips it.

curl -X POST -H "Authorization: Bearer $EZGH_API_KEY" \
  "https://ocr.ezghcloud.com/v1/organizations/$ORG_ID/projects/$PROJECT_ID/ocr/processors/$PROCESSOR_ID/disable"

curl -X POST -H "Authorization: Bearer $EZGH_API_KEY" \
  "https://ocr.ezghcloud.com/v1/organizations/$ORG_ID/projects/$PROJECT_ID/ocr/processors/$PROCESSOR_ID/enable"

curl -X DELETE -H "Authorization: Bearer $EZGH_API_KEY" \
  "https://ocr.ezghcloud.com/v1/organizations/$ORG_ID/projects/$PROJECT_ID/ocr/processors/$PROCESSOR_ID"

DisableProcessor and EnableProcessor take no body (or {}) and return 200 with the processor; a processor already in that state is returned unchanged. DeleteProcessor returns 204.

Model versions

modelVersion is either:

An exact version, such as 1.0.0. The processor keeps using it until you change it. If the version is deprecated, warnings has model_version_deprecated. A retired version can’t be chosen, and a processor pinned to one gets model_version_retired and can’t process documents (409 model_unavailable).
latest, which follows the model’s latestVersion. Each request uses the version that is latest at that time.

resolvedModelVersion shows the version in use now, and each processing result’s modelVersion shows the version that produced it.

Concurrent changes

GetProcessor, CreateProcessor and every change return an ETag. Send it as If-Match on PATCH, DELETE, disable or enable to apply the change only if the processor hasn’t changed since you read it. Otherwise the request fails with 412 precondition_failed; read the processor again and retry. If-Match is optional; * matches any version.

Retries

CreateProcessor, DisableProcessor and EnableProcessor accept an Idempotency-Key header (1 to 200 characters). A retry with the same key and the same request returns the first response instead of acting again. Keys are kept for at least 24 hours. Reusing a key for a different request fails with 409 idempotency_conflict; a retry while the first request is still running fails with 409 idempotency_in_progress.

Errors

Status	Code	Cause
`400`	`invalid_request`	A missing, unknown, `null` or invalid field. `issues` lists each problem as `{ "path", "message" }`.
`400`	`invalid_cursor`	A cursor from another project, or edited
`403`	`access_denied`	The caller lacks the action on the project or processor
`404`	`not_found`	The organization, project or processor doesn’t exist or you can’t see it
`401`	`unauthenticated`	Missing or invalid credentials
`409`	`quota_exceeded`	The project is at its processor quota (`ocr.processors.count`, 50 by default)
`409`	`organization_deletion_pending`	The organization is being deleted
`409`	`idempotency_conflict`, `idempotency_in_progress`	See Retries
`412`	`precondition_failed`	`If-Match` doesn’t match the processor’s current `ETag`
`429`	`quota_exceeded`	Too many creates in the project (`ocr.processors.createsPerMinute`, 10 per minute by default)
`429`	`too_many_requests`	Too many requests. Retry after the `Retry-After` header’s seconds
`503`	`unavailable`	A dependency is unavailable. Retry after the `Retry-After` header’s seconds

Quota refusals have no Retry-After header. See Pricing and limits.