OpenCode: API Feature Request For Model Selection

This article discusses a crucial feature request for OpenCode, focusing on enabling provider and model selection through the HTTP API for sessions. Currently, when using the OpenCode HTTP API programmatically, there's no option to specify which AI provider or model to use for each session or message. This limitation forces all sessions to utilize the server's default configured model. We'll explore the problem, use cases, current behavior, desired behavior, and potential solutions to enhance the OpenCode API.

Problem: The Need for Dynamic Model Selection

The central issue is the inability to dynamically select AI providers and models when interacting with the OpenCode HTTP API. When integrating OpenCode into programmatic workflows, especially in scenarios involving sub-agent orchestration, this lack of flexibility becomes a significant bottleneck. The system's reliance on a single, default model hinders the optimization of resource utilization and overall performance. This limitation is particularly felt when trying to balance cost-effectiveness with the need for powerful processing capabilities across various tasks.

Currently, the OpenCode HTTP API does not allow specifying the AI provider or model to be used for each session or message. This means that every session initiated through the API uses the server's default model, which can be restrictive and inefficient for various use cases. The absence of model selection capabilities limits the potential for cost optimization, performance tuning, and parallel processing, making it challenging to leverage the full spectrum of AI models available.

This constraint becomes especially problematic when building complex systems that require different AI models for different tasks. For instance, a system might need a fast, inexpensive model for simple tasks like syntax checking, while a more powerful model is required for complex analyses. Without the ability to specify the model via the API, users are forced to either accept the default model for all tasks or manually reconfigure the server for each specific need, which is neither scalable nor practical. The inability to select models dynamically also impacts testing and experimentation, as it prevents developers from easily comparing the performance of different models within the same system.

Use Cases: Why Model Selection Matters

The ability to select providers and models via the OpenCode HTTP API unlocks several critical use cases, particularly in complex, multi-agent systems. Let's delve into some scenarios where this feature would be invaluable:

• Cost Optimization: One of the primary advantages of enabling model selection is the potential for significant cost savings. Different AI models come with varying pricing structures, and the ability to choose the most cost-effective model for a given task is crucial. For simple tasks like linting or basic data validation, using cheaper models such as Haiku can dramatically reduce operational expenses. By intelligently routing tasks to the appropriate models based on complexity and resource requirements, organizations can optimize their AI spending and avoid overspending on high-end models for low-complexity tasks. This level of granularity in model selection ensures that resources are used efficiently, making AI-driven workflows more sustainable and scalable.
• Performance: Performance is another key driver for model selection. Different AI models excel in different areas, with some optimized for speed and others for accuracy or complex reasoning. For tasks that require quick responses, such as real-time query processing, fast models are essential. Conversely, for tasks involving in-depth analysis or complex problem-solving, more powerful models are necessary, even if they come with higher latency. The ability to select models based on performance characteristics allows developers to fine-tune their applications for optimal responsiveness and efficiency. This is particularly important in systems where speed and accuracy are both critical, as it enables a balanced approach to resource allocation and task execution.
• Testing: Testing is a crucial aspect of AI system development, and the ability to test behavior across different providers and models is vital for ensuring robustness and reliability. By selecting specific models for testing purposes, developers can verify how their applications perform under various conditions and with different AI engines. This capability allows for the identification of potential issues or biases in specific models, ensuring that the system behaves predictably and accurately regardless of the underlying AI technology. Model selection for testing also facilitates comparative analysis, enabling developers to assess the strengths and weaknesses of different models and choose the best one for their needs. This comprehensive testing approach enhances the quality and trustworthiness of AI-driven applications.
• Parallel Workflows: Parallel workflows benefit significantly from the ability to run different sub-agents with different models simultaneously. In complex systems, various tasks may have different requirements in terms of processing power, speed, and cost. By enabling model selection, developers can design workflows where each sub-agent uses the most appropriate model for its specific task. This parallel execution not only improves overall efficiency but also allows for better resource utilization. For example, one sub-agent might use a fast model for quick data retrieval, while another uses a powerful model for complex data analysis. This parallel processing capability is essential for building scalable and high-performance AI systems that can handle diverse workloads effectively.

Current Behavior: Limitations of the OpenCode API

Currently, the OpenCode HTTP API has significant limitations in terms of model selection. When a session is created or a message is sent, there is no mechanism to specify which AI provider or model should be used. All interactions default to the server's configured model, regardless of the specific requirements of the task. This behavior restricts the flexibility and efficiency of the system, as it prevents dynamic allocation of resources based on task complexity and cost considerations.

