# HIPS

> HIPS is building a centrally managed AI inference marketplace on a distributed GPU network. It connects people buying inference with independently supplied GPU time.

We are inviting early-access interest while we develop the platform. Joining the list does not create an operating inference account or guarantee an invitation date.

## Home
Route: https://hips.com/

# AI inference for builders.

A distributed GPU network, managed by HIPS.

We’re bringing available GPUs together to make AI inference more affordable. Run open-weight models and models of your own through one API, with HIPS managing the network behind your application.

### More room in your AI budget

More of your AI budget should go toward what you are building. HIPS brings available GPU capacity together around that goal: useful inference with room to grow.

Bring inference costs into the design of your product. Choose the model and capacity that fit the work, with a clear view of what each request costs.

### Build with HIPS

**Familiar code. A new inference network.**

For open-weight language models, we’re designing HIPS to work with familiar coding tools and supported provider-style client SDKs, starting with OpenAI-style integrations. Connect your client with a HIPS API key, base URL, and supported model ID, and let HIPS coordinate the GPU capacity behind each request.

A HIPS API key, base URL, and supported model or deployment ID are the starting configuration. Explore the developer previews and see what needs checking when moving an existing integration.

### Run the models your application needs

From language and images to audio, video, and specialist tasks, we’re bringing a curated range of open-weight models into one inference platform.

Explore model capabilities, test an idea in the playground, and connect through an API. Follow the same path from your first experiment to an application people use.

### Bring your own model

Already trained a model for your product or business? We’re building a way to run it through HIPS.

Bring the model you have trained for your product, then choose the execution option that fits its workload and your requirements.

Your model weights will never be used to train other models. Request inputs and generated outputs follow your plan’s separate data-use policy.

### Keep a model loaded when it matters

Keep a model loaded between requests with always-on GPU capacity, supplied by providers suited to continuous allocation.

Choose an hourly allocation for work that needs a model to remain resident, and follow the deployment and its cost in the Console.

### Make more of the compute already here

Good ideas need somewhere to run. Useful compute is already out there, in personal computers and data centers. HIPS is bringing it into an AI inference marketplace, connecting people who need model results with people who have GPU time to offer.

Providers choose when they contribute capacity. HIPS coordinates the network, matching supported workloads to suitable GPUs and the policies attached to each request.

### Understand what you use

Start with usage-based inference, choose always-on capacity for a resident model, or explore monthly plans with included credits.

See the billing unit that fits each model’s work, with separate input and output token rates for language models and appropriate units for media and specialist tasks. Compare market and stable-price options as you plan your usage.

### Have a GPU that spends time idle

We’re building a way for people and businesses to contribute GPU capacity and earn when it is used.

Set your availability, define a minimum price, and see work and earnings in the HIPS Console. Register your interest to receive updates about supported hardware and provider access.

### Questions before joining

**Is HIPS available to use today?**

We are inviting early-access interest while we develop the platform. Joining the list does not create an operating inference account or guarantee an invitation date.

**Will HIPS support my model?**

We intend to support selected open-weight models and customer-owned models across several modalities. Supported architectures, hardware requirements, and the launch catalog will be announced as they are confirmed.

**Is the network decentralized?**

The GPU supply is distributed. HIPS centrally manages how work is assigned and how the service is operated.

**Will you train other models with my weights?**

No. Customer-owned model weights will never be used to train other models on any plan. Request inputs and generated outputs are a separate category and may be used for training on Free/PAYG and the lower paid plan.

**Do I need a wallet to join early access?**

No. You do not need a wallet or payment method to register interest.

**What happens to HIPS Payments?**

HIPS Payments continues as a separate division. Existing payments customers can use the HIPS Payments path for their product and support needs.

### Help shape what comes next

Tell us you’re interested in HIPS. We’ll send updates about early-access availability and the capabilities we’re preparing.

## AI inference API for your applications
Route: https://hips.com/inference

# AI inference for what you are building

Run open-weight models and your own models through one platform. HIPS is being built for the moment an idea needs useful inference: a response, an image, a transcript, a classification, or the next step in an application.

Start with a model from the catalog, test it in the playground, and connect through the API. Bring your own model when your application needs something specific.

### From model choice to useful output

A good inference platform should make the next step obvious. Discover what a model accepts, what it returns, and how its usage is charged. Try a realistic input before integrating it. Move from the browser to your application with the same model in mind.

The HIPS Console will bring those steps together, alongside the usage, activity, and billing information needed to keep building.

### Compute matched to the work

HIPS will coordinate compatible GPUs across a distributed network. Shared, usage-based inference gives open-weight models access to available capacity. Always-on capacity provides another route when a model needs to stay loaded between requests.

Choose how your own models are executed, with pool selection and the relevant policies visible before deployment.

For work that does not need an answer right away, batch jobs will let you send many requests at once in one file, in the OpenAI-style batch format. HIPS will run them as capacity becomes free, within a window you choose from 24 hours to 7 days, and tell you when they are done. A batch will cost half the on-demand rate of the same model. No completion time is promised: requests still unfinished when the window closes will come back as expired and will not be charged.

### A clearer view of cost

Different models do different work. Their prices should reflect that. Language models use separate input and output token rates; other models use units suited to the result they produce.

Compare the available market and stable-price options before sending work. Track the resulting usage in one account balance.

When requests begin with the same text, such as a long system prompt or a shared document, HIPS will reuse that work automatically from a cache kept for your workspace alone. Cached input will be billed at a lower rate than other input, and writing to the cache will cost nothing.

### Built for useful applications

Use language models for assistants, combine vision and language for documents, generate media, work with speech, or apply specialist models to classification. Explore the use cases to find a starting point for your application.

### Get closer to launch

Join early access and tell us what you want to run. Your use case will help us understand which models and workflows matter most.

## Open-weight AI models for inference
Route: https://hips.com/inference/models

# Find the model that fits the task

A useful catalog starts with what you want to do. We’re preparing a curated collection of open-weight models across language, image, audio, video, and specialist tasks.

Explore by capability, compare the details that affect your application, and move into the playground when you are ready to try an input.

### More than a model name

Each model page will explain the supported task, input and output formats, relevant limits, model version, and billing units. Where a model has specific licensing or usage conditions, those belong alongside the practical details.

For language models, see input and output token pricing separately. For classification, compare a defined task at a price per 1,000 classifications. For media, understand how dimensions, duration, or other supported settings affect the charge.

### Your task comes first

Look for language models when your product needs responses or summaries. Explore image and video models for visual workflows. Use audio models for speech tasks, and specialist models when a focused decision or classification is the right output.

A model’s size alone does not tell you whether it is right for your application. The catalog should help you evaluate its behavior, constraints, and cost with your own examples.

### Have a model already

Already have a model trained for your application? Bring its requirements to HIPS and explore the route from your weights to inference.

## Deploy your AI model for inference
Route: https://hips.com/inference/deploy

# Your model with a clearer path to inference

You have trained a model for a reason. HIPS is being built to help you put it to work.

Import a supported model from Hugging Face, choose an execution pool, and use the HIPS SDK to run inference across supported model types beyond language models. For compatible open-weight language models, use a supported provider-style client. Choose always-on GPU capacity when the model needs to remain loaded.

### Choose where your model runs

Choose between personal GPUs and an approved-provider pool. Compare the quoted price, current availability, and model-access conditions before deploying.

Cross-pool fallback will be off by default. If you enable it, it must still respect your region and data-use rules.

Personal GPU supply is intended to provide a lower-cost option. The actual quote will depend on the model, eligible capacity, and the selected pricing mode.

Customer models will run in the approved-provider pool first. Personal GPUs will follow later, only for supported ONNX models and only for deployments you opt in. If you opt in, the device owner’s machine will hold your model’s weights while it serves your requests.

### Keep your weights separate from request data

Your model weights will never be used to train other models, on any plan.

Request inputs and generated outputs are governed separately. On Free/PAYG and the lower paid plan, they may be used for training, including when requests run against your own model. On the higher paid plan, request-data training is off by default.

Execution-pool choice also matters. Before deployment, you will need to understand the model-access conditions of the selected pool. Encryption in transit and at rest does not by itself prevent a GPU operator from accessing data or weights while a workload runs.

### Match capacity to the workload

A model used occasionally and a model serving steady traffic may need different deployment choices. HIPS will profile supported customer models before assigning a tariff, accounting for more than memory fit alone.

Always-on capacity keeps a model loaded between requests and is charged by allocated time. Usage-based access, where supported, follows the applicable model tariff.

### Tell us what you need to run

Join early access with your model’s architecture, approximate size, task, and expected traffic. These details help us assess support without requiring you to upload model weights during enrollment.

## Always-on GPU capacity for AI inference
Route: https://hips.com/inference/always-on

# Always-on GPU capacity for models that stay loaded

Keep your model ready for the next request without loading it from scratch each time.

HIPS is developing hourly capacity for inference workloads that need a model to remain resident. This supply will come from providers suited to continuous availability, primarily data centers.

### Pay for capacity while you need it

The hourly charge covers allocated capacity, including time between requests. Compare compatible GPU configurations and the applicable quote before allocating resources.

The Console will show allocation state, model loading, readiness, accumulated usage, and the controls to stop the deployment. A GPU being allocated and a model being ready to serve are separate steps.

### Choose around the model

GPU memory, model architecture, runtime requirements, and expected workload all affect the right configuration. Supported region selection will be available through the higher paid plan.

Keeping weights loaded removes repeated model-loading work. Response time still depends on the model, hardware, input, and workload.

### Plan for steady work

Always-on capacity is intended for custom models and other inference workloads where continuous allocation makes sense. It is a distinct option from the shared pool of idle personal GPUs.

## More compute put to work
Route: https://hips.com/inference/how-it-works

# More compute put to work

Useful GPU capacity is spread across personal computers and data centers. HIPS is building a centrally managed inference marketplace that connects that supply with businesses and developers who want to run models.

You choose the model and the product option. HIPS coordinates the work. Providers decide what capacity they contribute.

### Start with the model

Select a supported open-weight model or bring compatible weights of your own. The model’s architecture, memory needs, and execution requirements determine which resources can run it.

### Apply your choices

Pricing mode, execution-pool choice, data-use policy, and any supported region requirement become part of the job’s requirements. They must continue to apply if work is retried or capacity changes.

### Assign compatible capacity

HIPS will route work to eligible GPUs. Shared inference can use available personal GPU capacity. Always-on deployments use supply appropriate for keeping models resident continuously.

### Return the result and account for the work

Results return through the service. Usage is recorded in the model’s billing units and deducted from the account’s credit balance, with the applicable price visible in the usage record.

### A coordinated network

Providers supply GPUs; HIPS operates the service around them. This gives customers one place to access models, manage deployments, and understand usage, while providers control their own participation.

## Understand how your models and data will be used
Route: https://hips.com/inference/security

# Understand how your models and data will be used

A model’s weights, the inputs sent to it, and the outputs it generates are different things. The HIPS platform is being designed to make those distinctions visible before you choose a plan or execution pool.

### Your model weights

Customer-owned model weights will never be used to train other models on any plan.

That commitment applies to the weights themselves. It does not change the separate policy for request inputs and generated outputs.

Your model will come to HIPS from a model hub as weight files only. HIPS will run those files on its own inference engines: no executable code from your model’s repository (scripts, libraries or custom operators) will run anywhere in the network, a language model’s chat template will be read as data and rendered only inside the inference engine’s sandbox, and files that would need code to load will be refused when the model is imported.

### Request inputs and generated outputs

On Free/PAYG and the lower paid plan, request inputs and generated outputs may be used for training. This includes requests processed by customer-owned models.

On the higher paid plan, request-data training is off by default. The Console will show the applicable policy so that teams can understand it before sending work.

Retention, deletion, and any other permitted uses will be set out in the service terms before production access. Turning training off is not, by itself, a promise of zero retention.

When you submit a batch job, HIPS will keep its input file, and the output and error files it produces, for 30 days, or for less if you set a shorter expiry or delete them sooner. Their content will follow the same request-data policy as requests sent one at a time. Prompt caches will be kept apart for each workspace, and personal GPUs will not keep one at launch.

### Where computation happens

HIPS will centrally coordinate inference across independently supplied GPUs. For customer-owned models, customers will select between personal GPUs and an approved-provider pool.

The choices must disclose the relevant model-access conditions as well as price and availability. Cross-pool fallback will be off by default and require explicit enablement. It must not override region or data-use rules.

Customer models will run in the approved-provider pool first. Personal GPUs will follow later, only for supported ONNX models and only for deployments you opt in. If you opt in, the device owner’s machine will hold your model’s weights while it serves your requests.

### Encryption and runtime access

Encryption in transit and at rest is part of the platform requirements. It protects data during transfer and storage, but does not by itself prevent a GPU operator from accessing weights or request data during execution.

We will publish the execution protections and access conditions for each pool before customers deploy workloads to it.

### Organization controls

The higher paid plan is intended to include region selection and single sign-on. The scope of region controls, including how they apply to processing and related data, will be specified before that feature is offered.

### Early-access information

The contact details you submit to join early access are enrollment information, not inference request data. They require a separate privacy notice explaining how we use them for access updates and how you can withdraw.

## AI inference for assistants and agents
Route: https://hips.com/inference/use-cases/assistants-and-agents

# AI inference for assistants and agents

Give your application a way to respond, summarize, and work with language.

### AI inference for assistants and agents

HIPS is being built for developers who want to connect open-weight models to useful experiences, from an assistant inside a product to a model step in a larger workflow. Start with a representative conversation, test how the model behaves, and understand its input and output token costs.

Bring a model you have trained when your application needs specialized behavior. Compare shared inference with always-on capacity as your workload develops.

## AI inference for document processing
Route: https://hips.com/inference/use-cases/document-processing

# AI inference for document processing

Turn documents into information your application can use.

### AI inference for document processing

Combine supported vision, language, and specialist models to explore extraction, summarization, document classification, and question answering. A useful workflow starts with real document examples and a clear definition of a correct result.

Choose models around the document type and task, then evaluate the output before putting it into a business process. The data policy applies to uploaded content and generated outputs, so select the appropriate plan before sending sensitive material.

### Send a large set of documents as one batch

When the results are not needed right away, a batch job will take many documents in one file. HIPS will run the lines when capacity is free and tell you when the batch is done, inside the completion window you choose: 24 hours by default, up to 7 days.

Batch will cost 50% less than on-demand for the same model, with the price known before you submit. Lines that have not finished when the window closes come back as expired and are not charged.

## AI inference for image and video
Route: https://hips.com/inference/use-cases/image-and-video

# AI inference for image and video

Build visual generation into your product or creative workflow.

### AI inference for image and video

Explore models that turn inputs into images or video, compare their supported controls, and understand how settings affect usage. HIPS is being designed to bring those capabilities into the same model catalog, playground, and account as other inference tasks.

For production workflows, start with the output you need: format, dimensions, duration, and the rights required for its use. The supported model and its terms determine what is possible.

## AI inference for speech and audio
Route: https://hips.com/inference/use-cases/speech-and-audio

# AI inference for speech and audio

Give audio a useful place in your application.

### AI inference for speech and audio

Transcription, translation, and speech generation each ask something different of a model. HIPS is preparing support for audio workflows within its broader inference platform, with model-specific inputs, outputs, and billing units.

Evaluate the languages and sound conditions relevant to your use case. Choose around the quality and processing behavior you need, whether the output is text, translated content, or generated speech.

## AI inference for classification and content analysis
Route: https://hips.com/inference/use-cases/classification-and-content-analysis

# AI inference for classification and content analysis

Sometimes the useful output is a category, a score, or a decision about what happens next.

### AI inference for classification and content analysis

Use specialist or general models to explore ticket routing, document categories, content attributes, and other defined classification tasks. HIPS will express classifier benchmarks per 1,000 defined classifications so the workload behind the comparison stays clear.

Evaluate errors as well as correct results. A classification that helps route a support ticket has different consequences from one that triggers an irreversible action.

### Classify a backlog as one batch

A backlog of tickets, records, or content items rarely needs an answer within seconds. A batch job will take the whole set in one file and run it when capacity is free, inside the completion window you choose: 24 hours by default, up to 7 days.

Batch will cost 50% less than on-demand for the same model and unit. Lines that have not finished when the window closes come back as expired and are not charged.

## AI inference for software and SaaS
Route: https://hips.com/inference/use-cases/software-and-saas

# AI inference for the features your users need

The next useful feature in your product might be an assistant, a document workflow, or a small decision that saves someone a repetitive step.

HIPS is building managed inference for software teams that want to put those ideas into their applications. Work with open-weight models or bring a model trained for your product, through a familiar integration path.

### Start with a useful interaction

Add language assistance where users already work. Summarize an activity feed, draft a response from supplied context, or help someone find the next action in a document. For focused tasks, a classifier can route an input or assign a category without generating a long answer.

Choose the model around the task and test it with representative inputs before expanding the feature.

### Make the cost part of the design

A prototype and a busy production feature have different needs. Compare usage-based inference with capacity that keeps your model loaded. Follow input and output tokens, classification units, and the cost of each workflow in the Console.

Keep your team’s data policy and execution choices visible as the product grows.

## AI inference for ecommerce and retail
Route: https://hips.com/inference/use-cases/ecommerce-and-retail

# AI inference for the work behind your storefront

A better shopping experience depends on a lot of work customers never see: clear product information, useful imagery, organized catalogs, and responsive support.

HIPS is building an inference platform for teams bringing AI into those workflows, with language, vision, image, and specialist models connected through one service.

### Turn a growing catalog into usable information

Use language and vision models to explore product descriptions, attribute extraction, and category suggestions. A defined classification task can help organize incoming items or route uncertain records for review.

Keep the original product facts close to the workflow. Model output should help your team prepare accurate listings, with human review where the consequences call for it.

### Give creative and support teams a starting point

Explore image generation for concepts and campaign variations. Use language models to summarize customer conversations or prepare a draft reply from the information your application supplies.

The useful question is what each model contributes to the job. Compare output quality, relevant usage units, and the settings that affect the bill.

### Build around your store

Connect supported inference into the systems your team already uses. Bring a customer-owned model when your catalog or workflow calls for specialized behavior, and choose the plan whose request-data policy fits the material you send.

## AI inference for creative and media workflows
Route: https://hips.com/inference/use-cases/creative-and-media

# More room to make

Creative work moves through possibilities before it arrives at a finished result. A useful inference platform should make those experiments easier to explore and their costs easier to follow.

HIPS is building access to image, video, audio, and language models for applications and creative workflows. Start with the medium and result you need, then choose a supported model around the work.

### Move from a brief to a direction

Explore visual concepts, generate variations, or use language models to develop a brief into prompts and structured instructions. Audio models can contribute transcription or speech where the workflow calls for them.

The model’s controls matter. Dimensions, duration, output format, and supported settings shape both the result and the usage.

### Give experiments a clear cost

Compare the billing unit before running a large set of variations. Follow work and outputs in the Console, including longer-running tasks where supported.

When a workflow relies on a model of your own, compare the available execution pools and always-on capacity. Keep model access conditions and request-data policy part of that choice.

### Keep the final decision creative

Treat generation as material to work with. Review the result, check the model’s usage terms, and decide what belongs in the finished piece.

## Earn with your GPU
Route: https://hips.com/earn

# Earn with your GPU

Your GPU can do more when you are not using it.

We’re building a way to contribute available GPU capacity to HIPS and earn when it runs inference. Whether you have a personal computer or operate data-center capacity, register your interest in becoming a provider.

### Your GPU on your schedule

Choose when your GPU is available and set the minimum price you’re willing to accept.

A small background app will detect when your computer is idle and automatically offer spare GPU time within your settings. You keep control of the schedule and minimum price, and earn when eligible inference work uses that time.

### Come back to your computer

When you return, HIPS will stop assigning new work and give active work a short window to finish.

### See work and earnings clearly

Follow your devices and availability in **My GPUs**, and your income and payouts in **GPU earnings**.

See the work your GPU completes, the earnings being processed, and the funds ready for payout. Earnings depend on eligible work being assigned and performed.

### A fit for different kinds of supply

Personal GPUs can contribute to the shared inference pool during suitable availability windows. Data-center providers can offer capacity for workloads that need continuous allocation.

### Payouts that reflect where you operate

Payout options will depend on where you operate, with payouts to bank accounts intended where available. Your account will show the methods and terms that apply to you.

### Register your interest

Leave your email for provider updates. You can also share your country and hardware if you would like to help us understand the capacity you want to contribute.

## AI inference pricing that follows the work
Route: https://hips.com/pricing

# AI inference pricing that follows the work

Start with a monthly free allowance, pay for additional inference as you use it, or choose a monthly plan with included credits and more controls.

HIPS is preparing for early access. Join the list for availability updates and the prices and allowances that will accompany paid access.

### Three ways to start

### Pay for the work each model does

Language models will have separate rates for input and output tokens. Classification prices will be expressed per 1,000 defined classifications, with the task and input conditions clearly stated. Image, video, and audio models will use billing units appropriate to the work they perform.

Always-on capacity is charged by allocated time. Customer-owned models will be profiled before a tariff is assigned.

Account credits are a balance used to pay for services. They are different from model usage units.

### Market pricing and a stable option

Market pricing will reflect changing supply and demand. A stable-price option will give customers another way to plan their spend.

Compare the quoted rate and the period it covers. Choose the option that fits the way you want to manage your budget; stable-price duration and eligibility will be defined before purchase.

### Find your starting point

Begin with the free allowance when access opens, then choose the plan and payment option that fit your work. Complete credit and subscription terms will accompany the published plans.

## More room to build
Route: https://hips.com/company/about

# More room to build

Every AI product needs somewhere to run. HIPS is bringing GPU capacity from personal computers and data centers into reach for the teams creating those products.

We’re building managed inference for companies and individual developers: a way to use open-weight models, deploy models of your own, and connect useful capacity to useful work. HIPS will manage the coordination so builders can focus on what they want to make.

AI inference is becoming our primary business. HIPS Payments continues as a separate division.

### Our mission

Bring available GPU capacity together so businesses and developers can put their models to work.

That means making model access simpler, costs easier to understand, and participation practical for the people contributing compute.

### Our vision

More useful AI, within reach of more builders.

We want a wider range of people and companies to be able to turn ideas into working applications. Making more of the compute already available is one part of that future.

### Connecting capacity to possibility

Our background is in high-volume payment networks: connecting participants, coordinating transactions, and making complex infrastructure useful to the people relying on it.

