How to use TTAPI Agent Skills: music API guide

TTAPI Agent Skills are our project instructions for coding agents that can work with a terminal, files, and web documentation. A Skill tells the agent how to inspect the project, read the relevant TTAPI API reference, choose supported request fields, save generated assets, and check the result in the app.

The catalog currently groups 16 product Skills: eight image Skills, six video Skills, and two music Skills. They are workflow guides, not new models or a separate billing product. Installation is free; media generation uses the TTAPI balance for the selected product and operation.

• Use an agent that supports Skills and can access the project terminal.
• Install only the product Skills the project needs.
• Keep the TTAPI key in the local environment used by the agent.

Start with the result your product needs. The ttapi-suno Skill is a strong fit for songs, vocals, instrumentals, covers, and stem workflows. The ttapi-flowmusic Skill is useful when a project needs Lyria based music generation, continuation, or stem operations.

The Skill helps your agent follow the current API contract, but it does not decide whether a track is right for the product. Keep the creative brief, target scene, vocal choice, tempo, and review criteria in the prompt you give the agent.

Run the installer from the project folder, then ask your agent to confirm the Skill name and installed path. This prepares the workflow only; it does not submit a music request or spend generation credits.

You can install ttapi-flowmusic instead by changing the final Skill argument. If a project uses both products, install both and tell the agent which one to use for each task.

npx skills add ttapi-io/ttapi-skills --skill ttapi-suno

• Run the command from the project you want the agent to edit.
• Confirm the installed Skill file paths before generating media.
• Do not add a second overlapping Skill unless the project needs another product workflow.

The Skill can read the key from the environment, but it should never receive the secret in chat or source files. Set TTAPI_API_KEY in the same terminal or command environment that starts Codex, Claude Code, Cursor, or Gemini CLI.

Ask the agent to check only whether the variable is configured. A configuration check should not print the key, make a generation request, or claim that the balance is valid.

# PowerShell
$env:TTAPI_API_KEY = Read-Host 'TTAPI API key'

# Bash
export TTAPI_API_KEY="your_key_here"

• Use a hidden local prompt or a client environment setting.
• Start the agent after the variable is set in its command environment.
• Keep the real key out of screenshots, logs, commits, and prompts.

Once the Skill and key are ready, describe the creative job in the project chat. Include the product Skill, the music brief, where the result should be saved, and how the agent should verify playback. The Skill supplies the API workflow while your prompt supplies the project context and acceptance bar.

For a first run, ask for one short track and require the agent to keep the task ID. If the request is asynchronous, a submitted job means processing has started; the final audio is ready only after the documented fetch or callback reports completion.

Inspect this project, then use ttapi-suno to create a slow cinematic electronic-soul track with warm Rhodes piano, deep bass, and intimate low male vocals. Read the relevant TTAPI API docs before submitting. Keep the task ID, save the returned track in the existing asset folder, add a player with user-initiated playback, and check the result in the app.

Ask the agent to download the returned track into the existing asset folder, add a user initiated player, and check the page it changed. Keep the prompt, Skill name, model ID, task ID, response status, and saved file path together so you can reproduce or revise the result.

Listen for the requested mood, tempo, arrangement, vocal presence, and unwanted artifacts. If the result misses the brief, change one part of the prompt or model selection at a time. A successful API response is not the same as an approved creative result.

• Save the task ID before leaving the request flow.
• Handle pending, completed, failed, and timeout states.
• Use user initiated playback and check the generated file in the real page.
• Record the operation and current TTAPI price when estimating production cost.