AI Provider Reference Knowledge Base

An AI provider receives an application request, runs a model, and returns a result. Selecting a provider is not only about intelligence. It also selects an API shape, data path, limits, billing model, reliability profile, observability surface, and recovery path.

Core rule: never activate a production model because one playground prompt worked. It must pass the application's output contract, smoke tests, timeout, retry, fallback, and usage-recording gates.

1. Separate Models, Providers, and Gateways

The same model through two providers may not accept the same parameters. Endpoint paths, token fields, reasoning controls, structured output, usage responses, and errors can differ. Use an adapter per API surface instead of changing only a model string.

2. Choose Direct Access or an Aggregator

Direct providers

Direct access is useful when you need:

• the earliest access to official features;
• a direct support and contract relationship;
• specific regions, privacy controls, or enterprise agreements;
• direct billing and observability;
• parameters not yet supported by an aggregator.

The trade-off is owning adapters, credentials, rate limits, and cross-provider fallback.

Aggregators

An aggregator is useful when you need:

• one API across model families;
• inference-provider routing;
• programmatic model discovery;
• faster fallback or evaluation across models;
• consolidated billing.

The trade-off is another layer. Verify the final provider, data policy, forwarded parameters, routing latency, and price differences.

A healthy production shape

Feature or pipeline stage
        |
        v
Internal AI gateway
  - schema validation
  - timeout budget
  - retry policy
  - usage and cost log
        |
        +--> Primary target
        +--> Fallback 1
        +--> Fallback 2

Every fallback must pass through the same adapter and validator boundary. Never call a fallback from the browser or place provider credentials in client code.

3. Minimum Provider and Model Record

Keep provider and model records versioned. A minimum record looks like this:

{
  "providerKey": "provider-slug",
  "connectionType": "direct_or_aggregator",
  "apiSurface": "responses_or_messages_or_generate_content",
  "baseUrl": "server-side configuration",
  "credentialEnv": "PROVIDER_API_KEY",
  "providerModelId": "exact-api-model-id",
  "lifecycle": "eval_or_active_or_deprecated",
  "capabilities": {
    "structuredOutput": true,
    "tools": true,
    "streaming": true,
    "reasoning": true
  },
  "limits": {
    "contextWindowTokens": null,
    "maxOutputTokens": null
  },
  "pricing": {
    "sourceUrl": "official-pricing-url",
    "verifiedAt": "YYYY-MM-DD",
    "pricingMode": "flat_or_tiered"
  },
  "conformance": {
    "status": "untested",
    "testedAt": null,
    "schemaVersion": "your-output-contract.v1"
  }
}

Never interpret null as zero. It means the value is not recorded or verified.

4. Major Provider References

OpenAI direct

OpenAI provides models through its official API, with the Responses API as the primary surface for many new workflows. Verify the exact model ID, lifecycle, modalities, supported reasoning effort, output limit, structured output, tools, project rate limits, and usage fields.

Keep OPENAI_API_KEY on the server. Structured output controls JSON shape, but the application must still validate semantics and business rules.

Anthropic direct

Anthropic's Messages API differs from OpenAI's request and response shape. Check the top-level system prompt format, required max_tokens, multiple content blocks, stop reason, usage normalization, exact model ID, and retirement timeline.

Test the parser against text, tool calls, refusals, and error responses.

Google Gemini direct

Gemini exposes model discovery and capability metadata. Model names may be stable, preview, latest, or experimental.

• Prefer stable for production when it meets the requirement.
• Preview versions can change and have shutdown schedules.
• Latest aliases can move to another version.
• Experimental models are not stable production contracts.

Structured output supports a subset of JSON Schema. Syntactically valid JSON can still contain invalid business values, so domain validation remains mandatory.

Alibaba Cloud Model Studio direct

Alibaba Model Studio provides Qwen and other models through regional endpoints and several API surfaces. Verify workspace permission, regional availability, exact model code, structured output, tools, reasoning, tiered input pricing, cache pricing, and 429 behavior.

