---
title: "Update Segment Prompts Endpoint"
method: POST
path: "/segments/{segment_id}/update-prompts"
tags: ["segments"]
---

# Update Segment Prompts Endpoint

`POST /segments/{segment_id}/update-prompts`

## Request

- Base URL: `https://api.framesail.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.framesail.com/segments/{segment_id}/update-prompts`
- Auth: HTTP bearer

Directly set a segment's final prompts verbatim — no LLM rewrite.

## Path parameters

- `segment_id` string, required

## Request body

- UpdateSegmentPromptsRequest: Directly set a segment's final prompts — no LLM rewrite. Only the fields provided are touched; each one is written verbatim to director_payload and mirrored onto the matching segment_assets config.description (the text the renderer actually reads). Renders keep their status: the new prompts apply when the segment renders again.
  - `image_prompt` string, nullable: The segment's image prompt (every segment; the real-photo fallback too).
  - `video_prompt` string, nullable: Motion/video prompt (video segments / b-roll fallback).
  - `media_queries` string[], nullable: Stock-search queries for fetched media (real b-roll / real photo segments). Replaces the segment's media_query.queries verbatim; the fetched media changes when the segment is fetched again.

## Response `200`

Successful Response

- SegmentOperationResponse: Response for all segment operations. A dry_run returns `preview` with an empty `segments` list; a real run returns the mutated segments.
  - `segments` object[], required
  - `warning` string, nullable
  - `preview` TransitionPreview: dry_run disclosure for a destructive segment operation — one payload shape for every op and every surface (storyboard UI, editor, MCP).
    - `kept` integer, required
    - `stale` integer, required
    - `recreated` integer, required
    - `deleted` integer, required
    - `jobs_cancelled` integer, required
    - `rendered_assets_lost` string[]: What each already-rendered asset this operation destroys is (image, clip, real photo, ...), named by generation.roles.asset_label.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/framesail/apis/framesail-api.md) · [All operations](https://skmtc.dev/framesail/apis/framesail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/framesail/apis/framesail-api/revisions/12602eae0820?raw)