Project File Export
Convert a gtrk v1 timeline structure into project files for multiple non-linear editors (NLE) in a single call: Premiere/FCP7 XML, Final Cut Pro X, OpenTimelineIO, JianYing draft, CapCut draft, and the Tonghe gtrk project file. Ideal for importing an algorithmically arranged video structure straight into an editor for further refinement.
ℹ️ Note: Unlike other endpoints, this one requires no file upload — the request body itself is the timeline structure. The asset paths in
materials[].pathare local references in the caller's editing environment; the server never reads the asset files, it only converts the structure.materials[].idis the platform-returned file ID (file_id) in cloud scenarios.
Create Task
Basic Information
| Item | Value |
|---|---|
| Request Method | POST |
| Request Path | /task/video_project_struct |
| Content-Type | application/json |
| Authentication | Raw API key in the Authorization header |
Request Body
The body is a gtrk v1 timeline structure. All time fields are in seconds.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
version | string | Yes | - | Contract version, fixed at "v1" |
video_size | array | Yes | - | Canvas size [width, height] in pixels, e.g. [1920, 1080] |
video_rate | number | Yes | - | Overall frame rate (fps, integer), e.g. 60 |
duration | number | Yes | - | Total output duration (seconds) |
materials | array | Yes | - | Asset list; each entry has an id plus metadata (see below) |
video_track | array | Yes | - | Video tracks (layered), see below |
audio_track | array | Yes | - | Audio tracks (layered), see below |
beat_track | array | No | [] | HTML particle overlay layers. This endpoint ignores beat_track; to render particles use html_animate_render |
struct_meta | object | No | {} | Contains nle_draft_dir (draft folder path), see below |
project_formats | array | No | all | Subset of formats to produce; omit to produce all public formats. The legacy name output_formats is still accepted as an alias |
materials[] entry
Each asset is identified by a single id — the platform file_id in cloud scenarios, or a local ID in purely local scenarios. Clips in video_track / audio_track / beat_track reference this id via their material field.
Each entry uses one of two reference forms, and both may be mixed within one request:
- Local reference: the entry carries a non-empty
path(absolute path recommended, always forward slashes/). Theidmay then be any local identifier — it only serves as the clip reference key and no platform file check is performed. The path is written into the generated project file as-is for your local editing software to load, so make sure it is valid in your environment; - Cloud reference: the entry has no
path. Theidmust then be a platform file ID (file_id) of an existing file, otherwise6004(file not found) is returned.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Unique asset identifier; any local ID when path is present, must be a platform file ID (file_id) when it is not; referenced by clips via material |
path | string | No | Local asset path (absolute + forward slashes recommended) for NLE project files / offline ffmpeg; never read by the server; when present, the entry is exempt from the platform file check |
duration | number | No | Total asset duration (seconds) |
video_size | array | No | Original asset size [width, height] (video assets) |
video_rate | number | No | Asset frame rate (video assets) |
audio_channel | string | No | Channel layout, "stereo" or "mono" (audio assets) |
💡 Tip: Fill in as much metadata per asset as you can, so that a client holding the gtrk can rebuild the project offline with ffmpeg without resolving IDs back through the cloud. A missing field does not break serialization — it is simply omitted.
Track object in video_track[] / audio_track[]
Both video and audio tracks are layered by track: track_index is an explicit integer z-order, and the track with the smallest track_index is the base track (main); the rest are overlays (larger track_index is closer to the front).
| Field | Type | Required | Description |
|---|---|---|---|
track_index | number | Yes | Explicit layer; the smallest is the base track (main) |
track_size | array | No | (video track only) Original asset size [width, height] of this track, for scaling against the canvas video_size |
muted | boolean | No | (video track only) Track-level default mute, can be overridden by a clip-level muted |
volume | number | No | (audio track only) Track-level default volume, can be overridden by a clip-level volume |
track_timeline | array | Yes | Sequence of clip objects on the track. Array order does not matter (the server places clips by track_st) |
Clip object in track_timeline[] (video / audio)
Every non-gap clip carries both the source-trim timecodes (clip_st/clip_ed) and the on-track timecodes (track_st/track_ed/duration). The two sets are kept redundantly to serve both "start + duration" and "start + end" consumers. The array order of track_timeline does not matter: every clip is placed absolutely on the timeline by its track_st (the server always positions clips by track_st), so out-of-order submissions produce the same output as time-ordered ones, and real gaps between clips are preserved as-is.
| Field | Type | Required | Description |
|---|---|---|---|
clip_id | string | Yes | Clip identifier; an empty string "" means a Gap (a gap omits material / clip_st / clip_ed) |
material | string | Yes | References a materials[].id (omitted for gaps) |
clip_st | number | Yes | Source in-point within the asset (seconds) |
clip_ed | number | Yes | Source out-point within the asset (seconds); for retimed clips clip_st + duration × speed |
track_st | number | Yes | Clip in-point on the timeline (seconds) |
track_ed | number | Yes | Clip out-point on the timeline (seconds) |
duration | number | Yes | Clip duration on the timeline (seconds) |
muted | boolean | No | (video) Clip-level mute, overrides the track-level muted |
volume | number | No | (audio) Clip-level volume, overrides the track-level volume |
clip_transform | object | No | (video) Static clip transform, see "clip_transform & clip_keyframes" below |
clip_keyframes | object | No | Keyframe animation channels (all channels on video clips / volume only on audio clips), see "clip_transform & clip_keyframes" below |
border_radius | number | No | (video) Corner radius of the clip's displayed rectangle, canvas pixels, ≥ 0, see "border_radius & clip_mask" below |
clip_mask | object | No | (video) Shape mask (circle / rounded rectangle / heart / diamond / star), see "border_radius & clip_mask" below |
speed | number | No | Constant playback speed, 0.01–100, default 1, see "speed & keep_pitch" below |
keep_pitch | boolean | No | Whether to keep the original pitch when retimed, default false, see "speed & keep_pitch" below |
ℹ️ Two-layer mute / volume semantics: video uses
muted, audio usesvolume, each at both the track level and the clip level. Precedence: clip-level if present, otherwise track-level, otherwise the default (muteddefaults tofalse,volumedefaults to1.0).
clip_transform & clip_keyframes (optional: static transform & keyframe animation)
Both fields are honored only by the JianYing / CapCut drafts; the other formats (Premiere / FCPX / OTIO) ignore them without error. Omitting them means no transform / no animation.
clip_transform (static transform, video clips): {position_x, position_y, scale_x, scale_y, rotation, alpha}. Units: position_x/y in canvas pixels (canvas center is the origin, +x right / +y down); scale_x/y as ratios (1.0 = 100%, negative = flip); rotation in clockwise degrees; alpha opacity 0..1.
clip_keyframes (keyframe animation): an object whose keys are property names and whose values are non-empty [{t, v}] arrays. Video clips support seven channels: position_x / position_y / scale_x / scale_y / rotation / alpha / volume; audio clips support volume only (volume ramps). Rules:
tis in seconds relative to the clip's on-track in-point, must fall within[0, duration], and must be strictly increasing within a channel;vuses the same unit as the matchingclip_transformproperty (volumeis linear gain, must be ≥ 0,1.0= original volume);- adjacent keyframes are linearly interpolated (JianYing draft keyframes are linear);
- at most 3000 keyframes per channel;
- when a property is keyframed, set the matching
clip_transformstatic value to the first keyframe's value (inside JianYing the curve wins; the static value serves as a fallback for formats that do not honor animation); - a
scale_x/scale_ychannel containing any negative value is not honored (JianYing's flip is a boolean and cannot be keyframed); the clip's other channels convert as usual. Express a static flip via a negative scale inclip_transform.
speed & keep_pitch (optional: constant speed)
Allowed on video and audio clips. Gaps and HTML particles in beat_track cannot be retimed; requests that try are rejected. Omitted means normal speed.
speed: constant playback speed, a finite number from0.01to100.> 1speeds up,< 1slows down;durationis the clip's length on the timeline; the clip consumesduration × speedof source, i.e.clip_ed = clip_st + duration × speed(in whole milliseconds,.5rounds up);keep_pitch: boolean,truekeeps the original pitch after retiming, defaultfalse(pitch follows speed);tinclip_keyframesis still in timeline seconds and is not scaled by speed.
Format support: Jianying drafts and FCPX carry both speed and pitch; CapCut drafts, Premiere XML and OTIO carry speed, and when a pitch setting cannot be expressed it is counted per format in the returned warnings (kind = speed_keep_pitch_not_carried); gtrk keeps both fields as-is.
// Occupies 3 s on the timeline, plays source 10–16 s at 2x with pitch kept
{ "clip_id": "c1", "material": "F100", "clip_st": 10.0, "clip_ed": 16.0,
"track_st": 0.0, "track_ed": 3.0, "duration": 3.0, "speed": 2.0, "keep_pitch": true }
border_radius & clip_mask (optional: rounded corners & shape mask)
Both fields are accepted on video clips only (an audio clip carrying either is rejected), and are honored only by the JianYing / CapCut drafts; the other formats ignore them without error. Omitting them means no rounding / no mask. The typical use is picture-in-picture: scale and position the clip with clip_transform, then round its corners with border_radius or open a circular window with clip_mask.
border_radius (rounded corners): a number ≥ 0 in canvas pixels, applied to the four corners of the clip's displayed rectangle (after scaling) and rotating with the clip. Inside JianYing it is expressed as a full-size rounded-rectangle mask.
clip_mask (shape mask, at most one per clip): {shape, center_x, center_y, width, height, rotation, corner_radius, feather, invert}.
shape:rectangle(rectangle, optionally withcorner_radius) /ellipse(equal width and height gives a circle) /heart/diamond/star;center_x/center_y: mask center, normalized to the clip's displayed rectangle with the origin at its center —0is the center,±0.5the edges, +x right / +y down, values outside the edges are allowed; default0;width/height: mask size as a ratio of the clip's displayed width / height (> 0, may exceed 1); default0.5;rotation: clockwise degrees around the mask center;corner_radius:rectangleonly, 0..1, corner radius as a fraction of half the mask's shorter side (1 = fully rounded);feather: 0..100, feather width as a percentage of the mask's shorter side (0 = hard edge);invert: boolean, inverts the mask (keeps the outside, hides the inside).
Conversion notes: JianYing's ellipse / heart / star masks have a fixed aspect ratio, so when width and height do not match, height is honored; diamond has no JianYing counterpart, so that clip's mask is skipped while its other fields convert as usual; when a clip carries both border_radius and clip_mask, only clip_mask is applied in JianYing (a segment holds a single mask); a material without video_size cannot be converted and the mask is skipped.
{
"clip_id": "c1", "material": "F100",
"clip_st": 0.0, "clip_ed": 4.0, "track_st": 0.0, "track_ed": 4.0, "duration": 4.0,
"clip_transform": { "alpha": 0.0 },
"clip_keyframes": {
"alpha": [ { "t": 0.0, "v": 0.0 }, { "t": 1.0, "v": 1.0 } ],
"position_y": [ { "t": 0.0, "v": 270 }, { "t": 1.0, "v": 0 } ]
}
}
The example above is a "fade in + slide up from 270px below": the exported JianYing clip carries 4 keyframes that remain editable inside JianYing.
struct_meta object
| Field | Type | Required | Description |
|---|---|---|---|
nle_draft_dir | string | No | Absolute path to the JianYing / CapCut draft folder. The legacy name capcut_draft_path is still accepted as an alias |
client_visual_elements | object | No | Mirror of client-side overlay elements such as subtitles. Subtitle (text) elements are assembled into a text track inside the JianYing draft — selectable and editable in JianYing. See "Subtitle text track" below |
⚠️ What
nle_draft_diractually is: it is the absolute path of the draft folder where the JianYing / CapCut draft should land on disk. JianYing / CapCut recognize a draft by the pair ofdraft_content.json+draft_meta_info.jsonsitting in that folder. If you omit this path, the endpoint only producesdraft_content.json(the content file); withoutdraft_meta_info.json(the meta file) the editor may fail to open the draft. So to open the finished draft in JianYing / CapCut, always passnle_draft_dir.
Subtitle text track (struct_meta.client_visual_elements)
When this field is present, its subtitle elements are assembled into a text track in the JianYing draft, layered above every video track. In JianYing you can select them, edit the wording, and keep adjusting the styling; they arrive as real subtitles (usable with JianYing's bulk subtitle panel), and line wrapping is left to JianYing.
Only JianYing carries the subtitle text track. Every other output format skips it, for different reasons:
| Format | Carries subtitles | Reason |
|---|---|---|
jianying | ✅ Yes | — |
capcut | ❌ No | Target library limitation (no shadow API, required CJK font missing from its font table) |
xml (Premiere) | ❌ No | This endpoint's Premiere output path has no text vocabulary yet; may be added later |
fcpxml | ❌ No | Same as above, and titles must reference machine-local template resources |
otio | ❌ No | The format itself has no text/subtitle structure |
⚠️ The time unit must be declared explicitly: the object's
time_unitfield must be"second". With any other value (or none), the endpoint will not assemble a subtitle track — this is deliberate: interpreting the times under the wrong unit yields a draft that is structurally valid but temporally wrong (it opens fine, yet every subtitle sits far past the end of the video).Size limits: at most 200 overlay lanes / 2000 elements / 2 MB. Exceeding any of them returns a parameter error.
Styling follows the parameters as they stand in your client (styles you tweaked by hand carry over). Dimensions JianYing cannot express (e.g. non-uniform glyph scaling) are skipped and recorded rather than faked with a different field. Stickers, graphics and effects do not enter the draft, but their skipped counts are recorded.
beat_track[] particle overlays
beat_track carries HTML animation particle overlay layers. This Project File Export endpoint ignores beat_track — NLE project files do not carry HTML particles. To actually render particles into the picture, use html_animate_render instead. The request body may still include beat_track to keep the gtrk structure complete, but it does not affect this endpoint's output.
project_formats values
There are 6 public output formats:
| Value | Output | Saved as |
|---|---|---|
xml | Premiere / FCP7 XML | .xml |
fcpxml | Final Cut Pro X | .xml |
otio | OpenTimelineIO | .json |
jianying | JianYing draft (produced as a pair automatically) | draft_content.json + draft_meta_info.json |
capcut | CapCut draft (produced as a pair automatically) | draft_content.json + draft_meta_info.json |
gtrk | Tonghe project file (single-index JSON, for import into the Tonghe client) | .gtrk |
ℹ️ Note: JianYing / CapCut drafts require both the content and meta files placed together in the draft folder to be recognized, so selecting
jianying/capcutautomatically produces both.files[].formatin the response still identifies individual files (e.g.jianying_draft/jianying_meta). Compatibility: the legacy fine-grained values (jianying_draft, etc.) are still accepted with their original single-file semantics; new integrations should use the table above.
🆕 Drafts open in "free layer" mode by default: the JianYing / CapCut drafts produced by this endpoint default to free-layer mode, so clip layers can be reordered freely instead of being bound to the traditional main-track-plus-overlay model. Multi-track stacking order is unchanged.
⚠️ Previously exported drafts cannot be switched: JianYing locks the layer mode at import time, and it cannot be changed from the project settings afterwards. If an older draft needs free-layer mode, export it again.
Request Example
The example below shows cutting multiple segments from one source: materials declares a single video source, video_track cuts several segments from the same asset using different clip_st / clip_ed and stitches them together, then layers an audio_track, and specifies project_formats.
curl -X POST https://api.ai-mcn.tv:10000/task/video_project_struct \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"version": "v1",
"video_size": [1920, 1080],
"video_rate": 60,
"duration": 9.0,
"materials": [
{
"id": "F100",
"path": "C:/clips/source.mp4",
"duration": 120.0,
"video_size": [1920, 1080],
"video_rate": 60,
"audio_channel": "stereo"
},
{
"id": "F200",
"path": "C:/clips/bgm.mp3",
"duration": 180.0,
"audio_channel": "stereo"
}
],
"video_track": [
{
"track_index": 0,
"track_size": [1920, 1080],
"muted": false,
"track_timeline": [
{
"clip_id": "c1", "material": "F100",
"clip_st": 10.0, "clip_ed": 13.0,
"track_st": 0.0, "track_ed": 3.0, "duration": 3.0
},
{
"clip_id": "c2", "material": "F100",
"clip_st": 55.0, "clip_ed": 59.0,
"track_st": 3.0, "track_ed": 7.0, "duration": 4.0,
"muted": true
},
{
"clip_id": "c3", "material": "F100",
"clip_st": 88.0, "clip_ed": 90.0,
"track_st": 7.0, "track_ed": 9.0, "duration": 2.0
}
]
}
],
"audio_track": [
{
"track_index": 0,
"volume": 0.8,
"track_timeline": [
{
"clip_id": "a1", "material": "F200",
"clip_st": 0.0, "clip_ed": 9.0,
"track_st": 0.0, "track_ed": 9.0, "duration": 9.0
}
]
}
],
"struct_meta": {
"nle_draft_dir": "C:/Users/Me/AppData/Local/JianyingPro/User Data/Projects/com.lveditor.draft/20260626"
},
"project_formats": ["xml", "gtrk", "jianying"]
}'
Success Example
{
"code": 200,
"msg": "success",
"data": {
"task_id": "537489015178247",
"task_type": "video_project_struct",
"status": "queued"
}
}
Query Task Result
Basic Information
| Item | Value |
|---|---|
| Request Method | GET |
| Request Path | /task/video_project_struct/{task_id} |
| Authentication | Raw API key in the Authorization header |
Response Fields (output_result)
| Field | Type | Description |
|---|---|---|
files | array | List of successfully produced project files |
files[].format | string | Output format: xml / fcpxml / otio / gtrk / jianying_draft / jianying_meta / capcut_draft / capcut_meta |
files[].file_id | string | Output file ID |
files[].download_url | string | Download path |
files[].filename | string | Suggested file name (e.g. draft_content.json; the editor only recognizes it once placed in a draft folder) |
errors | object | Failed formats and reasons (non-empty on partial success) |
warnings | array | Non-blocking warnings; may be empty. A completed task can still have warnings. These are distinct from format-generation failures in errors |
ℹ️ Partial success: each format is generated independently; a failure in one format does not affect the others, and the task is still marked
completedwith the failures recorded undererrors. The task is markedfailedonly when all formats fail.
Missing subtitle content key
If a text element considered for subtitle parsing lacks the params.content key, warnings includes an entry such as:
{"kind": "text_content_key_missing", "count": 2, "total": 10}
count: number of text segments missing the content key. They are skipped as empty text, so the draft can still be generated successfully while those subtitles are absent.total: total number of text segments considered for this subtitle parse, not the number of subtitles ultimately generated.- Action: check the sending client's text-parameter mapping and retain the
params.contentkey. Do not ignore this warning just because the task completed.
An existing but empty content value does not trigger this warning. A format's normal lack of subtitle support does not trigger it either. Successfully carrying subtitles does not produce a separate success notice.
Success Example
{
"code": 200,
"msg": "success",
"data": {
"task_id": "537489015178247",
"status": "completed",
"progress": 100,
"output_result": {
"files": [
{"format": "xml", "file_id": "537489015178248", "download_url": "/download/a1/537489015178248.xml", "filename": "premiere.xml"},
{"format": "gtrk", "file_id": "537489015178249", "download_url": "/download/a2/537489015178249.gtrk", "filename": "project.gtrk"},
{"format": "jianying_draft", "file_id": "537489015178250", "download_url": "/download/a3/537489015178250.json", "filename": "draft_content.json"},
{"format": "jianying_meta", "file_id": "537489015178251", "download_url": "/download/a4/537489015178251.json", "filename": "draft_meta_info.json"}
],
"errors": {}
},
"create_time": "2026-06-01T08:00:00Z",
"update_time": "2026-06-01T08:00:03Z"
}
}
Error Codes
| Code | HTTP Status | Description | Resolution |
|---|---|---|---|
6013 | 400 | Missing required parameter (video_size/video_rate/duration/materials/video_track/audio_track) | Provide the required parameters |
6004 | 400 | A cloud-referenced asset does not exist (an entry without path whose id matches no platform file) | Verify the file_id, or add a path to switch the entry to a local reference |
6016 | 400 | Invalid parameter type or structure (e.g. a material not in the materials list, an illegal value in project_formats) | Check the timeline structure and values |
6502 | 401 | Authentication failed | Check the Authorization header |
6201 | 402 | Quota insufficient | Buy a quota pack or top up |
6202 | 402 | Balance insufficient | Top up in the dashboard |
Limitations
- Structure-only conversion: the server does not read the files referenced by
materials[].path; it only writes the paths into the project files. Make sure those paths are valid in your editing environment. - Particles are not rendered here:
beat_trackis ignored by this endpoint; render HTML particles via html_animate_render. - Per-call billing: billed once per request, regardless of how many formats are produced.
- Draft version compatibility: the generated JianYing / CapCut drafts must be opened with a compatible client version (the draft schema evolves with the app). Place
draft_content.jsonanddraft_meta_info.jsoninto the corresponding draft folder to open and keep editing. - Draft meta:
jianying_meta/capcut_metaare produced only whenstruct_meta.nle_draft_diris provided; without it only the content file is produced and the editor may fail to open the draft.