With tiered pricing, do not use one price per million tokens for every request. Select the tier from the total input tokens in a request, then apply the provider's documented rule.

OpenRouter

OpenRouter is an aggregator with model discovery and provider routing. Verify the canonical model slug, supported parameters, provider order, allow_fallbacks, require_parameters, data collection, zero-data-retention preference, final-provider metadata, attempts, usage, and billed cost.

OpenRouter fallback and application-level fallback are separate layers. Document which layer selected the final provider so an incident remains traceable.

5. Output Contract before Saving a Model

Use a small but representative smoke-test contract:

{
  "type": "object",
  "properties": {
    "summary": { "type": "string", "minLength": 1 },
    "language": { "type": "string", "enum": ["id", "en"] },
    "risks": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["summary", "language", "risks"],
  "additionalProperties": false
}

Read the idea and return only an object that matches the schema.
The output language must match the idea language.

Idea: A family spending tracker with a monthly summary.

Pass only when HTTP succeeds, timeout is respected, parsing works, the schema is exact, language is correct, no forbidden wrapper text appears, usage is recorded, logs contain no secrets, and repeated runs remain consistent.

6. Layered Validation Gates

A model that passed only connectivity is not production-ready.

7. Routing, Retry, and Fallback

Retry only failures that can reasonably recover, such as transient network errors, timeouts, 429, or selected 5xx responses. Never retry indefinitely.

Request
  -> primary attempt
     -> success: validate and return
     -> retryable failure: bounded retry or fallback
     -> non-retryable failure: stop and report
  -> fallback attempt
     -> success: validate and return
     -> failure: persist a safe diagnostic and support reference

Use one total timeout budget, exponential backoff with jitter, Retry-After when present, circuit breakers, idempotency for billed or side-effecting jobs, compatibility checks before fallback, and secret-safe attempt logs.

8. Usage and Cost Calculation

Prefer provider usage or billing data when available. Record the actual provider and model, input/cached/reasoning/output tokens, provider request ID, pricing version, reported or calculated cost, currency, conversion rate, and any difference from the final invoice.

If cost is absent, calculate it from usage and a versioned price table. Tiered pricing must be selected per request. Never mix direct-provider pricing with aggregator pricing or a different model alias.

9. Security and Data Governance

• Keep API keys in server environments or a secret manager.
• Separate development, staging, and production keys.
• Apply project, budget, rate, and permission limits.
• Never log authorization headers or raw secrets.
• Redact personal data from prompt logs.
• Decide retention, training opt-out, region, and data residency.
• Restrict production routing changes.
• Audit who activated a model, when, and why.
• Rotate keys after suspected exposure.

An API proxy does not replace authorization. Check the user, entitlement, quota, and scope before calling a provider.

10. Observability and Incident Response

An operational dashboard should show the requested route, actual model and provider, primary or fallback position, per-attempt latency, HTTP and normalized error, token usage, reported or estimated cost, schema result, correlation or Support ID, retryability, and recovery instructions.

Alert on rising 429, 5xx, timeouts, invalid JSON, schema mismatch, cost spikes, and fallback rate. A continuously used fallback is a hidden incident, not proof that everything is healthy.

11. New Model Activation Checklist

• Provider record and exact model ID exist.
• Official sources, verification date, lifecycle, region, and pricing are recorded.
• Request and response adapters match the API surface.
• Credentials remain server-side.
• Connectivity smoke test passes.
• Structured output and semantic assertions pass repeatedly.
• Timeout, 429, 5xx, retry, and fallback are simulated.
• Usage and cost reconcile.
• Logs are safe and include a correlation ID.
• Canary, alerts, and rollback are ready.
• Production activation creates an audit event.

12. Freshness and Governance

Review the catalog at least every 30 days and immediately after a new model, pricing change, deprecation, privacy change, or conformance failure. Preserve history instead of overwriting old evidence. An eval model must not become active only because its record is complete.

The structured database shown after this article is an educational snapshot. Production AI Routing must keep using the application's validation gates, approvals, and operational configuration.