Tasks

The versioned contract the HIPS SDK wraps: the envelope, the routes, the states and the rules that hold for every task. Task types, their inputs, options and output shapes are the catalog's.

POST/v1/taskspreview

A synchronous task: one request, one batch of inputs, one result array.

Fig. 1, sheet 11API reference

Request

00000000000000000000000000000000000000001{2  "model": "<catalog id>",3  "task": "classification",4  "inputs": [5    {"id": "a", "type": "image", "data": "<base64>"},6    {"id": "b", "type": "image", "upload_id": "upl_..."}7  ],8  "options": {"top_k": 3},9  "hips": {"pool": "personal", "pricing_mode": "market", "fallback": false}10}

Request sample

Parts list: Fields

model or deploymentExactly one
model is a catalog id, alias or pinned id; deployment is a dep_ id. A dep_ in model is a 400 invalid_value that points at deployment.
taskRequired
Must be the model's task, or one of them for a model advertising several; otherwise a 400 task_mismatch.
inputsRequired
An array; each input an object with an optional id (unique within the request; the index is used when absent), a type (text, image, audio, file) and exactly one of text, data (base64 inline, within the limits) or upload_id (an upl_ of the key's workspace). No url at launch Not decided yet.
optionsPer task
The task's options as the catalog defines them per task (labels for a zero-shot classifier, top_k, image size, voice, language). An unknown option is a 400 unknown_parameter.
hipsOptional
The request requirements: pool, pricing_mode, region, fallback.

Batching

The inputs array is the batch. One request is one job, one quote, one usage record and one x-hips-cost-micros; the cost is the number of inputs times the model's unit price. The maximum inputs per request and the maximum inline bytes are the model's hips.limits and the plan's limit. The whole batch runs on one worker; it is not split across pools.

The response

Response

00000000000000000000000000000000000000001{2  "object": "task",3  "id": "job_...",4  "model": "<pinned id>",5  "task": "classification",6  "results": [7    {"input": "a", "labels": [{"label": "invoice", "score": 0.91}, {"label": "receipt", "score": 0.07}]},8    {"input": "b", "error": {"message": "...", "type": "invalid_request_error", "param": "inputs[1].data", "code": "invalid_image"}}9  ],10  "usage": {"units": 2, "unit": "classification", "billed_units": 1}11}

Response sample

Parts list: Rules

results
One entry per input, in request order, with input the input's id. A task's result shape (labels with scores, a vector, an image, a transcript with segments) is the catalog's per task type.
Per-input failure
An input the worker cannot read gets an error entry in the envelope's shape and is not billed; the other inputs are answered. usage.billed_units counts the answered ones.
Request failure
A request that is malformed, over a limit, or names a model, task or requirement it cannot use is a 400 before any work; nothing is billed.
Synchronous limit
A task that would exceed the synchronous time limit Not decided yet is refused with a 400 use_jobs before it starts, when the gateway can tell; one that runs over it is timed_out.
id
The job id. A task is a job that answered inline; GET /v1/jobs/{id} returns the same result until it expires.

Errors this route can answer

Status	Type	Code	Situation	Retry
400	`invalid_request_error`	`invalid_json`	The body is not JSON, or not an object	No
400	`invalid_request_error`	`missing_required_parameter`	A required field is absent; `param` names it	No
400	`invalid_request_error`	`invalid_type`	A field has the wrong JSON type	No
400	`invalid_request_error`	`invalid_value`	A value is out of range or malformed	No
400	`invalid_request_error`	`unknown_parameter`	A field the gateway does not know, at any depth; `param` names it	No
400	`invalid_request_error`	`invalid_image`	An image part or input cannot be decoded, is of an unsupported type or over the pixel limit	No
400	`invalid_request_error`	`request_too_large`, `input_too_large`, `too_many_inputs`, `upload_too_large`	A limit of the Limits page	No
400	`invalid_request_error`	`task_mismatch`	`task` is not the model's task	No
400	`invalid_request_error`	`deployment_stopped`	The `dep_` is in `stopped`; start it in the Console	No
400	`invalid_request_error`	`upload_not_found`, `upload_expired`, `upload_incomplete`, `upload_mismatch`, `upload_consumed`	An `upload_id` that is unknown or another workspace's, past `expires_at`, without bytes, with bytes that differ from the declaration, or already consumed	No (`upload_incomplete`: after the PUT)
400	`invalid_request_error`	`invalid_requirement`	A requirement header or field with an unknown value	No
400	`invalid_request_error`	`requirement_conflict`	Two requirements that cannot both hold, a header and a `hips` field that differ, a pool the model is never offered in, `personal` with an always-on deployment	No
400	`invalid_request_error`	`use_jobs`	A synchronous task the gateway can tell will exceed the synchronous limit	As a job
400	`invalid_request_error`	`invalid_idempotency_key`, `idempotency_key_reused`, `idempotency_in_progress`	The idempotency rules	The last one, later
402	`insufficient_credit`	`insufficient_credit`	The balance does not cover the request's maximum cost at the bound quote. On the free plan with the allowance used, the message names when it resets	After a top-up
403	`permission_error`	`model_not_on_plan`	The model or feature is not in the workspace's plan	No
403	`permission_error`	`pool_not_allowed`	A pool the workspace may not use for this model	No
404	`not_found_error`	`model_not_found`	Unknown catalog id, alias, pinned id or `dep_`; another workspace's `dep_`	No
404	`not_found_error`	`job_not_found`, `upload_not_found`	An id in the path that is unknown or another workspace's	No
429	`rate_limit_error`	`rate_limit_exceeded`	A rate limit; `param` is `requests`, `tokens`, `units` or `uploads`; `Retry-After`	Yes, after `Retry-After`
503	`overloaded_error`	`no_capacity`	No eligible worker under the request's requirements, in any pool the requirements allow; `Retry-After`	Yes
503	`overloaded_error`	`pool_unavailable`	The named pool has no eligible supply for this model now and fallback is off; the other pool may have; `Retry-After`	Yes, or with fallback
503	`overloaded_error`	`overloaded`	Eligible workers exist and every one is saturated, or the queue is full; `Retry-After`	Yes
500	`api_error`	`internal_error`	A fault in HIPS. Nothing billed	Once
500	`api_error`	`attempt_failed`	Every attempt failed for a reason that is not the client's and retries are exhausted. Nothing billed	Once

Status
400
Type
invalid_request_error
Code
invalid_json
Situation
The body is not JSON, or not an object
Retry
No
Status
400
Type
invalid_request_error
Code
missing_required_parameter
Situation
A required field is absent; param names it
Retry
No
Status
400
Type
invalid_request_error
Code
invalid_type
Situation
A field has the wrong JSON type
Retry
No
Status
400
Type
invalid_request_error
Code
invalid_value
Situation
A value is out of range or malformed
Retry
No
Status
400
Type
invalid_request_error
Code
unknown_parameter
Situation
A field the gateway does not know, at any depth; param names it
Retry
No
Status
400
Type
invalid_request_error
Code
invalid_image
Situation
An image part or input cannot be decoded, is of an unsupported type or over the pixel limit
Retry
No
Status
400
Type
invalid_request_error
Code
request_too_large, input_too_large, too_many_inputs, upload_too_large
Situation
A limit of the Limits page
Retry
No
Status
400
Type
invalid_request_error
Code
task_mismatch
Situation
task is not the model's task
Retry
No
Status
400
Type
invalid_request_error
Code
deployment_stopped
Situation
The dep_ is in stopped; start it in the Console
Retry
No
Status
400
Type
invalid_request_error
Code
upload_not_found, upload_expired, upload_incomplete, upload_mismatch, upload_consumed
Situation
An upload_id that is unknown or another workspace's, past expires_at, without bytes, with bytes that differ from the declaration, or already consumed
Retry
No (upload_incomplete: after the PUT)
Status
400
Type
invalid_request_error
Code
invalid_requirement
Situation
A requirement header or field with an unknown value
Retry
No
Status
400
Type
invalid_request_error
Code
requirement_conflict
Situation
Two requirements that cannot both hold, a header and a hips field that differ, a pool the model is never offered in, personal with an always-on deployment
Retry
No
Status
400
Type
invalid_request_error
Code
use_jobs
Situation
A synchronous task the gateway can tell will exceed the synchronous limit
Retry
As a job
Status
400
Type
invalid_request_error
Code
invalid_idempotency_key, idempotency_key_reused, idempotency_in_progress
Situation
The idempotency rules
Retry
The last one, later
Status
402
Type
insufficient_credit
Code
insufficient_credit
Situation
The balance does not cover the request's maximum cost at the bound quote. On the free plan with the allowance used, the message names when it resets
Retry
After a top-up
Status
403
Type
permission_error
Code
model_not_on_plan
Situation
The model or feature is not in the workspace's plan
Retry
No
Status
403
Type
permission_error
Code
pool_not_allowed
Situation
A pool the workspace may not use for this model
Retry
No
Status
404
Type
not_found_error
Code
model_not_found
Situation
Unknown catalog id, alias, pinned id or dep_; another workspace's dep_
Retry
No
Status
404
Type
not_found_error
Code
job_not_found, upload_not_found
Situation
An id in the path that is unknown or another workspace's
Retry
No
Status
429
Type
rate_limit_error
Code
rate_limit_exceeded
Situation
A rate limit; param is requests, tokens, units or uploads; Retry-After
Retry
Yes, after Retry-After
Status
503
Type
overloaded_error
Code
no_capacity
Situation
No eligible worker under the request's requirements, in any pool the requirements allow; Retry-After
Retry
Yes
Status
503
Type
overloaded_error
Code
pool_unavailable
Situation
The named pool has no eligible supply for this model now and fallback is off; the other pool may have; Retry-After
Retry
Yes, or with fallback
Status
503
Type
overloaded_error
Code
overloaded
Situation
Eligible workers exist and every one is saturated, or the queue is full; Retry-After
Retry
Yes
Status
500
Type
api_error
Code
internal_error
Situation
A fault in HIPS. Nothing billed
Retry
Once
Status
500
Type
api_error
Code
attempt_failed
Situation
Every attempt failed for a reason that is not the client's and retries are exhausted. Nothing billed
Retry
Once

Sheet: 11 of 13
Detail: E
Updated: 2026-10-21
Status: Preview

Join early access

1{2 "model": "<catalog id>",3 "task": "classification",4 "inputs": [5 {"id": "a", "type": "image", "data": "<base64>"},6 {"id": "b", "type": "image", "upload_id": "upl_..."}7 ],8 "options": {"top_k": 3},9 "hips": {"pool": "personal", "pricing_mode": "market", "fallback": false}10}

1{2 "object": "task",3 "id": "job_...",4 "model": "<pinned id>",5 "task": "classification",6 "results": [7 {"input": "a", "labels": [{"label": "invoice", "score": 0.91}, {"label": "receipt", "score": 0.07}]},8 {"input": "b", "error": {"message": "...", "type": "invalid_request_error", "param": "inputs[1].data", "code": "invalid_image"}}9 ],10 "usage": {"units": 2, "unit": "classification", "billed_units": 1}11}

Status

Type

Code

Situation

Retry

400

invalid_request_error

invalid_json

The body is not JSON, or not an object

400

invalid_request_error

missing_required_parameter

A required field is absent; param names it

400

invalid_request_error

invalid_type

A field has the wrong JSON type

400

invalid_request_error

invalid_value

A value is out of range or malformed

400

invalid_request_error

unknown_parameter

A field the gateway does not know, at any depth; param names it

400

invalid_request_error

invalid_image

An image part or input cannot be decoded, is of an unsupported type or over the pixel limit

400

invalid_request_error

request_too_large, input_too_large, too_many_inputs, upload_too_large

A limit of the Limits page

400

invalid_request_error

task_mismatch

task is not the model's task

400

invalid_request_error

deployment_stopped

The dep_ is in stopped; start it in the Console

400

invalid_request_error

upload_not_found, upload_expired, upload_incomplete, upload_mismatch, upload_consumed

An upload_id that is unknown or another workspace's, past expires_at, without bytes, with bytes that differ from the declaration, or already consumed

No (upload_incomplete: after the PUT)

400

invalid_request_error

invalid_requirement

A requirement header or field with an unknown value

400

invalid_request_error

requirement_conflict

Two requirements that cannot both hold, a header and a hips field that differ, a pool the model is never offered in, personal with an always-on deployment

400

invalid_request_error

use_jobs

A synchronous task the gateway can tell will exceed the synchronous limit

As a job

400

invalid_request_error

invalid_idempotency_key, idempotency_key_reused, idempotency_in_progress

The idempotency rules

The last one, later

402

insufficient_credit

The balance does not cover the request's maximum cost at the bound quote. On the free plan with the allowance used, the message names when it resets

After a top-up

403

permission_error

model_not_on_plan

The model or feature is not in the workspace's plan

403

permission_error

pool_not_allowed

A pool the workspace may not use for this model

404

not_found_error

model_not_found

Unknown catalog id, alias, pinned id or dep_; another workspace's dep_

404

not_found_error

job_not_found, upload_not_found

An id in the path that is unknown or another workspace's

429

rate_limit_error

rate_limit_exceeded

A rate limit; param is requests, tokens, units or uploads; Retry-After

Yes, after Retry-After

503

overloaded_error

no_capacity

No eligible worker under the request's requirements, in any pool the requirements allow; Retry-After

Yes

503

overloaded_error

pool_unavailable

The named pool has no eligible supply for this model now and fallback is off; the other pool may have; Retry-After

Yes, or with fallback

503

overloaded_error

overloaded

Eligible workers exist and every one is saturated, or the queue is full; Retry-After

Yes

500

api_error

internal_error

A fault in HIPS. Nothing billed

Once

500

api_error

attempt_failed

Every attempt failed for a reason that is not the client's and retries are exhausted. Nothing billed

Once

Batching

The response

Errors this route can answer

Related sheets

Batching

The response

Errors this route can answer

Related sheets