Skip to main content
PUT
https://api.submagic.co
/
v1
/
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
    },
    "items": [
      {
        "type": "user-media",
        "startTime": 10.5,
        "endTime": 15.2,
        "userMediaId": "123e4567-e89b-12d3-a456-426614174000"
      },
      {
        "type": "ai-broll",
        "startTime": 25,
        "endTime": 31,
        "prompt": "smooth slider shot of a team collaborating in a modern studio"
      }
    ]
  }'

{
  "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

​
id
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.
​
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.
​
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.
​
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.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:
  1. Go to the Submagic editor
  2. Navigate to the ‘B-roll’ tab
  3. Add a B-roll to access your media library
  4. Go to the ‘My videos’ tab
  5. Each video will display its unique media ID that you can use with this API
Example.png

​
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.
​
id
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
    },
    "items": [
      {
        "type": "user-media",
        "startTime": 10.5,
        "endTime": 15.2,
        "userMediaId": "123e4567-e89b-12d3-a456-426614174000"
      },
      {
        "type": "ai-broll",
        "startTime": 25,
        "endTime": 31,
        "prompt": "smooth slider shot of a team collaborating in a modern studio"
      }
    ]
  }'

{
  "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.