Skip to main content

​
Custom Providers

Emby lets you plug in any OpenAI-compatible provider behind the same /v1 endpoint. Use this when you want to:
  • Connect a self-hosted model (vLLM, SGLang, LM Studio, Ollama, etc.)
  • Route to a third-party gateway or vendor that speaks OpenAI format
  • Expose an internal company LLM behind Emby’s routing, logging, and controls
  • Test new providers without changing your app code
All you need is:
  • A name for the provider
  • A base URL
  • An API key / token

​
How Custom Providers Work

Once configured, you call models using: 
<provider-name>/<model-id>
For example:
  • mycompany/gpt-4.1-mini
  • lab/deepseek-r1
  • internal/qwen-3.5-coder
Emby will:
  • Forward the request to your custom provider
  • Keep the OpenAI-style request/response shape
  • Apply the same usage logging & observability as built-in models

​
Quick Setup

​
1. Add a Custom Provider in the Dashboard

1

Open Providers in Emby

Go to your Emby dashboard → Settings → Providers.
2

Create Custom Provider

Add a new Custom Provider with:
  • Name – lowercase name, e.g. mycompany or internal
  • Base URL – your provider’s API root, e.g. https://api.mycompany.ai
  • API Key / Token – the key Emby should use when calling your provider
3

Save & Test

Save the provider, then use the “Test connection” button (if available) or send a small request from your app to confirm everything works.

​
2. Call Your Custom Provider

Once the provider is created, you can call it like any other model.

​
cURL Example

curl -X POST "https://api.emby.dev/v1/chat/completions" \
  -H "Authorization: Bearer $EMBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mycompany/custom-gpt-4",
    "messages": [
      { "role": "user", "content": "Hello from my custom provider!" }
    ]
  }'
Emby takes care of:
  • Setting Authorization: Bearer <your-custom-provider-key> when calling your backend
  • Forwarding the OpenAI-style payload to https://api.mycompany.ai/v1/chat/completions
  • Normalizing the response back to the Emby/OpenAI format
No changes needed in your application besides the model value.

​
Configuration Requirements

Provider Name

  • Lowercase letters only: a-z
  • Examples: mycompany, internal, lab
  • Invalid: MyCompany, my-company, my_company, 123test

Must match: /^[a-z]+$/

Base URL

  • Must be a valid HTTPS URL
  • Should point to the root of your OpenAI-compatible API
  • Emby will append /v1/chat/completions automatically if needed
  • Example: https://api.mycompany.ai

API Token

  • Provider-specific API key or token
  • Sent as Authorization: Bearer <token>
  • Stored securely on Emby’s side

OpenAI Compatibility

Your provider must support the OpenAI-style /v1/chat/completions format (or equivalent), including model, messages, and optional parameters like temperature, max_tokens, etc.

​
Example: Self-Hosted vLLM / SGLang

If you’re running a local or cloud vLLM/SGLang server exposed at: 
https://llm.mycompany.ai
Configure Emby custom provider:
  • Name: mycompany
  • Base URL: https://llm.mycompany.ai
  • API Key: (optional, if your gateway uses keys)
Then call it like: 
curl -X POST "https://api.emby.dev/v1/chat/completions" \
  -H "Authorization: Bearer $EMBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mycompany/qwen-3.5-coder",
    "messages": [
      { "role": "user", "content": "Refactor this function for clarity." }
    ]
  }'

​
What Features You Get via Emby

Custom providers still benefit from:

Unified Endpoint

One base URL for everything:
https://api.emby.dev/v1
Works for Emby-hosted and custom providers.

Centralized Auth

Your apps only store one key:
$EMBY_API_KEY.
Per-provider secrets live inside Emby.

Logging & Analytics

See usage, latency, error rates, and model mix for custom providers right in the Emby dashboard.

Routing Rules

Combine Emby-hosted models with your custom ones in the same project, or gradually shift traffic as you evaluate performance.

​
Best Practices

Name things clearly

Use names like lab, staging, or prod so it’s obvious which backend a model uses.

Keep models discoverable

Mirror the provider’s own model IDs:
mycompany/deepseek-r1, mycompany/qwen-32b, etc.

Monitor latency & errors

Custom providers might sit on slower networks or less-optimized hardware. Watch their metrics and adjust accordingly.

Compliance & data flow

Emby shows you where requests go. For custom providers, you control location, logs, and retention policies.

​
Troubleshooting

❓ Calls to my custom provider fail
  • Check that the base URL is HTTPS and reachable from the internet (or your Emby region)
  • Verify that the provider supports the OpenAI chat completions format
  • Confirm the API key is valid and not expired
  • Try a direct request to your provider outside Emby to confirm behavior
curl -X POST "https://api.mycompany.ai/v1/chat/completions" \
  -H "Authorization: Bearer $MYCOMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "custom-gpt-4",
    "messages": [
      { "role": "user", "content": "Test from direct call" }
    ]
  }'
If that fails, fix your provider first.
If that works but Emby fails, check your Custom Provider settings in the dashboard.

​
Need Help Wiring Up a Custom Provider?

If you’re connecting a private gateway, on-prem model, or custom EU deployment and want to get it right: 📞 Book a call: https://cal.com/absolum/30min
💬 WhatsApp us: https://wa.absolum.nl