Skip to main content

​
Edit the Transcript Before Rendering

By default, a project created through the API is rendered automatically as soon as transcription finishes. If you want to review or fix the captions first (correct a misheard word, retime a caption, add or remove words), create the project with autoRender: false. The project then waits for you to edit the transcript and trigger the export yourself.
1

Create the project with autoRender: false

Pass autoRender: false to Create Project. The video is downloaded and transcribed, but no render is started.
cURL
curl -X POST "https://api.submagic.co/v1/projects" \
  -H "x-api-key: sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Awesome Video",
    "language": "en",
    "videoUrl": "https://example.com/videos/sample.mp4",
    "templateName": "Hormozi 2",
    "autoRender": false,
    "webhookUrl": "https://yoursite.com/webhook/submagic"
  }'
2

Wait until transcription is ready

You have two options to learn when the transcript is ready:
  • Webhook (recommended): if you passed a webhookUrl, you’ll receive a completed notification once transcription finishes. For an autoRender: false project this fires after transcription (the video is not rendered yet, so downloadUrl will be empty until you export).
  • Polling: call Get Project until transcriptionStatus is "COMPLETED". At that point the words array is available.
cURL
curl "https://api.submagic.co/v1/projects/{id}" \
  -H "x-api-key: sk-your-api-key-here"
Response (transcription done)
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "transcriptionStatus": "COMPLETED",
  "words": [
    { "id": "w1EydrN5", "text": "Do",  "type": "word", "startTime": 0.08, "endTime": 0.16 },
    { "id": "8VUdYfGN", "text": "you", "type": "word", "startTime": 0.16, "endTime": 0.24 }
  ]
}
For an autoRender: false project, status: "completed" means “transcribed and ready to edit” — the video has not been rendered yet. A downloadUrl only appears after you export in step 4.
3

Get the words array and edit it

Take the words array from the Get Project response and change whatever you need. You can:
  • Fix text — change a word’s text.
  • Retime — adjust startTime / endTime.
  • Add a word — insert a new entry and omit its id (a fresh id is assigned for you).
  • Remove a word — leave it out of the array.
Send the full array back — it replaces the current transcript.
4

Submit the edited words

Send the edited array to Update Project in the words field. The caption layout is rebuilt automatically so everything stays in sync at render time.
cURL
curl -X PUT "https://api.submagic.co/v1/projects/{id}" \
  -H "x-api-key: sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "words": [
      { "id": "w1EydrN5", "text": "Did", "type": "word", "startTime": 0.08, "endTime": 0.16 },
      { "id": "8VUdYfGN", "text": "you", "type": "word", "startTime": 0.16, "endTime": 0.24 }
    ]
  }'
200 OK
{
  "message": "Project updated successfully",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed"
}
Editing words is only allowed after transcription completes. Calling it too early returns a VALIDATION_ERROR.You can also combine words with other fields (e.g. music, items) in the same request — the caption edit is applied first, then the rest.
5

Export the final video

When the captions look right, trigger the render with Export Project. You’ll be notified at your webhookUrl (or can poll Get Project) when the rendered video is ready and downloadUrl is populated.
cURL
curl -X POST "https://api.submagic.co/v1/projects/{id}/export" \
  -H "x-api-key: sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{}'

​
Notes

  • You can edit the transcript as many times as you like before exporting — repeat steps 3–4.
  • Default behavior is unchanged: omit autoRender (or set it to true) and the project renders automatically once transcription completes, exactly as before.
  • This flow does not apply to Magic Clips, which follow their own pipeline.