Agent Flow

Recommended Flow

1. Call get_workspace.
2. Call list_generation_catalog and list_workspace_assets.
3. If the user needs a voice, call recommend_voice.
4. If the user wants a template look, call list_generation_catalog again with section and template_slug, then choose a built-in preset_id or saved custom_reference_inspiration_id.
5. If the user provides reference media, use suggest_reference_template_targets, ask for the target if needed, then call create_reference_inspiration.
6. Call the matching create tool.
7. Poll the matching status tool until the result is completed or failed.
8. Only say the asset is ready when the final answer includes a visible preview, direct URL, or local file path.

Local Or Rendered Media

When the user or agent already has a rendered image, audio file, or MP4:

1. If the file is already reachable over HTTPS, call upload_editor_media_from_url with url (or upload_editor_media with source_url).
2. For a local file above 3 MiB, call prepare_editor_media_upload with filename, content_type, and actual size_bytes. PUT the raw file bytes from the agent machine to the returned upload.url, using upload.headers.
3. After the PUT succeeds, call upload_editor_media_from_url with url set to the returned source_url. Local inline base64 and REST multipart uploads are limited to 3 MiB per file. Remote/direct uploads allow video up to 200 MiB and image/audio up to 50 MiB.
4. Use the returned My Media media.id for publish_media_to_social, add_editor_media, or media-id fields in create_generation.

The hosted MCP server cannot fetch /local/path/file.mp4 or file:// URIs from the client machine. Do not place those strings in media.data; that field is only for base64 bytes or data URLs.

For a prevalidated, playable MP4/WebM render, set preserve_original: true on the import to skip video transcoding. The original codec and container are retained, no thumbnail is generated, and the caller must check playback and destination compatibility. Omit the flag for the default Stream transcoding flow. The upload preparation and PUT do not create a My Media item; the import does. Transfer timeouts remain possible.

Prompt Handling

For template generations, preserve the user's prompt.

Pass it as-is or minimally trim tool-routing words. Do not expand a short request into a full creative brief unless the user asks.

Use built-in presets and saved reference inspirations as internal routing details. Do not expose raw ids unless the user asks for API or debugging details.

Retries

For paid create tools, pass idempotency_key when retrying.

Reuse the same key for the same paid action.

Do not create backup or variant generations unless the user asks for them.