We’re bringing that experience to AI inference. Across personal computers and data centers, GPU capacity can serve different kinds of work. HIPS brings those resources together around the models that businesses and developers want to run.

The opportunity is simple: put more available compute to work, and bring more AI ideas within reach. Inference is our primary focus, while HIPS Payments continues as a separate division.

### How we work

Make the next step clear. Explain what the customer is choosing and what it costs. Respect the policies attached to a workload. Build around useful applications. Show the difference between what is available and what comes next.

These are simple ideas, but they affect everything from a model page to an interrupted job.

### HIPS Payments

Looking for our payments business? HIPS Payments remains a separate division with its own product and customer needs.

### Talk to HIPS

Interested in running models, contributing GPUs, or discussing a potential partnership? Tell us what you are working on and we’ll route your inquiry to the right team.

## Resources
Route: https://hips.com/company/resources

# Resources

### Docs

The Docs section: previews of the developer hub, the Quickstart, Migrate to HIPS and the HIPS SDK.

Route: https://hips.com/docs

### Security and Data

How model weights, request inputs and generated outputs will be used.

Route: https://hips.com/inference/security

### Legal

The terms, policies and notices of HIPS, in force.

Route: https://hips.com/legal

### Machine-readable

Plain-text files for AI tools and security researchers.

- llms.txt: https://hips.com/llms.txt : A short summary of HIPS and its pages, for AI tools.
- llms-full.txt: https://hips.com/llms-full.txt : The full text of the site, for AI tools.
- security.txt: https://hips.com/.well-known/security.txt : Where to report a security issue.

## Contact HIPS
Route: https://hips.com/company/contact

# What are you building

Tell us what you want to do with HIPS and we’ll help direct the conversation.

### What are you building

**Run AI models.** Join early access for inference updates, or describe the application, model, or workload you want to bring to HIPS.

**Earn with your GPU.** Register GPU interest if you have personal hardware or data-center capacity to contribute. Hardware details are optional at enrollment.

**Work with HIPS.** Share a partnership or project inquiry and the context we need to understand it. Start with a short description rather than confidential model weights, credentials, or customer data.

**Looking for payments support?** HIPS Payments continues as a separate division. Use the HIPS Payments destination for its products and existing-customer support.

## Affiliate program

- Affiliate program: https://hips.com/affiliates : How the HIPS affiliate program works: your referral link and code, the discount for people you refer, commissions, holds, payouts and the program rules. (The affiliate program opens later.)

## An AI inference API for developers
Route: https://hips.com/docs
Status: preview; updated 2026-10-21

**Familiar code. A new inference network.**

For open-weight language models, we’re designing HIPS to work with familiar coding tools and supported provider-style client SDKs, starting with OpenAI-style integrations. Connect your client with a HIPS API key, base URL, and supported model ID, and let HIPS coordinate the GPU capacity behind each request.

These developer pages preview the intended experience. Credentials, endpoint addresses, the model catalog, and compatibility details will be supplied with access.

- [Start with your language](/docs/quickstart): Python, JavaScript, or cURL: the first request, small and easy to inspect.
- [Put HIPS into your workflow](/docs/tools): Coding tools, each with its own supported configuration and tested behavior.
- [Go beyond language models](/docs/sdk): The HIPS SDK for image, video, audio, and specialist models such as classifiers.

### Start with your language

Follow examples in Python, JavaScript, or cURL. Test a small request, inspect the result and usage, then build around the model’s supported features.

Python preview:

```
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HIPS_API_KEY"],
    base_url=os.environ["HIPS_BASE_URL"],  # https://ai.hips.com/v1
)
result = client.chat.completions.create(
    model=os.environ["HIPS_MODEL"],
    messages=[{"role": "user", "content": "Explain GPU inference in two sentences."}],
)
print(result.choices[0].message.content)
```

JavaScript preview:

```
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.HIPS_API_KEY,
  baseURL: process.env.HIPS_BASE_URL, // https://ai.hips.com/v1
});
const result = await client.chat.completions.create({
  model: process.env.HIPS_MODEL,
  messages: [{ role: "user", content: "Explain GPU inference in two sentences." }],
});
console.log(result.choices[0].message.content);
```

cURL preview:

```
# HIPS_BASE_URL is https://ai.hips.com/v1
curl "$HIPS_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$HIPS_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"Explain GPU inference in two sentences.\"}]}"
```

The goal is a familiar integration path with clear boundaries. Model behavior, available parameters, and supported endpoints will be documented explicitly. HIPS will not host OpenAI’s proprietary models simply because it uses a compatible request style.

### Put HIPS into your workflow

We also want developers to use HIPS with coding tools, including Claude Code where compatibility can be established. Each tool needs its own supported configuration and tested behavior.

An intended setup helper will guide configuration for supported tools. Tool-specific instructions will explain what changes, how credentials are handled, and how to restore the previous setup.

### Go beyond language models with the HIPS SDK

The HIPS SDK will provide the intended path for other supported model types, including image, video, audio, and specialist models such as classifiers. [Import your supported model](/docs/import-and-run) from Hugging Face, then use the SDK to send inputs and work with its results. The guides will explain each task’s request format, usage units, and result handling.

### Which path applies to which model

Two integration paths, never mixed on one page. A client guide documents only the OpenAI-compatible routes and only language models; an SDK guide documents only the task API and the model types it serves.

| Work | Path | Where to read |
| --- | --- | --- |
| Open-weight language models from the catalog, and customer-owned language models in supported architectures | A provider-style OpenAI client with a HIPS key, the base URL `https://ai.hips.com/v1` and a model or deployment id | [Quickstart](/docs/quickstart), [Migrate to HIPS](/docs/migrate), [Chat completions](/docs/reference/chat-completions) |
| Every other supported model type (image, video, audio, classifiers and other specialist models), and customer-owned models of those types | The HIPS SDK over the task API: tasks, jobs, uploads | [HIPS SDK](/docs/sdk), [Task guides](/docs/tasks), [Tasks](/docs/reference/tasks) |

## Your first HIPS inference request
Route: https://hips.com/docs/quickstart
Status: preview; updated 2026-10-21

The first request should be small and easy to inspect. This preview shows the intended setup for a supported chat-completion model using familiar clients.

HIPS will supply the API root, a supported model or deployment identifier, and instructions for creating a key. The environment variables below are configuration names, not live credentials or service addresses.

### Five steps

1. Create a HIPS API key in the Console and store it as HIPS_API_KEY.
2. Set HIPS_BASE_URL to the API root supplied with your access.
3. Set HIPS_MODEL to a supported model or deployment identifier.
4. Send a small request using the example for your language.
5. Check the result, usage, and applicable charge before expanding the workload.

Python preview:

```
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HIPS_API_KEY"],
    base_url=os.environ["HIPS_BASE_URL"],  # https://ai.hips.com/v1
)
result = client.chat.completions.create(
    model=os.environ["HIPS_MODEL"],
    messages=[{"role": "user", "content": "Explain GPU inference in two sentences."}],
)
print(result.choices[0].message.content)
```

JavaScript preview:

```
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.HIPS_API_KEY,
  baseURL: process.env.HIPS_BASE_URL, // https://ai.hips.com/v1
});
const result = await client.chat.completions.create({
  model: process.env.HIPS_MODEL,
  messages: [{ role: "user", content: "Explain GPU inference in two sentences." }],
});
console.log(result.choices[0].message.content);
```

cURL preview:

```
# HIPS_BASE_URL is https://ai.hips.com/v1
curl "$HIPS_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$HIPS_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"Explain GPU inference in two sentences.\"}]}"
```

These examples illustrate a future interface contract. Confirm the client version, route, model, and supported fields in the launch documentation before using them. Keep keys on the server or in an appropriate secret store, rather than shipping them in a public browser application.

### What comes back

Every route is relative to the base URL, `https://ai.hips.com/v1`, the value of `HIPS_BASE_URL` that each sample names in its comment.

A chat completion in OpenAI's shape. Its `id` is the request id (`req_...`), the same value as the `x-hips-request-id` header, so a log line and a support question name the same thing. `usage` holds the token counts; the charge is in the `x-hips-cost-micros` header, never in `usage`. The [Usage](/docs/reference/usage) and [Requirements and headers](/docs/reference/headers) pages list every field.

### Client guides

One guide per provider-style client and version is added only with a validated row in the [compatibility matrix](/docs/operating/compatibility). None exists at launch.

## Move your inference API to HIPS
Route: https://hips.com/docs/migrate
Status: preview; updated 2026-10-21

Keep the client patterns you know. For supported OpenAI-style integrations, the intended starting point is three settings: your HIPS API key, base URL, and model.

Our migration guide will help you choose a model, check the features your application uses, and compare results before moving traffic.

**Familiar tools, with a new inference network behind them.**

### Check what your application uses

Review the endpoints, parameters, response fields, streaming behavior, structured outputs, and tool calls your application depends on. A shared client format does not mean every provider feature or model behavior is identical.

For image, audio, video, and specialist tasks, follow the relevant task guide. Some workflows may require asynchronous jobs or a different request shape.

> Prelaunch: The [compatibility matrix](/docs/operating/compatibility) is required before migration is encouraged. Every row is unvalidated at launch, so the matrix is empty of supported rows until then.

### Test quality and operating behavior

Start with a small representative set of inputs. Compare output usefulness, errors, latency, and measured cost. Confirm the applicable data-use policy and execution requirements.

Add streaming, concurrency, and failure handling after the simplest request works. Follow the documented rate limits and retry rules, including how charges are handled. Do not assume that every failed or retried attempt has the same billing outcome.

The rules are on [Retries and billing outcomes](/docs/operating/retries) and [Data handling](/docs/operating/data).

### Move deliberately

Keep your existing configuration recoverable. Begin with limited traffic and use the Console to understand results and usage. Expand after the integration and selected models meet your requirements.

### Where HIPS differs by design

Three settings move; three things do not behave as a drop-in. Nothing is silently dropped: a field that would change the output or the bill and that the named model cannot honor is a 400, never ignored. Nothing is silently substituted: the model served is the model named. A requirement is never weakened to make a request succeed.

| Where | OpenAI's behavior | HIPS |
| --- | --- | --- |
| Unknown model | `invalid_request_error` | 404 `not_found_error`, code `model_not_found` |
| Rate limit | `type` carries the dimension | `rate_limit_error` with the dimension in `param` |
| `n` | Several answers per request | `1` only: one quote, one line on the bill |
| `store`, `metadata` | Accepted | 400 `stateful_not_supported`: the gateway stores no bodies |
| Completion `id` | A completion id | The request id, `req_...` |
| Extras | In the body | In `x-hips-*` headers, and in the `hips` object of a stream's final usage chunk |

## The HIPS SDK for other supported model types
Route: https://hips.com/docs/sdk
Status: preview; updated 2026-10-21

**Go beyond language models with the HIPS SDK**

The HIPS SDK will provide the intended path for other supported model types, including image, video, audio, and specialist models such as classifiers. [Import your supported model](/docs/import-and-run) from Hugging Face, then use the SDK to send inputs and work with its results. The guides will explain each task’s request format, usage units, and result handling.

### Eight languages, released together

The HIPS SDK will ship in Python, TypeScript and JavaScript, Go, Rust, Java (usable from Kotlin), .NET, PHP and Ruby, released together. Package names and methods are not yet decided (not decided yet); each language's page previews its configuration, a first task and its idioms.

| Language | Runtime | Repository |
| --- | --- | --- |
| [Python](/docs/sdk/languages/python) | Python 3.10 and newer | `hips-ai/hips-sdk-python` |
| [TypeScript and JavaScript](/docs/sdk/languages/node) | Node 20 and newer, Deno, Bun, edge runtimes | `hips-ai/hips-sdk-node` |
| [Go](/docs/sdk/languages/go) | Set with the build | `hips-ai/hips-sdk-go` |
| [Rust](/docs/sdk/languages/rust) | Set with the build | `hips-ai/hips-sdk-rust` |
| [Java (usable from Kotlin)](/docs/sdk/languages/java) | JVM 17 and newer | `hips-ai/hips-sdk-java` |
| [.NET](/docs/sdk/languages/dotnet) | .NET 8 and newer | `hips-ai/hips-sdk-dotnet` |
| [PHP](/docs/sdk/languages/php) | PHP 8.2 and newer | `hips-ai/hips-sdk-php` |
| [Ruby](/docs/sdk/languages/ruby) | Ruby 3.2 and newer | `hips-ai/hips-sdk-ruby` |

> No install command or package name appears until the package names are decided and every SDK passes the shared conformance suite (not decided yet). Swift, Kotlin-native and Dart get a page only if they ship.

### The same task in every language

One call, a classification task against your own model's deployment, as each SDK will write it. The names are proposals and the shapes illustrative; each language's page has the rest.

Python:

```
from hips import Hips

# Reads HIPS_API_KEY and HIPS_BASE_URL (https://ai.hips.com/v1);
# fails without a key.
client = Hips()

result = client.tasks.run(
    deployment="dep_...",
    input={"text": "I was charged twice and nobody has replied."},
    requirements={"pool": "approved", "pricing_mode": "stable"},
)

print(result.output.label)       # the model's label, as sent
print(result.usage.units)        # in the model's billing unit
print(result.meta.cost_micros)   # what this request cost
print(result.meta.request_id)
```

TypeScript:

```
import { Hips } from "@hips-ai/sdk";

// Reads HIPS_API_KEY and HIPS_BASE_URL (https://ai.hips.com/v1);
// fails without a key.
const client = new Hips();

const result = await client.tasks.run({
  deployment: "dep_...",
  input: { text: "I was charged twice and nobody has replied." },
  requirements: { pool: "approved", pricingMode: "stable" },
});

console.log(result.output.label, result.usage.units);
console.log(result.meta.costMicros, result.meta.requestId);
```

Go:

```
// Reads HIPS_API_KEY and HIPS_BASE_URL (https://ai.hips.com/v1);
// fails without a key.
client, err := hips.NewClient()
if err != nil {
	return err
}

result, err := client.Tasks.Run(ctx, hips.TaskParams{
	Deployment:   "dep_...",
	Input:        map[string]any{"text": "I was charged twice and nobody has replied."},
	Requirements: &hips.Requirements{Pool: "approved", PricingMode: "stable"},
})
if err != nil {
	return err
}

fmt.Println(result.Output.Label, result.Usage.Units)
fmt.Println(result.Meta.CostMicros, result.Meta.RequestID)
```

Rust:

```
use hips::{Client, Requirements, TaskParams};
use serde_json::json;

// Reads HIPS_API_KEY and HIPS_BASE_URL (https://ai.hips.com/v1);
// fails without a key.
let client = Client::new()?;

let result = client
    .tasks()
    .run(TaskParams {
        deployment: Some("dep_...".into()),
        input: json!({ "text": "I was charged twice and nobody has replied." }),
        requirements: Some(Requirements::new().pool("approved").pricing_mode("stable")),
        ..Default::default()
    })
    .await?;

println!("{} {}", result.meta.cost_micros, result.meta.request_id);
```

Java:

```
import com.hips.sdk.Hips;
import com.hips.sdk.Requirements;
import com.hips.sdk.TaskParams;
import com.hips.sdk.TaskResult;
import java.util.Map;

// Reads HIPS_API_KEY and HIPS_BASE_URL (https://ai.hips.com/v1);
// fails without a key.
Hips client = new Hips();

TaskResult result = client.tasks().run(TaskParams.builder()
    .deployment("dep_...")
    .input(Map.of("text", "I was charged twice and nobody has replied."))
    .requirements(Requirements.builder().pool("approved").pricingMode("stable").build())
    .build());

System.out.println(result.meta().costMicros() + " " + result.meta().requestId());
```

.NET:

```
using Hips.Sdk;

// Reads HIPS_API_KEY and HIPS_BASE_URL (https://ai.hips.com/v1);
// fails without a key.
var client = new HipsClient();

var result = await client.Tasks.RunAsync(new TaskParams
{
    Deployment = "dep_...",
    Input = new { text = "I was charged twice and nobody has replied." },
    Requirements = new Requirements { Pool = "approved", PricingMode = "stable" },
});

Console.WriteLine($"{result.Meta.CostMicros} {result.Meta.RequestId}");
```

PHP:

```
<?php

use Hips\Sdk\Hips;

// Reads HIPS_API_KEY and HIPS_BASE_URL (https://ai.hips.com/v1);
// fails without a key.
$client = new Hips();

$result = $client->tasks->run([
    'deployment' => 'dep_...',
    'input' => ['text' => 'I was charged twice and nobody has replied.'],
    'requirements' => ['pool' => 'approved', 'pricing_mode' => 'stable'],
]);

echo $result->meta->costMicros, ' ', $result->meta->requestId, PHP_EOL;
```

Ruby:

```
require "hips"

# Reads HIPS_API_KEY and HIPS_BASE_URL (https://ai.hips.com/v1);
# fails without a key.
client = Hips::Client.new

result = client.tasks.run(
  deployment: "dep_...",
  input: { text: "I was charged twice and nobody has replied." },
  requirements: { pool: "approved", pricing_mode: "stable" },
)

puts result.meta.cost_micros, result.meta.request_id
```

### What the SDK wraps

The SDK wraps the HIPS task API, the versioned contract for every model type other than open-weight language models: `POST /v1/tasks` for synchronous work, `POST /v1/jobs` with `GET /v1/jobs/{id}` for asynchronous work, `POST /v1/uploads` for task inputs, and the read side of deployments and models.

The SDK runs a customer model through its deployment and never imports a model, uploads weights or handles a hub token: the import is the Console's, described on [Import and run your model](/docs/import-and-run).

For open-weight language models the SDK adds nothing: the OpenAI client is the client, and the SDK's documentation says so rather than wrapping it. A customer who uses both paths holds one key and one base URL; the OpenAI client and the HIPS SDK read the same three environment variables, `HIPS_API_KEY`, `HIPS_BASE_URL` and `HIPS_MODEL`; the base URL is `https://ai.hips.com/v1`.

### What the SDK adds

- Typed methods per task type with the result shapes the catalog defines.
- An upload helper that sends an input through `POST /v1/uploads` above an inline threshold and names the `upl_` id.
- An `idempotency-key` generated per task and job call, so a retry can never double-bill.
- Polling of `GET /v1/jobs/{id}` with backoff and a wait helper.
- Retries on 429 and 503 honoring `Retry-After`, and on connection failures before any byte; never on a 400.
- The error envelope as typed exceptions by `type` and `code`.
- The `x-hips-*` headers and the streamed `hips` object as typed fields.
- The requirement object (pool, pricing mode, region, fallback) as a per-client default and a per-call override; the SDK sends the `hips` body object and never the headers on the task API.

### What the SDK never does

- No telemetry: nothing is sent that the call does not need.
- No second network destination, except the upload PUT to the address the API returned, always on a HIPS-controlled host over https.
- No stored keys: the key is read from an argument or the environment and never written to a file, a keychain or a cache; it is never logged.
- No caching, no deduplication, no thresholds, no interpretation: a score is returned as sent.
- No model substitution and no weakened requirement: the SDK sends what it was given; the server rejects what it cannot serve.

### One behavior for every language

A language's SDK is released only when it implements the whole specification and passes the whole conformance suite: a language-neutral case file, a mock server for behavior cases, and a smoke test against the hosted API. There are no partial SDKs and no language-only features.

### SDK task guides

One guide per task follows, each with the request format, the usage unit and the result handling, in that order. Until the languages are decided, the [task guides](/docs/tasks) carry the wire shapes of the task API, which every SDK method maps onto.

## Import and run your model
Route: https://hips.com/docs/import-and-run
Status: preview; updated 2026-10-21

The import-to-inference workflow for a customer model, end to end. A customer model is imported from a model hub, never uploaded, and it runs as weight files on HIPS's own engines: no code from its repository runs anywhere.

The import runs from the Console in the first version, so this page describes the Console's steps in words and shows no command. A request sample for importing appears only once a public import route is decided and validated (not decided yet).

### What a customer model is

A model you import from a model hub: weight files only, run by HIPS's own engines, vLLM for a language model in data centers and ONNX Runtime for every other model type. Nothing is uploaded: `POST /v1/uploads` carries task inputs only ([Uploads](/docs/reference/uploads)).

| Id | What it is |
| --- | --- |
| `mdl_` | The customer model: its name, its task and its versions |
| `imp_` | One import of a repository at a revision. It ends `ready`, `refused` or `failed` |
| `ver_` | A version, made by an import that ends `ready`: signed, immutable, with its source and license record. A refused or failed import makes none |
| `dep_` | A deployment: a version made runnable, the id your requests name |

In the Console an import takes seven steps, on My models and deployments:

1. Hub: the hubs whose adapters have shipped, Hugging Face first.
2. Repository and revision: the repository in the hub's own form and a branch, a tag or a commit.
3. Access: a public repository with no token, or one of the workspace's stored hub tokens.
4. Model: a new customer model's name and task, and for a model that is not a language model its task definition; or a new version of an existing one.
5. Where it may run: read-only, the pools the task can use and the region its copy is stored in.
6. License: the attestation, ticked before Import is enabled.
7. Review: everything above, then Import, which opens the import's own page.

### Hubs

Hugging Face model repositories, public, gated or private. Another hub is named on this page only once its adapter ships (not decided yet). A Hugging Face Space is an application and a dataset is data: neither is a model source.

You name the repository in the hub's own form, `owner/name` on Hugging Face, and a revision: a branch, a tag or a commit. A pasted address of the repository's page is reduced to the name and, where it carries one, the revision.

### Access tokens

A public repository needs no token. A private or gated repository needs your access token for the hub: for Hugging Face, a fine-grained, read-only token scoped to the repository is asked for. For a gated repository, its terms are accepted on the hub by the token's own account, never by HIPS.

> HIPS stores read-only tokens only. A token the hub reports as able to write is refused and not kept. A read-only token that reaches beyond the repositories you name, or one whose permissions the hub does not report, is stored only after a warning and a second confirmation in the Console, and is only ever used to read.

- Kept encrypted under a cloud key; only its last four characters are ever shown.
- Used only in the import job, and never sent to a data-center worker, its RunPod pod or a device.
- Reused when you import a newer revision.
- Deleted when you delete it. Deleting it at HIPS does not revoke it at the hub.

Tokens are managed in the Console's Workspace settings, under Model-hub access tokens.

### Formats and what is refused

