---
title: "Write the score's plan with AI (costs credits)"
method: POST
path: "/v1/storyboards/{id}/score/plan"
tags: ["Storyboards"]
---

# Write the score's plan with AI (costs credits)

`POST /v1/storyboards/{id}/score/plan`

## Request

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

One text call to Gemini Flash-Lite writes how each section of the score should sound (2-6 positive and up to 4 negative styles, and a one-line reason) and the film's global styles, from the film (each section's moments, action prompts, lines heard, light and weather, its place in the story: the opening, a decision's wait, the end) and the owner's direction (`setScoreDirection`), which outranks the rest. The sections are the ones `POST .../score` composes; the answer is stored in the storyboard (`doc.score.sections`, by `ai`), so the next score composes exactly that plan. Sections edited by hand (`setScoreSection`, by `owner`) are kept and not asked for. **Costs credits**: `score_plan` per call (see `/v1/pricing`), checked before the call and charged after a readable answer is on the storyboard, through your token so its daily cap applies. Quote first with `dry_run: true`: `credits`, `sections` (to write) and `kept` (yours); `available: false` comes with a `reason`. Read the plan back with `POST .../score { dry_run: true }`. A storyboard whose owner approves agent spending answers `403` except for the quote.

## Request body

- object
  - `dry_run` boolean

## Response `200`

The quote (dry_run), or what was written

- object
  - `dry_run` boolean
  - `available` boolean
  - `reason` string
  - `credits` integer, nullable
  - `sections` union: Quote: how many sections will be written. Written: each one.
    - integer
    - object[]
      - `key` string
      - `positive` string[]
      - `negative` string[]
      - `reason` string
  - `kept` integer: Sections edited by hand, kept as they are.
  - `written` integer
  - `credits_cost` integer
  - `global` object, nullable
    - `positive` string[]
    - `negative` string[]

## Other responses

- `400`: Add the first key moment to write the plan
- `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 plan could not be read: try again. Nothing was charged.
- `503`: Writing the plan with AI is not available yet: its price has not been set.

## Changes

- **2026-10-20** `7f7d4a72b17c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nanostudiopro/apis/nano-studio-pro-api/changes/v1/storyboards/:id/score/plan/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)