curl -X PUT "https://api.submagic.co/v1/projects/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "removeSilencePace": "fast",
    "removeBadTakes": true,
    "hookTitle": {
      "text": "New intro in 15 seconds",
      "template": "laura",
      "top": 40,
      "size": 28
    },
    "music": {
      "userMediaId": "88a08eec-712a-45d0-8d0b-3b631700cb3a",
      "volume": 25,
      "startFromTime": 10,
      "fade": true
    },
    "items": [
      {
        "type": "user-media",
        "startTime": 10.5,
        "endTime": 15.2,
        "userMediaId": "123e4567-e89b-12d3-a456-426614174000",
        "layout": "pip-top-right"
      },
      {
        "type": "ai-broll",
        "startTime": 25,
        "endTime": 31,
        "prompt": "smooth slider shot of a team collaborating in a modern studio",
        "layout": "split-50-50"
      }
    ]
  }'

{
  "message": "Project updated successfully",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

PUT

projects

{id}

curl -X PUT "https://api.submagic.co/v1/projects/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "removeSilencePace": "fast",
    "removeBadTakes": true,
    "hookTitle": {
      "text": "New intro in 15 seconds",
      "template": "laura",
      "top": 40,
      "size": 28
    },
    "music": {
      "userMediaId": "88a08eec-712a-45d0-8d0b-3b631700cb3a",
      "volume": 25,
      "startFromTime": 10,
      "fade": true
    },
    "items": [
      {
        "type": "user-media",
        "startTime": 10.5,
        "endTime": 15.2,
        "userMediaId": "123e4567-e89b-12d3-a456-426614174000",
        "layout": "pip-top-right"
      },
      {
        "type": "ai-broll",
        "startTime": 25,
        "endTime": 31,
        "prompt": "smooth slider shot of a team collaborating in a modern studio",
        "layout": "split-50-50"
      }
    ]
  }'