| Kind | What the import takes | Engine and pool |
| --- | --- | --- |
| Language model | safetensors in the Hugging Face repository layout, of an architecture on the engine's list, with its tokenizer files and its chat template where it has one | vLLM, in the `approved` pool: data centers only, at launch and after |
| Every other model type (classifier, vision, audio, video, specialist) | One ONNX graph with its external data files, within the runtime's opset range, with the task definition you give at import naming every input and output | ONNX Runtime, in the `approved` pool at launch |

What the repository holds besides the model (code, notebooks, images, a pickle file beside safetensors of the same weights) is listed on the import and never downloaded. A refusal ends the import with its reason code, the check and the file at fault, never the file's content:

*Refusals at import, as the Console shows them*

| Reason code | What it means | What to change |
| --- | --- | --- |
| `format_unsupported` | The repository has no weights in a format HIPS's engines load (safetensors in the Hugging Face layout for a language model, or ONNX for another model type), or what it has does not load: an architecture off the engine's list, an opset outside the runtime's range, a tokenizer that does not load, a task definition that does not match the graph. The failing check is named. | Choose a repository or revision that publishes safetensors or ONNX weights of a supported architecture, or correct the task definition. Formats are not converted at launch (not decided yet). |
| `code_required` | The model needs code from its repository to load: it asks for `trust_remote_code`, or its configuration carries an `auto_map`. Customer models run on HIPS's engines without any repository code. | Choose a model whose architecture the engine supports without custom code, or a revision that has none. |
| `pickle_weights` | The weights exist only as pickle files (`.bin`, `.pt`, `.pth`, `.ckpt`, `.pkl`, or any file whose bytes are a pickle, whatever its name), which can run code when they are loaded. A pickle file beside safetensors of the same weights is never opened and does not refuse the import. | Publish the weights as safetensors (or ONNX) in the repository and import that revision. |
| `custom_operator` | The ONNX graph uses an operator outside the standard domains of the ONNX Runtime release HIPS runs. | Export the model again with standard operators, within the supported opset range. |
| `external_data_outside` | The ONNX graph's external data points to a file outside the model's own files. | Export again with the external data stored beside the graph in the repository. |
| `template_refused` | The language model's chat template did not pass the template checks. A template is data, rendered only in the engine's sandboxed template environment on data-center workers. | Use the architecture's standard chat template, or remove what the check names. |
| `license_refused` | The license the hub records does not allow paid hosted inference under the license rules (not decided yet). | Choose a model whose license allows it, or contact HIPS about another license. |
| `access_denied` | The repository cannot be read: it is private or gated and no token was given, the token cannot read it (for a gated repository, its account has not accepted the terms), or there is no such repository. All three are answered alike, so an import never discloses whether a private repository exists. | Check the repository's name; accept the terms on the hub with the token's account; or choose or add a token that can read the repository. |
| `revision_not_found` | The repository was read and holds no such branch, tag, commit or version. | Check the revision, and import again. |
| `too_large` | The files exceed the size HIPS imports for this kind of model (not decided yet), or the model fits no hardware class of the `approved` pool. | Choose a smaller variant, or a quantization the engine loads. |

An import can also fail for a reason that is not the model's. Nothing is kept and no version is made; starting again is a new import:

*Failures that are not the model's*

| Failure | What happened | What to do |
| --- | --- | --- |
| `hub_unavailable` | The hub did not answer. | Retry. |
| `timed_out` | The import ran past its time limit (not decided yet). | Retry; a smaller variant if it happens again. |
| `credential_deleted` | The hub token the import used was deleted before the import had fetched with it. | Import again, choosing or adding a token. |
| `canceled` | A member canceled the import. | Import again. |
| `internal` | A failure on HIPS's side, with the request id for support. | Retry, or contact HIPS. |

### Revisions and versions

The revision you enter, a branch, a tag, a commit or a hub version, is pinned at import to the exact commit or version id. Later changes on the hub never reach the version.

| Import state | What happens |
| --- | --- |
| `queued` | Accepted, waiting for an import job |
| `fetching` | The revision is pinned, the hub's license is read, and only the files an engine reads are fetched. The only step that holds the hub token |
| `checking` | Each file is parsed with the pinned engine release, with no token and no network; what passes is re-saved: safetensors rewritten, ONNX re-serialized |
| `copying` | The re-saved files are copied once into encrypted HIPS storage in the workspace's storage region, where its deployments run. The import takes no region |
| `signing` | The copy is signed with a HIPS key and the version is created. Workers and devices load only that signed copy, never the hub |
| `ready`, `refused` or `failed` | A new version; or the reason code; or the failure. Only `ready` makes a version |

A version records its hub, repository, pinned revision, license, attestation time, the signed manifest's digest and the signing time. Importing a newer revision makes a new version and reuses the stored token. Versions are immutable. Deleting a version or a model removes HIPS's copies and never touches the hub. Stored models and a stopped deployment's weights cost $0.10 per GB-month while they are kept.

### Licenses

The hub's license is recorded on the version, and before importing you attest the right to run the model commercially as a hosted service. Which licenses allow paid hosted inference, and the attestation's text, are not yet decided (not decided yet), so this page states no license rule.

### Checks, profiling and the tariff

1. Engine fit, and hardware fit beyond VRAM: the weights must fit at least one hardware class of the `approved` pool.
2. Profiling on HIPS-operated capacity, per version, pool and hardware class: load time, memory, throughput at representative inputs, and correctness.
3. The tariff, assigned after profiling and never before. It belongs to the version, and every deployment of the version inherits it.

A version still profiling can serve an always-on deployment, charged by allocated time. A `shared` deployment may be created while its version's tariff is pending: it waits in `tariff_pending`, serving nothing and charged nothing, until the tariff takes effect.

### Pools

At launch every customer model runs in the approved-provider pool (`approved`) only. A language model in safetensors stays in data centers in every phase. The personal pool opens later to customer ONNX models only, on four conditions together:

- An opt-in per deployment that says in plain words that the device owner's machine holds the weights.
- The device engine sandboxed: a separate process with no network and no file access outside its model cache.
- The provider agreement binding device owners as processors.
- Verification sampling running.

Opt-in runs on both sides: such a deployment reaches only devices whose provider has turned on that device's own switch for customer models, which is off until the provider turns it on. The pool choice shows the quote, availability and runtime-access conditions together. Cross-pool fallback is off by default, never weakens a region or data-use rule, and reaches `personal` only on a deployment that opted in.

### Deploy and call

A deployment (`dep_`) runs on `shared`, or, from `approved` only, on `always_on`: the separate option for a model that must stay loaded, charged by allocated time, including between requests. The request-data policy is shown before the first request can be sent.

| Model type | Field | Route |
| --- | --- | --- |
| Language model | `model: "dep_..."` | `POST /v1/chat/completions`, through an OpenAI client |
| Every other model type | `deployment: "dep_..."` | `POST /v1/tasks` or `POST /v1/jobs`, through the [HIPS SDK](/docs/sdk) |

| Deployment state | Meaning |
| --- | --- |
| `allocating` | Capacity is being assigned; requests answer 503 `deployment_not_ready` with `Retry-After` |
| `loading` | The model is being loaded; the same answer |
| `tariff_pending` | A `shared` deployment waiting for its version's tariff; the same answer, and nothing is charged |
| `ready` | Serving |
| `busy` | Serving at capacity |
| `degraded` | Served; the state is visible in `GET /v1/models/{id}` |
| `stopped` | Requests answer 400 `deployment_stopped`; start it in the Console |

Allocation is not readiness: every transition is timestamped and explained in the Console. The [Deployments](/docs/reference/deployments) page has the read side.

### Your weights and your request data

> Policy: Customer-owned model weights will never be used to train other models on any plan.

> Policy: On Free/PAYG and the lower paid plan, request inputs and generated outputs may be used for training. This includes requests processed by customer-owned models. On the higher paid plan, request-data training is off by default.

The rest is on [Security and Data](/inference/security) and [Data handling](/docs/operating/data).

## Models and task guides
Route: https://hips.com/docs/models
Status: preview; updated 2026-10-21

A model page explains the supported task, input and output formats, relevant limits, model version, and billing units; where a model has specific licensing or usage conditions, those sit alongside the practical details. This page shows the catalog's shape. The catalog lists every model HIPS has published, each with its status, on [Models](/inference/models) and in `GET /v1/models`.

> Prelaunch: The catalog is the only source of model names, limits and prices. Nothing here is hardcoded, and no model id appears on these pages; samples use the `HIPS_MODEL` variable.

### What a model page carries

| Field | What it holds |
| --- | --- |
| Catalog id | The unversioned id (the alias) and the pinned ids of its versions |
| Display name | The name shown on the page and in `GET /v1/models`; no version in a display name |
| Family, size, variant | The three tokens of the id, as structured fields so the catalog can be filtered |
| Type and task | The model type and the task key the request is validated against |
| Modality | Inputs accepted (text, image, audio, video) and outputs returned |
| Formats | Input and output formats per modality; for language models, the runtime weight format per pool |
| Limits | Context length, maximum output tokens, images per request, input dimensions, audio or video duration, batch, upload size; set per model in the catalog |
| Version | The current version the alias resolves to; every pinned version with its status, release, deprecation and sunset dates |
| License and usage conditions | License name, the conditions that bind the customer and HIPS, the recorded source |
| Billing unit | The unit charged and the rates per pool and pricing mode; language models show input and output rates separately |
| Current availability | The supply state per pool: `available`, `limited`, `unavailable`, `unknown`, with its last update; a stale reading becomes `unknown` |
| Hardware fit | Per pool, the hardware classes the version fits, with engine and format per class |
| Supported features | For language models, each feature of the compatibility matrix with its validated status; unvalidated is shown as unvalidated |

### Model types and their routes

| Type | Task keys (working) | Public route |
| --- | --- | --- |
| `language` | `chat` (text in, text out; image inputs where the model is a vision-language model) | OpenAI-compatible routes |
| `image` | `image_generation`, `image_edit` | Task API |
| `audio` | `transcription`, `translation`, `speech` | Task API |
| `video` | `video_generation` | Task API |
| `specialist` | `classification`, `embedding`, `detection`, and further focused tasks as the catalog adds them | Task API |

A model is offered in a pool only when that pool's engine for its type runs it on at least one hardware class of the pool, as measured. The task list is set per model in the catalog.

### Ids, aliases and pinned versions

A catalog id (`<family>-<size>[-<variant>]`, lowercase) resolves to the current pinned version and moves with releases; a pinned id (`<catalog id>-<version>`) names one version and does not move. An alias moves with releases. Retirement of a pinned id and its notice period are open (not decided yet); a pinned id with a retirement date carries `deprecates_at` in `GET /v1/models`.

### What a model page never claims

No availability before the catalog's listing state says so. No accuracy or benchmark claim without a labeled evaluation set and task-relevant error measures. No cost or performance comparison without measured representative workloads with the comparison, model, hardware, configuration and date stated.

## Task guides
Route: https://hips.com/docs/tasks
Status: preview; updated 2026-10-21

One guide per task the source names: language (chat), classification, image, video, audio, and document processing as the combination of vision and language. Each says whether the task is synchronous (`POST /v1/tasks`) or asynchronous (`POST /v1/jobs`), and which route carries it.

| Task | Route | Mode |
| --- | --- | --- |
| [Language (chat)](/docs/tasks/chat) | `POST /v1/chat/completions` | Synchronous, streamed or not, on `POST /v1/chat/completions`. |
| [Classification](/docs/tasks/classification) | `POST /v1/tasks`, `POST /v1/jobs` | Synchronous on `POST /v1/tasks`; as a job on `POST /v1/jobs` for a large batch. |
| [Image](/docs/tasks/image) | `POST /v1/tasks`, `POST /v1/jobs` | Synchronous on `POST /v1/tasks` within the synchronous limits; long or batched generation on `POST /v1/jobs`. |
| [Video](/docs/tasks/video) | `POST /v1/tasks`, `POST /v1/jobs` | Asynchronous only, on `POST /v1/jobs`. |
| [Audio](/docs/tasks/audio) | `POST /v1/tasks`, `POST /v1/jobs` | Synchronous on `POST /v1/tasks` within the synchronous limits; `POST /v1/jobs` for long media. |
| [Document processing](/docs/tasks/document-processing) | `POST /v1/tasks`, `POST /v1/jobs` | The language step on `POST /v1/chat/completions` with `image_url` parts; the specialist steps (classification, detection, embedding) on `POST /v1/tasks`. |

### Which shape carries which model type

| Model type | Shape | Route |
| --- | --- | --- |
| Language model, text in and out | OpenAI | `POST /v1/chat/completions`, later `/v1/responses` |
| Language model with image input (vision) | OpenAI `image_url` parts | `POST /v1/chat/completions` |
| Image generation and editing | HIPS task | `POST /v1/tasks`; long or batched generation `POST /v1/jobs` |
| Audio: transcription, translation, speech | HIPS task | `POST /v1/tasks` within the synchronous limits; `POST /v1/jobs` for long media |
| Embeddings | HIPS task | `POST /v1/tasks`, task `embedding` |
| Video generation and understanding | HIPS job | `POST /v1/jobs` only |
| Classification, detection, specialist models | HIPS task | `POST /v1/tasks` |
| Customer-owned language model | OpenAI | `POST /v1/chat/completions` with `model: dep_...` |
| Customer-owned model of any other type | HIPS task | `POST /v1/tasks` or `POST /v1/jobs` with `deployment: dep_...` |

## Language (chat)
Route: https://hips.com/docs/tasks/chat
Status: preview; updated 2026-10-21

Text in, text out, with image inputs where the model is a vision-language model. The one task that does not go through the task API or the SDK.

| Task | Path | Mode |
| --- | --- | --- |
| `chat` | OpenAI-compatible | Synchronous, streamed or not, on `POST /v1/chat/completions`. |

### Request format

- OpenAI's chat completion body: `model`, `messages`, `stream`, and the accepted fields of the [chat completions reference](/docs/reference/chat-completions).
- `image_url` parts in a `user` message on a model advertising `vision`; `input_audio` and `file` parts are refused (audio goes through the task API).
- Tool calls, `json_object` and `json_schema` outputs, `logprobs` and `reasoning_effort` where the model advertises the feature; otherwise a 400 `unsupported_parameter`.

### Usage unit

- `input_output_tokens`: `prompt_tokens` and `completion_tokens` at the model's separate input and output rates, counted by the serving engine's tokenizer for the pinned model.
- With image inputs, tokens under the model's image-token rule; image count and dimensions change the charge.
- The charge is `x-hips-cost-micros`, or on a stream the `hips` object of the final usage chunk.

### Result handling

- OpenAI's `chat.completion` object; `id` is the request id. `finish_reason` is `stop`, `length` or `tool_calls`; `content_filter` is never emitted.
- Streamed: one `data:` line per chunk, a final usage chunk with `stream_options.include_usage`, then `data: [DONE]`. A failure after the stream started is one `data:` line with the error envelope and no `[DONE]`.

> Prelaunch: Every number a task guide needs (limits, durations, dimension bands) is set per model in the catalog and is not written here. The SDK guide of the same task follows once the SDK's package names are decided (not decided yet).

## Classification
Route: https://hips.com/docs/tasks/classification
Status: preview; updated 2026-10-21

An item evaluated once under the task's input conditions: text, an image, an audio clip or a feature vector, against the model's labels.

| Task | Path | Mode |
| --- | --- | --- |
| `classification` | Task API | Synchronous on `POST /v1/tasks`; as a job on `POST /v1/jobs` for a large batch. |

### Request format

- `model` (a catalog classifier) or `deployment` (your own); `task: "classification"`; `inputs` as the batch, each with `type` `text`, `image` or `audio` and `text`, inline `data` or an `upload_id`.
- `options` as the task definition states them: labels for a zero-shot classifier, `top_k`, a threshold where the model is multi-label.
- The whole batch runs on one worker; the maximum inputs per request is the model's `hips.limits.max_inputs`. An over-condition item is refused with a 400 (the alternative, counting it as several units, is open (not decided yet)).

### Usage unit

- `per_1000_classifications`: one classification is one item evaluated once under the task's input conditions; a batch of forty items is forty.
- `usage.units` counts the inputs and `usage.billed_units` the answered ones; an input the worker cannot read is not billed.

### Result handling

- One entry per input, in request order, with `input` the input's id: `labels: [{label, score}]` ordered by score, as the task definition's output states (softmax, sigmoid or logits; single-label or multi-label).
- A per-input failure is an `error` entry in the envelope's shape beside the other inputs' results.

> Prelaunch: Every number a task guide needs (limits, durations, dimension bands) is set per model in the catalog and is not written here. The SDK guide of the same task follows once the SDK's package names are decided (not decided yet).

## Image
Route: https://hips.com/docs/tasks/image
Status: preview; updated 2026-10-21

Image generation and editing. OpenAI's images shape is not served; the task API carries these model types.

| Task | Path | Mode |
| --- | --- | --- |
| `image_generation`, `image_edit` | Task API | Synchronous on `POST /v1/tasks` within the synchronous limits; long or batched generation on `POST /v1/jobs`. |

### Request format

- `model` or `deployment`; `task` `image_generation` or `image_edit`; for an edit, `inputs` with the source image inline or as an `upload_id`.
- `options` as the model exposes them: width and height, steps, number of outputs, and the passes the model exposes. An unsupported setting is rejected with a 400, never dropped.

### Usage unit

- `per_image`: per output image at a stated dimension band, and per step where the model exposes steps. Width and height, steps and the number of outputs change the charge.

### Result handling

- Inline for a task; for a job, `result.outputs: [{upload_id, download_url, content_type, bytes, expires_at}]` with a presigned GET, retrievable until `expires_at` (not decided yet).

> Prelaunch: Every number a task guide needs (limits, durations, dimension bands) is set per model in the catalog and is not written here. The SDK guide of the same task follows once the SDK's package names are decided (not decided yet).

## Video
Route: https://hips.com/docs/tasks/video
Status: preview; updated 2026-10-21

Video generation and video understanding: long-running work, results retrieved by id.

| Task | Path | Mode |
| --- | --- | --- |
| `video_generation` | Task API | Asynchronous only, on `POST /v1/jobs`. |

### Request format

- `model` or `deployment`; `task: "video_generation"`; `inputs` and `options` as the model exposes them: duration, resolution, frame rate, number of outputs.
- The job answers 202 at once with the job object; poll `GET /v1/jobs/{id}` or use the SDK's wait helper. Cancel with `POST /v1/jobs/{id}/cancel`.

### Usage unit

- `per_second`: per second of output video at a stated resolution and frame rate. Duration, resolution, frame rate and the number of outputs change the charge.

### Result handling

- `result.outputs` with a presigned GET per output, retrievable until `expires_at` (not decided yet); the job record and its usage stay. Every status transition carries a timestamp and, when the scheduler has one, an explanation.

> Prelaunch: Every number a task guide needs (limits, durations, dimension bands) is set per model in the catalog and is not written here. The SDK guide of the same task follows once the SDK's package names are decided (not decided yet).

## Audio
Route: https://hips.com/docs/tasks/audio
Status: preview; updated 2026-10-21

Transcription, translation and speech generation. Audio uploads go through `POST /v1/uploads`; an OpenAI audio shape after validation is open (not decided yet).

| Task | Path | Mode |
| --- | --- | --- |
| `transcription`, `translation`, `speech` | Task API | Synchronous on `POST /v1/tasks` within the synchronous limits; `POST /v1/jobs` for long media. |

### Request format

- `model` or `deployment`; `task` `transcription`, `translation` or `speech`; for audio in, `inputs` with `type: "audio"` and an `upload_id` (or inline `data` within the inline limit); for speech, `type: "text"` inputs.
- `options` as the model exposes them: language, diarization or word timestamps where offered, voice settings for speech.

### Usage unit

- `transcription`, `translation`: per minute of input audio, rounded as the pricing document states; diarization or word timestamps where priced separately.
- `speech`: per 1,000 input characters, or per second of output audio where the model's cost follows the output.

### Result handling

- A transcript with segments for transcription and translation; for speech, an output with a presigned GET on a job, or inline within the synchronous limits.

> Prelaunch: Every number a task guide needs (limits, durations, dimension bands) is set per model in the catalog and is not written here. The SDK guide of the same task follows once the SDK's package names are decided (not decided yet).

## Document processing
Route: https://hips.com/docs/tasks/document-processing
Status: preview; updated 2026-10-21

Document processing is the combination of vision and language: a vision-language model reads the page, a classifier or detector finds its structure, an embedding model indexes it.

| Task | Path | Mode |
| --- | --- | --- |
| vision and language, combined | Task API | The language step on `POST /v1/chat/completions` with `image_url` parts; the specialist steps (classification, detection, embedding) on `POST /v1/tasks`. |

### Request format

- Page images as `image_url` parts to a model advertising `vision`, with the extraction instructions in the prompt and, where the model advertises it, a `json_schema` response format for structured output.
- A classifier run on the same pages through `POST /v1/tasks` with `task: "classification"`; a detector through `detection`; embeddings through `embedding`.
- A long batch of pages as a job on `POST /v1/jobs`, with the pages uploaded once through `POST /v1/uploads` and named by `upload_id`.

### Usage unit

- Each step bills in its own unit: tokens for the language step (image count and dimensions change the charge), `per_1000_classifications` for the classifier, tokens for the embedding.

### Result handling

- Structured text from the language step; labels with scores from the classifier; vectors from the embedding; each with its own usage record and request id, so the Console shows the cost of each step.

> Prelaunch: Every number a task guide needs (limits, durations, dimension bands) is set per model in the catalog and is not written here. The SDK guide of the same task follows once the SDK's package names are decided (not decided yet).

## Coding-tool setup
Route: https://hips.com/docs/tools
Status: preview; updated 2026-10-21

Every tool is unvalidated at launch. A tool is listed where compatibility can be established, and only with a dated validation record. Each tool needs its own supported configuration and tested behavior.

We also want developers to use HIPS with coding tools, including Claude Code where compatibility can be established. An intended setup helper will guide configuration for supported tools. Tool-specific instructions will explain what changes, how credentials are handled, and how to restore the previous setup.

### The supported-tools matrix

A tool is listed as supported only after every column is tested on a stated version; one untested column keeps the row at `unvalidated`. HIPS Code is the first row and is tested first, since the company controls both ends.

| Tool | Versions tested | Configuration surface | Authentication | Model mapping | Streaming | Complete tool-call round trips | Status |
| --- | --- | --- | --- | --- | --- | --- | --- |
| HIPS Code | none | not tested | not tested | not tested | not tested | not tested | unvalidated |
| [Claude Code](/docs/tools/claude-code) | none | not tested | not tested | not tested | not tested | not tested | unvalidated |
| [Other coding tools and editor integrations](/docs/tools/openai-style-tools) | none | not tested | not tested | not tested | not tested | not tested | unvalidated |

