---
title: "Suggest sound effects for takes (costs credits)"
method: POST
path: "/v1/storyboards/{id}/effects/suggest"
tags: ["Storyboards"]
---

# Suggest sound effects for takes (costs credits)

`POST /v1/storyboards/{id}/effects/suggest`

## Request

- Base URL: `https://nanostudiopro.com/api`
- URL: `https://nanostudiopro.com/api/v1/storyboards/{id}/effects/suggest`
- Auth: HTTP bearer

For each take, the AI reads its exact frames (up to 8 at even steps over what plays of it, as one numbered sheet) with its action prompt, the moments it runs between, their light and weather, who is there, the place and what is said, and proposes small physical sounds that happen on screen, each at its second of the clip: `{at_s, duration_s, name, prompt, level, rise?, why?}` (`prompt` is a concise sound-effect prompt; `level` 0.6 soft, 1 medium, 1.4 loud; `rise` dB it starts under for a sound coming toward the camera). Short, matched to the visible motion, never music, a voice or an ambience the place already has, at most 2 in any 4 seconds, the same sound at most twice. `take_ids` names the takes; absent, every take in use with a clip and no effects yet. **Costs credits**: one `scan` per take read (see `/v1/pricing`), checked before each call and charged only after an answer with a suggestion, through your token so its daily cap applies. Quote first with `dry_run: true`. The proposal is NOT saved: send what you keep (edited or not) to `POST /v1/storyboards/{id}/effects`. A storyboard whose owner approves agent spending answers `403` except for the quote.

## Request body

- object
  - `take_ids` string[]
  - `dry_run` boolean

## Response `200`

The quote (dry_run), or the suggestions

- object
  - `dry_run` boolean
  - `available` boolean
  - `reason` string
  - `credits` integer
  - `per_take` integer
  - `takes` object[]
    - `take_id` string
    - `target` object
    - `credits` integer
  - `suggestions` object[]
    - `take_id` string
    - `target` object: {kind: segment, id} | {kind: loop, decision_id} | {kind: ending, panel_id}.
    - `span` object: What plays of the clip.
      - `in_s` number
      - `out_s` number
    - `effects` object[]
      - `at_s` number
      - `duration_s` number
      - `name` string
      - `prompt` string
      - `level` number
      - `rise` integer
      - `why` string
  - `failed` string[]: Takes read with nothing usable back (not charged).
  - `skipped` object[]
    - `take_id` string
    - `reason` string
  - `credits_cost` integer

## Other responses

- `400`: Those takes have no clip yet
- `401`: Missing or invalid token
- `402`: Insufficient credits
- `403`: The owner approves an agent's spending on this storyboard
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/nanostudiopro/apis/nano-studio-pro-api.md) · [All operations](https://skmtc.dev/nanostudiopro/apis/nano-studio-pro-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nanostudiopro/apis/nano-studio-pro-api/revisions/b454211e598e?raw)