Put an effect over a clip
apply_effectPut one effect from search_effects into the film. It writes the effect on a new track in front of the clip it goes over, adds what the effect draws to the project, and makes what the effect needs. An effect on a person reuses a person mask of the clip's footage, or runs cutout_subject on the part of the footage the effect covers. An effect on a face reuses a face track of that footage, or runs track_faces there and takes the first face. Those runs use credits as those tools do. at is the timeline second the effect starts. duration null uses the effect's own length. clipId is the video clip the effect goes over: an effect on a person or a face needs it, and every effect sits in front of it when it is given. values is JSON text of the settings that differ from the effect's defaults, such as {"emoji": "ðŸ˜"} or {"face": "track_face_2"}; photos go in by Asset ID, such as {"top": "img_a", "bottom": "img_b"}. region is the part of the frame an overlay effect covers, as [x0, y0, x1, y1] fractions of the frame; null uses the effect's own box, most often the whole frame. Use one effect per moment, on a real beat or impact: an effect on every cut reads as noise. It writes the current version. The effect is in the film at once, and the editor shows it waiting while its mask or face is made; if that cannot be made, the effect is taken out again and the answer says why. A long cutout answers with a Job ID: wait for it with wait_for_jobs, and the effect plays when the cutout ends. Check the result with preview_frame.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"effectId": "<effectId>",
"at": "<at>",
"duration": "<duration>",
"clipId": "<clipId>",
"values": "<values>",
"region": "<region>",
"projectId": "<projectId>"
},
"name": "apply_effect"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| at | Yes | Timeline second the effect starts. | |
| clipId | Yes | Id of the video clip the effect goes over, from read_film. Needed for an effect on a person or a face. null places the effect in front of every track. | |
| region | Yes | The part of the frame an overlay effect covers, as [x0, y0, x1, y1]: its top left and bottom right corners as fractions of the frame. null (or leaving it out) uses the effect's own box, most often the whole frame. An effect drawn on a person or a face ignores it. | |
| values | Yes | JSON text of the effect's settings that differ from its defaults, as search_effects lists them, such as {"emoji": "ðŸ˜"}. Photos go in by Asset ID. null keeps every default. | |
| duration | Yes | How long the effect runs on the timeline, in seconds. null uses the effect's own length. | |
| effectId | Yes | Effect id from search_effects. | |
| projectId | Yes | The project this call runs on without changing the open project. null (or leaving it out) uses the open project. wait_for_jobs takes the projectId of the calls that started the jobs. |