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.
https://app.softsolz.uk/api/v1/services/creative-studio/designs/{id}/storyRecent Requests
Kept only in this browserPath Params
idstringrequiredHeaders
AuthorizationstringrequiredBearer token: Bearer sk_live_... (or sk_test_... for sandbox). A login token will not work here.
Idempotency-KeystringOptional idempotency key for safe retries.
Body Params
titlestringTitle in the library. Defaults to the first headline.
templatestringTemplate id from GET /story-templates. Leave out to pick one from category and the scenes.
formatstringstory 9:16 (default), landscape 16:9 or square 1:1.
paletteobjectOnly to override the brand kit: { primary, secondary, accent, dark, light } as #rrggbb.
product_asset_idstringProduct photo from POST /assets.
product_photostringOr the name of a saved photo.
voicestringVoice of the voice-over.
musicstringMusic mood; none for voice only.
notestringNote for the version history.
expected_updated_atstringupdated_at from your last read.
scenesarray of objectsScenes 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" ] }}