prompt_spark
GenerationRewrite a Generation Prompt
Rewrite a draft or idea into model-specific prompts and valid generation parameters. Use for short or underspecified prompts, reference-driven suggestions, or model-tuned settings. Uses Scenario Prompt Spark v3 to preserve the subject and intent while regenerating the wording; this is not a light edit.
Use dry_run to estimate cost without running or charging. A normal call produces suggestions, not a finished image, video, audio or 3D asset. It does not submit the suggested model_run.
Returns: prompt variants, recommended_prompt (text alone), and recommended_call with model_id and parameters when available. Use recommended_call.parameters as the model_run parameters, adopt them as-is or edit them first. They already include the rewritten prompt.
Examples:
- "Improve this prompt for a custom model" -> model_id="model_xxx", prompt="a fast vehicle"
- "Suggest prompts from a reference" -> model_id="model_xxx", images=["asset_xxx"], num_results=3
Don't use when: the user wants exact wording preserved — pass it directly to model_run. For image analysis use asset_analyze (catalog-only — run via scenario_tool_execute_write); for finished assets use model_run.
open-world
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| model_id | string | ✓ | Required Scenario model ID. Prompt Spark v3 conditions on this model — its training images, examples, and input signature — and returns parameters that conform to it. |
| prompt | string | — | Draft prompt or user intent to rewrite into an on-model prompt — always pass it when you have one; omitting it makes Prompt Spark invent an idea from the model context alone. Prompt Spark rewrites (preserving subject and intent), it does not lightly edit. |
| images | array | — | Optional image asset IDs or data URLs to condition the prompt (e.g. reference images). |
| num_results | number | 1 | Number of prompt variants to return (1–5). |
| 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. |