Requests and models
This reference for Local AI models covers how the AI Gateway, the API Alien hosts at ai.alien.dev, routes each request. Every request carries three routing inputs:
curl "https://ai.alien.dev/v1/chat/completions" \
-H "Authorization: Bearer $ALIEN_AI_API_KEY" \
-H "X-Alien-External-ID: org_8f2k" \
-H "Content-Type: application/json" \
-d '{"model": "byo/claude-opus-5", "messages": [{"role": "user", "content": "Hello"}]}'| Input | Example | Selects |
|---|---|---|
Authorization | Bearer $ALIEN_AI_API_KEY | Your Alien project |
X-Alien-External-ID | org_8f2k | The customer's provider connection |
model | byo/claude-opus-5 | A model your project configured |
Customer IDs
The external ID is a stable tenant or organization ID from your own database. Resolve it after authenticating the user, on your server.
Never let a browser choose X-Alien-External-ID. Anyone who can set it while using your server API key could target another customer's connection.
To target one deployment instead of a customer, send X-Alien-Deployment-ID in place of X-Alien-External-ID.
Model IDs
Use the exact IDs under AI Gateway → Models in the dashboard. A byo/ prefix selects a model the customer supplies. To list the models one customer can call:
curl "https://ai.alien.dev/v1/models" \
-H "Authorization: Bearer $ALIEN_AI_API_KEY" \
-H "X-Alien-External-ID: $CUSTOMER_ID"The list is specific to that customer's provider connection and your current configuration.
Model status
Alien checks each configured model by reading the customer's provider configuration, never by sending a test request. Checking doesn't use the customer's quota or accept provider terms for them.
The capability overview reports it per model in models.modelCoverage:
availability | Meaning |
|---|---|
available | The provider's configuration includes this model for this customer |
blocked | Something in the customer's account stops it. blockerCodes says what. |
unknown | Alien hasn't checked it yet |
Blocker codes include agreement-required, entitlement-required, model-activation-required, deployment-required, quota-configuration-required, region-unavailable, access-denied, and observation-failed.
available doesn't promise the next request succeeds. Quota, policy, capacity, and request settings can still reject it, so treat GET /v1/models as discovery, not as an inference test.
Client protocols
| Client API | Endpoint |
|---|---|
| OpenAI Chat Completions | POST /v1/chat/completions |
| OpenAI Responses | POST /v1/responses |
| Anthropic Messages | POST /v1/messages |
| Model discovery | GET /v1/models |
When the provider speaks the same protocol, the gateway passes the request body through. When it translates, it rejects provider-specific or stateful fields it can't represent, instead of dropping them.
Static provider headers
AI Gateway → Provider Headers adds fixed headers to every request sent to one provider. Use them for provider-required attribution or routing metadata. Never use them for per-customer secrets or values your end users supply.
Diagnose requests
Gateway logs record routing and outcome metadata, never prompt or response bodies. Open AI Gateway → Logs, or search from the CLI:
alien logs --source ai-gateway --since 24h
alien logs --source ai-gateway --status provider-error --provider anthropic --jsonFilters: --status, --model, --provider, --deployment-group, --since, and --json.
Inspect usage
alien usage ai --range 24h
alien usage ai --range 7d --jsonUsage is an aggregate with no request content. --range takes 24h, 7d, or 30d. It reports:
- requests, successes, and errors;
- input and output tokens;
- estimated provider cost;
- average and p95 latency.
Next
- Add to your product: the settings page that connects a customer's provider
- Local AI models in a deployment: call the customer's models from inside their cloud
Add to your product
Build an AI models settings page into a product you host. The customer connects their model provider; your backend calls it through the AI Gateway.
In a deployment
Call models in the customer's own Amazon Bedrock, Vertex AI, or Azure AI Foundry with no API keys, or serve open-weight models on GPUs.