AvailableInference · Utility models

Utility model APIs

Detect document structure, extract text, transcribe and translate audio, synthesize speech, and create consent-backed voices through the public API or a Tarka Agent Host.

Provisioning and managementUse the console or the Control API.

Create and scope API keys, select model access, and inspect usage in the console or through the Control API. Runtime inference requests go to the Inference API.

Open console Control API reference

Use model discovery as the source of truth.

Public utility requests require a key with the utilities scope and explicit access to the requested alias. GET /v1/models returns the aliases available to that key.

Choose a surface

Canonical REST, native gRPC, and Agent Host

Canonical /v1 REST and native gRPC reach the same service. The old /v2 REST prefix is a deprecated alias with identical request fields.

Surface	Base address	Authentication	Use it for
Public REST	`https://tarka.rest/v1`	Bearer API key	OpenAI-compatible clients and utility routes
Native gRPC	`grpc.tarka.rest:443`	`authorization` metadata	Typed clients and server streaming
Agent Host v1	`http://tarka/v1`	Automatically authorized within the host	Host-local requests without a public network round trip
Deprecated REST alias	`https://tarka.rest/v2`	Bearer API key	Temporary compatibility for existing integrations

Keep public API keys server-side.

Never embed a tk_live_... key in browser code. The http://tarka address resolves only inside a Tarka Agent Host and is not a public fallback.

REST reference

Canonical v1 endpoints

Prefix each path with /v1. Model listing and retrieval are available at GET /v1/models and GET /v1/models/{model}. The deprecated /v2 prefix remains an alias.

POST/ocr

Extract text from one or more images · v1 canonical

POST/document/layout

Detect ordered document regions and geometry · Tarka v1 extension

POST/chat/completions

Run OCR through an OpenAI-compatible multimodal message · v1 canonical

POST/audio/transcriptions

Transcribe audio in its source language · v1 canonical

POST/audio/translations

Transcribe audio and translate it to English · v1 canonical

POST/audio/speech

Generate audio from text · v1 canonical

POST/audio/voice-clones

Create a consent-backed custom voice · v1 canonical

GET/audio/voice-clones/{voice_id}

Read custom voice status · v1 canonical

DELETE/audio/voice-clones/{voice_id}

Delete a custom voice · v1 canonical

Discover available aliases

ShellGET /v1/models

curl "https://tarka.rest/v1/models" \
  -H "Authorization: Bearer $TARKA_API_KEY"

Currently available utility aliases

Modality	Alias	Designed for	Status
Speech to text	`whisper-large-v3`	Multilingual transcription and English translation	Available
Speech to text	`whisper-nepali-medium`	Nepali-specialized speech transcription	Available
Speech to text	`qwen3-asr`	Multilingual transcription with Qwen3-ASR 1.7B	Available
OCR	`glm-ocr`	General document text and structured extraction	Available
OCR	`glm-ocr-nepali`	Nepali and Devanagari document text	Available
OCR	`paddleocr-vl-1.6`	Page-level document parsing with Markdown and structured blocks	Available
Document layout	`pp-doclayout-v3`	Fast document-region detection, geometry, and reading order	Available
Text to speech	`nepali-parler-tts`	Nepali speech with descriptive voice instructions	Available
TTS + voice cloning	`qwen3-tts`	Text to speech with consent-backed voice cloning	Available
Text to speech	`kokoro`	Fast English speech with named built-in voices	Available
Text to speech	`piper`	Efficient English speech with a fixed voice	Available

Availability can be narrower for an individual organization or key. If an alias does not appear in GET /v1/models, do not route requests to it.

Available · canonical v1

OCR with the dedicated endpoint

Send one image or an images array to POST /ocr. Non-streaming requests return an ocr.completion; stream: true returns server-sent events ending in data: [DONE].

modelstring · required

Use glm-ocr for general extraction, glm-ocr-nepali for Nepali and Devanagari text, or paddleocr-vl-1.6 for page-level document parsing and Markdown.

imagestring · conditionally required

One base64 value or base64 data URI. Use this or images, not both.

imagesstring[] · conditionally required

Up to 32 images in request order. Use this or image.

promptstring · optional

Extraction instructions such as reading order or output structure.

streamboolean · default false

Return incremental server-sent events when true.

max_tokensinteger · optional

Maximum output tokens.

temperaturenumber · default 0

Controls output randomness.

output_formatstring · default markdown

Choose the portable top-level text representation: text, markdown, or a serialized json page document.

includestring[] · optional

