Probably
Docs

Prepare a storyboard

storyboard, in Changes: A connection or key that may make changes. None spends credits; prepare_* and stage tools (research, brainstorm, write_script, review, generate_clip, voice, storyboard) prepare paid work for confirm_spend.

POST
/api/v1/tools/storyboard

Prepare a storyboard of a script: the studio's producer turns it into scenes (each a prompt, the line said in it and its seconds) and draws each scene's still on the image routes, which the image critics judge; stills they send back are redrawn once. The script is a write_script result of the same video or your own words. Cast the Space's personas (list_personas) and library images: the stills that show them are drawn from them. A scene's prompt, line, still (or its references) and durationSeconds are what generate_clip takes. It runs on a video of the Space (videoId, using that video's brief) or on a new draft made from brief, never both. Its raw form (stills alone) is to come: it is reviewed on every connection. The producer and critics are metered at cost, at most 90 credits, and each still drawn is charged one still's price, held for each scene's still and one redraw: the preview's storyboard shows the still's price and what the cap is made of, and the docs' pricing page lists it. A failed or refused still is charged nothing. Read it with get_stage, which links to each still. Show the person the preview. If the connection may spend, call confirm_spend with the confirmationId once they agree; otherwise send them the confirmUrl to confirm it in the studio. It expires in 15 minutes. Pass a new requestKey; repeating one returns the same confirmation.

Authorization

apiKey
headerAuthorizationBearer <token>

An API key (prb_…) from Settings → Connections.

Request Body

application/json
  1. body
spaceId*string
Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
videoId?string

A video of the Space to run on, with its current brief. Don't pass brief, name or attachments with it

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
brief?string

The brief for a new draft video, when no videoId is given

Length10 <= length <= 20000
name?string
Length1 <= length <= 120
attachments?array<||>
Itemsitems <= 45
requestKey*string
Match^[\w.:-]+$
Length8 <= length <= 64
script*|

The script to storyboard: { "kind": "revision", "revisionId" } for a write_script result of the same video (get_stage's result revisionId), or { "kind": "text", "text" } for your own words, as written

cast?

Who and what the stills show: up to 4 of the Space's personas by ID (list_personas), each with a photo or headshot, and up to 4 ready image versions of the library (list_assets); the stills that show them are drawn from them

Default
{  "personas": [],  "references": []}
format?string
Default"portrait"
Value in"portrait""square""landscape"
scenes?

How many scenes the producer plans, between min and max (1 to 7); the hold covers max

Default
{  "min": 3,  "max": 5}

Response Body

The tool's answer.

application/json
  1. response
videoId*string
Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
confirmationId*string
Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
expiresAt*string
preview*||||||
confirmUrl*|null
curl -X POST 'https://studio.probably.co/api/v1/tools/storyboard' \  -H "Authorization: Bearer $PROBABLY_API_KEY" \  -H 'Content-Type: application/json' \  -d '{  "spaceId": "5b0e7c1a-3f52-4d8e-9a61-2c4f8e9d7b30",  "videoId": "9c3d5e2f-8a14-4b67-b0d9-6e1f2a3c4d5e",  "attachments": [],  "requestKey": "storyboard-trailguard-1",  "script": {    "kind": "revision",    "revisionId": "3c4d5e6f-7a8b-4c9d-8e1f-2a3b4c5d6e7f"  },  "cast": {    "personas": [      "7b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e"    ],    "references": []  },  "format": "portrait",  "scenes": {    "min": 3,    "max": 5  }}'
{  "videoId": "9c3d5e2f-8a14-4b67-b0d9-6e1f2a3c4d5e",  "confirmationId": "e7a1b2c3-d4e5-4f60-8172-93a4b5c6d7e8",  "expiresAt": "2026-10-25T09:15:00.000Z",  "preview": {    "kind": "stage",    "stage": "storyboard",    "capCredits": 135,    "availableCredits": 1840,    "fits": true,    "clip": null,    "voice": null,    "raw": false,    "storyboard": {      "scenesMax": 5,      "stillCredits": 4.5,      "stills": 10,      "passesCapCredits": 90,      "withoutRedrawCredits": 112.5    },    "sandbox": false  },  "confirmUrl": null}