The HIPS SDK for TypeScript and JavaScript

The HIPS SDK for TypeScript and JavaScript runs image, video, audio and specialist models, and your own imported models, through the HIPS task API. It is one of eight SDKs generated from one API description, hand-finished and checked by one shared conformance suite, so it behaves exactly as the other seven do; only the language's code and idioms differ.

The install command appears here when the eight SDKs are published. Until then the package name is a proposal, and no command is printed that would install something else.

The client reads two names from the environment, HIPS_API_KEY and HIPS_BASE_URL, whose value is https://ai.hips.com/v1. An argument given to the client wins over the environment, and an empty argument counts as not given. A client with no key fails when it is constructed, before any request. Your own code reads HIPS_MODEL and passes it as the model, or passes a dep_ deployment id; the SDK sends either exactly as given.

00000000000000000000000000000000000000001export HIPS_API_KEY="<a key created in the Console>"2export HIPS_BASE_URL="https://ai.hips.com/v1"3export HIPS_MODEL="<a catalog model id or a dep_ deployment id>"

Keep the key on the server or in a secret store. The SDK never writes it to a file, a keychain or a cache, and never logs it.

A classification task against your own model's deployment, the example every SDK page shares. The input and output shapes are illustrative; the task's real shape is on its task guide.

00000000000000000000000000000000000000001import { Hips } from "@hips-ai/sdk";2 3// Reads HIPS_API_KEY and HIPS_BASE_URL (https://ai.hips.com/v1);4// fails without a key.5const client = new Hips();6 7const result = await client.tasks.run({8  deployment: "dep_...",9  input: { text: "I was charged twice and nobody has replied." },10  requirements: { pool: "approved", pricingMode: "stable" },11});12 13console.log(result.output.label, result.usage.units);14console.log(result.meta.costMicros, result.meta.requestId);

client.uploads.upload sends a file that is too large to inline: it creates the upload with POST /v1/uploads, puts the bytes to the address the API returned, always a HIPS host over https, and gives you the upl_ id to name in a task's input. Uploads are for task inputs only: the SDK has no way to send model weights.

Your model is imported from its model hub in the Console, never uploaded: the import pins the revision, checks the files, re-saves them as weight files only and signs them (Import and run your model). You deploy the version there, and the SDK takes the dep_ deployment id as given. The SDK never starts an import and never asks for, stores or sends a hub token.

Video, long audio and batched generation are jobs. client.jobs.create answers at once with the job; client.jobs.wait polls client.jobs.get with backoff, honoring the server's suggested interval, until the job is completed, failed, canceled or interrupted. client.jobs.cancel stops one.

One error envelope on every route, mirrored as typed errors, all deriving from a base error that carries the status, type, code, param, the server's message and the request id. Rejected promises with typed errors: if (e instanceof RateLimitError) reads e.retryAfter.

• Retried: 429 and 503, honoring Retry-After, and a connection failure before any byte of a response, with exponential backoff and jitter Not decided yet.
• Never retried: any other 4xx, and 500.
• An idempotency-key is generated for every client.tasks.run and client.jobs.create call and sent on every attempt, so a retry can never bill twice; you can supply your own.
• Redirects are never followed, so a key is never sent to another host.

Do not assume that every failed or retried attempt has the same billing outcome: each result's meta and usage show what that response was charged (Retries and billing outcomes).

Pool, pricing mode, region and fallback are set as client defaults and overridden per call; the SDK writes them as the hips object in the body. A requirement left unset is left out, so the key's defaults from the Console apply. The SDK never sends a requirement it was not given and never weakens one.

The neutral names of the SDK specification, as TypeScript and JavaScript writes them. The full reference is generated from the SDK's own doc comments when it is released.