---
title: "Suggest a place, propose or improve the plot, draft keyframes (costs credits)"
method: POST
path: "/v1/storyboards/{id}/assist"
tags: ["Storyboards"]
---

# Suggest a place, propose or improve the plot, draft keyframes (costs credits)

`POST /v1/storyboards/{id}/assist`

## Request

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

The guided steps' AI buttons. One text call to Gemini Flash-Lite that knows the film's format (model, clip lengths, shape), tone, art style, look, story, cast palette (each character with the skins and mounts the film uses for it) and places, and answers a **proposal**: nothing is written. `kind`: `place` suggests one place the film does not have (`place: {name, description}`; make it with `POST /v1/entities` kind `location`, then `{op: "addPlace", entry: {entityId}}`); `plot` proposes a plot, grown from the story's few words when there are some (offered while the story is under 280 characters); `improve` improves the story, its events, names and order kept (`text`, `note` on what changed, and `ops`: the one `setIdea` that keeps it); `keyframes` drafts the first moments (4 to 10: beat, camera, who is in it with which skin and mount, the place) and, only where the story offers a choice, up to 3 decisions of 2 or 3 options, for a film with at most one moment and no segment (`draft.moments`, and `ops`: ordinary mutations with fresh ids, `addPanel`, `updatePanel`, `connect`, `updateSegment`, `addDecision`, `addOption`; a blank first moment is filled, a first moment with words goes on into the draft, nothing is removed). Keep a proposal with `PATCH /v1/storyboards/{id} { mutations: ops }` (one batch, one undo). **Costs credits**: `storyboard_assist` per call (see `/v1/pricing`), checked before the call and charged after a readable answer, through your token so its daily cap applies. Quote first with `dry_run: true`: `credits`, and `available: false` with a `reason` when it cannot be asked now. A storyboard whose owner approves agent spending answers `403` except for the quote.

## Request body

- object
  - `kind` 'place' | 'plot' | 'improve' | 'keyframes', required
  - `dry_run` boolean

## Response `200`

The quote (dry_run), or the proposal

- object
  - `dry_run` boolean
  - `kind` 'place' | 'plot' | 'improve' | 'keyframes'
  - `available` boolean
  - `reason` string
  - `credits` integer, nullable
  - `credits_cost` integer
  - `place` object
    - `name` string
    - `description` string
  - `text` string: plot, improve: the proposed story.
  - `note` string
  - `draft` object
    - `moments` object[]
      - `key` string
      - `beat` string
      - `camera` string
      - `cast` object[]
        - `id` string
        - `skinId` string
        - `mountId` string
      - `placeId` string
      - `next` string
      - `action` string
      - `choices` object[]
        - `label` string
        - `to` string
        - `action` string
  - `ops` object[]: The mutations that keep the proposal.
  - `saved` boolean: Always false: a proposal is never written by itself.

## Other responses

- `400`: Write the story first
- `401`: Missing or invalid token
- `402`: Insufficient credits
- `403`: The owner approves an agent's spending on this storyboard
- `429`: Rate limit exceeded
- `502`: The AI's answer could not be read: try again. Nothing was charged.
- `503`: Draft keyframes from the story is not available yet: its price has not been set.

## Changes

- **2026-10-20** `b454211e598e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nanostudiopro/apis/nano-studio-pro-api/changes/v1/storyboards/:id/assist/post.md)

---

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