### HIPS Code

HIPS Code is the company's own coding agent for the terminal and the desktop, a fork of an open-source project, rebranded and themed by HIPS, which will run on HIPS inference. It is the first row of the matrix and is tested first. It needs no API key: it signs in as you with OAuth device authorization, showing a code `XXXX-XXXX`, a QR code and a link in the terminal, which you approve in the Console while signed in, choosing the workspace its usage is attributed to; it keeps the tokens in the operating system's keystore ([how sign-in works](/docs/cli/login)). `HIPS_API_KEY` remains the path for CI and scripted use. Its page here is published once its HIPS provider is built against the gateway, with its validation record (not decided yet).

### What a tested value states

| Column | What a tested value states |
| --- | --- |
| Versions tested | The exact tool and client SDK versions, with the date; a newer version is untested until retested. |
| Configuration surface | Where the tool reads base URL, key and model (environment, file, flag, UI), and which the helper uses for session and for persistent configuration. |
| Authentication | How the tool sends the key, and that HIPS accepts it as `Authorization: Bearer`. |
| Model mapping | Which tool slots map to which catalog ids, and what the tool does with an id it does not know. |
| Streaming | That streamed completions arrive whole and in order over `POST /v1/chat/completions`, including the usage event the tool expects. |
| Complete tool-call round trips | That tool calls are emitted by the model, parsed and executed by the tool, and their results sent back in the next request, repeatedly, with every parameter the tool sends accepted. |
| Status | `unvalidated`; `experimental` (tested, with named gaps); `supported` (every column tested on the stated versions). |

### What gateway documentation does not establish

A coding tool's own gateway or proxy documentation describes that tool's expectations, not HIPS's compatibility with them. OpenAI compatibility alone does not establish another vendor's interface or a coding tool's protocol expectations: serving `POST /v1/chat/completions` says nothing about a Messages-style interface, a Responses-shaped tool loop, a tool's system-prompt conventions, its streaming event names or its retry behavior. Each is tested or it is unvalidated. Until a row says supported, no page says HIPS works with the tool.

### The three settings

Every tool that takes an OpenAI-style base URL is configured with the same three names: `HIPS_API_KEY`, `HIPS_BASE_URL` (`https://ai.hips.com/v1`) and `HIPS_MODEL`. No credential, and no command that implies a working integration, appears here until a row is validated.

### The setup helper

A future product, described as intended and never a download. It should discover the tool and version, prefer temporary session configuration first, preview persistent changes, back up existing settings, configure the published base URL, authentication and model mapping, avoid printing secrets, test only with permission to incur usage, and provide selective undo. It must not quietly change unrelated providers or global defaults.

## Claude Code
Route: https://hips.com/docs/tools/claude-code
Status: preview; updated 2026-10-21

Named by the source specification as a candidate where compatibility can be established.

| Status | Tool and version tested | Validated on |
| --- | --- | --- |
| `unvalidated` | none | none |

### What changes in the tool's configuration

Not tested. When the row is validated, this section states where the tool reads its base URL, key and model (environment, file, flag or UI), and which of those the setup helper uses for a session and for a persistent configuration.

### How credentials are handled

Not tested. When validated: how the tool sends the key, that HIPS accepts it as `Authorization: Bearer`, and that the helper never prints a secret. The key is read as `HIPS_API_KEY` and kept on the machine's own secret store or environment.

### How to restore the previous setup

Not tested. When validated: the backup the helper takes before a persistent change, and the selective undo that restores the previous provider, model mapping and defaults without touching unrelated providers.

### The conditions of the status

- Tool and SDK versions: none tested.
- Configuration surface: not tested.
- Authentication: not tested.
- Model mapping: not tested.
- Streaming: not tested.
- Complete tool-call round trips: not tested.

> Prelaunch: The status is `unvalidated` (not decided yet). A page moves past unvalidated only with a dated validation record; the record's date and test results replace the "not tested" lines above.

## Other coding tools and editor integrations
Route: https://hips.com/docs/tools/openai-style-tools
Status: preview; updated 2026-10-21

Tools that take an OpenAI-style base URL, each validated separately.

| Status | Tool and version tested | Validated on |
| --- | --- | --- |
| `unvalidated` | none | none |

### What changes in the tool's configuration

Not tested. When the row is validated, this section states where the tool reads its base URL, key and model (environment, file, flag or UI), and which of those the setup helper uses for a session and for a persistent configuration.

### How credentials are handled

Not tested. When validated: how the tool sends the key, that HIPS accepts it as `Authorization: Bearer`, and that the helper never prints a secret. The key is read as `HIPS_API_KEY` and kept on the machine's own secret store or environment.

### How to restore the previous setup

Not tested. When validated: the backup the helper takes before a persistent change, and the selective undo that restores the previous provider, model mapping and defaults without touching unrelated providers.

### The conditions of the status

- Tool and SDK versions: none tested.
- Configuration surface: not tested.
- Authentication: not tested.
- Model mapping: not tested.
- Streaming: not tested.
- Complete tool-call round trips: not tested.

> Prelaunch: The status is `unvalidated` (not decided yet). A page moves past unvalidated only with a dated validation record; the record's date and test results replace the "not tested" lines above.

## The HIPS SDK for Python
Route: https://hips.com/docs/sdk/languages/python
Status: preview; updated 2026-10-21

The HIPS SDK for Python 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 package name and the method names below are proposals (not decided yet). The eight SDKs are released together, once every one passes the conformance suite; nothing here is installable yet.

### At a glance

- `Runtime`: Python 3.10 and newer
- `Repository`: `hips-ai/hips-sdk-python`, one repository per language under `hips-ai`
- `Import`, proposed: `hips`
- `Package`, proposed: `hips-ai` on PyPI, not yet reserved (not decided yet)
- `Idioms`: snake_case methods and fields; errors are exceptions deriving from `HipsError`.
- `Forms`: A blocking client and an `async` client with the same methods.

### Install

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.

### Configuration

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.

Environment:

```
export HIPS_API_KEY="<a key created in the Console>"
export HIPS_BASE_URL="https://ai.hips.com/v1"
export 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 first task

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](/docs/tasks/classification).

Python:

```
from hips import Hips

# Reads HIPS_API_KEY and HIPS_BASE_URL (https://ai.hips.com/v1);
# fails without a key.
client = Hips()

result = client.tasks.run(
    deployment="dep_...",
    input={"text": "I was charged twice and nobody has replied."},
    requirements={"pool": "approved", "pricing_mode": "stable"},
)

print(result.output.label)       # the model's label, as sent
print(result.usage.units)        # in the model's billing unit
print(result.meta.cost_micros)   # what this request cost
print(result.meta.request_id)
```

### Task-input uploads

`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.

### Running your own model

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](/docs/import-and-run)). 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.

### Jobs

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.

### Errors and retries

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. Exceptions, caught by class: `except RateLimitError as e:` reads `e.retry_after`.

| Status and type | Error |
| --- | --- |
| 400 `invalid_request_error` | `InvalidRequestError` |
| 401 `authentication_error` | `AuthenticationError` |
| 402 `insufficient_credit` | `InsufficientCreditError` |
| 403 `permission_error` | `PermissionError` |
| 403 `workspace_suspended` | `WorkspaceSuspendedError` |
| 404 `not_found_error` | `NotFoundError` |
| 429 `rate_limit_error` | `RateLimitError`, with the wait from `Retry-After` |
| 503 `overloaded_error` | `OverloadedError`, with the wait from `Retry-After` |
| 500 `api_error` | `ApiError` |
| No response | `ConnectionError`, `TimeoutError` |

- 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](/docs/operating/retries)).

### Requirements

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.

### Method reference

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

| Method | Sends and returns |
| --- | --- |
| `client.tasks.run` | `POST /v1/tasks`, synchronous: the task's typed output, `usage` and `meta` |
| `client.jobs.create` | `POST /v1/jobs`, asynchronous: the job with its id and state |
| `client.jobs.get` | `GET /v1/jobs/{id}`: the job, with the result when `completed` |
| `client.jobs.wait` | `jobs.get` repeated, honoring the server's interval, until `completed`, `failed`, `canceled` or `interrupted` |
| `client.jobs.cancel` | The cancel route: the job |
| `client.uploads.upload` | `POST /v1/uploads` then the `PUT`: a task input, never model weights |
| `client.models.list` | `GET /v1/models`: a page of models |
| `client.deployments.get` | The read side of a deployment, with its state |
| `client.tasks.run_raw` | The body exactly as given: a field this SDK version does not know yet |

## The HIPS SDK for TypeScript and JavaScript
Route: https://hips.com/docs/sdk/languages/node
Status: preview; updated 2026-10-21

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 package name and the method names below are proposals (not decided yet). The eight SDKs are released together, once every one passes the conformance suite; nothing here is installable yet.

### At a glance

- `Runtime`: Node 20 and newer, Deno, Bun, edge runtimes
- `Repository`: `hips-ai/hips-sdk-node`, one repository per language under `hips-ai`
- `Import`, proposed: `@hips-ai/sdk`
- `Package`, proposed: `@hips-ai/sdk` on npm, not yet reserved (not decided yet)
- `Idioms`: camelCase methods and fields, typed results; errors are classes extending `HipsError`.
- `Forms`: Every method returns a promise; the same package runs in Node, Deno, Bun and edge runtimes.

### Install

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.

### Configuration

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.

Environment:

```
export HIPS_API_KEY="<a key created in the Console>"
export HIPS_BASE_URL="https://ai.hips.com/v1"
export 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 first task

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](/docs/tasks/classification).

TypeScript and JavaScript:

```
import { Hips } from "@hips-ai/sdk";

// Reads HIPS_API_KEY and HIPS_BASE_URL (https://ai.hips.com/v1);
// fails without a key.
const client = new Hips();

const result = await client.tasks.run({
  deployment: "dep_...",
  input: { text: "I was charged twice and nobody has replied." },
  requirements: { pool: "approved", pricingMode: "stable" },
});

console.log(result.output.label, result.usage.units);
console.log(result.meta.costMicros, result.meta.requestId);
```

### Task-input uploads

`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.

### Running your own model

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](/docs/import-and-run)). 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.

### Jobs

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.

### Errors and retries

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`.

| Status and type | Error |
| --- | --- |
| 400 `invalid_request_error` | `InvalidRequestError` |
| 401 `authentication_error` | `AuthenticationError` |
| 402 `insufficient_credit` | `InsufficientCreditError` |
| 403 `permission_error` | `PermissionError` |
| 403 `workspace_suspended` | `WorkspaceSuspendedError` |
| 404 `not_found_error` | `NotFoundError` |
| 429 `rate_limit_error` | `RateLimitError`, with the wait from `Retry-After` |
| 503 `overloaded_error` | `OverloadedError`, with the wait from `Retry-After` |
| 500 `api_error` | `ApiError` |
| No response | `ConnectionError`, `TimeoutError` |

- 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](/docs/operating/retries)).

### Requirements

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.

### Method reference

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.

| Method | Sends and returns |
| --- | --- |
| `client.tasks.run` | `POST /v1/tasks`, synchronous: the task's typed output, `usage` and `meta` |
| `client.jobs.create` | `POST /v1/jobs`, asynchronous: the job with its id and state |
| `client.jobs.get` | `GET /v1/jobs/{id}`: the job, with the result when `completed` |
| `client.jobs.wait` | `jobs.get` repeated, honoring the server's interval, until `completed`, `failed`, `canceled` or `interrupted` |
| `client.jobs.cancel` | The cancel route: the job |
| `client.uploads.upload` | `POST /v1/uploads` then the `PUT`: a task input, never model weights |
| `client.models.list` | `GET /v1/models`: a page of models |
| `client.deployments.get` | The read side of a deployment, with its state |
| `client.tasks.runRaw` | The body exactly as given: a field this SDK version does not know yet |

## The HIPS SDK for Go
Route: https://hips.com/docs/sdk/languages/go
Status: preview; updated 2026-10-21

The HIPS SDK for Go 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 package name and the method names below are proposals (not decided yet). The eight SDKs are released together, once every one passes the conformance suite; nothing here is installable yet.

### At a glance

- `Runtime`: Set with the build
- `Repository`: `hips-ai/hips-sdk-go`, one repository per language under `hips-ai`
- `Import`, proposed: `hips`
- `Package`, proposed: `github.com/hips-ai/hips-sdk-go`, the repository's own path on The Go module proxy, not yet reserved (not decided yet)
- `Idioms`: PascalCase exported names, a `context.Context` first on every call, option structs where Go has no optional arguments; errors are values.
- `Forms`: Blocking calls; cancel or time out through the context.

### Install

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.

### Configuration

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.

Environment:

```
export HIPS_API_KEY="<a key created in the Console>"
export HIPS_BASE_URL="https://ai.hips.com/v1"
export 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 first task

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](/docs/tasks/classification).

Go:

```
// Reads HIPS_API_KEY and HIPS_BASE_URL (https://ai.hips.com/v1);
// fails without a key.
client, err := hips.NewClient()
if err != nil {
	return err
}

result, err := client.Tasks.Run(ctx, hips.TaskParams{
	Deployment:   "dep_...",
	Input:        map[string]any{"text": "I was charged twice and nobody has replied."},
	Requirements: &hips.Requirements{Pool: "approved", PricingMode: "stable"},
})
if err != nil {
	return err
}

fmt.Println(result.Output.Label, result.Usage.Units)
fmt.Println(result.Meta.CostMicros, result.Meta.RequestID)
```

### Task-input uploads

`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.

### Running your own model

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](/docs/import-and-run)). 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.

### Jobs

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.

### Errors and retries

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. Error values matched with `errors.As`: a `*hips.RateLimitError` carries `RetryAfter`.

| Status and type | Error |
| --- | --- |
| 400 `invalid_request_error` | `InvalidRequestError` |
| 401 `authentication_error` | `AuthenticationError` |
| 402 `insufficient_credit` | `InsufficientCreditError` |
| 403 `permission_error` | `PermissionError` |
| 403 `workspace_suspended` | `WorkspaceSuspendedError` |
| 404 `not_found_error` | `NotFoundError` |
| 429 `rate_limit_error` | `RateLimitError`, with the wait from `Retry-After` |
| 503 `overloaded_error` | `OverloadedError`, with the wait from `Retry-After` |
| 500 `api_error` | `ApiError` |
| No response | `ConnectionError`, `TimeoutError` |

- 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](/docs/operating/retries)).

### Requirements

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.

### Method reference

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

| Method | Sends and returns |
| --- | --- |
| `client.Tasks.Run` | `POST /v1/tasks`, synchronous: the task's typed output, `usage` and `meta` |
| `client.Jobs.Create` | `POST /v1/jobs`, asynchronous: the job with its id and state |
| `client.Jobs.Get` | `GET /v1/jobs/{id}`: the job, with the result when `completed` |
| `client.Jobs.Wait` | `jobs.get` repeated, honoring the server's interval, until `completed`, `failed`, `canceled` or `interrupted` |
| `client.Jobs.Cancel` | The cancel route: the job |
| `client.Uploads.Upload` | `POST /v1/uploads` then the `PUT`: a task input, never model weights |
| `client.Models.List` | `GET /v1/models`: a page of models |
| `client.Deployments.Get` | The read side of a deployment, with its state |
| `client.Tasks.RunRaw` | The body exactly as given: a field this SDK version does not know yet |

## The HIPS SDK for Rust
Route: https://hips.com/docs/sdk/languages/rust
Status: preview; updated 2026-10-21

The HIPS SDK for Rust 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 package name and the method names below are proposals (not decided yet). The eight SDKs are released together, once every one passes the conformance suite; nothing here is installable yet.

### At a glance

- `Runtime`: Set with the build
- `Repository`: `hips-ai/hips-sdk-rust`, one repository per language under `hips-ai`
- `Import`, proposed: `hips`
- `Package`, proposed: `hips-ai` on crates.io, not yet reserved (not decided yet)
- `Idioms`: snake_case methods, builder-style parameter structs, `Result` on every call.
- `Forms`: An async client, and a blocking client behind a feature flag.

### Install

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.

### Configuration

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.

Environment:

```
export HIPS_API_KEY="<a key created in the Console>"
export HIPS_BASE_URL="https://ai.hips.com/v1"
export 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 first task

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](/docs/tasks/classification).

Rust:

```
use hips::{Client, Requirements, TaskParams};
use serde_json::json;

// Reads HIPS_API_KEY and HIPS_BASE_URL (https://ai.hips.com/v1);
// fails without a key.
let client = Client::new()?;

let result = client
    .tasks()
    .run(TaskParams {
        deployment: Some("dep_...".into()),
        input: json!({ "text": "I was charged twice and nobody has replied." }),
        requirements: Some(Requirements::new().pool("approved").pricing_mode("stable")),
        ..Default::default()
    })
    .await?;

println!("{} {}", result.meta.cost_micros, result.meta.request_id);
```

### Task-input uploads

`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.

### Running your own model

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](/docs/import-and-run)). 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.

### Jobs

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.

### Errors and retries

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. `Result<T, hips::Error>`, with one variant per error type: `Error::RateLimit` carries `retry_after`.

| Status and type | Error |
| --- | --- |
| 400 `invalid_request_error` | `InvalidRequestError` |
| 401 `authentication_error` | `AuthenticationError` |
| 402 `insufficient_credit` | `InsufficientCreditError` |
| 403 `permission_error` | `PermissionError` |
| 403 `workspace_suspended` | `WorkspaceSuspendedError` |
| 404 `not_found_error` | `NotFoundError` |
| 429 `rate_limit_error` | `RateLimitError`, with the wait from `Retry-After` |
| 503 `overloaded_error` | `OverloadedError`, with the wait from `Retry-After` |
| 500 `api_error` | `ApiError` |
| No response | `ConnectionError`, `TimeoutError` |

- 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](/docs/operating/retries)).

### Requirements

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.

### Method reference

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

| Method | Sends and returns |
| --- | --- |
| `client.tasks().run` | `POST /v1/tasks`, synchronous: the task's typed output, `usage` and `meta` |
| `client.jobs().create` | `POST /v1/jobs`, asynchronous: the job with its id and state |
| `client.jobs().get` | `GET /v1/jobs/{id}`: the job, with the result when `completed` |
| `client.jobs().wait` | `jobs.get` repeated, honoring the server's interval, until `completed`, `failed`, `canceled` or `interrupted` |
| `client.jobs().cancel` | The cancel route: the job |
| `client.uploads().upload` | `POST /v1/uploads` then the `PUT`: a task input, never model weights |
| `client.models().list` | `GET /v1/models`: a page of models |
| `client.deployments().get` | The read side of a deployment, with its state |
| `client.tasks().run_raw` | The body exactly as given: a field this SDK version does not know yet |

## The HIPS SDK for Java (usable from Kotlin)
Route: https://hips.com/docs/sdk/languages/java
Status: preview; updated 2026-10-21

The HIPS SDK for Java (usable from Kotlin) 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 package name and the method names below are proposals (not decided yet). The eight SDKs are released together, once every one passes the conformance suite; nothing here is installable yet.

### At a glance

- `Runtime`: JVM 17 and newer
- `Repository`: `hips-ai/hips-sdk-java`, one repository per language under `hips-ai`
- `Import`, proposed: `com.hips.sdk`
- `Package`, proposed: `com.hips:sdk` on Maven Central, not yet reserved (not decided yet)
- `Idioms`: camelCase methods, builders for parameters, accessors for results; usable from Kotlin as it is.
- `Forms`: Blocking methods, and an async client whose methods return `CompletableFuture`.

### Install

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.

### Configuration

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.

Environment:

```
export HIPS_API_KEY="<a key created in the Console>"
export HIPS_BASE_URL="https://ai.hips.com/v1"
export 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 first task

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](/docs/tasks/classification).

Java:

```
import com.hips.sdk.Hips;
import com.hips.sdk.Requirements;
import com.hips.sdk.TaskParams;
import com.hips.sdk.TaskResult;
import java.util.Map;

// Reads HIPS_API_KEY and HIPS_BASE_URL (https://ai.hips.com/v1);
// fails without a key.
Hips client = new Hips();

TaskResult result = client.tasks().run(TaskParams.builder()
    .deployment("dep_...")
    .input(Map.of("text", "I was charged twice and nobody has replied."))
    .requirements(Requirements.builder().pool("approved").pricingMode("stable").build())
    .build());

System.out.println(result.meta().costMicros() + " " + result.meta().requestId());
```

### Task-input uploads

`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.

### Running your own model

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](/docs/import-and-run)). 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.

### Jobs

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.

### Errors and retries

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. Unchecked exceptions extending `HipsException`: a `RateLimitException` carries `retryAfter()`.

| Status and type | Error |
| --- | --- |
| 400 `invalid_request_error` | `InvalidRequestError` |
| 401 `authentication_error` | `AuthenticationError` |
| 402 `insufficient_credit` | `InsufficientCreditError` |
| 403 `permission_error` | `PermissionError` |
| 403 `workspace_suspended` | `WorkspaceSuspendedError` |
| 404 `not_found_error` | `NotFoundError` |
| 429 `rate_limit_error` | `RateLimitError`, with the wait from `Retry-After` |
| 503 `overloaded_error` | `OverloadedError`, with the wait from `Retry-After` |
| 500 `api_error` | `ApiError` |
| No response | `ConnectionError`, `TimeoutError` |

- 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](/docs/operating/retries)).

### Requirements

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.

### Method reference

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

| Method | Sends and returns |
| --- | --- |
| `client.tasks().run` | `POST /v1/tasks`, synchronous: the task's typed output, `usage` and `meta` |
| `client.jobs().create` | `POST /v1/jobs`, asynchronous: the job with its id and state |
| `client.jobs().get` | `GET /v1/jobs/{id}`: the job, with the result when `completed` |
| `client.jobs().wait` | `jobs.get` repeated, honoring the server's interval, until `completed`, `failed`, `canceled` or `interrupted` |
| `client.jobs().cancel` | The cancel route: the job |
| `client.uploads().upload` | `POST /v1/uploads` then the `PUT`: a task input, never model weights |
| `client.models().list` | `GET /v1/models`: a page of models |
| `client.deployments().get` | The read side of a deployment, with its state |
| `client.tasks().runRaw` | The body exactly as given: a field this SDK version does not know yet |

## The HIPS SDK for .NET
Route: https://hips.com/docs/sdk/languages/dotnet
Status: preview; updated 2026-10-21

The HIPS SDK for .NET 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 package name and the method names below are proposals (not decided yet). The eight SDKs are released together, once every one passes the conformance suite; nothing here is installable yet.

### At a glance

- `Runtime`: .NET 8 and newer
- `Repository`: `hips-ai/hips-sdk-dotnet`, one repository per language under `hips-ai`
- `Import`, proposed: `Hips.Sdk`
- `Package`, proposed: `Hips.Sdk` on NuGet, not yet reserved (not decided yet)
- `Idioms`: PascalCase members, `Async` methods with a `CancellationToken`; errors are exceptions deriving from `HipsException`.
- `Forms`: Task-based async methods throughout.

### Install

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.

### Configuration

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.

Environment:

```
export HIPS_API_KEY="<a key created in the Console>"
export HIPS_BASE_URL="https://ai.hips.com/v1"
export 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 first task

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](/docs/tasks/classification).