Add blocks to return typed page blocks or layout to include the underlying layout result. These are additive Tarka extensions.

layout_shapestring · default auto

Geometry for Paddle blocks: auto, box, quadrilateral, or polygon.

Canonical request

ShellPOST /v1/ocr

curl "https://tarka.rest/v1/ocr" \
  -H "Authorization: Bearer $TARKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "paddleocr-vl-1.6",
    "image": "data:image/png;base64,iVBORw0KGgoAAA...",
    "output_format": "markdown",
    "include": ["blocks", "layout"],
    "layout_shape": "auto"
  }'

Response

JSON200 OK

{
  "id": "ocr-01K3...",
  "object": "ocr.completion",
  "created": 1787596800,
  "model": "paddleocr-vl-1.6",
  "text": "# Quarterly report\n\nRevenue increased by 12%.",
  "pages": [{
    "index": 0,
    "width": 1600,
    "height": 2200,
    "text": "Quarterly report\n\nRevenue increased by 12%.",
    "markdown": "# Quarterly report\n\nRevenue increased by 12%.",
    "blocks": [{
      "id": "block-0",
      "label": "doc_title",
      "reading_order": 0,
      "bbox": {"x_min": 112, "y_min": 84, "x_max": 946, "y_max": 180},
      "polygon": [{"x": 112, "y": 84}, {"x": 946, "y": 84}, {"x": 946, "y": 180}, {"x": 112, "y": 180}],
      "confidence": 0.98,
      "content": "# Quarterly report"
    }]
  }],
  "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
}

Deprecated v2 alias

ShellPOST /v2/ocr

curl "https://tarka.rest/v2/ocr" \
  -H "Authorization: Bearer $TARKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-ocr-nepali",
    "image": "data:image/png;base64,iVBORw0KGgoAAA..."
  }'

Images must be inline.

OCR accepts base64 image data and does not fetch remote HTTP or HTTPS image URLs.

Tarka extension · canonical v1

Document layout without recognition

Call POST /document/layout with pp-doclayout-v3 when your pipeline needs semantic regions, coordinates, and reading order but not generated text. This extension follows the same authentication, discovery, metering, and error conventions as the OpenAI-compatible routes.

modelstring · required

Use pp-doclayout-v3.

imagestring · required

One inline base64 image or base64 data URI. Remote URLs are rejected.

thresholdnumber · optional

Confidence cutoff from 0 through 1.

shapestring · default auto

auto, box, quadrilateral, or polygon.

labelsstring[] · optional

Return only matching semantic labels, such as text, table, or formula.

Layout request

ShellPOST /v1/document/layout

curl "https://tarka.rest/v1/document/layout" \
  -H "Authorization: Bearer $TARKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pp-doclayout-v3",
    "image": "data:image/png;base64,iVBORw0KGgoAAA...",
    "threshold": 0.3,
    "shape": "polygon",
    "labels": ["doc_title", "text", "table", "formula"]
  }'

Ordered regions

JSON200 OK

{
  "id": "layout-01K3...",
  "object": "document.layout",
  "created": 1787596800,
  "model": "pp-doclayout-v3",
  "width": 1600,
  "height": 2200,
  "regions": [{
    "id": "region-0",
    "label": "doc_title",
    "class_id": 0,
    "score": 0.98,
    "bbox": {"x_min": 112, "y_min": 84, "x_max": 946, "y_max": 180},
    "polygon": [{"x": 112, "y": 84}, {"x": 946, "y": 88}, {"x": 942, "y": 180}, {"x": 116, "y": 176}],
    "reading_order": 0
  }],
  "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
}

Do not call both routes unless you need two independent passes.

paddleocr-vl-1.6 already runs PP-DocLayoutV3 inside its page-level OCR pipeline. Use the standalone layout route for geometry-only workflows or custom region routing.

OpenAI-compatible OCR

OCR through Chat Completions

Use the same POST /chat/completions route as a language model, select an OCR alias, and include an inline image in a standard multimodal user message. The response is a normal chat.completion.

Request

ShellPOST /v1/chat/completions

curl "https://tarka.rest/v1/chat/completions" \
  -H "Authorization: Bearer $TARKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-ocr-nepali",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Extract the Nepali text in reading order."},
        {"type": "image_url", "image_url": {
          "url": "data:image/png;base64,iVBORw0KGgoAAA..."
        }}
      ]
    }],
    "temperature": 0
  }'

Response

JSON200 OK

{
  "id": "chatcmpl-01K3...",
  "object": "chat.completion",
  "created": 1787596800,
  "model": "glm-ocr-nepali",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "बाढी राहत केन्द्र"},
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 412,
    "completion_tokens": 18,
    "total_tokens": 430
  }
}

