Direct Tool Execution

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

POST /v1/creative-agent/tools/execute Auth required

Execute one synchronous composition/planning tool and return its structured payload. Long-lived media generation tools such as generate_image and generate_video are intentionally rejected; use Creative Workflows for exact media steps or Chat Completions when the LLM should interpret a request.

#Body

Name	Type	In	Description
tool*	string	body	Synchronous hosted tool name. `tool_name` is accepted as an alias.
arguments*	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.
app_source	string	body/header	Optional caller label (max 128 chars). `X-App-Source` header accepted.

#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.

$ 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",
      "destination_tool": "generate_image"
    },
    "token_type": "spark",
    "app_source": "my-app"
  }'

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',
    destination_tool: 'generate_image',
  },
  tokenType: 'spark',
});

console.log(response.data.message);

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",
            "destination_tool": "generate_image",
        },
        "token_type": "spark",
    },
)
response.raise_for_status()
print(response.json()["data"]["message"])

#Response

{
  "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..."
  }
}

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

#Direct Synchronous Tool Execution

#Body

#Supported tools

#Response