.NET:

```
using Hips.Sdk;

// Reads HIPS_API_KEY and HIPS_BASE_URL (https://ai.hips.com/v1);
// fails without a key.
var client = new HipsClient();

var result = await client.Tasks.RunAsync(new TaskParams
{
    Deployment = "dep_...",
    Input = new { text = "I was charged twice and nobody has replied." },
    Requirements = new Requirements { Pool = "approved", PricingMode = "stable" },
});

Console.WriteLine($"{result.Meta.CostMicros} {result.Meta.RequestId}");
```

### Task-input uploads

`client.Uploads.UploadAsync` 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.

### Running your own model

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](/docs/import-and-run)). 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.

### Jobs

Video, long audio and batched generation are jobs. `client.Jobs.CreateAsync` answers at once with the job; `client.Jobs.WaitAsync` polls `client.Jobs.GetAsync` with backoff, honoring the server's suggested interval, until the job is `completed`, `failed`, `canceled` or `interrupted`. `client.Jobs.CancelAsync` stops one.

### Errors and retries

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. Exceptions caught by type: `catch (RateLimitException e)` reads `e.RetryAfter`.

| Status and type | Error |
| --- | --- |
| 400 `invalid_request_error` | `InvalidRequestError` |
| 401 `authentication_error` | `AuthenticationError` |
| 402 `insufficient_credit` | `InsufficientCreditError` |
| 403 `permission_error` | `PermissionError` |
| 403 `workspace_suspended` | `WorkspaceSuspendedError` |
| 404 `not_found_error` | `NotFoundError` |
| 429 `rate_limit_error` | `RateLimitError`, with the wait from `Retry-After` |
| 503 `overloaded_error` | `OverloadedError`, with the wait from `Retry-After` |
| 500 `api_error` | `ApiError` |
| No response | `ConnectionError`, `TimeoutError` |

- 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.RunAsync` and `client.Jobs.CreateAsync` 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](/docs/operating/retries)).

### Requirements

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.

### Method reference

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

| Method | Sends and returns |
| --- | --- |
| `client.Tasks.RunAsync` | `POST /v1/tasks`, synchronous: the task's typed output, `usage` and `meta` |
| `client.Jobs.CreateAsync` | `POST /v1/jobs`, asynchronous: the job with its id and state |
| `client.Jobs.GetAsync` | `GET /v1/jobs/{id}`: the job, with the result when `completed` |
| `client.Jobs.WaitAsync` | `jobs.get` repeated, honoring the server's interval, until `completed`, `failed`, `canceled` or `interrupted` |
| `client.Jobs.CancelAsync` | The cancel route: the job |
| `client.Uploads.UploadAsync` | `POST /v1/uploads` then the `PUT`: a task input, never model weights |
| `client.Models.ListAsync` | `GET /v1/models`: a page of models |
| `client.Deployments.GetAsync` | The read side of a deployment, with its state |
| `client.Tasks.RunRawAsync` | The body exactly as given: a field this SDK version does not know yet |

## The HIPS SDK for PHP
Route: https://hips.com/docs/sdk/languages/php
Status: preview; updated 2026-10-21

The HIPS SDK for PHP 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 package name and the method names below are proposals (not decided yet). The eight SDKs are released together, once every one passes the conformance suite; nothing here is installable yet.

### At a glance

- `Runtime`: PHP 8.2 and newer
- `Repository`: `hips-ai/hips-sdk-php`, one repository per language under `hips-ai`
- `Import`, proposed: `Hips\Sdk`
- `Package`, proposed: `hips-ai/sdk` on Packagist, not yet reserved (not decided yet)
- `Idioms`: camelCase methods, associative arrays for parameters, typed result objects; errors are exceptions extending `HipsException`.
- `Forms`: Blocking calls through any PSR-18 HTTP client.

### Install

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.

### Configuration

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.

Environment:

```
export HIPS_API_KEY="<a key created in the Console>"
export HIPS_BASE_URL="https://ai.hips.com/v1"
export 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 first task

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](/docs/tasks/classification).

PHP:

```
<?php

use Hips\Sdk\Hips;

// Reads HIPS_API_KEY and HIPS_BASE_URL (https://ai.hips.com/v1);
// fails without a key.
$client = new Hips();

$result = $client->tasks->run([
    'deployment' => 'dep_...',
    'input' => ['text' => 'I was charged twice and nobody has replied.'],
    'requirements' => ['pool' => 'approved', 'pricing_mode' => 'stable'],
]);

echo $result->meta->costMicros, ' ', $result->meta->requestId, PHP_EOL;
```

### Task-input uploads

`$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.

### Running your own model

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](/docs/import-and-run)). 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.

### Jobs

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.

### Errors and retries

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. Exceptions caught by class: `catch (RateLimitException $e)` reads `$e->retryAfter`.

| Status and type | Error |
| --- | --- |
| 400 `invalid_request_error` | `InvalidRequestError` |
| 401 `authentication_error` | `AuthenticationError` |
| 402 `insufficient_credit` | `InsufficientCreditError` |
| 403 `permission_error` | `PermissionError` |
| 403 `workspace_suspended` | `WorkspaceSuspendedError` |
| 404 `not_found_error` | `NotFoundError` |
| 429 `rate_limit_error` | `RateLimitError`, with the wait from `Retry-After` |
| 503 `overloaded_error` | `OverloadedError`, with the wait from `Retry-After` |
| 500 `api_error` | `ApiError` |
| No response | `ConnectionError`, `TimeoutError` |

- 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](/docs/operating/retries)).

### Requirements

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.

### Method reference

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

| Method | Sends and returns |
| --- | --- |
| `$client->tasks->run` | `POST /v1/tasks`, synchronous: the task's typed output, `usage` and `meta` |
| `$client->jobs->create` | `POST /v1/jobs`, asynchronous: the job with its id and state |
| `$client->jobs->get` | `GET /v1/jobs/{id}`: the job, with the result when `completed` |
| `$client->jobs->wait` | `jobs.get` repeated, honoring the server's interval, until `completed`, `failed`, `canceled` or `interrupted` |
| `$client->jobs->cancel` | The cancel route: the job |
| `$client->uploads->upload` | `POST /v1/uploads` then the `PUT`: a task input, never model weights |
| `$client->models->list` | `GET /v1/models`: a page of models |
| `$client->deployments->get` | The read side of a deployment, with its state |
| `$client->tasks->runRaw` | The body exactly as given: a field this SDK version does not know yet |

## The HIPS SDK for Ruby
Route: https://hips.com/docs/sdk/languages/ruby
Status: preview; updated 2026-10-21

The HIPS SDK for Ruby 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 package name and the method names below are proposals (not decided yet). The eight SDKs are released together, once every one passes the conformance suite; nothing here is installable yet.

### At a glance

- `Runtime`: Ruby 3.2 and newer
- `Repository`: `hips-ai/hips-sdk-ruby`, one repository per language under `hips-ai`
- `Import`, proposed: `Hips`
- `Package`, proposed: `hips-ai` on RubyGems, not yet reserved (not decided yet)
- `Idioms`: snake_case methods with keyword arguments; errors are exceptions under `Hips::Error`.
- `Forms`: Blocking calls, safe to share between threads.

### Install

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.

### Configuration

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.

Environment:

```
export HIPS_API_KEY="<a key created in the Console>"
export HIPS_BASE_URL="https://ai.hips.com/v1"
export 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 first task

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](/docs/tasks/classification).

Ruby:

```
require "hips"

# Reads HIPS_API_KEY and HIPS_BASE_URL (https://ai.hips.com/v1);
# fails without a key.
client = Hips::Client.new

result = client.tasks.run(
  deployment: "dep_...",
  input: { text: "I was charged twice and nobody has replied." },
  requirements: { pool: "approved", pricing_mode: "stable" },
)

puts result.meta.cost_micros, result.meta.request_id
```

### Task-input uploads

`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.

### Running your own model

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](/docs/import-and-run)). 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.

### Jobs

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.

### Errors and retries

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. Exceptions rescued by class: `rescue Hips::RateLimitError => e` reads `e.retry_after`.

| Status and type | Error |
| --- | --- |
| 400 `invalid_request_error` | `InvalidRequestError` |
| 401 `authentication_error` | `AuthenticationError` |
| 402 `insufficient_credit` | `InsufficientCreditError` |
| 403 `permission_error` | `PermissionError` |
| 403 `workspace_suspended` | `WorkspaceSuspendedError` |
| 404 `not_found_error` | `NotFoundError` |
| 429 `rate_limit_error` | `RateLimitError`, with the wait from `Retry-After` |
| 503 `overloaded_error` | `OverloadedError`, with the wait from `Retry-After` |
| 500 `api_error` | `ApiError` |
| No response | `ConnectionError`, `TimeoutError` |

- 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](/docs/operating/retries)).

### Requirements

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.

### Method reference

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

| Method | Sends and returns |
| --- | --- |
| `client.tasks.run` | `POST /v1/tasks`, synchronous: the task's typed output, `usage` and `meta` |
| `client.jobs.create` | `POST /v1/jobs`, asynchronous: the job with its id and state |
| `client.jobs.get` | `GET /v1/jobs/{id}`: the job, with the result when `completed` |
| `client.jobs.wait` | `jobs.get` repeated, honoring the server's interval, until `completed`, `failed`, `canceled` or `interrupted` |
| `client.jobs.cancel` | The cancel route: the job |
| `client.uploads.upload` | `POST /v1/uploads` then the `PUT`: a task input, never model weights |
| `client.models.list` | `GET /v1/models`: a page of models |
| `client.deployments.get` | The read side of a deployment, with its state |
| `client.tasks.run_raw` | The body exactly as given: a field this SDK version does not know yet |

## Batch jobs
Route: https://hips.com/docs/batch
Status: preview; updated 2026-10-21

Send many requests at once and collect the results when they are done. HIPS runs batch lines when GPU capacity is free, at 50% less than the on-demand price of the same model, and tells you when the batch is finished. The API is OpenAI's Batch API, so the official SDKs and the batch scripts you already have work against HIPS unchanged.

> Batch is decided and not yet served. The queue of enqueued tokens per model and workspace is set per plan, and its values are still open (not decided yet).

### How a batch runs

1. Write a JSONL file, one request per line, each with your own `custom_id`.
2. Upload it with `POST /v1/files` and the purpose `batch`.
3. Create the batch with `POST /v1/batches`, naming the endpoint and the completion window. The price is quoted and bound here.
4. HIPS runs the lines when capacity is free. Live requests always come first.
5. When the batch ends, a signed webhook and a mail tell you; download the output and error files.

Python preview:

```
import json
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HIPS_API_KEY"],
    base_url=os.environ["HIPS_BASE_URL"],  # https://ai.hips.com/v1
)

# One request per line, each with your own custom_id.
with open("requests.jsonl", "w") as f:
    for i, text in enumerate(["First document.", "Second document."]):
        f.write(json.dumps({
            "custom_id": f"doc-{i}",
            "method": "POST",
            "url": "/v1/chat/completions",
            "body": {
                "model": os.environ["HIPS_MODEL"],
                "messages": [{"role": "user", "content": f"Summarize: {text}"}],
            },
        }) + "\n")

batch_file = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch")
batch = client.batches.create(
    input_file_id=batch_file.id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
)
print(batch.id, batch.status)
```

cURL preview:

```
# HIPS_BASE_URL is https://ai.hips.com/v1
# Upload the JSONL file of requests.
curl "$HIPS_BASE_URL/files" \
  -H "Authorization: Bearer $HIPS_API_KEY" \
  -F purpose="batch" \
  -F file="@requests.jsonl"

# Create the batch with the file's id from the answer above.
curl "$HIPS_BASE_URL/batches" \
  -H "Authorization: Bearer $HIPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"input_file_id\":\"$FILE_ID\",\"endpoint\":\"/v1/chat/completions\",\"completion_window\":\"24h\"}"
```

### Collect the results

The output file holds one line per finished request, matched to your input by `custom_id`, in no particular order. Lines that failed, and lines still unfinished when the window closed, come back in the error file.

Python:

```
batch = client.batches.retrieve(batch.id)

if batch.status == "completed":
    for line in client.files.content(batch.output_file_id).text.splitlines():
        record = json.loads(line)
        print(record["custom_id"], record["response"]["status_code"])

    # Lines that failed, or expired when the window closed, are in the error file.
    if batch.error_file_id:
        print(client.files.content(batch.error_file_id).text)
```

### The routes

On `https://ai.hips.com`, in OpenAI's Batch API shape.

**POST /v1/files** (preview): Upload the JSONL input file with the purpose `batch`.

**POST /v1/batches** (preview): Create a batch from an input file: `input_file_id`, `endpoint`, `completion_window`.

**GET /v1/batches/{id}** (preview): A batch with its status, its line counts and its output and error file ids.

**POST /v1/batches/{id}/cancel** (preview): Cancel a batch. Finished lines are delivered and charged; the rest are not.

**GET /v1/batches** (preview): The workspace's batches, newest first.

**GET /v1/files/{id}/content** (preview): Download an output or error file.

### What a line can call

- `/v1/chat/completions`, for language models.
- Embeddings.
- The HIPS task API, for every other model type: a line that OpenAI's Batch API does not offer.
- One model per input file; your own model's lines follow the pools it may run in.

### The completion window

You choose how long HIPS may take: `24h` by default, or any whole number of hours or days up to `7d`. The price is the same for every window. No finish time is promised inside it: everything that finishes is delivered, and lines still unfinished when the window closes come back as `expired` and are not charged.

### Price

|  | Batch |
| --- | --- |
| Discount | 50% less than the on-demand rate of the same model, pool and unit, applied to every rate a line uses: input, cached input, output and every task unit |
| Quote | Bound when `POST /v1/batches` accepts the batch, and held for every line through the window |
| Prompt caching | The batch discount and the cached-input rate multiply ([Prompt caching](/docs/prompt-caching)) |
| Balance | The batch's maximum charge (input at batch rates plus each line's output cap) is held against your prepaid balance at creation and released line by line as lines finish or expire |
| Expired lines | Not charged |
| A model without batch | A model whose price cannot carry the discount is sold without batch rather than at a smaller discount, and the catalog says so |

Actual prices are set per model in the catalog; the [Pricing](/pricing) page shows the shape.

### Limits

*The limits match OpenAI's, so existing scripts run unchanged*

| Limit | Value |
| --- | --- |
| Lines per input file | 50,000 |
| Input file size | 200 MB |
| Models per input file | One |
| Embedding inputs per batch | 50,000 |
| Batches created per hour | 2,000 |
| Open batches per workspace | 100 |
| Enqueued input tokens per model and workspace | Set per plan (not decided yet) |

### Where batch lines run

- On every eligible idle GPU: personal devices the moment they come online, and spare capacity in the approved data-center pool.
- Live requests always come first. A device finishes the batch line it is running before it takes a live request.
- Lines that share a long prompt prefix are grouped and run in order on one worker, so the shared part is cached once.
- A batch line on your own model runs only where the model may run: the approved pool, at launch.

### Files and retention

Batch input and output files are kept 30 days and then deleted, sooner when you set a shorter expiry (`expires_after`, `output_expires_after`) or delete them. Their content follows the same training rule as a live request on the same plan ([Data handling](/docs/operating/data)).

## Prompt caching
Route: https://hips.com/docs/prompt-caching
Status: preview; updated 2026-10-21

Prompt caching is automatic. When a request starts with the same tokens as an earlier request in your workspace, the work on that shared prefix can be reused, and those input tokens are billed at the cached-input rate. There is nothing to switch on and no charge to write the cache.

> Caching is decided and not yet served. Each model's cached-input rate is set per model in the catalog.

### What it costs

| Token | Rate |
| --- | --- |
| Input, uncached | The model's input rate |
| Input, cached | Its own rate per model, pool and pricing mode: by default 10% of the input rate |
| Cache write | No charge. `cache_write_tokens` is reported as 0 |
| Output | The model's output rate |
| In a batch | The batch discount and the cached rate multiply: at the defaults, a cached input token in a batch costs 5% of the on-demand input rate |

HIPS bills only cache hits it can verify: in the approved pool, the lower of the engine's count and the gateway's own record of your workspace's prefixes.

### Read it in the usage

*Usage fields*

- `usage.prompt_tokens`: Every input token, cached ones included, as OpenAI counts them.
- `usage.prompt_tokens_details.cached_tokens`: The cached input tokens billed at the cached rate.
- `cache_write_tokens`: Always 0: writing the cache is not charged.
- `x-hips-cost-micros`: The request's cost with the cached rate applied; on a stream, the `hips` object of the final usage chunk.

The Console's Usage and activity view splits uncached input, cached input and output per request and per batch.

### Get more hits

- Put what stays the same first: the system prompt, tool definitions, long documents and examples.
- Put what changes last: the user's question, the current date, a request id.
- Keep the shared part byte for byte identical between requests.
- Send `prompt_cache_key` to group requests that share a prefix: it narrows the cache within your workspace and steers them to a worker that holds it.

### Isolation

A cache never crosses workspaces. Each workspace's cache is kept apart, narrowed further by `prompt_cache_key`, with a salt the gateway derives and sends itself, so a client's `cache_salt` is refused with a 400. Placement prefers a worker that holds your prefix, bounded by load and never over a requirement you set.

### Where caching applies

| Pool | At launch |
| --- | --- |
| Approved data-center pool | Cached, and billed at the cached rate |
| Personal GPUs | No cross-request cache, and no cached tokens billed: a device engine cannot yet keep one workspace's cache apart from another's. A device cache comes later, in memory only and never on disk |

### Limits

- Cached tokens count toward your tokens-per-minute limit.
- No cache lifetime is promised at launch: a prefix may be evicted at any time, and the next request simply pays the uncached rate for it.

## The hi command line
Route: https://hips.com/docs/cli
Status: preview; updated 2026-10-21

`hi` is the HIPS command line for buyers: one binary for signing in, models, batches, imports, keys and usage. It signs in as you, in the browser, by device authorization, so it never needs an API key. It is its own binary, separate from the provider app that runs on a GPU owner's machine.

> `hi` is decided and not yet published. It will be distributed through Homebrew, a shell installer and Windows packages; the install command appears here when it is.

### Sign in

Shell:

```
hi login
```

`hi login` shows a code and a link, and you approve it in the Console while signed in. Every step is on [Sign in with device authorization](/docs/cli/login).

### What hi covers

| Command group | What it does | Page |
| --- | --- | --- |
| `hi login`, `hi logout` | Sign in by device authorization, sign out and revoke | [Sign in](/docs/cli/login) |
| Models | The catalog and your own models | When the command ships |
| Batches | Create, follow and download [batch jobs](/docs/batch) | When the command ships |
| Imports | Import a model from its hub, follow the import | When the command ships |
| Keys | The workspace's API keys, for servers and SDKs | When the command ships |
| Usage | Usage and cost by key, tool and person | When the command ships |

A management command's page waits for the platform API it calls (not decided yet); each command group gets its page once it ships.

### Keys or sign-in

An API key is a workspace's credential for servers and SDKs. A person's tools, `hi`, HIPS Code and the provider app, sign in as the person instead, and their usage is attributed to the person and the workspace chosen at approval. The [Authentication](/docs/reference/authentication) reference has both.

## Sign in with device authorization
Route: https://hips.com/docs/cli/login
Status: preview; updated 2026-10-21

Your tools sign in as you with OAuth 2.0 device authorization (RFC 8628). The tool shows a code; you approve it in the Console, where you are already signed in, and choose the workspace its usage belongs to. The tool never sees your password and never needs an API key.

> Sign-in is decided and not yet served; `hi` and HIPS Code use it once they are published.

### Four steps

1. Run `hi login`. It prints a user code `XXXX-XXXX`, a QR code drawn in the terminal and the link that both encode.
2. Open the link, or scan the QR code with a phone: the approval page needs no browser on the same machine.
3. In the Console, check the tool's name, the access it asks for and where the request came from, choose the workspace, and approve.
4. `hi` stops waiting and says which workspace it is signed in to.

Shell:

```
hi login
```

### The code

- Eight characters from an alphabet with no look-alike characters, shown as `XXXX-XXXX`.
- Single use, and valid for 10 minutes.
- Void after five wrong attempts, and rate-limited per address and per account.
- Approve only a code you started yourself. If a code reaches you any other way, deny it.

### Approving

The approval page at `console.hips.com/device` shows the tool's name, the access it asks for in plain words, the address and country the request came from, and the workspace choice with that workspace's tool defaults. Approve or deny; nothing happens until you do.

| The Console answers | What it means |
| --- | --- |
| `tool_defaults_required` | The workspace has no tool defaults yet: an owner or admin sets the pool, pricing mode, region and fallback used for tools in Workspace settings, then you approve again |
| `verification_required` | The workspace owner has not passed identity verification |
| Not found | The code is unknown, expired, used or voided. One message for all four, so a guess learns nothing |

### What hi asks for

*The client `hi` asks for two of the four scopes; `provider` is the provider app's and `admin` is never asked for by a buyer's tool*

| Scope | Allows |
| --- | --- |
| `inference` | Requests in the workspace you chose, attributed to you |
| `account` | Reading who is signed in |

### Tokens

- An access token that lasts 1 hour, and a refresh token that lasts 30 days and is replaced each time it is used.
- Both kept in the operating system's keystore and refreshed by the tool without asking. Never printed.
- At the gateway the access token works like a key of the workspace you chose, with the same rate limits, and the workspace's tool defaults in place of a key's defaults.

### The routes

Three exact paths on `ai.hips.com`, in OAuth's own wire format. A tool calls them; you never do.

**POST /auth/device/code** (preview): Start a sign-in: the device code, the user code `XXXX-XXXX` and the links.

