Skip to main content

Hosted model aliases

A hosted model is a stable project-local alias for either a training job or a verified ReOpenly ModelArtifact. Aliases are routing identities over a shared serving pool; creating one does not allocate a dedicated GPU.

Model lifecycle endpoints​

GET  /api/v1/projects/{owner_slug}/{project_slug}/models
POST /api/v1/projects/{owner_slug}/{project_slug}/models
PUT  /api/v1/projects/{owner_slug}/{project_slug}/models/{model_slug}
PATCH /api/v1/projects/{owner_slug}/{project_slug}/models/{model_slug}
GET  /api/v1/projects/{owner_slug}/{project_slug}/models/{model_slug}/target-compatibility
GET  /api/v1/projects/{owner_slug}/{project_slug}/models/{model_slug}/download-metadata
POST /api/v1/projects/{owner_slug}/{project_slug}/models/{model_slug}/disable
POST /api/v1/projects/{owner_slug}/{project_slug}/models/{model_slug}/enable
GET  /api/v1/projects/{owner_slug}/{project_slug}/models/{model_slug}/shares
POST /api/v1/projects/{owner_slug}/{project_slug}/models/{model_slug}/shares
DELETE /api/v1/projects/{owner_slug}/{project_slug}/models/{model_slug}/shares/{share_id}

Creating a text-generation alias requires its display name, stable slug, and source job:

{
  "name": "Support assistant",
  "slug": "support-assistant",
  "training_job_id": 87
}

An embedding alias references a verified, project-owned artifact receipt through a discriminated source. The catalog id and Hugging Face provenance are server owned; a client cannot submit a repository URL or branch as a serving target:

{
  "name": "Citation encoder",
  "slug": "citation-encoder",
  "task": "embedding",
  "source": {
    "kind": "provisioned_artifact",
    "model_artifact_id": 101
  }
}

For the text-generation example, the job must have a promoted artifact. Re-pointing an existing alias lets an owner publish a new training result without changing the client-facing model slug. The update body can carry only the new job reference; the alias name and slug remain stable:

{
  "training_job_id": 87
}

The owner can select this operation from the project Models screen. A retired base or a text job with no promoted artifact is rejected with 409.

Embedding re-pointing is same-task only. If the candidate changes vector dimension or normalization, send index_compatibility_acknowledged: true after checking GET .../target-compatibility; otherwise the server returns 409. GET .../download-metadata returns verified file hashes and sizes for an authorized embedding alias, but never a storage URL, object prefix, or raw manifest. That download is for a model provisioned to your project; a model you trained is downloaded as its adapter from its training job (GET .../training-jobs/{job_id}/download, see Training jobs).

From a finished training job, Host model uses the same dialog for text and embedding projects. Choose a new endpoint or an existing project alias, then review the fine-tune and the suggested name and API slug. Repointing an embedding alias that changes vector dimension or normalization requires acknowledging that existing indexes must be re-embedded. The success receipt shows the saved alias and its status until you select Done; repointing a disabled alias keeps it disabled.

Trained embedding models​

As for a text fine-tune, a successful embedding training job can be hosted as soon as its adapter is verified and promoted; no evaluation is required first:

{
  "name": "Citation encoder tuned",
  "slug": "citation-encoder-tuned",
  "task": "embedding",
  "source": {"kind": "training_job", "training_job_id": 87}
}

PUT .../models/{model_slug} points an embedding alias at a different training job the same way. Each change increments the auditable target revision, and the alias records the adapter it serves; every request is served by exactly that adapter.

This release has no Retrieval quality or Retrieval evaluation panel. Separate model evaluation jobs for text and embeddings are planned for a later release. Training validation is checkpoint-selection evidence, not served quality. evaluation_receipt_sha256 and evaluation_acknowledged remain accepted and ignored for compatibility; neither is required to host a model.

Listing and pagination​

Project aliases always use a bounded cursor page. No pagination mode opt-in is required. The cursor belongs to this project and cannot be used with another project.

GET /api/v1/projects/{owner_slug}/{project_slug}/models?limit=25
GET /api/v1/projects/{owner_slug}/{project_slug}/models?limit=25&cursor=<next_cursor>

Cursor responses are {data, next_cursor, total_count}. The default limit is 25 and the maximum is 100. Cursors are opaque, ordered by immutable alias id, and must be sent back unchanged. Authorization and filters are applied before the page, so following next_cursor reaches every alias the caller is allowed to see.

The cross-project registry is the separate GET /api/v1/models endpoint. It uses the same cursor shape and 25-row default/100-row maximum; access, status and archive visibility filters are server-side. Its totals object contains usage rollups, not a client-derived total of registry rows.

Access​

An alias can be owner-only, shared with selected accounts, or public according to the model sharing fields. The OpenAI model list is caller-aware and only returns aliases the bearer can invoke. A caller who cannot access a model gets the same model_not_found response as an unknown alias; this prevents model slug enumeration.

Private shares​

An owner creates a private share for an account slug and chooses who pays:

{
  "user_slug": "alex",
  "payer": "user",
  "extra_charge_percent": 10
}

payer is exactly owner or user. With owner, usage is charged to the model owner; with user, the recipient must have sufficient credits and pays the base inference charge plus extra_charge_percent. The surcharge is bounded from 0 through 100. Listing and deleting shares are owner-only operations.

Public access​

Update an alias with is_public and public_extra_charge_percent. Public callers pay their own inference charge plus the configured surcharge; the surcharge is also bounded from 0 through 100. A disabled alias remains disabled when sharing fields change: only the explicit /enable route activates it.

Serving a hosted alias​

Use the alias directly:

{
  "model": "support-assistant",
  "messages": [{"role": "user", "content": "Hello"}]
}

ReOpenly resolves the alias to its owner and payer and serves exactly the verified adapter it points at. A missing or invalid adapter never silently falls back to the base model.

For a stopped source job, cancelled is the terminal attempt state, not a signal that the adapter is absent. Serving uses the promoted artifact and model_available; a cancelled attempt without a promoted artifact is rejected.

Deprecation​

The catalog is authoritative. A fine-tune trained on a retired base is marked deprecated: true in training/model payloads, cannot be newly published or re-pointed, and returns 410 with error.code = "model_deprecated" when served. Existing artifact downloads remain available so owners can migrate or audit their data.

Project archives​

Archiving is reversible and does not delete chats, jobs, aliases, or artifacts. Archived projects are read-only: writes return the regular project-archive conflict, while OpenAI inference returns:

{
  "error": {
    "type": "invalid_request_error",
    "code": "project_archived"
  }
}

The OpenAI response is 404 with no Retry-After, because an archive is a deliberate owner action rather than a transient outage. Unarchive the project from project settings before serving again.

Revoking a share through the DELETE endpoint returns 200 with {"status":"deleted"}.

Base models​

Every existing or new project lists its task-appropriate base models in Hosted models. Use a base without creating an alias or fine-tuning first. Use model supplies Python, cURL and JavaScript examples with your project URL. Embedding bases support Search, Vector and Similarity without an alias. Base calls are available only to the project owner and depend on serving availability.

Embedding base Use model examples omit input_type: public bases have no query instruction to apply. Hosted examples explicitly set input_type to query for trained query instructions. Python sends this through extra_body={"input_type": "query"}; cURL and JavaScript include input_type in the request body. To embed corpus passages with a hosted model, choose document. The API still accepts the optional role for bases.

The global Base models section shows each public base once. When several projects can use it, choose a project on the card before selecting Use model; the SDK example and Playground link use that project.