Generate media
runRun any generation model by name with a params object. Returns a job_ref; poll get_job until completed for the output URL (or result_text for transcription). File-input params (see list_models file_inputs) take an upl_ ref (from POST /api/upload, or the upload_from_url / upload_file tools), the job_ref of an earlier completed job to chain its result into this one, or a hosted URL; transcription/speech-to-text models and models priced by their input's length or size require a ref so the input can be measured. The price depends on the model and params and is charged in whole app credits ($0.10 each): cost_credits in the reply is what is reserved, cost_micros/cost_usd the same amount in usd_micros and USD. The credits are RESERVED when the run is submitted and released again if it fails or is rejected; only a completed run is charged, so a failed generation costs nothing and needs no refund; if your credits do not cover it, buy credits in the app.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"model": "<model>"
},
"name": "run"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | the model name from list_models (e.g. flux-2, kling-video-text) | |
| params | No | parameters for the model as an object, e.g. {"prompt":"a cat","num_images":2}. Call list_models to see each model's params and defaults. | |
| idempotency_key | No | optional caller-chosen id (any unique string) that makes a retry safe - repeating it returns the original job instead of running and billing again. Use one whenever a network error leaves you unsure whether the run started. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | ||
| status | Yes | ||
| job_ref | Yes | ||
| message | Yes | ||
| cost_usd | No | ||
| agent_token | No | ||
| cost_micros | No | ||
| cost_credits | No | ||
| agent_token_note | No |