**POST /auth/device/token** (preview): Poll with the device code until approved; later, exchange the refresh token for a new access token.

**POST /auth/device/revoke** (preview): Revoke the sign-in (RFC 7009); `hi logout` calls it.

| While polling | What hi does |
| --- | --- |
| `authorization_pending` | Keeps waiting |
| `slow_down` | Waits longer between polls |
| `access_denied` | Stops: the code was denied in the Console |
| `expired_token` | Stops: the code expired; run `hi login` again |

### At the gateway

| Answer | What the tool does |
| --- | --- |
| 401 `authentication_error`, code `token_expired` | Refreshes the access token and retries once |
| 403 `permission_error`, code `insufficient_scope` | The sign-in lacks the scope; sign in again |

### Sign out and revoke

Shell:

```
hi logout
```

`hi logout` revokes the sign-in at HIPS and removes the stored tokens. To revoke a tool from anywhere, open Account in the Console, Authorized devices and apps, and revoke it there; it takes effect on the tool's next request.

### HIPS Code signs in the same way

HIPS Code, the company's coding agent, is the client `hips-code` with the scopes `inference` and `account`. Its sign-in shows the same code, QR code and link in the terminal, keeps the tokens in the keystore and sends the access token to the gateway; `HIPS_API_KEY` remains the path for CI and scripted use. Its row in the [supported-tools matrix](/docs/tools) is the first one, unvalidated until tested (not decided yet).

## HIPS API reference
Route: https://hips.com/docs/reference
Status: preview; updated 2026-10-21

The public wire contract, rendered: the OpenAI-compatible routes for open-weight language models, the HIPS task API for every other model type and for customer-owned models, uploads, jobs, the request requirements, the response headers, the error envelope, usage and versioning. Every route is relative to the base URL `https://ai.hips.com/v1`, the value of `HIPS_BASE_URL`; HTTPS only; JSON bodies with `Content-Type: application/json`, except streaming responses (`text/event-stream`) and the presigned PUT of an upload.

> Prelaunch: Every route is a preview until the gateway answers it under the conformance suite. No route answers today; no key exists. The reference never shows a value that could be mistaken for a working credential, host or model id.

### Routes

| Method and path | Purpose | Status at launch |
| --- | --- | --- |
| `POST /v1/chat/completions` | Chat completion, streamed or not. The first route built and the first validated. | preview |
| `GET /v1/models` | The models and deployments the key may name, with the `hips` extensions. | preview |
| `GET /v1/models/{id}` | One entry of the list, by catalog id, pinned id or `dep_` id. | preview |
| `POST /v1/responses` | OpenAI's Responses shape. Answers 404 `route_not_available` until its matrix rows pass. | after validation |
| `POST /v1/tasks` | A synchronous task: one request, one batch of inputs, one result array. | preview |
| `POST /v1/jobs` | An asynchronous job: the same body as a task, answered 202 with the job object. | preview |
| `GET /v1/jobs/{id}` | The job object with its status, transitions, result, usage and error. | preview |
| `GET /v1/jobs` | The workspace's jobs, newest first, cursor-paginated. | preview |
| `POST /v1/jobs/{id}/cancel` | Cancels a queued, assigned or running job. | preview |
| `POST /v1/uploads` | A presigned PUT for a task or job input. The gateway never receives the bytes. | preview |
| `GET /v1/uploads/{id}` | The upload's status. | preview |

Any other OpenAI route (`/v1/embeddings`, `/v1/images/*`, `/v1/audio/*`, `/v1/files`, `/v1/batches`, `/v1/fine_tuning/*`, `/v1/assistants`, realtime) is not served and answers 404 `route_not_found`; the task API carries those model types. OpenAI-shaped embeddings and transcriptions after validation are open (not decided yet).

### Pages

| Page | Carries |
| --- | --- |
| [Authentication](/docs/reference/authentication) | API keys and a person's access token, `Authorization: Bearer`, key kinds, workspace state |
| [Chat completions](/docs/reference/chat-completions) | `POST /v1/chat/completions`, every field, the `model` values, streaming, features |
| [Responses](/docs/reference/responses) | `POST /v1/responses`, published only after validation |
| [Models](/docs/reference/models) | `GET /v1/models`, `GET /v1/models/{id}` and the `hips` entry |
| [Tasks](/docs/reference/tasks) | `POST /v1/tasks`: the envelope, batching, per-input errors |
| [Jobs](/docs/reference/jobs) | `POST /v1/jobs`, `GET /v1/jobs/{id}`, cancellation, result retrieval, states |
| [Uploads](/docs/reference/uploads) | `POST /v1/uploads`: the presigned PUT, purposes, statuses |
| [Deployments](/docs/reference/deployments) | The read side; `dep_` ids in `model` and in `deployment` |
| [Requirements and headers](/docs/reference/headers) | The four requirements, the `hips` body object, every `x-hips-*` and `x-ratelimit-*` header |
| [Errors](/docs/reference/errors) | The envelope and every type and code |
| [Usage](/docs/reference/usage) | Usage fields per billing unit; money separate from units |
| [Versioning](/docs/reference/versioning) | How the contract is versioned and deprecated |

## Authentication
Route: https://hips.com/docs/reference/authentication
Status: preview; updated 2026-10-21

The API takes two bearer credentials: an API key, a workspace's server-to-server credential for the inference API and the SDKs, and a person's access token, issued to the person's own tools by sign-in. Use a key for a server or an SDK; `hi` and HIPS Code sign in. Every request is attributed to one workspace and one plan; the plan decides limits, the request-data policy and which requirements are allowed.

*Authentication*

- `Credential`: `Authorization: Bearer` followed by the key. Created in the Console's API keys view, named, of a kind, shown once, stored as a hash. Public id `key_`. The key's value is read from `HIPS_API_KEY`; no key value appears on any page.
- `Where keys live`: On the server or in a secret store. Keep keys on the server or in an appropriate secret store, rather than shipping them in a public browser application. The gateway sends no cross-origin headers for live keys (not decided yet).
- `Publishable keys`: Reserved for a later browser path and not part of this version of the contract (not decided yet).
- `A person's tools`: The `hi` CLI, the provider app and HIPS Code need no API key: they sign in as the person with OAuth 2.0 device authorization. The tool shows a user code `XXXX-XXXX` and its link, the person approves it in the Console while signed in and chooses the workspace, and the tool receives a short-lived, scoped access token with a refresh token. The gateway accepts that token as the bearer beside API keys and attributes usage to the chosen workspace. The access token lasts 1 hour and the refresh token 30 days, replaced on each use; an expired access token answers 401 `token_expired`, and a token without the `inference` scope 403 `insufficient_scope`. The steps are on [Sign in with device authorization](/docs/cli/login).
- `Key defaults`: Each key carries defaults for the four request requirements (pool, pricing mode, region, fallback), set in the Console.
- `Key kind` (`full` or `inference_only`): `full` reaches every route; `inference_only` the inference routes alone (chat completions, responses, models, tasks, jobs, uploads and the jobs it created). Fixed at creation. A route the kind excludes is a 403 `key_scope_denied`. A per-key model or deployment allow-list is open (not decided yet).
- `Workspace state`: A key of a paused or deleted workspace answers 403 `workspace_suspended` on every route; a key of a workspace whose owner has not passed identity verification answers 403 `permission_error` with the code `workspace_unverified`.

### Errors this page can answer

| Status | Type | Code | Situation | Retry |
| --- | --- | --- | --- | --- |
| 401 | `authentication_error` | `missing_api_key` | No `Authorization` header, or not a bearer | No |
| 401 | `authentication_error` | `invalid_api_key` | Unknown, malformed or revoked key. The message never says which | No |
| 403 | `permission_error` | `key_scope_denied` | The key's kind excludes the route | No |
| 403 | `permission_error` | `workspace_unverified` | The workspace's owner has not passed identity verification; the message names the Console's verification screen | After verification |
| 403 | `workspace_suspended` | `workspace_paused` | The workspace is paused: by balance, by an administrator, by a dispute, by a budget hard stop or by an owner. The message says which and where to resolve it | After resolution |
| 403 | `workspace_suspended` | `plan_lapsed` | The subscription lapsed and no owner has yet acknowledged the free plan's request-data policy or paid; the policies hold meanwhile | After acknowledgment or payment |
| 403 | `workspace_suspended` | `workspace_deleted` | The workspace is deleted (restorable 30 days) | After restore |

## Chat completions
Route: https://hips.com/docs/reference/chat-completions
Status: preview; updated 2026-10-21

For open-weight language models the public API is OpenAI-compatible, so OpenAI client SDKs work with a HIPS key, base URL and model id. Compatibility is a request and response shape, validated per endpoint, model and client version; it is never a model list.

**POST /v1/chat/completions** (preview): Chat completion, streamed or not. The first route built and the first validated.

### Three rules

- Nothing is silently dropped. A field that would change the model's output or the bill and that HIPS or the named model cannot honor is a 400, never ignored.
- Nothing is silently substituted. The model served is the model named. No fallback to another model, ever.
- A requirement is never weakened to make a request succeed.

### The request

The body is OpenAI's. A 400 names the field in `param` and the model in `message` when the refusal depends on the model.

*Fields*

- `model`, Required: A catalog id, an alias, a pinned id or a `dep_` id.
- `messages`, Required, non-empty: Roles `system`, `developer`, `user`, `assistant`, `tool`. `content` a string or an array of parts. Text parts always; `image_url` parts only on a model that advertises `vision`; `input_audio` and `file` parts are a 400 `unsupported_parameter` (audio goes through the task API).
- `stream`, Accepted: Server-sent events, one `data:` line per chunk, then `data: [DONE]`.
- `stream_options`, Accepted with `stream: true`: `include_usage` honored. Without `stream` a 400 `unsupported_value`.
- `max_completion_tokens, max_tokens`, Accepted: Both names; both given and different is a 400 `invalid_value`. Over the model's `max_output_tokens` is a 400 `max_tokens_exceeded`. Absent: the model's default from its entry.
- `temperature, top_p, stop, seed, presence_penalty, frequency_penalty`, Accepted: Passed to the engine. `stop` up to the count in the model's entry. `seed` is best effort; determinism is not promised across workers.
- `n`, Accepted as 1: Any other value is a 400 `unsupported_value`: one answer per request, so the quote and the bill are one line.
- `response_format`, Accepted: `text` always; `json_object` on a model advertising `json_object`; `json_schema` with `name`, `schema` and `strict` on a model advertising `json_schema`. Otherwise a 400 `unsupported_parameter` naming the feature.
- `tools, tool_choice, parallel_tool_calls`, Accepted: On a model advertising `tools` (and `parallel_tool_calls` for the third). Shapes are OpenAI's, unchanged.
- `logprobs, top_logprobs`, Accepted: On a model advertising `logprobs`.
- `logit_bias`, Accepted: On a model advertising `logit_bias`.
- `reasoning_effort`, Accepted: On a model advertising `reasoning`; otherwise a 400 `unsupported_parameter`.
- `user`, Accepted, discarded: It changes neither the output nor the bill. Not stored. Stated here so the discard is not silent.
- `store, metadata`, Rejected, 400 `stateful_not_supported`: The gateway stores no bodies.
- `functions, function_call`, Rejected, 400 `unsupported_parameter`: OpenAI's deprecated names; `tools` is the shape.
- `modalities, audio, prediction, web_search_options, service_tier`, Rejected, 400 `unsupported_parameter`: Audio and media go through the task API; pools and pricing modes are headers, not a tier.
- `Any other name`, Rejected, 400 `unknown_parameter`: Typos are caught, not ignored.

### The model field

| Value | Form | Resolves to |
| --- | --- | --- |
| Catalog id | `<family>-<size>[-<variant>]`, lowercase | The current pinned version of that catalog entry; moves with releases |
| Alias | As listed in the entry's `hips.aliases` | The entry it names |
| Pinned id | `<catalog id>-<version>` | That version, as long as it is served |
| Deployment id | `dep_<base32>` | A customer model deployment, or a catalog model pinned to an always-on allocation, of the key's workspace |

| Situation | Answer |
| --- | --- |
| Unknown id, or another workspace's `dep_` | 404 `model_not_found` |
| A model the plan does not allow, or a route the key's kind excludes | 403 `model_not_on_plan` or `key_scope_denied` |
| A `dep_` whose model is not a language model | 400 `not_a_language_model` (use `POST /v1/tasks`) |
| A deployment in `stopped` | 400 `deployment_stopped` |
| A deployment in `allocating` or `loading` | 503 `deployment_not_ready` with `Retry-After` |
| A deployment waiting for its version's tariff (`tariff_pending`) | 503 `deployment_not_ready` with `Retry-After`; the message says the tariff is pending. Nothing is charged |
| A deployment in `degraded` | Served; the state is in `GET /v1/models/{id}` |

The response's `model` and the `x-hips-model` header carry the pinned id that was served; `x-hips-deployment` carries the `dep_` id when the request named one.

### The response

OpenAI's `chat.completion` object: `id`, `object`, `created`, `model`, `choices[{index, message{role, content, tool_calls, refusal}, finish_reason, logprobs}]`, `usage`.

*HIPS specifics*

- `id`: The request id, `req_...`, so a log line and a support question name the same thing.
- `model`: The pinned id served.
- `finish_reason`: `stop`, `length`, `tool_calls`. `content_filter` is never emitted: HIPS applies no output filter on this route.
- `system_fingerprint`: Omitted.
- `usage`: The [usage object](/docs/reference/usage). Money is never in it.
- `Extras`: In headers, not in the body, except the streamed `hips` object.

### Streaming

`stream: true` answers 200 with `Content-Type: text/event-stream`, one `data:` line per chunk in OpenAI's `chat.completion.chunk` shape, then `data: [DONE]`. The rules are on [Streaming](/docs/operating/streaming); the final usage chunk with its `hips` object looks like this:

Final chunk:

```
data: {"id":"req_...","object":"chat.completion.chunk","created":0,"model":"<pinned id>","choices":[],"usage":{"prompt_tokens":0,"completion_tokens":0,"total_tokens":0},"hips":{"cost_micros":0,"latency_ms":0,"quote":"quote_..."}}

data: [DONE]
```

### Tool calls and structured outputs

Features are advertised per model in `GET /v1/models` and come from the engine and the model together. Shapes are OpenAI's, unchanged. A feature the model does not advertise is a 400 `unsupported_parameter`.

| Feature | Request | Response |
| --- | --- | --- |
| `tools` | `tools: [{"type":"function","function":{...}}]`; `tool_choice` as `auto`, `none`, `required` or a named function | `message.tool_calls` with `arguments` a JSON string; `finish_reason: "tool_calls"`. Streamed as `delta.tool_calls` by `index` |
| `parallel_tool_calls` | `parallel_tool_calls` as `true` or `false` | More than one entry in `tool_calls` |
| `json_object` | `response_format: {"type":"json_object"}` | `content` is one JSON document |
| `json_schema` | `response_format: {"type":"json_schema","json_schema":{"name","schema","strict": true}}` | `content` validates against the schema; `strict: false` accepted where the model advertises it |
| `vision` | `image_url` parts in a `user` message | As text |
| `logprobs` | `logprobs: true`, `top_logprobs` | `choices[].logprobs` |
| `reasoning` | `reasoning_effort` | `usage.completion_tokens_details.reasoning_tokens` |
| `logit_bias` | `logit_bias` | Applied by the engine |

### 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` | `unsupported_parameter` | A known OpenAI field HIPS does not accept, or a feature the named model does not advertise | No |
| 400 | `invalid_request_error` | `unsupported_value` | `n` other than 1, `stream_options` without `stream`, a message role or part type not accepted | No |
| 400 | `invalid_request_error` | `stateful_not_supported` | `store`, `metadata`, `previous_response_id`, `conversation` | No |
| 400 | `invalid_request_error` | `context_length_exceeded` | The prompt is over the model's `context_length`; the prompt is never truncated | No |
| 400 | `invalid_request_error` | `max_tokens_exceeded` | `max_tokens` over the model's `max_output_tokens` | 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` | `not_a_language_model` | A task model or a task-model deployment named on an OpenAI-compatible route | No |
| 400 | `invalid_request_error` | `deployment_stopped` | The `dep_` is in `stopped`; start it in the Console | No |
| 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` | `stable_price_not_in_force` | `pricing_mode: stable` with no stable price covering this workspace, model and period | No |
| 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 |
| 404 | `not_found_error` | `model_not_found` | Unknown catalog id, alias, pinned id or `dep_`; another workspace's `dep_` | No |
| 429 | `rate_limit_error` | `rate_limit_exceeded` | A rate limit; `param` is `requests`, `tokens`, `units` or `uploads`; `Retry-After` | Yes, after `Retry-After` |
| 429 | `rate_limit_error` | `concurrency_limit_exceeded` | Too many concurrent streams or active jobs; `param` is `streams` or `jobs`; `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` | `deployment_not_ready` | The `dep_` is `allocating` or `loading`, or waits for its version's tariff (`tariff_pending`); `Retry-After` | Yes |
| 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 |

## Responses
Route: https://hips.com/docs/reference/responses
Status: preview; updated 2026-10-21

OpenAI's Responses shape, served after validation: the route answers 404 `route_not_available` until its rows of the compatibility matrix pass.

**POST /v1/responses** (after validation): OpenAI's Responses shape. Answers 404 `route_not_available` until its matrix rows pass.

### When served

- OpenAI's Responses request and response shapes with `input` as a string or as message items with `input_text` and `input_image` parts; `instructions`; `tools` and `text.format` (the `json_schema` feature); `stream: true` as OpenAI's typed events; `max_output_tokens`.
- The same `model` values, the same headers, errors and requirements as [chat completions](/docs/reference/chat-completions).
- `store: true`, `previous_response_id`, `conversation`, file and audio items, built-in tools (web search, file search, computer use) and background mode are 400 `stateful_not_supported` or `unsupported_parameter`: the gateway holds no state between requests.

> Prelaunch: Published only after validation. The matrix row for this route is unvalidated; until it passes, the route is not served.

## Models
Route: https://hips.com/docs/reference/models
Status: preview; updated 2026-10-21

OpenAI's list shape with one entry per catalog id the key may name, one per pinned id being served, and one per deployment of the key's workspace; `owned_by` is `hips` for the catalog and the workspace's `ws_` id for a deployment.

**GET /v1/models** (preview): The models and deployments the key may name, with the `hips` extensions.

**GET /v1/models/{id}** (preview): One entry of the list, by catalog id, pinned id or `dep_` id.

### The hips object on each entry

- `task`: The task type: `chat`, `classification`, `embedding`, `image_generation`, `transcription`, `speech`, `video_generation`, and the others the catalog defines.
- `modality`: `{"input": ["text", "image", ...], "output": ["text", ...]}`.
- `family, version, aliases, pinned_ids`: The catalog entry's names; `pinned_ids` the versions currently served.
- `billing_unit`: `input_output_tokens`, `per_1000_classifications`, `per_image`, `per_second`, and the others of the pricing document.
- `features`: The features the model advertises, per pool: `{"approved": [...], "personal": [...]}`.
- `pools`: The supply state per pool under no requirements: `available`, `limited`, `unavailable` or `unknown`. A snapshot, never a reservation; stale becomes `unknown`.
- `lanes`: `shared`, `always_on` or both.
- `context_length, max_output_tokens, limits`: The model's limits; `limits` holds the task-specific ones (inputs per request, input bytes, duration).
- `license`: The model's license identifier and conditions URL.
- `deprecates_at`: For a pinned id with a retirement date; absent otherwise.
- `deployment`: On a `dep_` entry: `{"state", "model", "lane", "pool", "since"}`.
- `available_on_plan`: `false` on a model the plan does not allow, so a client can tell unknown from not on my plan before sending a request.

Both routes answer with the key's view: a model the plan does not allow is listed with `hips.available_on_plan: false`, so a client can tell unknown from not on my plan before sending a request. The catalog is the only source of names; it lists every model HIPS has published, each with its status.

### Errors these routes can answer

| Status | Type | Code | Situation | Retry |
| --- | --- | --- | --- | --- |
| 403 | `permission_error` | `key_scope_denied` | The key's kind excludes the route | No |
| 404 | `not_found_error` | `model_not_found` | Unknown catalog id, alias, pinned id or `dep_`; another workspace's `dep_` | No |

## Tasks
Route: https://hips.com/docs/reference/tasks
Status: preview; updated 2026-10-21

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/tasks** (preview): A 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": "personal", "pricing_mode": "market", "fallback": false}
}
```

*Fields*

- `model or deployment`, Exactly 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`.
- `task`, Required: Must be the model's task, or one of them for a model advertising several; otherwise a 400 `task_mismatch`.
- `inputs`, Required: 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).
- `options`, Per 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`.
- `hips`, Optional: 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:

```
{
  "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}
}
```

*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 |

## Jobs
Route: https://hips.com/docs/reference/jobs
Status: preview; updated 2026-10-21

The same request body as a task. `POST /v1/jobs` answers 202 at once with the job object; the client polls `GET /v1/jobs/{id}` or waits for the SDK's helper. Video, long audio and batched generation are jobs; any task type may be submitted as a job.

**POST /v1/jobs** (preview): An asynchronous job: the same body as a task, answered 202 with the job object.

**GET /v1/jobs/{id}** (preview): The job object with its status, transitions, result, usage and error.

**GET /v1/jobs** (preview): The workspace's jobs, newest first, cursor-paginated.

**POST /v1/jobs/{id}/cancel** (preview): Cancels a queued, assigned or running job.

Job object:

```
{
  "object": "job",
  "id": "job_...",
  "status": "queued",
  "model": "<pinned id>",
  "task": "video_generation",
  "created_at": "2026-10-20T12:00:00Z",
  "transitions": [{"status": "queued", "at": "2026-10-20T12:00:00Z"}],
  "requirements": {"pool": "approved", "pricing_mode": "market", "region": null, "fallback": false},
  "quote": "quote_...",
  "result": null,
  "error": null,
  "usage": null,
  "expires_at": null
}
```

### States