The content part type is image_url, but its url value must be an inline base64 data URI.
Set stream: true to receive chat.completion.chunk events followed by data: [DONE].
OCR through Chat Completions still requires the utilities scope; an inference-only key is rejected.
The deprecated /v2/chat/completions alias accepts the same request body.

Available · canonical v1

Speech to text and translation

Upload audio as multipart form data. Transcriptions preserve the source language. Use whisper-nepali-medium for Nepali-specialized transcription; English translation is available with whisper-large-v3.

filefile · required

The audio file to process.

modelstring · required

Use whisper-large-v3, whisper-nepali-medium, or qwen3-asr for transcription. Only whisper-large-v3 supports translation.

languagestring · transcription only

ISO-639-1 source-language hint. Pass ne for Nepali audio.

promptstring · optional

Vocabulary, names, or style context.

response_formatstring · default json

json, text, srt, verbose_json, or vtt.

temperaturenumber · optional

Controls decoding randomness. Use 0 for deterministic decoding.

timestamp_granularities[]string[] · optional

segment or word timestamps.

Transcription

ShellPOST /v1/audio/transcriptions

curl "https://tarka.rest/v1/audio/transcriptions" \
  -H "Authorization: Bearer $TARKA_API_KEY" \
  -F "file=@./meeting-nepali.wav" \
  -F "model=whisper-nepali-medium" \
  -F "language=ne" \
  -F "response_format=json"

Translation

ShellPOST /v1/audio/translations

curl "https://tarka.rest/v1/audio/translations" \
  -H "Authorization: Bearer $TARKA_API_KEY" \
  -F "file=@./interview-nepali.mp3" \
  -F "model=whisper-large-v3" \
  -F "response_format=json"

JSON200 OK

{
  "text": "नमस्ते, हामी राहत सामग्री लिएर आउँदैछौँ।"
}

Available · canonical v1

Text to speech

Generate binary audio with POST /audio/speech. Pick an alias based on language and voice behavior.

modelstring · required

nepali-parler-tts, kokoro, piper, or a cloning-capable alias.

inputstring · required

The text to synthesize.

voicestring · required

A delivery description for Parler, a named built-in voice for Kokoro, default for Piper, or a voice_... clone ID for Qwen3-TTS.

response_formatstring · default mp3

mp3, opus, aac, flac, wav, or pcm.

speednumber · default 1

Playback speed from 0.25 to 4.

instructionsstring · optional

Additional model-specific speaking instructions.

stream_formatstring · optional

Requested streaming representation where supported.

ShellPOST /v1/audio/speech · binary response

curl "https://tarka.rest/v1/audio/speech" \
  -H "Authorization: Bearer $TARKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nepali-parler-tts",
    "input": "नमस्ते नेपाल",
    "voice": "A clear, calm Nepali speaker",
    "response_format": "wav",
    "speed": 1
  }' \
  --output speech.wav

Kokoro with a named voice

ShellPOST /v1/audio/speech · binary response

curl "https://tarka.rest/v1/audio/speech" \
  -H "Authorization: Bearer $TARKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kokoro",
    "input": "Tarka utility inference is ready.",
    "voice": "af_heart",
    "response_format": "wav",
    "speed": 1
  }' \
  --output kokoro.wav

Voice values are model-specific.

Do not send a delivery description, built-in voice name, or clone ID to a model that does not support that voice type. A clone ID can only be used with the model that created it.

Available · canonical v1

Voice cloning

Create a consent-backed voice resource with qwen3-tts, then use its identifier with the same model at /audio/speech. The clone is available when the response status is ready.

Consent is required.

Only upload a speaker sample when you have permission to create and use that voice. Tarka records the consent name and date with the clone.

modelstring · required

Use qwen3-tts.

namestring · required

Your display name for the voice.

samplefile · required

A clean recording of the consenting speaker.

consent_signed_bystring · required

The consenting speaker's legal name.

consent_datedate · required

The ISO-8601 consent date.

Create a clone

ShellPOST /v1/audio/voice-clones

curl "https://tarka.rest/v1/audio/voice-clones" \
  -H "Authorization: Bearer $TARKA_API_KEY" \
  -F "model=qwen3-tts" \
  -F "name=Product narrator" \
  -F "sample=@./consented-sample.wav" \
  -F "consent_signed_by=Example Person" \
  -F "consent_date=2026-08-28"

Response

JSON202 Accepted