To illustrate these limitations, consider the following API interactions:

# 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

In the above examples, even though the providerID and modelID are included in the message payload, they are ignored by the API. The system always defaults to the server's configured model, such as claude-sonnet-4-5-20250929. This behavior makes it impossible to leverage different models for different tasks within the same system, hindering the potential for optimization and parallel processing.

The current workaround is to accept the server's default model, which may not be the most efficient or cost-effective solution for all tasks. This limitation necessitates a more flexible API that allows for dynamic model selection, enabling developers to build sophisticated AI systems that can adapt to varying requirements and constraints.

Desired Behavior: Enhancing API Flexibility

To address the current limitations, the OpenCode API should be enhanced to allow provider and model selection. There are several ways this could be implemented, each with its own set of advantages and trade-offs. Here are three potential options:

Option 1: Set at Session Creation

One approach is to allow model selection at the time of session creation. This would involve adding parameters to the /session endpoint to specify the desired providerID and modelID. For example:

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

In this scenario, the selected model would be used for all messages within the session, providing a consistent environment for the task. This approach is straightforward and easy to implement, making it a good option for scenarios where the model requirements are consistent throughout the session. However, it lacks the flexibility to switch models mid-session, which may be necessary for more complex workflows.

Option 2: Set Per Message

Another option is to allow model selection on a per-message basis. This would involve adding providerID and modelID parameters to the /session/:id/message endpoint. For example:

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

This approach offers the greatest flexibility, allowing developers to use different models for different messages within the same session. This is particularly useful for systems that require a dynamic approach to model selection, where the optimal model may vary depending on the specific task or context. However, this flexibility comes at the cost of increased complexity, as each message request must include the model selection parameters. This can also lead to increased overhead, as the system must switch models more frequently.

Option 3: Both (Most Flexible)

The most flexible approach would be to combine both options, allowing model selection at session creation with the ability to override it on a per-message basis. This would involve setting a default model for the session at creation time, with the option to specify a different model for individual messages. This approach provides a balance between consistency and flexibility, allowing developers to optimize for both performance and cost.

For example, a session could be created with a default model for general tasks, while specific messages that require more processing power could be sent using a higher-end model. This approach allows for fine-grained control over model selection, ensuring that resources are used efficiently while maintaining the flexibility to adapt to changing requirements. It also simplifies the API interaction, as model selection parameters only need to be specified when a different model is required.

Current Workaround: The Absence of a Solution

Currently, there is no workaround for the lack of provider and model selection in the OpenCode HTTP API. Developers are forced to accept the server's default model, which limits their ability to optimize for cost, performance, and testing. This constraint necessitates the implementation of one of the proposed solutions to enhance the API's flexibility and utility.

The absence of a workaround underscores the importance of this feature request. Without the ability to select models dynamically, developers are unable to fully leverage the capabilities of the OpenCode system. This limitation hinders the development of sophisticated AI applications that require a nuanced approach to resource allocation and task execution.

Additional Context: Leveraging Existing Endpoints

Fortunately, the OpenCode API already provides an endpoint that exposes all available providers and models. The /config/providers endpoint returns a list of all supported providers and their corresponding models, allowing clients to discover what's available. This information can be used to populate model selection interfaces or to programmatically choose the appropriate model for a given task.

To fully utilize this capability, the API needs to be extended to allow clients to actually select the discovered models. The current API only provides information about available models but does not offer a way to specify which model should be used for a given session or message. This gap in functionality highlights the need for the proposed enhancements, which would enable developers to take full advantage of the available resources.

Additionally, it's worth noting that while the /session/:id/init endpoint exists, it is primarily intended for AGENTS.md generation and does not address the need for model selection. This further emphasizes the necessity of implementing one of the proposed solutions to enhance the API's flexibility and utility.

Conclusion: A Call for Enhanced Flexibility

In conclusion, enabling provider and model selection via the OpenCode HTTP API is crucial for enhancing its flexibility and utility. The ability to dynamically choose AI models based on task requirements unlocks significant opportunities for cost optimization, performance tuning, and testing. By implementing one of the proposed solutions, OpenCode can empower developers to build sophisticated AI systems that can adapt to varying requirements and constraints.

This feature is especially valuable for programmatic workflows where different tasks have different model requirements. By allowing model selection at session creation or on a per-message basis, OpenCode can better support complex, multi-agent systems and enable developers to build more efficient and effective AI applications. This enhancement would not only improve the usability of the OpenCode API but also position it as a more powerful and versatile tool for AI development.

For more information on AI model selection and best practices, consider visiting OpenAI's documentation.