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.
/v1/tasksservedA synchronous task: one request, one batch of inputs, one result array.
Request
{ "model": "<catalog id>", "task": "classification", "inputs": [ {"id": "a", "type": "image", "data": "<base64>"}, {"id": "b", "type": "image", "upload_id": "upl_..."} ], "options": {"top_k": 3}, "hips": {"pool": "community", "pricing_mode": "market", "fallback": false}}Parts list: Fields
model or deploymentExactly onemodelis a catalog id, alias or pinned id;deploymentis adep_id. Adep_inmodelis a 400invalid_valuethat points atdeployment.taskRequiredMust be the model's task, or one of them for a model advertising several; otherwise a 400
task_mismatch.inputsRequiredAn array; each input an object with an optional
id(unique within the request; the index is used when absent), atype(text,image,audio,file) and exactly one oftext,data(base64 inline, within the limits) orupload_id(anupl_of the key's workspace, once uploads are offered). Nourlat launch Not decided yet. Animage_edittask'simageinputs may carry arole,reference(the default) ormask(Image generation and editing); on any other task aroleis a 400unsupported_parameter.optionsPer taskThe 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 400unknown_parameter.hipsOptionalThe request requirements:
pool(auto, the default,communityorcertified),pricing_mode,region,fallback.
The task values the gateway takes, with the inputs and options each accepts. A type is served once it has a price kind and a model of it is published and priced: today classification, embedding, rerank, image_generation and image_edit. Embeddings and rerank also have routes of their own in OpenAI's and Cohere's shapes, POST /v1/embeddings and POST /v1/rerank, and the image tasks OpenAI's POST /v1/images/generations and POST /v1/images/edits. A language model's chat is never the task API's: it goes to chat completions, Responses or Messages.
| Task | Inputs | Options | Unit | Priced now |
|---|---|---|---|---|
classification | text, image, audio, file | labels, top_k, threshold, multi_label | classification, priced per 1,000 | Yes |
embedding | text, image | dimensions, normalize | second (H109) | Yes |
rerank | text, each a document | query (required) | second (H109) | Yes |
detection | image | labels, top_k, threshold | detection | No |
transcription | audio, file | language, timestamps, diarization | audio_second | No |
translation | audio, file | language, timestamps | audio_second | No |
speech | text | voice, language, format, speed | character | No |
image_generation, image_edit | text, the prompt; for an edit also image, each with an optional role (reference or mask) | width, height, count, steps, seed, negative_prompt, sampler, scheduler, cfg_scale, guidance, output_format, output_quality | image, a fixed price per image at its size | Yes |
video_generation | text, image | duration_s, width, height, fps, count, seed | video_second; a job only | No |
- Task
classification- Inputs
text,image,audio,file- Options
labels,top_k,threshold,multi_label- Unit
classification, priced per 1,000- Priced now
- Yes
- Task
embedding- Inputs
text,image- Options
dimensions,normalize- Unit
second(H109)- Priced now
- Yes
- Task
rerank- Inputs
text, each a document- Options
query(required)- Unit
second(H109)- Priced now
- Yes
- Task
detection- Inputs
image- Options
labels,top_k,threshold- Unit
detection- Priced now
- No
- Task
transcription- Inputs
audio,file- Options
language,timestamps,diarization- Unit
audio_second- Priced now
- No
- Task
translation- Inputs
audio,file- Options
language,timestamps- Unit
audio_second- Priced now
- No
- Task
speech- Inputs
text- Options
voice,language,format,speed- Unit
character- Priced now
- No
- Task
image_generation,image_edit- Inputs
text, the prompt; for an edit alsoimage, each with an optionalrole(referenceormask)- Options
width,height,count,steps,seed,negative_prompt,sampler,scheduler,cfg_scale,guidance,output_format,output_quality- Unit
image, a fixed price per image at its size- Priced now
- Yes
- Task
video_generation- Inputs
text,image- Options
duration_s,width,height,fps,count,seed- Unit
video_second; a job only- Priced now
- No
Each model type that is not a language model gets OpenAI's own route as well, a thin front door on the same task workers, opened type by type (decided 2026-11-04). Until its type is served, each answers 400 type_not_served at model, naming the type, never a guess at a shape. The image routes are open: Images documents them.
/v1/audio/transcriptionsnot servedAnswers 400 type_not_served: no speech-to-text model is served yet. Opens once the type is served.
/v1/audio/speechnot servedAnswers 400 type_not_served: no text-to-speech model is served yet. Opens once the type is served.
An option a type does not take is a 400 unknown_parameter; a model's own task decides which type a request may name (400 task_mismatch otherwise). Rerank, detection and embedding have no task guide yet; their fields are here and on the Usage page. The image tasks' options, bounds and answer are on Image generation and editing.
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.
Response
{ "object": "task", "id": "job_...", "model": "<pinned id>", "task": "classification", "results": [ {"input": "a", "labels": [{"label": "invoice", "score": 0.91}, {"label": "receipt", "score": 0.07}]}, {"input": "b", "error": {"message": "...", "type": "invalid_request_error", "param": "inputs[1].data", "code": "invalid_image"}} ], "usage": {"units": 2, "unit": "classification", "billed_units": 1}}Parts list: Rules
resultsOne entry per input, in request order, with
inputthe 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 failureAn input the worker cannot read gets an
errorentry in the envelope's shape and is not billed; the other inputs are answered.usage.billed_unitscounts the answered ones.Image tasksOne entry per image asked, in order, each with
inputthe prompt's id and itsindex: the image inline, or theimage_withhelderror of an image the content checks withheld, which is not billed. The answer adds theseedthe images were made with (Image generation and editing).Request failureA 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.
Time limitAn embedding or rerank request the measured speed of every GPU serving the model shows cannot finish within the gateway's time limit is refused with a 400
exceeds_time_limitbefore it starts. A type that runs only as a job (video_generation) is a 400use_jobs; the job routes are not built yet.idThe request's job id,
job_..., the key of its usage record. The job routes that would read it again are not built yet.idempotency-keyTaken on this route: a retry while the first runs answers 400
idempotency_in_progress, and once it completed 404result_expired, its message naming the first request'sreq_id. No answer is kept; nothing runs or is billed again (Idempotency).
| 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 or header 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: stop with more than 16 entries, a prompt_cache_key over 512 characters, a string holding a lone surrogate escape, a router name with an empty or unknown suffix, both max_tokens names with different values | 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 | unsupported_parameter | A known field HIPS does not accept, or a feature the named model does not advertise in the pool the request resolves to; param names it and message names the model | No |
| 400 | invalid_request_error | unsupported_value | n other than 1, stream_options without stream, a message role, part, item or tool type not accepted, a hosted tool that is not served | 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 | exceeds_time_limit | An embedding or rerank request that the measured speed of every GPU serving the model shows cannot finish within its time limit; the message says how long it would take. Sent before any work, uncharged | No; send fewer or shorter inputs |
| 400 | invalid_request_error | task_mismatch | task is not the model's task, or the model is not an embedding model or a reranker on its route | No |
| 400 | invalid_request_error | use_jobs | A task type that runs only as an asynchronous job (video_generation); the job routes are not built yet | 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, upload_purpose_mismatch, upload_region_mismatch | An upload_id that is unknown or another workspace's, past expires_at, without bytes, with bytes that differ from the declaration, already consumed, of another purpose than the request needs, or stored in another region than the request's region requirement. Uploads are not offered in production yet | 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, community with an always-on deployment, a knowledge base whose requirements the request cannot meet | No |
| 400 | invalid_request_error | invalid_idempotency_key, idempotency_key_reused, idempotency_in_progress | The idempotency rules | The last one, later |
| 400 | invalid_request_error | content_refused | An image request the content checks refused: its prompt or an input image asks for content the Acceptable Use Policy prohibits (param the prompt, inputs[0].text, for a generation, inputs for an edit; before any work), or every image made was withheld (param task). The message is the statement of reasons. Nothing charged | No |
| 402 | insufficient_credit | insufficient_credit | The balance does not cover the request's maximum cost at the bound quote | After a top-up |
| 402 | insufficient_credit | budget_exceeded | A budget guardrail of the workspace, the key or the person is at its limit with block; the error carries guardrail and resets_at (null for a budget that never resets). Never a payment challenge | After resets_at, or once the limit is raised |
| 403 | permission_error | model_not_on_plan | A model or feature the workspace's plan does not include, read from the plan's terms: on Free a model outside the Free plan's models (today gemma-4-e4b-it-8b, gpt-oss-120b, gpt-oss-20b and qwen3-14b), a router or Knowledge; on Free and Pro a deployment (dep_). The error adds feature and required_plan, the lowest plan that includes it. Answered before any placement, uncharged. A deployment refused this way is kept and answers again once the workspace is on a plan with deployments | After an owner or admin chooses a plan that includes it |
| 403 | permission_error | pool_not_allowed | A pool the workspace may not use for this model: one an access guardrail keeps out (named in the error), or a customer model's pool whose runtime-access conditions were not accepted | No |
| 403 | permission_error | model_not_allowed, region_not_allowed | A model, or a region requirement, that an access guardrail keeps out, the guardrail named in the error's guardrail member | No |
| 403 | permission_error | guardrail_unsupported | A content moderation guardrail applies to text it does not scan yet: a batch, or a task request with text; the guardrail named, uncharged | No |
| 404 | not_found_error | model_not_found | Unknown catalog id, alias, pinned id or dep_; another workspace's dep_; a name starting with hips-router that is not one of the four routers | No |
| 404 | not_found_error | upload_not_found, file_not_found, batch_not_found | An id in the path, or input_file_id, that is unknown, deleted, expired, another workspace's, or out of the credential's reach. Batches and files are not offered in production yet | No |
| 404 | not_found_error | result_expired | A task, embeddings or rerank request retried with its idempotency-key after the first completed: no answer is kept, and the message names the first request's req_ id. It ran and was billed once | No |
| 429 | rate_limit_error | rate_limit_exceeded | A rate limit; param is requests, tokens, uploads, batches (batches created per hour) or knowledge_search; 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. The message says what those pools can do now: a GPU that fits the model takes it when free or loads it when asked, which can take minutes or longer; or nothing can serve it, and a retry sooner than the given delay gets the same answer | Yes, after the given delay |
| 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 |
| 503 | overloaded_error | content_check_unavailable | The content checks of an image request could not run (the decision service failed or did not answer in time), and HIPS sends no image request unchecked; Retry-After; uncharged | Yes, after Retry-After |
| 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 or header is absent;
paramnames 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:
stopwith more than 16 entries, aprompt_cache_keyover 512 characters, a string holding a lone surrogate escape, a router name with an empty or unknown suffix, bothmax_tokensnames with different values - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
unknown_parameter- Situation
- A field the gateway does not know, at any depth;
paramnames it - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
unsupported_parameter- Situation
- A known field HIPS does not accept, or a feature the named model does not advertise in the pool the request resolves to;
paramnames it andmessagenames the model - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
unsupported_value- Situation
nother than 1,stream_optionswithoutstream, a message role, part, item or tool type not accepted, a hosted tool that is not served- 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
exceeds_time_limit- Situation
- An embedding or rerank request that the measured speed of every GPU serving the model shows cannot finish within its time limit; the message says how long it would take. Sent before any work, uncharged
- Retry
- No; send fewer or shorter inputs
- Status
- 400
- Type
invalid_request_error- Code
task_mismatch- Situation
taskis not the model's task, or the model is not an embedding model or a reranker on its route- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
use_jobs- Situation
- A task type that runs only as an asynchronous job (
video_generation); the job routes are not built yet - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
deployment_stopped- Situation
- The
dep_is instopped; 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,upload_purpose_mismatch,upload_region_mismatch- Situation
- An
upload_idthat is unknown or another workspace's, pastexpires_at, without bytes, with bytes that differ from the declaration, already consumed, of another purpose than the request needs, or stored in another region than the request's region requirement. Uploads are not offered in production yet - 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
hipsfield that differ, a pool the model is never offered in,communitywith an always-on deployment, a knowledge base whose requirements the request cannot meet - Retry
- No
- 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
- 400
- Type
invalid_request_error- Code
content_refused- Situation
- An image request the content checks refused: its prompt or an input image asks for content the Acceptable Use Policy prohibits (
paramthe prompt,inputs[0].text, for a generation,inputsfor an edit; before any work), or every image made was withheld (paramtask). The message is the statement of reasons. Nothing charged - Retry
- No
- Status
- 402
- Type
insufficient_credit- Code
insufficient_credit- Situation
- The balance does not cover the request's maximum cost at the bound quote
- Retry
- After a top-up
- Status
- 402
- Type
insufficient_credit- Code
budget_exceeded- Situation
- A budget guardrail of the workspace, the key or the person is at its limit with
block; the error carriesguardrailandresets_at(nullfor a budget that never resets). Never a payment challenge - Retry
- After
resets_at, or once the limit is raised
- Status
- 403
- Type
permission_error- Code
model_not_on_plan- Situation
- A model or feature the workspace's plan does not include, read from the plan's terms: on Free a model outside the Free plan's models (today
gemma-4-e4b-it-8b,gpt-oss-120b,gpt-oss-20bandqwen3-14b), a router or Knowledge; on Free and Pro a deployment (dep_). The error addsfeatureandrequired_plan, the lowest plan that includes it. Answered before any placement, uncharged. A deployment refused this way is kept and answers again once the workspace is on a plan with deployments - Retry
- After an owner or admin chooses a plan that includes it
- Status
- 403
- Type
permission_error- Code
pool_not_allowed- Situation
- A pool the workspace may not use for this model: one an access guardrail keeps out (named in the error), or a customer model's pool whose runtime-access conditions were not accepted
- Retry
- No
- Status
- 403
- Type
permission_error- Code
model_not_allowed,region_not_allowed- Situation
- A model, or a region requirement, that an access guardrail keeps out, the guardrail named in the error's
guardrailmember - Retry
- No
- Status
- 403
- Type
permission_error- Code
guardrail_unsupported- Situation
- A content moderation guardrail applies to text it does not scan yet: a batch, or a task request with text; the guardrail named, uncharged
- Retry
- No
- Status
- 404
- Type
not_found_error- Code
model_not_found- Situation
- Unknown catalog id, alias, pinned id or
dep_; another workspace'sdep_; a name starting withhips-routerthat is not one of the four routers - Retry
- No
- Status
- 404
- Type
not_found_error- Code
upload_not_found,file_not_found,batch_not_found- Situation
- An id in the path, or
input_file_id, that is unknown, deleted, expired, another workspace's, or out of the credential's reach. Batches and files are not offered in production yet - Retry
- No
- Status
- 404
- Type
not_found_error- Code
result_expired- Situation
- A task, embeddings or rerank request retried with its
idempotency-keyafter the first completed: no answer is kept, and the message names the first request'sreq_id. It ran and was billed once - Retry
- No
- Status
- 429
- Type
rate_limit_error- Code
rate_limit_exceeded- Situation
- A rate limit;
paramisrequests,tokens,uploads,batches(batches created per hour) orknowledge_search;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. The message says what those pools can do now: a GPU that fits the model takes it when free or loads it when asked, which can take minutes or longer; or nothing can serve it, and a retry sooner than the given delay gets the same answer - Retry
- Yes, after the given delay
- 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
- 503
- Type
overloaded_error- Code
content_check_unavailable- Situation
- The content checks of an image request could not run (the decision service failed or did not answer in time), and HIPS sends no image request unchecked;
Retry-After; uncharged - Retry
- Yes, after
Retry-After
- 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
Related sheets
- Sheet
- 18 of 20
- Detail
- H
- Updated
- 2026-11-16