Skip to main content

Quickstart: Import from Hugging Face

The catalog isn't a fixed list. If a model on Hugging Face is compatible, you can import it and get a live endpoint. This quickstart runs the full loop: search → info → register → infer.

Prerequisites​

pip install colabhive
export COLABHIVE_API_KEY="hive_..."
export COLABHIVE_ACCOUNT_ID="..."
import os
from colabhive import ColabHive

client = ColabHive(
    api_key=os.getenv("COLABHIVE_API_KEY"),
    account_id=os.getenv("COLABHIVE_ACCOUNT_ID"),
)

Step 1 — Search​

Find repos that match a task. search(...) returns a list of HFModelInfo objects — access fields as attributes, not dictionary keys.

results = client.models.hf.search(
    query="embedding model",
    task_type="embeddings",     # ColabHive task vocabulary (see below)
    max_size_gb=2,
    min_downloads=10_000,
)

for m in results:
    print(m.repo_id, "→", m.compatibility.status)

task_type uses ColabHive's vocabulary, not the raw Hugging Face pipeline tags: embeddings, rerank, translation, ocr, stt, moderation, text-generation.

Each result carries a compatibility.status of compatible, requires_review, or incompatible.

Step 2 — Inspect a candidate​

Pull the full detail for one repo before committing — size, config, files, and the estimated resource requirements ColabHive computed for it.

details = client.models.hf.info("sentence-transformers/all-MiniLM-L6-v2")

print("size_mb:", details.size_mb)
print("requirements:", details.estimated_requirements)
print("compatibility:", details.compatibility.status)

Step 3 — Register​

Registering creates the model_config and an inference_endpoint in one call. task_type is required.

reg = client.models.hf.register(
    repo_id="sentence-transformers/all-MiniLM-L6-v2",
    task_type="embeddings",
)

print("model_config_id:", reg.model_config_id)   # a UUID
print("endpoint_id:    ", reg.endpoint_id)
print("status:         ", reg.status)

The response is an HFRegistrationResult — read reg.endpoint_id, reg.model_config_id (a UUID), reg.inference_url, and reg.test_request as attributes.

Hugging Face imports are public, free, and flagged as base

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. Only the literal public and candidate values are accepted during import; alternatives return HTTP 422. Its model_name is prefixed hf- (e.g. hf-sentence-transformers-all-MiniLM-L6-v2). See Model Catalog & Hugging Face.

New models enter as lifecycle_status="candidate" (usable, not yet fully validated). To learn how a model is promoted to ready, see the model lifecycle.

Step 4 — Infer​

Call the endpoint the registration returned. The model downloads on this first request (a cold start), so poll if it comes back queued.

out = client.endpoints.infer(
    reg.endpoint_id,
    {"text": "hello world"},
)
print(out["result"])

The same flow over REST​

# Search
curl -X POST "https://api.colabhive.com/api/builder/v1/models/hf/search" \
  -H "X-API-Key: $COLABHIVE_API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "embedding model", "task_type": "embeddings", "max_size_gb": 2}'

# Info (URL-encode the repo id)
curl "https://api.colabhive.com/api/builder/v1/models/hf/sentence-transformers%2Fall-MiniLM-L6-v2/info" \
  -H "X-API-Key: $COLABHIVE_API_KEY"

# Register
curl -X POST "https://api.colabhive.com/api/builder/v1/models/hf/register" \
  -H "X-API-Key: $COLABHIVE_API_KEY" -H "Content-Type: application/json" \
  -d '{"repo_id": "sentence-transformers/all-MiniLM-L6-v2", "task_type": "embeddings"}'

Search responses are under the results key; POST /models/hf/register returns model_config_id, endpoint_id, repo_id, status, message, inference_url, and test_request.

Next steps​