[Feature Request] Allow provider/model selection via HTTP API for sessions

[crayment]

Problem

When using the OpenCode HTTP API programmatically (e.g., for sub-agent orchestration), there's no way to specify which AI provider or model to use per session or message. All sessions use the server's configured default model.

Use Case

Building a parent-agent system that spawns multiple sub-agents via the OpenCode HTTP API:

• Cost optimization: Use cheaper models (e.g., Haiku) for simple tasks like linting
• Performance: Use fast models for quick queries, powerful models for complex analysis
• Testing: Verify behavior across different providers/models
• Parallel workflows: Run different sub-agents with different models simultaneously

Current Behavior

# Creating a session - no way to specify model
POST /session?directory=...
{"title": "My Task"}

# Sending a message - model selection ignored
POST /session/:id/message?directory=...
{"parts": [...], "providerID": "anthropic", "modelID": "claude-haiku-4-5"}
# ^ These fields are ignored, uses default model

Result: Always uses server default (e.g., claude-sonnet-4-5-20250929)

Desired Behavior

Allow provider/model selection via API:

Option 1: Set at session creation

POST /session?directory=...
{
  "title": "Fast Task",
  "providerID": "anthropic",
  "modelID": "claude-haiku-4-5"
}

Option 2: Set per message

POST /session/:id/message?directory=...
{
  "parts": [{"type": "text", "text": "..."}],
  "providerID": "anthropic",
  "modelID": "claude-haiku-4-5"
}

Option 3: Both (most flexible)

Set default at session creation, override per message if needed.

Current Workaround

None - must accept whatever default model the server is configured with.

Additional Context

The /config/providers endpoint already exposes all available providers and models, so clients can discover what's available. We just need a way to actually select them.

API currently tested:

• ✅ /config/providers - shows all models
• ❌ Session creation with providerID/modelID - ignored
• ❌ Message with providerID/modelID - ignored
• ❌ /session/:id/init endpoint - only for AGENTS.md generation

This would be especially valuable for programmatic workflows where different tasks have different model requirements.

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• [FEATURE]: Allow custom model headers #3499: [FEATURE]: Allow custom model headers - requests ability to define custom headers per provider/model in opencode.json, which is related to model customization via configuration
• [FEATURE]: custom model aliases #3439: [FEATURE]: custom model aliases - requests ability to create aliases for models in config, which addresses part of the model selection flexibility
• [FEATURE]: Expand Openrouter Blacklist via Json #3452: [FEATURE]: Expand Openrouter Blacklist via Json - requests customizable model filtering in opencode.json, showing demand for programmatic model control

Feel free to ignore if none of these address your specific case.

[rekram1-node]

@crayment every prompt sent can specify which model to use. We even use this in our own scripts:
https://github.com/sst/opencode/blob/fc8db6cdf9cb81e29c5dda69c8646aa52e453a9c/script/publish.ts#L30-L63

[crayment]

Thanks @rekram1-node! I tested it and confirmed it works perfectly with both anthropic/claude-sonnet-4-5-20250929 and openai/gpt-5. Really appreciate the quick response and the code example - that was exactly what I needed. This unlocks some great use cases for programmatic sub-agent orchestration. 🎉

[rekram1-node]

ofc, no problem