Source: https://docs.sogni.ai/api-reference/tool-execution/

# Direct Tool Execution

Run a known synchronous composition or planning tool with exact JSON arguments. Use this when your application already knows which tool to call and does not need an LLM round to choose or rewrite the arguments.

### POST /v1/creative-agent/tools/execute

Executes one synchronous composition or planning tool and returns its structured payload. Long-running media generation tools such as `generate_image` and `generate_video` are rejected here; use [Creative Workflows](https://docs.sogni.ai/api-reference/workflows/) for exact media steps, or [Chat Completions](https://docs.sogni.ai/api-reference/chat-completions/) when the LLM should interpret a request.

### [#](https://docs.sogni.ai/api-reference/tool-execution/#body)Body

| Name | Type | In | Description |
| --- | --- | --- | --- |
| toolrequired | string | body | Synchronous hosted tool name. `tool_name` is accepted as an alias. |
| argumentsrequired | object | body | Exact JSON arguments for the selected tool. Must be an object. |
| token\_type | string | body | `spark`, `sogni`, or `auto`. The camelCase alias `tokenType` is accepted; other values return `400`. |
| billing\_mode | string | body | `auto` (default), `subscription`, or `tokens`. `billingMode` is accepted. |
| safe\_content\_filter | boolean | body | Optional Sensitive Content Filter setting. `safeContentFilter` is accepted. |
| app\_source | string | body | Optional caller label; values longer than 128 characters are truncated. The `X-App-Source` header is accepted. |

Unknown body fields return `400`.

### [#](https://docs.sogni.ai/api-reference/tool-execution/#supported-tools)Supported tools

| Tool | Use |
| --- | --- |
| enhance\_prompt | Expand or adapt rough prompts into model-ready image, video, music, or edit prompts. |
| compose\_script | Draft scripts, storyboards, trailers, social shorts, campaign beats, or video prompts. |
| compose\_lyrics | Write vocal song lyrics and suggested musical parameters. |
| compose\_instrumental | Write instrumental structure and suggested musical parameters. |
| compose\_workflow | Compile a creative brief into a durable workflow `input` plan and cost estimate. |
| compose\_workflow\_template | Draft or edit a parameterized workflow template plus an example plan. |

### [#](https://docs.sogni.ai/api-reference/tool-execution/#request)Request

```bash
curl https://api.sogni.ai/v1/creative-agent/tools/execute \
  -H "Authorization: Bearer $SOGNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "enhance_prompt",
    "arguments": {
      "prompt": "A cinematic portrait of a glass robot",
      "target_output": "image_prompt",
      "destination_tool": "generate_image",
      "destination_model": "krea-2-turbo"
    },
    "token_type": "spark",
    "app_source": "my-app"
  }'
```

```javascript
import { SogniClient } from '@sogni-ai/sogni-client';

const sogni = await SogniClient.createInstance({
  appId: 'direct-tool-demo',
  apiKey: process.env.SOGNI_API_KEY,
});

const response = await sogni.chat.hosted.executeTool({
  tool: 'enhance_prompt',
  arguments: {
    prompt: 'A cinematic portrait of a glass robot',
    target_output: 'image_prompt',
    destination_tool: 'generate_image',
    destination_model: 'krea-2-turbo',
  },
  tokenType: 'spark',
});

console.log(response.data.message);
```

```python
import os
import requests

response = requests.post(
    "https://api.sogni.ai/v1/creative-agent/tools/execute",
    headers={
        "Authorization": f"Bearer {os.environ['SOGNI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "tool": "enhance_prompt",
        "arguments": {
            "prompt": "A cinematic portrait of a glass robot",
            "target_output": "image_prompt",
            "destination_tool": "generate_image",
            "destination_model": "krea-2-turbo",
        },
        "token_type": "spark",
    },
)
response.raise_for_status()
print(response.json()["data"]["message"])
```

### [#](https://docs.sogni.ai/api-reference/tool-execution/#response)Response

```json
{
  "status": "success",
  "data": {
    "toolCallId": "direct_1773353812000",
    "tool": "enhance_prompt",
    "result": {
      "ok": true,
      "success": true,
      "tool": "enhance_prompt",
      "prompt": "Cinematic portrait of a translucent glass robot...",
      "message": "Cinematic portrait of a translucent glass robot..."
    },
    "message": "Cinematic portrait of a translucent glass robot..."
  }
}
```

**Check `result.ok`.** A tool-level failure, such as a missing required argument, still returns `200`, with `data.result.ok: false`, `error_type`, `message`, `retryable`, and `suggested_next_action`. `enhance_prompt` requires `prompt`, `target_output` (`image_prompt`, `video_prompt`, `edit_prompt`, or `model_prompt`), and `destination_model`.

**A shortcut, not a planner loop.** This endpoint executes exactly one supported synchronous tool. It is the efficient path for prompt expansion, script and lyrics composition, and workflow planning when your app already has the tool and its arguments.