recommend
AnalysisRecommend a Model
Find the best Scenario platform/public model for a single generation task. Returns ranked models with real performance data (ELO, latency, cost) and explanations.
Args:
- capability: one of '3d23d', 'audio2audio', 'audio2txt', 'audio2video', 'img23d', 'img2img', 'img2txt', 'img2video', 'txt23d', 'txt2audio', 'txt2img', 'txt2txt', 'txt2video', 'video23d', 'video2audio', 'video2img', 'video2video' (optional — inferred from prompt)
- prompt: the user's original intent (required)
- priority: 'quality' | 'speed' | 'cost' (default 'quality')
- max_cost_cu, max_latency_seconds: optional constraints
- features: required features list
- limit: how many to return (1-10, default 5)
Returns: ranked list with per-model explanation, tradeoff, real performance numbers, suggested input params for model_run, and a `next_step` directive. When `next_step.type` is `ask_user`, present `next_step.question` and `next_step.options` to the user and wait for their choice before calling `model_run` — do not auto-select a model. When `next_step.type` is `proceed`, use `specialty` (if present) or the top `ranked` entry. `caveats` on a ranked entry flag uncertainty to confirm with the user before generating. Entries with `requires_plan_upgrade: true` need a subscription upgrade to the plan in `required_plan` before they can be run — keep them visible (mark with ✨), but do not call `model_run` with one until the user has upgraded.
Don't use when: the request needs multiple generation steps (use plan_generation) or you need to search private/unlisted models (use search).
read-onlyopen-world
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| capability | string | — | Generation capability. One of: '3d23d', 'audio2audio', 'audio2txt', 'audio2video', 'img23d', 'img2img', 'img2txt', 'img2video', 'txt23d', 'txt2audio', 'txt2img', 'txt2txt', 'txt2video', 'video23d', 'video2audio', 'video2img', 'video2video'. Intents with no capability value of their own: image upscaling → 'img2img' (upscaler models), video upscaling → 'video2video', text-to-speech (TTS) → 'txt2audio', inpainting/outpainting → 'img2img', textures → 'txt2img' or 'img2img' with the texture described in `prompt`. If omitted, inferred from the prompt. |
| prompt | string | — | The user's request. Always pass the user's original intent. |
| priority | enum(quality | speed | cost) | quality | Optimization priority. |
| max_cost_cu | number | — | Maximum cost per asset in compute units. |
| max_latency_seconds | number | — | Maximum acceptable generation time in seconds. |
| features | array | — | Required features (e.g. 'endImage', 'elements'). |
| duration | number | — | Minimum duration in seconds. |
| limit | number | 5 | |
| team_id | string | — | Team ID. Required if user belongs to multiple teams. |
| project_id | string | — | Project ID to scope the operation to. |
| response_format | enum(json | markdown) | json | Output format: 'json' for structured data, 'markdown' for human-readable text. |
| include_private_models | boolean | false | When true (and a projectId is available), also recommend the team's own private/unlisted trained models for this project. Set this when the user asks about their own / custom / trained models. |
Example Request
JSON
{
"capability": "txt2img",
"priority": "quality",
"prompt": "photorealistic product shot for instagram",
"limit": 3
}Example Response
JSON
{
"summary": "For a photorealistic Instagram product shot at 1:1, GPT Image 2 leads on Arena ELO with strong prompt adherence; Gemini 3.0 Pro is the high-fidelity alternative; Grok Imagine Pro adds the best cost-to-quality ratio at this resolution.",
"ranked": [
{
"model_id": "model_openai-gpt-image-2",
"name": "GPT Image 2",
"rank": 1,
"explanation": "ELO 1510 (Arena rank #1, image_edit) and 11.7 CU at 2K make this the top quality choice for photoreal product imagery.",
"tradeoff": "~65s p50 latency — plan for batch, not real-time.",
"quality_elo": 1510,
"speed_summary": "64.7s median",
"cost_summary": "11.7 CU",
"suggested_inputs": {
"aspectRatio": "1:1",
"numImages": 1
},
"key_insights": [
"Strong prompt adherence on product copy and finishes",
"Use elementsImage to lock identity across iterations"
]
}
],
"query": {
"capability": "txt2img",
"priority": "quality"
},
"platform_detected": "instagram_post — 1:1",
"total_matching": 634
}Common Use Cases
- Pick the best model before calling model_run without scanning the full catalog
- Compare quality (Arena ELO), speed (p50 latency), and cost (p50 CU) across candidates side by side
- Auto-detect platform context (Instagram, YouTube, TikTok) and receive matching aspect ratio suggestions
- Get suggested input values you can pass straight to model_run