Direct Tool Execution | Sogni: Learn

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.

#Execute a tool

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

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 for exact media steps, or Chat Completions when the LLM should interpret a request.

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

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

#Request

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"
  }'

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);

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"])

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

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.