SoftSolzSoftSolz
HomeAPI GuideAPI ReferenceWidget Tester

Change a story video: scenes, template, shape, voice or music

Makes a new version. Send only what changes. scenes holds the scenes to change by index (0 is the first): fields merge into the scene, remove: true deletes it, insert: true adds a new scene before index. A music-only change keeps the voice and costs no credits. Send expected_updated_at from GET /designs/{id} to get 409 STALE_VERSION instead of overwriting someone else's change. Errors: 400 invalid_input names the field to fix (for example text over its length); 400 field_not_available for hero_images or image_attachment_ids; 404 not_found for an unknown photo; 402 when the workspace is out of AI credits for the voice-over; 429 rate_limited when more than 20 videos are made in 10 minutes.

PATCHhttps://app.softsolz.uk/api/v1/services/creative-studio/designs/{id}/story

Recent Requests

Kept only in this browser
TimeStatusTook
Send a request with Try it to see it here.

Path Params

idstringrequired

Headers

Authorizationstringrequired

Bearer token: Bearer sk_live_... (or sk_test_... for sandbox). A login token will not work here.

Idempotency-Keystring

Optional idempotency key for safe retries.

Body Params

titlestring

Title in the library. Defaults to the first headline.

templatestring

Template id from GET /story-templates. Leave out to pick one from category and the scenes.

formatstring

story 9:16 (default), landscape 16:9 or square 1:1.

paletteobject

Only to override the brand kit: { primary, secondary, accent, dark, light } as #rrggbb.

product_asset_idstring

Product photo from POST /assets.

product_photostring

Or the name of a saved photo.

voicestring

Voice of the voice-over.

musicstring

Music mood; none for voice only.

notestring

Note for the version history.

expected_updated_atstring

updated_at from your last read.

scenesarray of objects

Scenes to change by index.

Response

Response Body

idstringDesign id.
titlestringTitle shown in the library.
formatstringstory (9:16), landscape (16:9), square (1:1) or a picture format.
widthintegerWidth in pixels.
heightintegerHeight in pixels.
versionintegerCurrent version. Every change makes a new one.
saved_atstring | nullWhen it joined the library.
created_atstringWhen it was made.
updated_atstringSend it back as expected_updated_at to make sure nobody changed the video since you read it.
is_storybooleanTrue for a story video made from a template.
storyobject | nullThe scenes of a story video. null for a picture or a custom design.
soundtrackobject | nullVoice-over and music. null when the design has none.
videoobjectThe MP4 file of the current version.
linksobjectPages in SoftSolz for this design.
notesarray of stringsOnly on create and change: anything that was adjusted, such as text that was shortened.

Request

curl --request PATCH \
--url https://app.softsolz.uk/api/v1/services/creative-studio/designs/{id}/story \
--header 'Authorization: Bearer sk_live_your_key' \
--header 'Content-Type: application/json' \
--data '{
"music": "calm",
"scenes": [
{
"index": 0,
"fields": {
"headline": "Slow mornings"
}
}
]
}'

Credentials

Sent as a Bearer token and used in the samples above and in Try it. Kept only in this browser tab until you close it. Use an sk_test_ key to stay in your sandbox.

Response · 200

{
"data": {
"id": "your-id",
"title": "your-title",
"format": "your-format",
"width": 1,
"height": 1,
"version": 1,
"saved_at": "2026-01-01T09:00:00.000Z",
"created_at": "2026-01-01T09:00:00.000Z",
"updated_at": "2026-01-01T09:00:00.000Z",
"is_story": true,
"story": {
"template": "your-template",
"format": "story",
"category": "your-category",
"voice": "your-voice",
"music": "your-music",
"target_seconds": 1,
"product_asset_id": "your-product-asset-id",
"scenes": [
{
"kind": "hook",
"fields": {},
"narration": "your-narration",
"image": "product"
}
]
},
"soundtrack": {
"status": "queued",
"voice": "your-voice",
"music": "your-music",
"total_ms": 1,
"error_code": "your-error-code",
"lines": 1,
"updated_at": "2026-01-01T09:00:00.000Z"
},
"video": {
"duration_ms": 1,
"mp4_ready": true,
"download_url": "https://example.com",
"download_expires_at": "2026-01-01T09:00:00.000Z"
},
"links": {
"open": "your-open"
},
"notes": [
"your-notes"
]
}
}