// Node.js (using fetch)
const apiUrl = "https://api.joinoverlap.com/trigger-template";
const headers = {
"Content-Type": "application/json",
"Authorization": `Bearer ${process.env.OVERLAP_API_KEY}`,
"Overlap-Workflow-Channel": "stable"
};
const payload = {
companyId: process.env.OVERLAP_COMPANY_ID,
workflowId: process.env.OVERLAP_WORKFLOW_ID,
url: "https://example.com/source-video.mp4",
broll: true
};
fetch(apiUrl, {
method: "POST",
headers,
body: JSON.stringify(payload)
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));
import requests
import os
api_url = "https://api.joinoverlap.com/trigger-template"
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {os.environ['OVERLAP_API_KEY']}",
"Overlap-Workflow-Channel": "stable"
}
payload = {
"companyId": os.environ["OVERLAP_COMPANY_ID"],
"workflowId": os.environ["OVERLAP_WORKFLOW_ID"],
"url": "https://example.com/source-video.mp4",
"broll": True
}
response = requests.post(api_url, json=payload, headers=headers)
print(response.json())
curl -X POST "https://api.joinoverlap.com/trigger-template" \
-H "Authorization: Bearer $OVERLAP_API_KEY" \
-H "Content-Type: application/json" \
-H "Overlap-Workflow-Channel: stable" \
-d '{
"companyId": "'"$OVERLAP_COMPANY_ID"'",
"workflowId": "'"$OVERLAP_WORKFLOW_ID"'",
"url": "https://example.com/source-video.mp4",
"broll": true
}'
Trigger Template
Start a clipping workflow from a saved template using a long-form video URL
POST
/
trigger-template
// Node.js (using fetch)
const apiUrl = "https://api.joinoverlap.com/trigger-template";
const headers = {
"Content-Type": "application/json",
"Authorization": `Bearer ${process.env.OVERLAP_API_KEY}`,
"Overlap-Workflow-Channel": "stable"
};
const payload = {
companyId: process.env.OVERLAP_COMPANY_ID,
workflowId: process.env.OVERLAP_WORKFLOW_ID,
url: "https://example.com/source-video.mp4",
broll: true
};
fetch(apiUrl, {
method: "POST",
headers,
body: JSON.stringify(payload)
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));
import requests
import os
api_url = "https://api.joinoverlap.com/trigger-template"
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {os.environ['OVERLAP_API_KEY']}",
"Overlap-Workflow-Channel": "stable"
}
payload = {
"companyId": os.environ["OVERLAP_COMPANY_ID"],
"workflowId": os.environ["OVERLAP_WORKFLOW_ID"],
"url": "https://example.com/source-video.mp4",
"broll": True
}
response = requests.post(api_url, json=payload, headers=headers)
print(response.json())
curl -X POST "https://api.joinoverlap.com/trigger-template" \
-H "Authorization: Bearer $OVERLAP_API_KEY" \
-H "Content-Type: application/json" \
-H "Overlap-Workflow-Channel: stable" \
-d '{
"companyId": "'"$OVERLAP_COMPANY_ID"'",
"workflowId": "'"$OVERLAP_WORKFLOW_ID"'",
"url": "https://example.com/source-video.mp4",
"broll": true
}'
Endpoint
POST https://api.joinoverlap.com/trigger-template
Find
workflowId in the workflow URL: https://portal.overlap.ai/workflows/{workflowId}/trigger.Authentication
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Overlap-Workflow-Channel: stable
Overlap-Workflow-Channel is optional; omit it to use the current workflow runtime.
Request Body
Required fields arecompanyId, workflowId, and url. Every other field is optional and overrides the saved template only for this run.
{
"companyId": "your-company-id",
"workflowId": "your-workflow-id",
"url": "https://example.com/source-video.mp4",
"broll": true,
"subtitles": true,
"promptAdjustment": "Prioritize clips about product announcements.",
"pinnedTimestamps": [{ "start": 120, "end": 165 }],
"pinnedTimestampsOnly": false,
"pinnedTimestampMode": "search_within"
}
Fields
| Field | Type | Required | Description |
|---|---|---|---|
companyId | string | Yes | Your Overlap company or organization identifier. |
workflowId | string | Yes | The workflow/template identifier to launch. |
url | string | Yes | Publicly accessible long-form video URL to process. |
orientation | string | No | Override output orientation, such as horizontal or vertical. |
minLengthTarget / maxLengthTarget | number | No | Override clip duration bounds in seconds. |
broll | boolean | No | Enable or disable automatic b-roll for this run. |
subtitles | boolean | No | Enable or disable subtitles for this run. |
subtitleConfig | object | No | Override subtitle styling when the workflow includes a subtitle node. |
titleOverlay | boolean | No | Enable or disable the title overlay when the workflow includes a title overlay node. |
titleConfig | object | No | Override title overlay prompt and styling. To set fixed title text instead of an AI-generated title, include generateTitle: false along with text (see Node Config). |
watermarkUrl | string | No | Override the watermark asset URL. |
keywords | string[] | No | Transcription enrichment keywords. Maximum 150. |
promptAdjustment | string | No | Text appended to the workflow’s clipping prompt. |
pinnedTimestamps | object[] | No | Source-video timestamp ranges to include as clips for this run. |
pinnedTimestampsOnly | boolean | No | When true, return only the clips from pinnedTimestamps; defaults to also discovering clips. |
pinnedTimestampMode | string | No | Use search_within to find individual clips only inside pinnedTimestamps; omit it for guaranteed timestamp clips. |
nodeConfigs | object | No | Advanced node-level overrides keyed by workflow node type. |
Selecting a styled title template
titleConfig accepts the same fields as the title node’s title_config, so a
run can pick one of the styled title templates
by id and, optionally, a palette. Selecting a template resets any template
customizations saved on the workflow’s title node, so the request is the only
source of styling for that run. Combine it with generateTitle: false and
text to pin the headline, or omit those two fields to let the node’s prompt
write it.
{
"companyId": "your-company-id",
"workflowId": "your-workflow-id",
"url": "https://example.com/source-video.mp4",
"orientation": "vertical",
"titleOverlay": true,
"titleConfig": {
"titlePresetId": "cyan-block-title",
"titlePaletteId": "breaking-news",
"generateTitle": false,
"text": "Storm hits coast, thousands flee"
}
}
Workflow Runtime Channel
By default, requests run on the current workflow service. To use the pinned stable service for a run, add:Overlap-Workflow-Channel: stable
current and stable are accepted. Any other value returns INVALID_WORKFLOW_CHANNEL without storing or dispatching the run. The response echoes the applied channel in the same header. The channel is routing metadata and is not passed to workflow nodes as input.
Workflow Runtime Channels
See channel behavior, complete request examples, responses, and errors
Google Drive Source URLs
You can use a Google Drive video as theurl value when triggering a workflow. Before sending the request, verify both of these requirements:
- Use a direct Google Drive file link. The URL should include
/file/, for examplehttps://drive.google.com/file/d/FILE_ID/view?usp=sharing. Folder links, preview links, and other Drive URLs that do not include/file/are not supported source-file links. - Make the file accessible to Overlap. Either set the file to public access, or share it directly with the Overlap service account:
[email protected].
Override Behavior
Overrides only apply when the referenced workflow contains the matching node. For example,subtitleConfig is ignored if the workflow does not include a subtitles node.
For advanced integrations, use nodeConfigs, nodeConfigOverrides, or actionConfigs to update action node configuration directly. Supported node keys include find_clips, convert_to_vertical, style_video, add_broll, add_music, and other workflow action nodes.
If a workflow contains the target node but the override shape is invalid, the request returns an INVALID_NODE_CONFIG error.
Node Config Overrides
See frontend-configurable override fields and per-node examples
// Node.js (using fetch)
const apiUrl = "https://api.joinoverlap.com/trigger-template";
const headers = {
"Content-Type": "application/json",
"Authorization": `Bearer ${process.env.OVERLAP_API_KEY}`,
"Overlap-Workflow-Channel": "stable"
};
const payload = {
companyId: process.env.OVERLAP_COMPANY_ID,
workflowId: process.env.OVERLAP_WORKFLOW_ID,
url: "https://example.com/source-video.mp4",
broll: true
};
fetch(apiUrl, {
method: "POST",
headers,
body: JSON.stringify(payload)
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));
import requests
import os
api_url = "https://api.joinoverlap.com/trigger-template"
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {os.environ['OVERLAP_API_KEY']}",
"Overlap-Workflow-Channel": "stable"
}
payload = {
"companyId": os.environ["OVERLAP_COMPANY_ID"],
"workflowId": os.environ["OVERLAP_WORKFLOW_ID"],
"url": "https://example.com/source-video.mp4",
"broll": True
}
response = requests.post(api_url, json=payload, headers=headers)
print(response.json())
curl -X POST "https://api.joinoverlap.com/trigger-template" \
-H "Authorization: Bearer $OVERLAP_API_KEY" \
-H "Content-Type: application/json" \
-H "Overlap-Workflow-Channel: stable" \
-d '{
"companyId": "'"$OVERLAP_COMPANY_ID"'",
"workflowId": "'"$OVERLAP_WORKFLOW_ID"'",
"url": "https://example.com/source-video.mp4",
"broll": true
}'
Response
{
"triggerId": "c1a27b63-91d9-45fb-9c89-5f418442fb6e",
"status": "pending",
"message": "Workflow trigger initiated successfully"
}
triggerId- Save this value and pollGET /workflow-results/{triggerId}.status- Usuallypendingimmediately after triggering.message- Human-readable confirmation or context.
Overlap-Workflow-Channel response header reports current or stable, matching the runtime selected for the run.
Processing Time
- Horizontal clips: about 3 minutes per hour of input video.
- Vertical clips: about 10 minutes per hour of input video.
- Actual runtime varies by workflow configuration, video length, and video complexity.
Get workflow results
Poll for status and retrieve generated clips with your triggerId
Was this page helpful?