Skip to content

prompt_spark

Generation

Rewrite 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

NameTypeRequiredDescription
model_idstring✓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.
promptstring—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.
imagesarray—Optional image asset IDs or data URLs to condition the prompt (e.g. reference images).
num_resultsnumber1Number of prompt variants to return (1–5).
dry_runboolean—Estimate cost without running. Sends ?dryRun=true so the API returns the cost estimate without executing or charging credits.
task_idstring—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_idstring—Team ID. Required with project_id for OAuth callers; an API key is scoped by the key.
project_idstring—Project ID. Required with team_id for OAuth callers; an API key is scoped by the key.
response_formatenum(json | markdown)jsonOutput format: 'json' for structured data, 'markdown' for human-readable text.