asset_caption
AnalysiscatalogCaption Asset
Not in the default tool list
This tool lives in the tool catalog. Discover it with scenario_tools_search (or enumerate everything with scenario_tools_list) and run it via scenario_tool_execute_write. To list every tool directly, connect with ?toolsets=full.
Generate a caption for a Scenario image asset. Creates a billed job unless dry_run=true. Repeated calls can create and charge for another job.
Args:
- asset_id: required — the image to caption
- details_level: optional — 'action' or 'action+style'
- parameters: optional — advanced controls (modelId, seed, temperature, topP, unwantedSequences)
- dry_run: optional — true returns a cost estimate without running or charging credits
- team_id, project_id: required for OAuth callers
Returns: captions (one per image) plus the job record. With dry_run=true, returns a cost estimate.
For instruction-driven or interactive analysis (specific questions, custom output format), use asset_analyze (Scenario LLM) instead — it is more flexible than this fixed caption endpoint.
open-world
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| asset_id | string | ✓ | Scenario asset ID of the image to caption. |
| details_level | enum(action | action+style) | — | Caption detail: 'action' (subject + action) or 'action+style' (also describes style). |
| parameters | record | — | Advanced caption controls passed through to the API (modelId, seed, temperature, topP, unwantedSequences). |
| dry_run | boolean | — | Estimate cost without running. Sends ?dryRun=true so the API returns the cost estimate without executing or charging credits. |
| task_id | string | — | Task of the team's task tracker (Jira, Wrike…) this call's Creative Units are attributed to. Required when the project enforces task ids: the call is then refused without one. Only an id the user chose from the project's task list or typed: never invent one, the API checks only its format. Pass the same task_id on later billed calls for the same work in the same project; ask again when the user moves to other work or switches project or team. A dry_run estimate needs none. project_tasks_list (catalog-only — run via scenario_tool_execute_read) lists the project's tasks. |
| team_id | string | — | Team ID. Required with project_id for OAuth callers; an API key is scoped by the key. |
| project_id | string | — | Project ID. Required with team_id for OAuth callers; an API key is scoped by the key. |
| response_format | enum(json | markdown) | json | Output format: 'json' for structured data, 'markdown' for human-readable text. |
Example Request
JSON
{
"asset_id": "asset_img001",
"team_id": "team_abc123",
"project_id": "proj_xyz789"
}Example Response
JSON
{
"source_asset_id": "asset_img001",
"captions": [
"A red sports car on a wet city street at night"
],
"detailsLevel": "action"
}Common Use Cases
- Auto-caption game assets for searchability and accessibility
- Generate alt text for a batch of generated images