{
  "id": "voice_0123456789abcdef0123456789abcdef",
  "object": "voice.clone",
  "model": "qwen3-tts",
  "name": "Product narrator",
  "status": "ready"
}

Generate speech with the clone

ShellPOST /v1/audio/speech

curl "https://tarka.rest/v1/audio/speech" \
  -H "Authorization: Bearer $TARKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-tts",
    "input": "This was generated with the consented reference voice.",
    "voice": "voice_0123456789abcdef0123456789abcdef",
    "response_format": "wav"
  }' \
  --output cloned-voice.wav

Read or delete a clone

ShellGET · DELETE

curl "https://tarka.rest/v1/audio/voice-clones/voice_0123456789abcdef0123456789abcdef" \
  -H "Authorization: Bearer $TARKA_API_KEY"

curl -X DELETE "https://tarka.rest/v1/audio/voice-clones/voice_0123456789abcdef0123456789abcdef" \
  -H "Authorization: Bearer $TARKA_API_KEY"

Lifecycle statuses are pending, processing, ready, and failed.

Native API

gRPC and protobuf

Connect to grpc.tarka.rest:443 over TLS and send the public API key as authorization: Bearer ... metadata. The service is tarka.inference.v2.InferenceService.

RPC	Purpose
`ListModels`	List aliases available to the API key
`RetrieveModel`	Retrieve one available alias
`CreateOCR / StreamOCR`	Extract image text as one response or a server stream
`CreateDocumentLayout`	Detect semantic regions, confidence, geometry, and reading order
`CreateChatCompletion / StreamChatCompletion`	Use the chat contract, including OCR aliases
`CreateTranscription`	Transcribe uploaded audio
`CreateTranslation`	Translate uploaded audio to English
`CreateSpeech`	Receive generated audio as a server stream
`CreateVoiceClone / GetVoiceClone / DeleteVoiceClone`	Manage consent-backed voice resources

Discover models

grpcurlListModels

grpcurl \
  -H "authorization: Bearer $TARKA_API_KEY" \
  -d '{}' \
  grpc.tarka.rest:443 \
  tarka.inference.v2.InferenceService/ListModels

Run OCR

grpcurlCreateOCR

grpcurl \
  -H "authorization: Bearer $TARKA_API_KEY" \
  -d '{
    "model": "glm-ocr-nepali",
    "image": "data:image/png;base64,iVBORw0KGgoAAA...",
    "prompt": "Extract the Nepali text."
  }' \
  grpc.tarka.rest:443 \
  tarka.inference.v2.InferenceService/CreateOCR

Detect layout

grpcurlCreateDocumentLayout

grpcurl \
  -H "authorization: Bearer $TARKA_API_KEY" \
  -d '{
    "model": "pp-doclayout-v3",
    "image": "data:image/png;base64,iVBORw0KGgoAAA...",
    "shape": "polygon"
  }' \
  grpc.tarka.rest:443 \
  tarka.inference.v2.InferenceService/CreateDocumentLayout

Generate typed clients from the public protobuf definition. The package remains tarka.inference.v2 for gRPC wire compatibility. Canonical REST follows the v1 OpenAPI contract.

Agent Host

Call utilities over the host-local v1 endpoint

Inside a Tarka Agent Host, replace the public base URL with http://tarka/v1 and omit the bearer header. Requests are authorized automatically and limited to the chat and utility aliases selected for that host.

ShellPOST http://tarka/v1/ocr

curl "http://tarka/v1/ocr" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-ocr-nepali",
    "image": "data:image/png;base64,iVBORw0KGgoAAA..."
  }'

Reliability

Errors, limits, and retries

REST failures use a top-level OpenAI-shaped error object. gRPC clients receive the corresponding gRPC status code.

JSON4xx

{
  "error": {
    "message": "The requested model is not available for this API key.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_allowed"
  }
}

Status	Meaning	Client action
`400`	Invalid field, format, modality, or image	Correct the request; do not retry unchanged
`401`	Missing, invalid, or revoked public key	Replace the key
`403`	Missing `utilities` scope or model access	Update the key in the console or Control API
`404`	Unknown model or voice resource	Refresh discovery or check the identifier
`429`	Concurrency, rate, or organization limit reached	Retry with exponential backoff and jitter
`5xx`	Temporary service or model failure	Retry safe requests with bounded backoff

Do not retry malformed requests or permission failures unchanged.
For interrupted streams, treat the output as incomplete and retry only if your application can tolerate duplicate work.
Keep uploaded images and audio within the limits returned by your organization policy.