{
  "message": "Project updated successfully",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

Update Project

Update an existing video project with new settings, AI features, or user media (B-roll) insertions. This endpoint allows you to modify project parameters and enhance your video with additional features or custom media content from your library.

This endpoint requires authentication and has a rate limit of 100 requests per hour. After modifying a video, you’ll need to re-export to see the changes using the export endpoint. When using removeBadTakes, the response may take 1-2 minutes as our AI processes the video.

Authentication

x-api-key

string

required

Your Submagic API key starting with sk-

Path Parameters

string

required

The unique identifier (UUID) of the project to update

Request Body

All fields are optional. Only provide the fields you want to update. If a field is provided with a different value from the current project settings, it will be updated.

words

array

Edit the project’s captions. Fetch the current transcript from Get Project, change anything you want (text, timing, add or remove words), and send the full array back — it replaces the transcript, so include every word you want to keep. The caption layout is rebuilt automatically.Requirements (otherwise VALIDATION_ERROR): the project must already be transcribed, and words must stay in chronological order — each startTime greater than or equal to the previous word’s.Can be combined with other fields in the same request: the words are applied first, then the rest. If the words edit fails, nothing else is applied.

Hide Word Object

string

The word’s id from the Get Project response. Keep it to edit an existing word; omit it to add a new word.

text

string

required

The word text. For silence segments it is ignored and stored as empty (silence never renders caption text).

type

string

required

Segment type. Must be one of "word", "silence", or "punctuation" — any other value is rejected with VALIDATION_ERROR.

startTime

number

required

Start time in seconds (must be ≥ 0).

endTime

number

required

End time in seconds (must be ≥ startTime).

Returns the standard update response (Project updated successfully). Re-export the project to render the edited captions.

removeSilencePace

string

Automatically remove silence from the video at the specified pace. Allowed values: natural, fast, extra-fast. - extra-fast: 0.1-0.2 seconds of silence removal - fast: 0.2-0.6 seconds of silence removal - natural: 0.6+ seconds of silence removal

removeBadTakes

boolean

Automatically detect and remove bad takes and silence from the video using AI analysis. Note: This process may take 1-2 minutes to complete.

disableCaptions

boolean

Hide captions from the exported video. Optional, defaults to false.

hookTitle

boolean | object

Update the animated hook caption shown at the start of the video. Set to true to enable the default AI-generated hook, false to remove it, or pass an object with optional overrides:

text: Custom copy (1-100 characters)
template: Hook title template name (defaults to "tiktok"). Fetch valid names using the hook title templates endpoint.
top: Vertical position between 0-80 (default 50)
size: Font size between 0-80 (default 30)

Template names are validated before processing resumes; invalid names return VALIDATION_ERROR immediately.

music

object

Optional background music track. When provided, replaces any existing background music on the project.

Hide Music Object

userMediaId

string

required

UUID of the music track. Accepts either an AUDIO file from your media library (use List User Media) or a Trendy Music track ID (copied from the editor’s Edit Audio → Trendy Music tab).

volume

number

required

Playback volume (1-100)

startFromTime

number

Start offset within the audio file in seconds. Defaults to 0.

fade

boolean

Apply a fade-in/fade-out effect to the music track. Defaults to true.

items

array

Array describing B-roll edits. Provide at least one entry when this field is included. Each item must include a type field to specify whether it’s user media from your library or AI-generated content.

Hide User Media Item

type

string

required

Must be set to "user-media"

startTime

number

required

Start time in seconds where the media should begin (must be ≥ 0)

endTime

number

required

End time in seconds where the media should end (must be greater than startTime)

userMediaId

string

required

UUID of the user media from your library. You can find this ID in the editor’s ‘B-roll’ tab → ‘My videos’ section under each video.

layout

string

Layout mode for the inserted media. Available values depend on the media type:Video media: "cover", "contain", "rounded", "square", "split-50-50", "split-35-65", "split-50-50-bordered", "split-35-65-bordered", "pip-top-right", "pip-bottom-right"Image media: "cover", "contain", "rounded", "square"

Hide AI B-roll Item

type

string

required

Must be set to "ai-broll"

startTime

number

required

Start time in seconds (must be ≥ 0)

endTime

number

required

End time in seconds. Must be greater than startTime and no more than 12 seconds later.

prompt

string

required

1-2500 character description of what the AI should render. This field is mandatory whenever type: "ai-broll" is present.

layout

string

Layout mode for the AI B-roll. Allowed values: "cover", "contain", "rounded", "square", "split-50-50", "split-35-65", "split-50-50-bordered", "split-35-65-bordered", "pip-top-right", "pip-bottom-right"

Important: Each item must have a type field. Items entries cannot overlap each other in time.

AI B-roll Workflow & Credits

Every AI B-roll item consumes 3 AI credits. Requests fail with VALIDATION_ERROR if the authenticated user lacks enough credits (unless their balance is unlimited).
When AI B-roll work is accepted, the project is moved back to processing and the generation jobs run asynchronously. Your webhook or polling logic should watch for the project to return to completed.
Stock/user-media updates continue to succeed immediately with the traditional Project updated successfully message.

Finding User Media ID

To find your userMediaId:

Go to the Submagic editor
Navigate to the ‘B-roll’ tab
Add a B-roll to access your media library
Go to the ‘My videos’ tab
Each video will display its unique media ID that you can use with this API

Response

message

string

Success message confirming the project update. When AI B-roll work is accepted, the message is Project update accepted to indicate asynchronous rendering.

string

The unique identifier of the updated project

status

string

Updated processing status of the project. If AI B-roll generation was requested, the project is moved to processing until the renders finish.

Error Responses

error

string

Error code: NOT_FOUND or VALIDATION_ERROR

message

string

Detailed error message explaining what went wrong

400 Invalid Hook Title Template

object

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid template name"
}

curl -X PUT "https://api.submagic.co/v1/projects/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "removeSilencePace": "fast",
    "removeBadTakes": true,
    "hookTitle": {
      "text": "New intro in 15 seconds",
      "template": "laura",
      "top": 40,
      "size": 28
    },
    "music": {
      "userMediaId": "88a08eec-712a-45d0-8d0b-3b631700cb3a",
      "volume": 25,
      "startFromTime": 10,
      "fade": true
    },
    "items": [
      {
        "type": "user-media",
        "startTime": 10.5,
        "endTime": 15.2,
        "userMediaId": "123e4567-e89b-12d3-a456-426614174000",
        "layout": "pip-top-right"
      },
      {
        "type": "ai-broll",
        "startTime": 25,
        "endTime": 31,
        "prompt": "smooth slider shot of a team collaborating in a modern studio",
        "layout": "split-50-50"
      }
    ]
  }'

{
  "message": "Project updated successfully",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

Important: After updating a project, you must re-export the project to see the changes in the final video. Use the export endpoint to generate the updated video with your modifications. Processing Time: When using removeBadTakes, the API response may take 1-2 minutes as our AI analyzes and processes the video to detect and remove bad takes and silence.

Get Project Export Project

​Update Project

​Authentication

​Path Parameters

​Request Body

​AI B-roll Workflow & Credits

​Finding User Media ID

​Response

​Error Responses

Update Project

Authentication

Path Parameters

Request Body

AI B-roll Workflow & Credits

Finding User Media ID

Response

Error Responses