sub2api/docs/COMPOSITE_GROUPS.md

Composite Groups

Composite groups are an admin routing layer for API keys that should choose a concrete provider from the requested model instead of binding the key to a single provider group.

Supported Providers

Composite groups can route to these concrete account platforms:

• Anthropic
• Gemini
• OpenAI
• Antigravity
• Grok

The selected concrete platform is used for account selection, user platform quota checks, post-usage billing, ops error platform attribution, channel mapping/pricing lookup, and platform usage reporting.

Model Detection

Composite routing detects common public model IDs and provider-prefixed IDs:

• claude-* and anthropic/claude-* route to Anthropic.
• gemini-* and google/gemini-* route to Gemini.
• gpt-*, o*, codex-*, text-embedding-*, dall-e-*, and openai/* route to OpenAI.
• grok-* and xai/grok-* route to Grok.

Unknown or ambiguous model names fail closed with a client error instead of guessing a provider.

Admin Workflows

• Admins can create a group with platform composite.
• Composite groups can copy accounts from concrete provider groups.
• Concrete provider accounts can be assigned directly to composite groups from account create/edit and bulk account workflows.
• Channel configuration exposes composite groups in concrete provider sections. The channel group_ids payload is still flat; provider-specific model mapping and pricing remain keyed by concrete platform.

Limits

Composite groups are not a full OpenRouter-compatible model registry. They do not add a provider/model mapping database, per-model admin routing overrides, or arbitrary third-party provider prefixes. Add those explicitly before relying on custom model IDs that cannot be detected from their names.