Create and continue
Create a project withPOST /projects. Send more work with POST /projects/{id}/messages, including while the agent is working. Stop it with POST /projects/{id}/stop; send another message to continue.
effort is standard or extended, chosen at creation and fixed for the project. Follow-up messages accept the same creative inputs without effort.
Attach uploaded library files through attachments: [{"asset_id": "ASSET_UUID"}]. Put web links directly in the prompt. Add saved references with template_ids and brand_kit_ids. Choose connections with connectors: [{"id": "CONNECTION_UUID", "actions": ["pages"]}]; action IDs come from List connectors. All selections must be accessible to your credential.
Read the project
GET /projects/{id} returns:
One generation can contain a video and two thumbnails: these are three compositions in one saved version. Use the composition’s
id when exporting; use the generation’s id when saving the whole version as a template.
Messages, generations and exports share turn_id, so you can match work to the turn that produced it. A steering message belongs to the active turn. A later follow-up starts another turn. Historical records may have no recorded turn ID.
limit sets the page size for both messages and generations. Use after_sequence for more messages and cursor for more generations. Use the export cursor with List exports.
Automatic exports
Setexport_formats to automatically export finished compositions when each turn finishes. For example, ["mp4", "png"] exports videos as MP4 and images as PNG.
Follow-up messages inherit the formats. Send a new array to change them, or [] to turn automatic exports off. Turns that only answer a question have nothing to export. An explicit request that cannot produce the requested format returns a failed export.
A completed project can have no exports when none were requested. Exports may still be preparing after the agent finishes.
Export later
UsePOST /projects/{id}/exports at any time after a composition is saved:
media exports a video as MP4 or an image as PNG. Editor exports include the project and its required assets.
A download can be a file or a ZIP containing those files. Check
filename and content_type; format identifies the requested export type.
Download files
Read exports inside Read a project, throughGET /projects/{id}/exports, or individually with GET /projects/{id}/exports/{export_id}. All three return the same export objects.
Each includes composition_ids, generation_id, turn_id, format, status, and download_url. Status is preparing, completed, or failed. A download link is available after completion and expires after one hour; read again to renew it.
stage: waiting means dispatch has not started. Poll until the export is completed or failed.
created_by_you tells you whether your user requested the export. origin is api or app. Later edits and other people’s exports do not change your export’s saved source. Older app bundles may contain several compositions or have no recorded generation link.
Access
API keys are bound to an organization and workspace. Scopes and your current permissions both apply. Project writes requiremotion:sessions:write; reads require motion:sessions:read. Selecting templates, brand kits, assets or connectors also requires their read scopes. Editor exports require Pro or above.