Providers, Model Types, and Model Discovery

Clouisle connects multimodal models through a unified provider abstraction. Providers are not independently configurable entities: there is no global provider registry holding default API keys, timeouts, or retry policies. Each model carries its own provider, base_url, api_key, and optional provider_display_name. "Configuring a provider" therefore means registering a model with a provider identifier; see Register models and authorize teams for the flow.

Provider identifiers and default endpoints

ModelProvider defines 23 provider identifiers. When no custom base_url is set, the runtime resolves the request address from the table below.

Endpoint resolution order is: the model's own base_url → the model-type-specific default → the provider default. Clearing base_url therefore does not fail; it falls back to the table above. This is also why a TTS model and a chat model under the same provider can call different addresses:

openai versus openai_responses

Both share the same default base URL (https://api.openai.com/v1) but speak different protocols:

• openai uses standard Chat Completions and is the normal choice for chat, embeddings, and TTS/STT.
• openai_responses uses OpenAI's Responses API (the SDK's client.responses.*) and currently backs the image generation path (the Responses hosted image tool, supporting size, quality, background, output_format, and other Responses-only parameters).

Model types

ModelType has 9 values, independent of the provider:

Creation and update validate only two combinations: embedding must use one of the 15 providers above, and decision must be typesafe. Other mismatches are not rejected on save:

Remote model discovery

Discover models lists the models a provider actually exposes before you save, so you never hand-write a wrong model_id. Call POST /api/v1/admin/models/discover with the admin:model:create permission; credentials are used for that request only and are never persisted.

Discovery supports 16 providers (the "Remote discovery" column above). Each uses a fixed list path and auth method:

azure_openai, runway, pika, luma, kling, stability, and midjourney do not support discovery; the call returns success: false with a "provider does not support model discovery" message. Every provider except ollama requires an API Key.

Hard requirements for a discovery request

• The base URL must pass the endpoint allowlist (model_endpoint_not_allowlisted), otherwise the request is rejected before it leaves the server.
• The base URL must be http(s)://host[:port] with no query string, fragment, username/password, backslash, or //-prefixed path; a trailing / is stripped.
• A 15-second timeout and no redirects (follow_redirects=false), so credentials cannot be forwarded to another host.
• The response body is capped at 2 MiB; at most 200 models are returned, and items with an over-long or duplicate id/name are skipped.
• Both data (OpenAI-compatible) and models (Google/Ollama) list shapes are recognized, and google strips the models/ prefix.
• Results carry id, name, context_length, max_output_tokens, and capabilities (vision, function_call, streaming, json_mode) that can be filled straight into the create form.

TypeSafe path rebasing

The typesafe discovery path is rebuilt from the configured base URL path so that gateway deployments work:

• Base URL path ends with /v1: that path is reused. https://gw.example.com/openai/v1 → requests /openai/v1/models.
• Base URL path is non-empty but does not end with /v1: /v1/models is appended. https://gw.example.com/api → requests /api/v1/models.
• Base URL has no path: the default /v1/models is used.

Endpoint allowlist

The Model Endpoint Allowlist site setting (model_endpoint_allowlist) is the master gate for all model egress: discovery, connection tests, and runtime requests all obey it. Matching rules:

• Exact Origin match on scheme + host + port, ignoring the path; https://gateway.example.com/anything and https://gateway.example.com are the same Origin.
• Non-default ports participate: http://ollama.internal:11434 differs from http://ollama.internal.
• 20 official Origins ship by default (including https://api.typesafe.ai, https://openspeech.bytedance.com, and http://localhost:11434); midjourney has no default Origin because it needs a self-hosted proxy.
• The allowlist holds up to 200 entries; an empty list blocks every model endpoint.
• Removing an Origin immediately blocks later discovery, tests, and runtime requests with no service restart.

Related pages

• Register models and authorize teams — register models, test connections, authorize teams, and set quotas
• Model — two-level model structure and quota semantics
• Model provider reference — field definitions and Embedding adapter details