Skip to main content

Model Catalog & Hugging Face

The single most important thing to understand about ColabHive's catalog: it is not a fixed list. Models arrive two ways, and both are served through the same inference path.

  1. Curated base models — vetted and maintained by ColabHive.
  2. Hugging Face imports — any compatible repo you bring in yourself.

Whichever way a model arrives, it becomes an ordinary catalog entry with an endpoint you call by name or UUID.

Two sources, one catalog​

Curated base models​

The base catalog is hand-picked and tested by ColabHive: general-purpose and coding LLMs, embedding and rerank specialists, translation/STT/OCR/moderation, image/audio/video generators, and trainable templates. These have stable names without an hf- prefix — for example qwen-2.5-7b-instruct, mistral-7b-instruct, specialist-embeddings. Many were originally built from a Hugging Face repo (they record an hf_repo_id showing where the weights came from), but they are curated endpoints — some are priced per request in USD.

Hugging Face imports​

Anything compatible on the Hugging Face Hub can be pulled in on demand:

POST /api/builder/v1/models/hf/search   →  find compatible repos for a task
GET  /api/builder/v1/models/hf/{repo}/info  →  size, config, estimated requirements, compatibility
POST /api/builder/v1/models/hf/register →  create a model_config + inference_endpoint

Registering builds both the model_config and its inference_endpoint in one call. The model is immediately callable; its weights download on the first request (a cold start). See the Quickstart: Import from Hugging Face for the end-to-end loop, and the import guide for options.

How to tell them apart: the hf- prefix​

Every model imported through the Hugging Face path gets a model_name prefixed with hf-, derived from the repo id — e.g. google/gemma-2-9b-it becomes hf-google-gemma-2-9b-it. Base curated models never carry that prefix.

Names in docs vs. the real catalog. A model's display name in prose can differ from its actual model_name. What reads as "Gemma 2 9B" in a doc is hf-google-gemma-2-9b-it in the catalog. Always use the real model_name / endpoint_name returned by the live catalog:

curl "https://api.colabhive.com/api/builder/v1/inference/models?active_only=true" \
  -H "X-API-Key: $COLABHIVE_API_KEY"

HF imports are public, free, and base​

This is a real, current constraint — not a recommendation:

When you register a Hugging Face model, ColabHive records it as visibility=public, lifecycle_status=candidate, is_base_model=true, and price_per_request=0. The request schema accepts only visibility="public" and lifecycle_status="candidate"; other values return HTTP 422.

If you need a private, priced, or reviewed endpoint, that path is registering a trained model (below), not importing from Hugging Face.

The two kinds of "register"​

The word "register" means two different things in ColabHive. Keep them apart:

Import a Hugging Face modelRegister a trained model
Callclient.models.hf.register(...) · POST /models/hf/registerclient.training.register_for_inference(...) · POST /training/runs/{id}/register-for-inference
SourceA Hugging Face repoA model you trained or merged on ColabHive
VisibilityOnly public accepted; other values return 422Real: account (default) or public
PriceForced 0 (free)You may set price_per_request (USD)
ReviewNonepublic requires a complete spec + review
Resulthf-* base endpointYour own endpoint

See Register a Trained Model for Inference for the second path.

Task types (for HF search/register)​

The Hugging Face search and register calls use ColabHive's task vocabulary, not raw Hugging Face pipeline tags:

embeddings · rerank · translation · ocr · stt · moderation · text-generation

A Hugging-Face-style value such as feature-extraction does not map, so that filter is silently ignored. Each search result reports a compatibility.status of compatible, requires_review, or incompatible.

Lifecycle​

Every model config carries a lifecycle_status. The full enum is:

StatusMeaning
candidateRegistered and usable, but not yet fully validated. HF imports and freshly trained models start here.
readyValidated (training and/or inference tests passed). Safe to rely on.
preferredPromoted above ready as the recommended choice.
disabledTurned off. Setting this requires a reason.

In practice the catalog today uses candidate and ready; preferred and disabled are available but not currently populated. Promotion from candidate to ready is done after a model passes its tests. You can change a model's status with PATCH /models/registry/{model_config_id}/lifecycle (SDK: client.models.hf.update_lifecycle(...)).

A model being in the catalog does not guarantee it is active. An endpoint can be active, paused, inactive, or deprecated, and a model_config can be inactive. The live catalog (?active_only=true) reflects what you can actually call right now.

Where to go next​