| Status | Meaning | Terminal |
| --- | --- | --- |
| `queued` | Accepted, quote bound, no worker yet | No |
| `assigned` | A worker took it; the attempt is `att_` | No |
| `running` | The worker reported a start | No |
| `completed` | `result` is set; `usage` and the cost are final | Yes |
| `failed` | `error` is set (the envelope's shape); nothing billed unless the retries page says otherwise | Yes |
| `canceled` | By `POST /v1/jobs/{id}/cancel`, by a client disconnect or by the workspace being paused; the running attempt, if any, ends `interrupted` with reason `canceled` | Yes |
| `interrupted` | An attempt was interrupted after a streamed partial answer had already reached the client, or the attempt limit was reached after an interruption; nothing billed | Yes |

Every transition carries a timestamp and, when the scheduler has one, an explanation. An attempt interrupted before any output returns the job to `queued` while attempts remain.

### Routes

*Behavior*

- `GET /v1/jobs/{id}`: The job object. `result` holds inline results (the task's result shape) or, for media, `outputs: [{upload_id, download_url, content_type, bytes, expires_at}]` with a presigned GET. Another workspace's job is a 404 `job_not_found`.
- `GET /v1/jobs`: The key's workspace's jobs, newest first, cursor-paginated, filterable by `status`, `model`, `deployment` and `task`.
- `POST /v1/jobs/{id}/cancel`: `queued`: canceled at once, nothing billed. `assigned` or `running`: cancellation is sent to the worker; the attempt ends `interrupted` with reason `canceled` and the job ends `canceled`; the charge for work done is (not decided yet) (proposed: nothing). A terminal job answers 200 with the job unchanged.
- `Expiry`: `result` and `outputs` are retrievable until `expires_at` (not decided yet); the job record and its usage stay. A read after expiry is a 404 `result_expired` on `result`; the job object itself still answers.
- `Webhooks`: None in this version; a completion webhook is open (not decided yet). The Console shows job progress.

### Errors these routes can answer

| Status | Type | Code | Situation | Retry |
| --- | --- | --- | --- | --- |
| 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 |
| 404 | `not_found_error` | `job_not_found`, `upload_not_found` | An id in the path that is unknown or another workspace's | No |
| 404 | `not_found_error` | `result_expired` | A job's result read after `expires_at` | No |
| 429 | `rate_limit_error` | `concurrency_limit_exceeded` | Too many concurrent streams or active jobs; `param` is `streams` or `jobs`; `Retry-After` | Yes, after `Retry-After` |

## Uploads
Route: https://hips.com/docs/reference/uploads
Status: preview; updated 2026-10-21

A presigned PUT for task and job inputs only. The gateway never receives the bytes: the client declares the file, PUTs it to the returned address with the given headers, then names the `upl_` id in a task input. A customer model is never uploaded: it is imported from a model hub in the Console, as [Import and run your model](/docs/import-and-run) describes.

**POST /v1/uploads** (preview): A presigned PUT for a task or job input. The gateway never receives the bytes.

**GET /v1/uploads/{id}** (preview): The upload's status.

Request:

```
{"purpose": "input", "filename": "call.wav", "content_type": "audio/wav", "size_bytes": 10485760, "sha256": "<hex>"}
```

answers 201:

Response:

```
{
  "object": "upload",
  "id": "upl_...",
  "purpose": "input",
  "status": "pending",
  "upload_url": "<presigned PUT>",
  "upload_headers": {"Content-Type": "audio/wav"},
  "upload_expires_at": "...",
  "expires_at": "..."
}
```

The client PUTs the bytes to `upload_url` with the given headers, then names `upl_...` in `inputs[].upload_id`.

*Rules*

- `purpose`: `input` (a task or job input), the only purpose. The `model` purpose is withdrawn: a customer model is imported from a model hub, never uploaded. `purpose: "model"` answers 400 `invalid_value` with `param: "purpose"` and a message naming the Console's import. The field stays required.
- `status`: `pending` (no bytes yet), `ready` (bytes received, size and type match), `consumed` (an `input` upload used by a job on a workspace whose policy deletes inputs after use), `expired`. `GET /v1/uploads/{id}` returns it.
- `Mismatch`: Bytes whose size, type or `sha256` differ from the declaration make the upload `failed` and its use a 400 `upload_mismatch`.
- `Limits`: Size per upload and uploads per day by plan (not decided yet); multipart for large inputs (long audio and video) (not decided yet).
- `Retention`: An upload is deleted at `expires_at` (not decided yet) or when consumed; where a region requirement applies, it is stored in that region (not decided yet).
- `Customer models`: Not an upload. A customer model version comes from an import from a model hub, a Console action; this contract addresses only its deployment (`dep_`). A public import route is open (not decided yet).

### Errors these routes can answer

| Status | Type | Code | Situation | Retry |
| --- | --- | --- | --- | --- |
| 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` | `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_idempotency_key`, `idempotency_key_reused`, `idempotency_in_progress` | The idempotency rules | The last one, later |
| 404 | `not_found_error` | `job_not_found`, `upload_not_found` | An id in the path that is unknown or another workspace's | No |

## Deployments
Route: https://hips.com/docs/reference/deployments
Status: preview; updated 2026-10-21

A deployment (`dep_`) is a customer model version made runnable, or a catalog model pinned to an always-on allocation. It is created in the Console in the first version (a public route is open (not decided yet)); the API reads it and addresses it.

### How a deployment is addressed

| Model type | Field | Route |
| --- | --- | --- |
| Customer-owned language model | `model: "dep_..."` | `POST /v1/chat/completions` |
| Customer-owned model of any other type | `deployment: "dep_..."` | `POST /v1/tasks`, `POST /v1/jobs` |
| A catalog model pinned to an always-on allocation | `model: "dep_..."` | The model's route |

A `dep_` in `model` on the task API is a 400 `invalid_value` that points at `deployment`; a task-model deployment named on an OpenAI-compatible route is a 400 `not_a_language_model`.

### Reading a deployment

`GET /v1/models` lists one entry per deployment of the key's workspace with `owned_by` the workspace's `ws_` id and a `hips.deployment` object; `GET /v1/models/{id}` with the `dep_` id returns it alone.

*The deployment object*

- `deployment.state` (`allocating`, `loading`, `ready`, `busy`, `degraded`, `stopped`, or `tariff_pending`): Every transition is timestamped and explained in the Console. Allocation is not readiness. A `shared` deployment created before its version's tariff waits in `tariff_pending`: it takes no request, a request naming it answers 503 `deployment_not_ready`, and nothing is charged.
- `deployment.model`: The customer model version (`mdl_` and its version) or the catalog pinned id.
- `deployment.lane` (`shared` or `always_on`): `always_on` exists in the `approved` pool only.
- `deployment.pool` (`personal` or `approved`): Customer-owned models run in the `approved` pool only at launch.
- `deployment.since`: When the current state was entered.

### Requirements on a deployment

The deployment's pool came with disclosed access conditions and fallback is set on the deployment: a request header or `hips` field may turn fallback off but never on; `fallback: true` on such a request is a 400 `requirement_conflict`. `x-hips-deployment` on the response carries the `dep_` id; `x-hips-lane` reports the lane.

### Errors a deployment can answer

| Status | Type | Code | Situation | Retry |
| --- | --- | --- | --- | --- |
| 400 | `invalid_request_error` | `not_a_language_model` | A task model or a task-model deployment named on an OpenAI-compatible route | No |
| 400 | `invalid_request_error` | `deployment_stopped` | The `dep_` is in `stopped`; start it in the Console | 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 |
| 503 | `overloaded_error` | `deployment_not_ready` | The `dep_` is `allocating` or `loading`, or waits for its version's tariff (`tariff_pending`); `Retry-After` | Yes |

## Requirements and headers
Route: https://hips.com/docs/reference/headers
Status: preview; updated 2026-10-21

Pool, pricing mode, region and fallback are requirements of a request. The scheduler enforces them on every attempt; the gateway validates them and binds the quote under them.

### Request requirements

| Requirement | Header (OpenAI-compatible routes) | `hips` body field (task API) | Values | Default when the key has none |
| --- | --- | --- | --- | --- |
| Pool | `x-hips-pool` | `pool` | `personal`, `approved` | Set on the key at creation (not decided yet) |
| Pricing mode | `x-hips-pricing-mode` | `pricing_mode` | `market`, `stable` | `market` |
| Region | `x-hips-region` | `region` | A coarse code (not decided yet), or absent | Absent (no region constraint) |
| Fallback | `x-hips-fallback` | `fallback` | `true`, `false` | `false` |

- Precedence: a value in the request (header or `hips` field) beats the key's default; the key's default beats the platform default. On the task API both may be sent; when both are present and differ, a 400 `requirement_conflict`. The HIPS SDK sends the `hips` object and never the headers.
- Validation at the gateway: an unknown value is a 400 `invalid_requirement`. A region on a plan without region selection is a 403 `region_not_on_plan`. `stable` without a stable price in force is a 400 `stable_price_not_in_force`. A conflict the catalog decides statically is a 400 `requirement_conflict`.
- Enforcement at the scheduler: whether eligible supply exists now is not the gateway's to know for certain; `pool_unavailable` and `no_capacity` are 503s from the scheduler's answer. Never silently cross a required boundary to make a request succeed.
- Fallback never weakens a rule: `fallback: true` lets the scheduler place a job in the other pool when the named pool has nothing eligible; it never relaxes region or the request-data policy, and it is off by default.
- Requirements travel with the job: stored at acceptance, applied to every attempt and every retry; the `requirements` object on a job and the `x-hips-pool`, `x-hips-pricing-mode` and `x-hips-region` response headers show the effective ones.
- The lane is not a requirement: a `dep_` on an allocation is `always_on`; everything else is `shared`. `x-hips-lane` reports it.

On the OpenAI clients a requirement rides as a header: `default_headers` on the Python client, `defaultHeaders` on the Node client, `-H` on cURL.

### The hips body object

hips:

```
{"hips": {"pool": "personal", "pricing_mode": "market", "region": null, "fallback": false}}
```

### Response headers

On every response, errors included unless the rule says otherwise. The `x-hips-*` values are also what the usage record stores, so a client that logs the headers can reconcile against the Console line by line.

- `x-hips-request-id` (`req_...`): On every response, every error, every stream head and every idempotent replay (the original's).
- `x-hips-model` (pinned id): The pinned id served. Not on errors before resolution.
- `x-hips-deployment` (`dep_...`): The deployment id, when the request named one.
- `x-hips-pool` (`personal` or `approved`): The pool that ran the work. When fallback was used, this is how a client sees it. Not on errors before placement.
- `x-hips-lane` (`shared` or `always_on`): Follows from what the request names: a `dep_` on an allocation is `always_on`; everything else is `shared`.
- `x-hips-pricing-mode` (`market` or `stable`): The effective pricing mode.
- `x-hips-region` (region code): The effective region code, or absent.
- `x-hips-quote` (`quote_...` or `offer_...`): The quote bound at acceptance; on a `stable` request, the stable-price offer in force. Whether it also carries the bound rates is open (not decided yet).
- `x-hips-cost-micros` (integer): The charge in USD micro-dollars. Not on streamed responses (the `hips` object of the final usage chunk instead) and not on errors (nothing charged).
- `x-hips-latency-ms` (integer): From the gateway's receipt of the complete request to the complete answer. On a streamed response, in the `hips` object.
- `x-ratelimit-limit-requests, x-ratelimit-remaining-requests, x-ratelimit-reset-requests` (integer, integer, duration): The key's request limit in the current window, what remains, and the time to reset in OpenAI's duration format, so clients that read them keep working.
- `x-ratelimit-limit-tokens, x-ratelimit-remaining-tokens, x-ratelimit-reset-tokens` (integer, integer, duration): The same for tokens on language-model routes; on the task API the unit is task units with the same header names.
- `Retry-After` (seconds): On 429 and 503, nothing else.

### Request id

`x-hips-request-id: req_<base32>` is on every response, every error, every stream head and every idempotent replay (the original's). It is the `id` of a chat completion, it is carried to the worker and onto every attempt, it is the usage record's key, and the Console's Usage and activity view searches by it. A support question quotes it. HIPS does not accept a client-chosen request id; whether the gateway also sends `x-request-id` is open (not decided yet).

## Errors
Route: https://hips.com/docs/reference/errors
Status: preview; updated 2026-10-21

One envelope on every public route, including unknown paths and the responses the edge answers when it can, in the OpenAI shape so compatible clients parse it. Only 503 and 500 are ever 5xx. Nothing is billed on an error.

Envelope:

```
{
  "error": {
    "message": "<a sentence a developer can act on>",
    "type": "<type>",
    "param": "<field or header, or null>",
    "code": "<code>"
  }
}
```

The `message` is for a developer: it names the field, the model, the limit and the count, and never a provider, a device, an address or another workspace. `param` names the field or header, or is null. Every error carries `x-hips-request-id`.

### Types

The `type` list is closed; a specific situation is a `code` under one of these types.

| Status | Type | Meaning |
| --- | --- | --- |
| 400 | `invalid_request_error` | The request cannot be served as sent; nothing is billed |
| 401 | `authentication_error` | No key, or a key the gateway does not accept |
| 402 | `insufficient_credit` | The balance does not cover the request's maximum cost at the bound quote |
| 403 | `permission_error`, `workspace_suspended` | The key, plan or workspace may not do this |
| 404 | `not_found_error` | A model, job, upload or route that does not exist for this key |
| 429 | `rate_limit_error` | A limit of the key or workspace; `Retry-After` is sent |
| 503 | `overloaded_error` | No capacity under the request's requirements; `Retry-After` is sent |
| 500 | `api_error` | A fault in HIPS; nothing is billed |

### Codes

The complete list for this version. A request either succeeds or fails as a whole, except a task's per-input errors and a stream that fails after it started. A limit is never a 5xx, so SDKs that retry every 5xx do not retry a limit.

| 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` | `unsupported_parameter` | A known OpenAI field HIPS does not accept, or a feature the named model does not advertise | No |
| 400 | `invalid_request_error` | `unsupported_value` | `n` other than 1, `stream_options` without `stream`, a message role or part type not accepted | No |
| 400 | `invalid_request_error` | `stateful_not_supported` | `store`, `metadata`, `previous_response_id`, `conversation` | No |
| 400 | `invalid_request_error` | `context_length_exceeded` | The prompt is over the model's `context_length`; the prompt is never truncated | No |
| 400 | `invalid_request_error` | `max_tokens_exceeded` | `max_tokens` over the model's `max_output_tokens` | 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` | `not_a_language_model` | A task model or a task-model deployment named on an OpenAI-compatible route | 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` | `stable_price_not_in_force` | `pricing_mode: stable` with no stable price covering this workspace, model and period | 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 |
| 400 | `invalid_request_error` | `request_timeout` | The body stopped arriving | Yes |
| 401 | `authentication_error` | `missing_api_key` | No `Authorization` header, or not a bearer | No |
| 401 | `authentication_error` | `invalid_api_key` | Unknown, malformed or revoked key. The message never says which | No |
| 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` | `key_scope_denied` | The key's kind excludes the route | No |
| 403 | `permission_error` | `model_not_on_plan` | The model or feature is not in the workspace's plan | No |
| 403 | `permission_error` | `region_not_on_plan` | A region requirement on a plan without region selection | No |
| 403 | `permission_error` | `pool_not_allowed` | A pool the workspace may not use for this model | No |
| 403 | `permission_error` | `workspace_unverified` | The workspace's owner has not passed identity verification; the message names the Console's verification screen | After verification |
| 403 | `workspace_suspended` | `workspace_paused` | The workspace is paused: by balance, by an administrator, by a dispute, by a budget hard stop or by an owner. The message says which and where to resolve it | After resolution |
| 403 | `workspace_suspended` | `plan_lapsed` | The subscription lapsed and no owner has yet acknowledged the free plan's request-data policy or paid; the policies hold meanwhile | After acknowledgment or payment |
| 403 | `workspace_suspended` | `workspace_deleted` | The workspace is deleted (restorable 30 days) | After restore |
| 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 |
| 404 | `not_found_error` | `result_expired` | A job's result read after `expires_at` | No |
| 404 | `not_found_error` | `route_not_found` | Unknown path | No |
| 404 | `not_found_error` | `route_not_available` | A route of this contract not yet served (`/v1/responses` before validation) | No |
| 404 | `not_found_error` | `method_not_allowed` | A known path with another method; `Allow` is sent | No |
| 429 | `rate_limit_error` | `rate_limit_exceeded` | A rate limit; `param` is `requests`, `tokens`, `units` or `uploads`; `Retry-After` | Yes, after `Retry-After` |
| 429 | `rate_limit_error` | `concurrency_limit_exceeded` | Too many concurrent streams or active jobs; `param` is `streams` or `jobs`; `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` | `deployment_not_ready` | The `dep_` is `allocating` or `loading`, or waits for its version's tariff (`tariff_pending`); `Retry-After` | Yes |
| 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 |

> Statuses outside this list (409 for `idempotency_in_progress`, 413 for an oversize body, 408 for a stalled body) are mapped to 400 to honor the closed list as written; the conventional statuses are open (not decided yet).

## Usage
Route: https://hips.com/docs/reference/usage
Status: preview; updated 2026-10-21

Usage is counted in the model's billing unit and reported on every answered request. Money is never in `usage`: the cost is `x-hips-cost-micros`, or on a streamed answer the `hips` object of the final usage chunk, and the usage record.

### The usage object on chat completions

usage:

```
{"usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "prompt_tokens_details": {"cached_tokens": 0}, "completion_tokens_details": {"reasoning_tokens": 0}}}
```

- `prompt_tokens, completion_tokens`: Counted by the serving engine's tokenizer for the pinned model. These are the billable units at the model's separate input and output rates.
- `total_tokens`: The sum; not a billing unit.
- `prompt_tokens_details.cached_tokens`: Reported where the engine reports prefix-cache hits; otherwise `0`. A cached prompt token is billed at the model's cached-input rate ([Prompt caching](/docs/prompt-caching)).
- `completion_tokens_details.reasoning_tokens`: On models advertising `reasoning`; counted inside `completion_tokens`.

### The usage object on tasks and jobs

usage:

```
{"usage": {"units": 2, "unit": "classification", "billed_units": 1}}
```

`units` counts the inputs, `unit` names the task's unit, `billed_units` the inputs that were answered. On a job, `usage` is null until the job is `completed`.

### Units per task

| Task | Billing unit | What is counted |
| --- | --- | --- |
| `chat` | `input_output_tokens` | `prompt_tokens` and `completion_tokens`, at separate input and output rates |
| `classification` | `per_1000_classifications` | `units` and `billed_units` in the task's `usage`; one item evaluated once under the task's input conditions is one classification |
| `image_generation`, `image_edit` | `per_image` | Per output image at a stated dimension band, and per step where the model exposes steps |
| `video_generation` | `per_second` | Per second of output video at a stated resolution and frame rate |
| `transcription`, `translation` | `per_minute` | Per minute of input audio |
| `speech` | `per_1000_characters` or `per_second` | Per 1,000 input characters, or per second of output audio where the model's cost follows the output |
| `embedding` | `input_output_tokens` | Input tokens; no output rate |

Every setting that changes the charge is a named parameter of the task's request, is shown in the Playground beside the measured usage, and is carried in the quote. The unit is set per model in the catalog.

### The usage record

One per request. It holds the request id, timestamps (received, accepted, first byte, completed), the key, the workspace, the pinned id, the deployment if any, task, pool, lane, pricing mode, region, the quote, units in and out, the rate version, the cost, the outcome (`completed`, `failed`, `canceled`, `interrupted`), the error code if any, the attempt count, latency, the client's address and user agent for abuse control, and the sizes of the body and the output. It holds no prompt, no input, no output. The Console's Usage and activity view shows and exports it.

## Versioning
Route: https://hips.com/docs/reference/versioning
Status: preview; updated 2026-10-21

The contract is versioned by its path; models are versioned separately; and a field the gateway does not know is an error, never a no-op, so a client that works today keeps working when a field becomes accepted.

- The path carries the version. `/v1` is this contract. A change that adds a field, a header, a code, a route or a model is not a version change; a change that removes or renames one, or changes a meaning, is a new path version with a notice period (not decided yet).
- Models are versioned separately. A catalog id resolves to the current pinned version and moves with releases; a pinned id names one version and does not move. Retirement of a pinned id and its notice period are open (not decided yet).
- Unknown is an error, not a no-op. A field the gateway does not know is a 400 `unknown_parameter`; a known OpenAI field the gateway does not accept is a 400 `unsupported_parameter`. Acceptance only turns a 400 into a served request.
- Every response carries `x-hips-request-id`, on every version and every error.

### The docs' own versioning

The Docs section is versioned by date, not by number: every page carries an updated date and the [changelog](/docs/changelog) lists dated entries, newest first, each naming the pages changed.

## Operating guidance
Route: https://hips.com/docs/operating
Status: preview; updated 2026-10-21

How the API behaves around a request: what a limit means, which errors to retry, what is charged when an attempt fails, how to make a retry safe, how a stream ends, what happens to your data, and which rows of the contract have been validated.

| Page | Carries |
| --- | --- |
| [Limits](/docs/operating/limits) | Rate limits per key and plan, the headers, what 429 means; no number until decided |
| [Errors](/docs/operating/errors) | Every error type with when it occurs and what to do; only 503 and 500 are ever 5xx |
| [Retries and billing outcomes](/docs/operating/retries) | What is charged when an attempt fails, is interrupted, times out or is retried |
| [Idempotency](/docs/operating/idempotency) | The `idempotency-key` header on the task and job routes; what a repeat answers |
| [Streaming](/docs/operating/streaming) | Server-sent events on chat completions, cancellation, where the cost of a streamed answer arrives |
| [Data handling](/docs/operating/data) | Weights versus request data, the request-data policy by plan, pools and runtime access, regions |
| [Compatibility matrix](/docs/operating/compatibility) | Status per endpoint, per model and per client version; every cell unvalidated at launch |

## Limits
Route: https://hips.com/docs/operating/limits
Status: preview; updated 2026-10-21

Limits are per key and per workspace, set by plan, shown on the key in the Console and reported in the response headers. Every number is a placeholder until decided (not decided yet).

| Limit | Scope | Value | Over the limit |
| --- | --- | --- | --- |
| Requests per minute | Key, workspace | (not decided yet) by plan | 429 `rate_limit_exceeded`, `param: "requests"` |
| Tokens per minute (language models) | Key, workspace | (not decided yet) | 429 `rate_limit_exceeded`, `param: "tokens"` |
| Task units per minute | Key, workspace | (not decided yet) | 429 `rate_limit_exceeded`, `param: "units"` |
| Concurrent streams | Key | (not decided yet) | 429 `concurrency_limit_exceeded`, `param: "streams"` |
| Jobs in `queued`, `assigned` or `running` | Workspace | (not decided yet) | 429 `concurrency_limit_exceeded`, `param: "jobs"` |
| Request body size | Request | (not decided yet) | 400 `request_too_large` |
| Inline input bytes per request (task API) | Request | (not decided yet) and the model's `hips.limits` | 400 `input_too_large` (send it as an upload) |
| Inputs per task request | Request | The model's `hips.limits.max_inputs` (not decided yet) | 400 `too_many_inputs` |
| `messages` size and `context_length` | Request | The model's `context_length` | 400 `context_length_exceeded`; the prompt is never truncated |
| `max_tokens` | Request | The model's `max_output_tokens` | 400 `max_tokens_exceeded` |
| `tools` per request, `json_schema` size, `stop` entries | Request | (not decided yet) | 400 `invalid_value` naming the field |
| Upload size, uploads per day | Upload, workspace | (not decided yet) by plan | 400 `upload_too_large`, 429 `rate_limit_exceeded` `param: "uploads"` |
| Body arrival | Connection | A stalled body is closed after (not decided yet) | 400 `request_timeout` |
| Job result retention | Job | (not decided yet) | 404 `result_expired` |
| Synchronous task time | Request | (not decided yet) | 400 `use_jobs` before start; `timed_out` after |

### Reading the headers

`x-ratelimit-limit-requests`, `x-ratelimit-remaining-requests` and `x-ratelimit-reset-requests` carry the key's request limit in the current window, what remains, and the time to reset in OpenAI's duration format; the token equivalents do the same for tokens on language-model routes, and for task units on the task API under the same header names. Clients that already read them keep working.

### What 429 means

A limit is never a 5xx. `rate_limit_exceeded` names the dimension in `param` (`requests`, `tokens`, `units`, `uploads`); `concurrency_limit_exceeded` names `streams` or `jobs`. Both carry `Retry-After` in seconds: wait that long, then retry; nothing was charged on the refusal, and the retry is a new quote. Rate-limit windows and burst behavior are the gateway's and will be documented with the numbers.

## Errors
Route: https://hips.com/docs/operating/errors
Status: preview; updated 2026-10-21

Read `type` to decide what to do, `code` to know why, `param` to know where, and `message` to know what to change. Only 503 and 500 are ever 5xx; nothing is billed on an error, with the two exceptions on [Retries and billing outcomes](/docs/operating/retries).

### What to do, by status

| Status | Type | What to do |
| --- | --- | --- |
| 400 | `invalid_request_error` | Fix the request. Never retry it unchanged. The message names the field, the model, the limit and the count. |
| 401 | `authentication_error` | Check `HIPS_API_KEY` and the `Authorization: Bearer` header. The message never says whether a key is unknown or revoked. |
| 402 | `insufficient_credit` | Top up, or wait for the free allowance to reset; the message names when. |
| 403 | `permission_error`, `workspace_suspended` | The key's kind, the plan, the pool or the workspace's state refuses the request; the message names the Console screen that resolves it. |
| 404 | `not_found_error` | The id, the route or the result does not exist for this key. Never retry unchanged. |
| 429 | `rate_limit_error` | Wait `Retry-After` seconds, then retry. Nothing was charged. |
| 503 | `overloaded_error` | Wait `Retry-After` seconds, then retry; or, for `pool_unavailable`, enable fallback if your data-use and region rules allow it. Nothing was charged. |
| 500 | `api_error` | Retry once. Nothing was charged. Quote the `x-hips-request-id` to support. |

### 400: the request cannot be served as sent

- `invalid_json`: The body is not JSON, or not an object. Retry: No.
- `missing_required_parameter`: A required field is absent; `param` names it. Retry: No.
- `invalid_type`: A field has the wrong JSON type. Retry: No.
- `invalid_value`: A value is out of range or malformed. Retry: No.
- `unknown_parameter`: A field the gateway does not know, at any depth; `param` names it. Retry: No.
- `unsupported_parameter`: A known OpenAI field HIPS does not accept, or a feature the named model does not advertise. Retry: No.
- `unsupported_value`: `n` other than 1, `stream_options` without `stream`, a message role or part type not accepted. Retry: No.
- `stateful_not_supported`: `store`, `metadata`, `previous_response_id`, `conversation`. Retry: No.
- `context_length_exceeded`: The prompt is over the model's `context_length`; the prompt is never truncated. Retry: No.
- `max_tokens_exceeded`: `max_tokens` over the model's `max_output_tokens`. Retry: No.
- `invalid_image`: An image part or input cannot be decoded, is of an unsupported type or over the pixel limit. Retry: No.
- `request_too_large`, `input_too_large`, `too_many_inputs`, `upload_too_large`: A limit of the Limits page. Retry: No.
- `task_mismatch`: `task` is not the model's task. Retry: No.
- `not_a_language_model`: A task model or a task-model deployment named on an OpenAI-compatible route. Retry: No.
- `deployment_stopped`: The `dep_` is in `stopped`; start it in the Console. Retry: No.
- `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. Retry: No (`upload_incomplete`: after the PUT).
- `invalid_requirement`: A requirement header or field with an unknown value. Retry: No.
- `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. Retry: No.
- `stable_price_not_in_force`: `pricing_mode: stable` with no stable price covering this workspace, model and period. Retry: No.
- `use_jobs`: A synchronous task the gateway can tell will exceed the synchronous limit. Retry: As a job.
- `invalid_idempotency_key`, `idempotency_key_reused`, `idempotency_in_progress`: The idempotency rules. Retry: The last one, later.
- `request_timeout`: The body stopped arriving. Retry: Yes.

### 401, 402 and 403

- `missing_api_key`: No `Authorization` header, or not a bearer. Retry: No.
- `invalid_api_key`: Unknown, malformed or revoked key. The message never says which. Retry: No.
- `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. Retry: After a top-up.
- `key_scope_denied`: The key's kind excludes the route. Retry: No.
- `model_not_on_plan`: The model or feature is not in the workspace's plan. Retry: No.
- `region_not_on_plan`: A region requirement on a plan without region selection. Retry: No.
- `pool_not_allowed`: A pool the workspace may not use for this model. Retry: No.
- `workspace_unverified`: The workspace's owner has not passed identity verification; the message names the Console's verification screen. Retry: After verification.
- `workspace_paused`: The workspace is paused: by balance, by an administrator, by a dispute, by a budget hard stop or by an owner. The message says which and where to resolve it. Retry: After resolution.
- `plan_lapsed`: The subscription lapsed and no owner has yet acknowledged the free plan's request-data policy or paid; the policies hold meanwhile. Retry: After acknowledgment or payment.
- `workspace_deleted`: The workspace is deleted (restorable 30 days). Retry: After restore.

### 404

- `model_not_found`: Unknown catalog id, alias, pinned id or `dep_`; another workspace's `dep_`. Retry: No.
- `job_not_found`, `upload_not_found`: An id in the path that is unknown or another workspace's. Retry: No.
- `result_expired`: A job's result read after `expires_at`. Retry: No.
- `route_not_found`: Unknown path. Retry: No.
- `route_not_available`: A route of this contract not yet served (`/v1/responses` before validation). Retry: No.
- `method_not_allowed`: A known path with another method; `Allow` is sent. Retry: No.

### 429

- `rate_limit_exceeded`: A rate limit; `param` is `requests`, `tokens`, `units` or `uploads`; `Retry-After`. Retry: Yes, after `Retry-After`.
- `concurrency_limit_exceeded`: Too many concurrent streams or active jobs; `param` is `streams` or `jobs`; `Retry-After`. Retry: Yes, after `Retry-After`.

### 503 and 500

- `no_capacity`: No eligible worker under the request's requirements, in any pool the requirements allow; `Retry-After`. Retry: Yes.
- `pool_unavailable`: 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.
- `deployment_not_ready`: The `dep_` is `allocating` or `loading`, or waits for its version's tariff (`tariff_pending`); `Retry-After`. Retry: Yes.
- `overloaded`: Eligible workers exist and every one is saturated, or the queue is full; `Retry-After`. Retry: Yes.
- `internal_error`: A fault in HIPS. Nothing billed. Retry: Once.
- `attempt_failed`: Every attempt failed for a reason that is not the client's and retries are exhausted. Nothing billed. Retry: Once.

### A stream that fails after it started

One `data:` line holding the error envelope, then the stream closes without `[DONE]`. OpenAI clients raise on it. The usage record shows the outcome. See [Streaming](/docs/operating/streaming).

## Retries and billing outcomes
Route: https://hips.com/docs/operating/retries
Status: preview; updated 2026-10-21

> Prelaunch: Do not assume that every failed or retried attempt has the same billing outcome.

The principle: the customer is charged once per completed answer, at the quote bound at acceptance. A failed, rejected, interrupted or timed-out attempt costs the customer nothing; what the provider is paid for it is defined independently. The outcomes below are proposals until decided (not decided yet), except where the rule is the company's.

| Situation | Who retries | Billing outcome |
| --- | --- | --- |
| 429 or 503 | The client, after `Retry-After`; the SDK does it | Nothing on the refusal; the retry is a new quote (market) or the same stable price |
| An attempt is rejected or interrupted before any output | The scheduler, on another eligible worker under the same requirements, up to (not decided yet) attempts | Nothing until a completed answer; then once |
| An attempt is interrupted after the first streamed token | Nobody: a stream cannot be restarted transparently. The stream ends with the error envelope | Proposed: nothing (no complete answer); the tokens delivered are in the usage record as `interrupted` |
| An attempt is interrupted after the first token on a non-streamed request | The scheduler, within the attempt count | Once, for the completed answer |
| Retries exhausted | Nobody; 500 `attempt_failed` or job `interrupted` | Nothing |
| A worker timed out | The scheduler, once, on another worker, when the timeout was the worker's | Nothing |
| The client closes a stream | Nobody; the job is canceled on the worker | (not decided yet) (proposed: the tokens delivered are charged) |
| The client cancels a queued job | Nobody | Nothing |
| The client cancels a running job | Nobody | (not decided yet) (proposed: nothing) |
| A market price changes while a job runs | Nobody | The bound quote applies to work already accepted |
| A retried request with the same `idempotency-key` | The idempotency rules | Once |

### Timeouts

All open (not decided yet): the synchronous request limit on chat completions and tasks; the idle limit between streamed tokens; the per-task maximum run time of a job; the worker's own limits. A request refused before it starts because it cannot fit is a 400 `use_jobs` or a 503, never a wait until the limit.

### Client guidance

- Retry 429 and 503 after `Retry-After`.
- Retry a connection failure before any byte was received.
- Retry a 500 once.
- Never retry a 400, 401, 402, 403 or 404 unchanged.
- On the task API send an `idempotency-key` so a retry can never double-bill.
- A retried chat completion is a new request, a new quote and a new charge: the route takes no idempotency key, because the gateway stores no completion body.

## Idempotency
Route: https://hips.com/docs/operating/idempotency
Status: preview; updated 2026-10-21

`idempotency-key` is accepted on `POST /v1/tasks`, `POST /v1/jobs`, `POST /v1/uploads` and `POST /v1/jobs/{id}/cancel`; its value is the client's, up to a length (not decided yet), scoped to the key. The SDK generates one per task and job call.

| Rule | Behavior |
| --- | --- |
| First request | Served; the key, the body's hash and the response are kept for the window (not decided yet) |
| Same key, same body, within the window | The stored response is returned, same status and body, with the original `x-hips-request-id`. Nothing runs, nothing is billed again |
| Same key, different body | 400 `idempotency_key_reused` |
| Same key while the first is still being answered | 400 `idempotency_in_progress` |
| A replay of a job | Returns the job object; the job's result is read from the job, not from a stored copy |
| Not on chat completions | `POST /v1/chat/completions` and `/v1/responses` take no `idempotency-key`: a replay would need the gateway to store a completion body, which it never does. A retried chat completion is a new request, a new quote and a new charge |

### How to use it

- Generate the key before the first attempt and reuse it on every retry of the same body.
- Treat a 400 `idempotency_in_progress` as a signal to wait and retry with the same key, not as a failure.
- A different body with the same key is a 400 `idempotency_key_reused`: a bug in the caller, never retried.
- The replay carries the original `x-hips-request-id`, so the Console shows one request and one charge.

## Streaming
Route: https://hips.com/docs/operating/streaming
Status: preview; updated 2026-10-21

`stream: true` on `POST /v1/chat/completions` answers 200 with `Content-Type: text/event-stream`, one `data:` line per chunk in OpenAI's `chat.completion.chunk` shape (`choices[].delta` with `role`, `content`, `tool_calls[]` by `index`; `finish_reason` on the last content chunk), then `data: [DONE]`.

| Rule | Behavior |
| --- | --- |
| Usage | With `stream_options.include_usage: true`, one final chunk before `[DONE]` with `choices: []` and `usage`. Without it, no usage chunk. |
| The `hips` object | The headers that need the finished answer (`x-hips-cost-micros`, `x-hips-latency-ms`) cannot be sent at the head of a stream. They are omitted from the head, and the final usage chunk carries a top-level `hips` object: `{"cost_micros", "latency_ms", "quote"}`. It is sent when `include_usage` is true; whether it is sent without it is open (not decided yet). The other `x-hips-*` headers are in the head as usual. |
| Keep-alive | A comment line (`: keep-alive`) at an interval (not decided yet) while the engine produces nothing. |
| A failure after the stream started | One `data:` line holding the error envelope, then the stream closes without `[DONE]`. OpenAI clients raise on it. The usage record shows the outcome. |
| Client disconnect | Closing the connection cancels the job on the worker. The charge for tokens already delivered is (not decided yet) (proposed: charged). |
| Relay | The gateway relays chunks as the worker emits them and buffers nothing beyond one chunk. |

> The cost of a streamed answer arrives in the `hips` object of the final usage chunk, not in `x-hips-cost-micros`: the cost is not known when the head is sent, and trailers do not pass the edge. Ask for `stream_options.include_usage` to receive it.

### Cancellation

Close the connection. The job is canceled on the worker; an attempt interrupted after the first streamed token is never restarted transparently, because a stream cannot be resumed. A tool call streamed as `delta.tool_calls` by `index` is complete only when its `finish_reason` arrives.

### Jobs are not streams

Long-running work goes through [jobs](/docs/reference/jobs): submit, poll `GET /v1/jobs/{id}`, cancel with `POST /v1/jobs/{id}/cancel`, retrieve the result until it expires. A completion webhook is open (not decided yet).

## Data handling
Route: https://hips.com/docs/operating/data
Status: preview; updated 2026-10-21

### Your model weights

> Policy: Customer-owned model weights will never be used to train other models on any plan.

That commitment applies to the weights themselves. It does not change the separate policy for request inputs and generated outputs.

### Customer models: the import path

A customer model is imported from a model hub, never uploaded, and it is weight files only: no customer code runs anywhere. The import pins the revision, fetches only the files an engine reads, re-saves what passes its checks, copies it once into encrypted HIPS storage in the workspace's storage region, where its deployments run, and signs it with a HIPS key. Workers and devices load only that signed copy, never the hub. [Import and run your model](/docs/import-and-run) has the whole path.

A hub token for a private or gated repository is read-only, kept encrypted under a cloud key, shown by its last four characters, used only in the import job and never sent to a data-center worker, its RunPod pod or a device; it is deleted when you delete it. [Access tokens](/docs/import-and-run#access-tokens) has the rules.

### Request inputs and generated outputs

> Policy: On Free/PAYG and the lower paid plan, request inputs and generated outputs may be used for training. This includes requests processed by customer-owned models. On the higher paid plan, request-data training is off by default.

The Console will show the applicable policy so that teams can understand it before sending work. Retention, deletion, and any other permitted uses will be set out in the service terms before production access. Turning training off is not, by itself, a promise of zero retention.

| Plan | Request-data policy | Can the workspace change it |
| --- | --- | --- |
| Free | `training_allowed` | No |
| The lower paid plan | `training_allowed` | No |
| The higher paid plan | `training_off` by default | Yes, to `training_allowed`, by an owner or admin; the change is audited and shown before any request |

The policy applies to requests against catalog models and against customer models alike. It is not a header; a request cannot override it. The policy in force at the moment the gateway accepts the request is the one recorded on the job and the usage event, and it travels with the job through every retry.

### What the gateway stores

| What | The gateway |
| --- | --- |
| Request bodies, prompts, inputs | Never stored. Read, validated, relayed to the worker, forgotten. Logged as sizes and counts, never as content. |
| Responses, outputs | Never stored, except a task or job result on the job record until `expires_at`, so a client can retrieve it. |
| Uploads | Never pass through the gateway (a presigned PUT). Stored encrypted in the HIPS account under the upload's retention. |
| The `user` field | Discarded. |
| The usage record | Operational metadata only: ids, timestamps, units, cost, outcome. No prompt, no input, no output. |

### Pools and runtime access

In the `personal` pool a job runs on a device that its owner controls physically. The provider app handles weights and inputs in memory and removes them after the job, and the software is signed; but a person with physical control of a machine can in principle read its memory, and HIPS cannot verify from outside that they did not. HIPS discloses this before a customer selects the pool. In the `approved` pool a job runs on data-center supply operated by an approved provider, with published execution protections and access conditions per provider (not decided yet).

Encryption in transit and at rest is part of the platform requirements. It protects data during transfer and storage, but does not by itself prevent a GPU operator from accessing weights or request data during execution. We will publish the execution protections and access conditions for each pool before customers deploy workloads to it.

Cross-pool fallback is off by default and requires explicit enablement. It never relaxes a region or data-use rule. Customer-owned models run in the `approved` pool only at launch.

### Regions

A region is a requirement of a request, available on the higher paid plan only. What a region requirement covers (processing, logs, storage, backups, retries, verification samples, operations access, sub-processors) is open (not decided yet), and it is not offered until specified. The rule that holds regardless: no request silently crosses a required boundary. If no eligible supply exists in the required region, the gateway answers 503 `overloaded_error` with `Retry-After`, never a result from elsewhere.

## Compatibility matrix
Route: https://hips.com/docs/operating/compatibility
Status: preview; updated 2026-10-21

A compatibility matrix by endpoint, model and client version is published before migration is encouraged. A row becomes `supported` only with a dated measurement on a named pinned id, pool and client version. Until then every row reads `unvalidated`: starting with OpenAI-style integrations, and a shared client format does not mean every provider feature or model behavior is identical.

> Prelaunch: Every cell is unvalidated at launch. A row changes only with a dated validation record; the matrix is empty of supported rows until then.

| Endpoint | Feature | Client | Client version | Model, pool | Status | Validated |
| --- | --- | --- | --- | --- | --- | --- |
| POST /v1/chat/completions | Non-streamed completion | OpenAI Python SDK | Recorded at validation | A pinned catalog model, approved | unvalidated | none |
| POST /v1/chat/completions | Non-streamed completion | OpenAI Node SDK | Recorded at validation | A pinned catalog model, approved | unvalidated | none |
| POST /v1/chat/completions | Non-streamed completion | cURL | none | none | unvalidated | none |
| POST /v1/chat/completions | Non-streamed completion | OpenAI Python SDK | none | A pinned catalog model, personal | unvalidated | none |
| POST /v1/chat/completions | Streaming, [DONE] | OpenAI Python SDK, Node SDK | none | both pools | unvalidated | none |
| POST /v1/chat/completions | stream_options.include_usage and the hips object tolerated by the SDK's types | OpenAI Python SDK, Node SDK | none | none | unvalidated | none |
| POST /v1/chat/completions | Tool calls, non-streamed | OpenAI Python SDK, Node SDK | none | none | unvalidated | none |
| POST /v1/chat/completions | Tool calls, streamed deltas by index | OpenAI Python SDK, Node SDK | none | none | unvalidated | none |
| POST /v1/chat/completions | parallel_tool_calls | OpenAI Python SDK, Node SDK | none | none | unvalidated | none |
| POST /v1/chat/completions | response_format json_object | OpenAI Python SDK, Node SDK | none | both pools | unvalidated | none |
| POST /v1/chat/completions | response_format json_schema, strict: true | OpenAI Python SDK, Node SDK | none | both pools | unvalidated | none |
| POST /v1/chat/completions | Vision image_url parts (data URL, https) | OpenAI Python SDK, Node SDK | none | none | unvalidated | none |
| POST /v1/chat/completions | logprobs, seed, stop, max_completion_tokens | OpenAI Python SDK, Node SDK | none | none | unvalidated | none |
| POST /v1/chat/completions | Error envelope parsed: 400, 401, 402, 403, 404, 429 with Retry-After, 503 | OpenAI Python SDK, Node SDK | none | none | unvalidated | none |
| POST /v1/chat/completions | SDK retries on 429 and 503 and not on 400 | OpenAI Python SDK, Node SDK | none | none | unvalidated | none |
| POST /v1/chat/completions | Rate-limit headers read | OpenAI Python SDK, Node SDK | none | none | unvalidated | none |
| POST /v1/chat/completions | Request id read by the SDK | OpenAI Python SDK, Node SDK | none | none | unvalidated | none |
| POST /v1/chat/completions | Mid-stream error envelope raised by the SDK | OpenAI Python SDK, Node SDK | none | none | unvalidated | none |
| POST /v1/chat/completions | Requirement headers via default_headers and extra_headers | OpenAI Python SDK, Node SDK | none | none | unvalidated | none |
| GET /v1/models | models.list() and models.retrieve() with the hips extension tolerated | OpenAI Python SDK, Node SDK | none | none | unvalidated | none |
| POST /v1/responses | Non-streamed, streamed events, tools, text.format | OpenAI Python SDK, Node SDK | none | none | unvalidated | none |
| POST /v1/chat/completions | A coding tool's complete tool-call round trip | Each tool separately (not decided yet) | none | none | unvalidated | none |
| POST /v1/tasks, /v1/jobs, /v1/uploads | The HIPS SDK conformance suite | HIPS SDK per language (not decided yet) | none | none | unvalidated | none |

### Statuses

| Status | Meaning |
| --- | --- |
| `unvalidated` | Not yet measured. The default of every row at launch. |
| `supported` | Measured on the stated client version, pinned id and pool, on the stated date. |
| `partial` | Measured, with named gaps recorded on the row. |
| `unsupported` | Measured and refused by design, with the reason recorded. |

### Where the contract differs from OpenAI's by design

- Error `type` values are the HIPS list: `not_found_error` on an unknown model where OpenAI sends `invalid_request_error`; `rate_limit_error` with the dimension in `param` where OpenAI uses `type` for it.
- `n` is 1. `store` is refused. The completion `id` is a `req_`.
- The `hips` extensions in `GET /v1/models` entries and in the final streamed chunk.