# Welcome to Pletor Pletor is the creative infrastructure for marketing teams. Orchestrate the best AI models, your brand context, and your performance data into production\ pipelines. Then deploy them as apps, run them at scale, or call them from your own tools. {% embed url="" %} ### What you can do with Pletor * **Produce on brand, at volume** — product imagery, static ads, UGC, video. From a single brief to every format a campaign needs. * **Orchestrate the best models in one pipeline** — chain image, video, and text models on one canvas instead of stitching tools by hand. * **Encode your brand, reuse it everywhere** — brand rules, references, and performance data live in one place and shape every run. * **Deploy anywhere** — ship an agent as an app for your team, or call it from your own tools via MCP and API. ### Your path with Pletor Four steps, from first agent to production: 1. **Understand** — how agents, nodes, and credits fit together. → [Key Concepts](/get-started/key-concepts) 2. **Build** — start from a [Template](/build-agents/templates), then [shape your own](/build-agents/agents) in Studio. 3. **Deploy** — turn an agent into [an app](/automate/apps) your whole team runs. 4. **Automate** — run at volume and make agents callable from your own tools. → [MCP](/automate/pletor-mcp) · [API](/automate/api-integrations) ### Who Pletor is for * Marketing & creative teams producing visual content at volume * Agencies standardizing delivery across clients * Teams that want brand and performance context encoded once, reused everywhere # Quickstart Let's get you started! We'll start by setting up your account, then jump straight into generating visuals with Pletor agents. ### Sign up You can create an account directly from [our website](https://pletor.ai/) or [sign up here](https://app.pletor.ai/signup). For the fastest setup, we recommend signing up with Google with your professional email address.
After signing up, you’ll receive an email to verify your address. Once verified, we’ll ask for a few quick details about you, and you’ll be ready to go. ### What's next? Understand Pletor’s [Key Concepts](/get-started/key-concepts): learn how nodes and AI models become agents to power the future of visual marketing. ### Joining as part of an organization? If you’re part of a team or company using Pletor, subscribe to a paid plan to get everyone collaborating under one workspace. ### Keep learning Built your first agent? **Learning** is where you go deeper — guided lessons inside Pletor that take you from first run to production pipelines. → Open **Learning** from [your workspace](https://app.pletor.ai/learning) to level up at your own pace.
# Key concepts A quick introduction to Pletor Before diving deeper into Pletor, let's clarify the foundational concepts that power everything you'll build. ### Agents **Agents are reusable creative systems**. They are designed to handle specific marketing tasks. You can use Agents to ideate and experiment freely with AI or as a scalable recipe. Once you've perfected the formula (the right models, brand context, etc.), it becomes a repeatable system that removes all production constraints.

A few agents built by the Pletor team

### Studio **The Studio is where the magic happens and Agents get built.** Here you can experiment with different nodes, test various AI models, and refine your workflow until it consistently delivers the results you want.

A (very) simple agent in the Studio

### Nodes **Nodes are LEGO blocks for Agents.** Each node performs one specific function: collecting user input or brand context, generating an image or a video, etc. Connect nodes together, and you've built an agent. No coding required. Just drag, drop, and connect.

Common nodes and models

### Models **Models are the AI engines under the hood.** When a node needs to generate an image, write copy, or create a video, it uses an AI model to do the heavy lifting. Different models excel at different things, see AI model library section.

A few model providers available on Pletor

**Ready to see these concepts in action?** Head to the [Studio](broken://pages/g1uXQ3dp6DlnKTLOKjvf) to start building your first custom agent, or explore our [template agents](/build-agents/templates) to see what's possible. # Templates For every use case, there's an template. Templates are pre-built agents for the most common marketing workflows. Clone one, run it as-is, or open it in Studio to make it yours. [Browse all templates in-app](https://app.pletor.ai/templates), or find recommended ones on your **Home** page.
## Find yours #### **By use case** The top row groups templates by what you're making: Product imagery, Static Ads, User-generated content, Brand assets, Automations, Campaign concepts. #### **Browse all** Filter the full gallery by **Level** and **Industry**, **Sort**, or **Search** by name. Look for the **Popular** badge for the most-used agents. ## Template or custom agent? A template is a starting point, not a cage. Run it as-is for fast output, or open it in **Studio** to rewire nodes, swap models, and encode your brand. Every template is a fully editable agent — the difference is only where you start. **Level** tells you how much is happening under the hood before you open it. Once you understand how these template agents work, you'll have the foundation to [build your own agents](/build-agents/agents) for any workflow you can imagine. ## Always evolving We regularly ship new templates as AI capabilities improve and new marketing needs emerge. Check back often: what you see today is just the beginning. # Agents Because your unique context matters. ## When to build your own While our template agents cover the most common marketing workflows, it is likely you will need a more tailored creative achieve your objective. Custom agents are perfect when: * **You need to tweak or personalize a template with your brand context**: add your brand guidelines or specific design requirements to any workflow * **You don't find an agent for your need**: maybe you need carousel ads, video storyboards or product unboxing videos that aren't in our library yet.
## How to create a custom agent Creating your own agent is straightforward: 1. **Click "New agent"** or duplicate an existing one as your starting point 2. **Enter the** [**AI Studio**](/build-agents/studio) - This is where you'll build and customize your agent using our nodes and AI models. 3. **Iterate on your agent** - Connect input nodes with AI nodes, run them, compare models until your agent delivers the results you want. Feel free to explore [Pro Tips](/build-agents/studio/building-tips) to achieve your objectives faster.. 4. **Publish when ready** - Once you're satisfied with your agent, publish it to share it or make it available as an app Ready to build your first agent? Head to the [Studio section](/build-agents/studio) to learn how our visual workflow builder works. # Studio Learn how to build your agents in the AI Studio. The Studio is an infinite canvas to build your agents. Think of it as connecting building blocks to orchestrate your workflow. It's all about dropping Nodes, chaining them, and putting a bit of your own intelligence and context.

Text prompt → AI Image → Aspect Ratio variation

## How nodes work 1. **Nodes are the building blocks** of your agent. Each node performs a specific function: generating images, generating text or prompts, briefing with brand guidelines, etc. You'll find more info on the different node types in the [Nodes](/build-agents/nodes) section. 2. **Connect nodes to create workflows**. Draw connections between nodes to define how data flows through your agent. For example: User Input → AI Image Generation → Upscale Image. 3. **Configure nodes as needed**. Try different models or change parameters to improve your outputs. 4. **Deploy as App**. Once your agent consistently delivers the results you want, make it available to other members of your organization. See [Apps](/automate/apps). # Toolbar The toolbar sits on the left of the Studio and gives you quick access to the most common actions while building agents. ### Add node The orange **+** button opens the node picker. This is how you add building blocks to your agent. The picker is organized into sections to help you navigate capabilities. Use the search bar at the top to find any node by name — this is the fastest way to add nodes when you know what you need.
*** ### Assets Opens the asset gallery where you can browse, search, and manage all the visuals and files generated by your agents. From here you can drag assets directly onto the canvas, preview outputs, or download them. You can also find all the assets generated on Pletor and use them in your work. *** ### Templates Browse pre-built agent templates for common use cases. Templates provide a ready‑made node chain that you can use as‑is, customize to fit your workflow, or treat as learning material. This is the fastest way to get started. *** ### Learn Pletor Opens learning resources directly inside the Studio — tutorials, walkthroughs, and tips to help you get the most out of the platform. Useful when you're building and want guidance without leaving the canvas. *** ### Chat with AI Opens the AI Copilot chat. Describe what you want to build and the Copilot will help you — suggesting nodes, explaining how features work, or helping you troubleshoot your agent. *** ### Other actions #### Change Agent name The top-left corner shows your agent's name. Click it to rename your agent. The dropdown next to the Pletor logo lets you switch between agents or navigate back to the dashboard.
#### Test run Executes your full agent chain from left to right. Each node runs in sequence, passing its output to the next connected node. The button is greyed out until your agent has at least one runnable node connected. You can also run individual nodes by selecting a node and clicking the **Run** button inside its configuration panel, useful for testing one step at a time.
#### Version history Access the work history for this agent. View previous versions, either via autosave or manually saved checkpoints. #### Save in Version History Saves the current state of your agent. Pletor auto-saves as you work, but you can trigger a manual save here when you want to capture a specific checkpoint in your work. A new version of your agent is also created automatically whenever you deploy an App or share it. #### Deploy as App Turn your Agent into an App. See more here: [Apps](/automate/apps). #### Share Share your agent with teammates or make it available publicly. *** ### Working with nodes | Action | How | | ----------------------- | ---------------------------------------------------------------------------------- | | **Add a node** | Click the orange **+** button in the left toolbar, or right-click on the canvas | | **Move a node** | Click and drag it (Select mode) | | **Connect nodes** | Drag from an output port (right edge) to an input port (left edge) on another node | | **Delete a connection** | Click the connection line, then press `Backspace` or `Delete` | | **Delete a node** | Select it, then press `Backspace` or `Delete` | | **Duplicate a node** | `Ctrl/⌘ + D` or `Ctrl/⌘ + C` then `Ctrl/⌘ + V` | | **Open node settings** | Click on the node to expand its configuration panel | | **Group nodes** | Select multiple nodes to organize them into visual groups on the canvas | *** # Navigation How to move around the Studio canvas, manage zoom, and access key actions. ### Canvas controls The bottom toolbar gives you two cursor modes and zoom controls. #### Cursor modes
ToolIconWhat it does
Select (default)Arrow cursorClick to select nodes, drag to move them, click + drag on empty canvas to box-select
PanHandClick + drag to pan around the canvas without selecting anything
You can switch between these modes using the toggle at the bottom center of the canvas:
#### Zoom The zoom level is shown as a percentage between the − and + buttons at the bottom center.
ActionHow
Zoom inClick +, or Ctrl/⌘ + scroll up, or pinch out on trackpad
Zoom outClick −, or Ctrl/⌘ + scroll down, or pinch in on trackpad
#### Right click Right-click opens a context menu with quick actions. What you get depends on where you click. * **On a node:** run, duplicate, download, group, and more * **On a group**: run group, ungroup, delete * **On empty canvas: a**dd nodes
### Keyboard shortcuts | Shortcut | Action | | -------------------- | ------------------------------------------- | | `Ctrl/⌘ + C` | Copy selected nodes | | `Ctrl/⌘ + V` | Paste nodes (or paste media from clipboard) | | `Ctrl/⌘ + D` | Duplicate selected nodes | | `Ctrl/⌘ + Z` | Undo | | `Ctrl/⌘ + Shift + Z` | Redo | {% hint style="info" %} You can paste images and videos directly from your clipboard onto the canvas — Pletor will automatically create the corresponding input node with the pasted content. {% endhint %} # Building tips ### Building approaches We observe that our most successful users follow **one of two building approaches:** * **Input-led**: Start with your available data (e.g., image prompt, brand guidelines) → build forward by adding nodes that transform inputs into marketing assets. * **Output-led**: Start with your desired output (text, image, video) → select the right AI node → work backwards to determine what inputs you need.

Building a fashion photo agent in one minute

Below are some additional **best practices** for building custom Pletor agents: * **Start simple**: Begin with a basic workflow and add complexity gradually. * **Test as you build**: Run individual nodes and group of nodes frequently to test them in isolation and catch issues early. * **Use AI text nodes with custom instructions** to: * enhance prompts * process multiple inputs at the same time (e.g., user prompt + brand context) * stabilize outputs' quality that will serve as inputs to other nodes * Use tools like [Prompt Cowboy](https://promptcowboy.ai/) to generate **custom instructions** in a few seconds. * **Iterate on models and configuration**. Adjust node settings, try different connections, and refine your workflow until you get the results you want. The AI Studio makes experimentation fast and visual.

Playing with configurations and models

### Organizing your canvas As agents grow in complexity, a well-organized canvas saves time and prevents mistakes. #### Sticky Notes Use Sticky Note nodes to document your workflow directly on the canvas. They don't affect execution — they're purely for communication. Good uses for Sticky Notes: * Explain **why** a node chain is structured a certain way * Leave instructions for teammates who'll edit the agent * Mark sections that are work-in-progress or need review * Document which models or settings work best after testing #### Name your nodes Click any node's title to rename it. Descriptive names like "Cinematic Video" or "Fixed Prompt Instruction" make your flow readable at a glance — much better than a row of generic "Generate Image" labels. #### Group related nodes Select multiple nodes and group them to create labeled sections on your canvas (e.g., "Brand Inputs," "Video Production"). Groups make complex agents scannable, help teammates understand the flow without clicking into every node, and can be run as self‑contained steps.
# Loop mode Scale your workflows with Loop mode. Loop Mode lets you process multiple inputs through the same node chain automatically — one at a time. Instead of generating a single output per run, the node iterates over each input and produces a separate output for each one. It's the fastest way to scale your workflows without duplicating nodes or running your agent manually for every asset. *** ### How it works When Loop Mode is **off**, a node takes all its connected inputs and produces one output per run. When Loop Mode is **on**, the node processes each input individually through the downstream chain. If you connect 10 images, the node runs 10 times — once per image — and produces 10 separate outputs. You'll find the **Loop Mode** toggle in the top-right corner of the Inputs section in any node's configuration panel.
*** ### Where Loop Mode appears Loop Mode is available on most nodes that accept inputs, including: * **AI Image nodes** (Generate Image, Edit Image, etc.) * **AI Video nodes** (Generate Video, etc.) * **Import from Google Drive** * **Text Assistants** When connected inputs have Loop Mode enabled, they show a **Loop** badge next to the input pill in the configuration panel.
*** ### Per-input loop control When a node has multiple inputs, you can enable Loop Mode independently on each one. This gives you fine-grained control over which inputs iterate and which stay fixed. **Example:** In a Generate Image node with Loop Mode on: * **Text prompt** → connected to a fixed prompt instruction (Loop off) — the same prompt is used for every iteration. * **Reference image(s)** → connected to Import from Google Drive (Loop on) — each imported image is processed one at a time. This means: one prompt × N images = N outputs, each using a different reference image but the same instructions. *** ### Common Loop Mode patterns #### Batch product shots from Google Drive Import product photos from a Drive folder, generate a styled variation of each one, and export back to Drive. **Flow:** Text Prompt (folder URL) → Import from Google Drive → Text Prompt (fixed instructions) → **Generate Image** (Loop Mode on for reference images) → Export to Google Drive Each product photo gets its own generation. The fixed prompt applies the same styling to every image. [→ Try this template](https://app.pletor.ai/flow/346c73f3-08ff-46eb-bc7e-3dc523977f33) (fashion) [→ Try this template](https://app.pletor.ai/flow/c5bef676-5137-4145-b397-52004cc45f51) (furniture) #### Multiple headline variations Use a Text Assistant to generate several headline options, split them, and generate an image for each one. **Flow:** Text Prompt (brief) → Text Assistant (generate 5 headlines) → Split Text → **Generate Image** (Loop Mode on for text prompt) Each headline becomes a separate image generation. #### Multi-format adaptation Take one source image and generate it in multiple aspect ratios for different platforms. **Flow:** Upload Image → **Change Aspect Ratio** (Loop Mode on) with multiple target ratios One input, multiple format outputs — ready for Instagram, Stories, and landscape. *** ### Cost and performance Each loop iteration counts as a separate run and consumes credits independently. The **run cost** shown in the configuration panel reflects the cost per iteration — multiply by the number of inputs to estimate total cost. Loop Mode processes inputs sequentially (one at a time), not in parallel. Larger batches take proportionally longer. *** ### Tips * **Start with a small batch.** Test your Loop Mode workflow with 2-3 inputs first to make sure the outputs look right before running it on a full folder of assets. * **Combine with Google Drive for end-to-end automation.** Import → Loop → Export is the core pattern for batch processing at scale. * **Use fixed prompts alongside looped inputs.** The power of Loop Mode is applying the same instructions to many different assets — keep your prompt constant and let the inputs vary. * **Check the run cost before launching large batches.** A 15-credit node × 50 looped inputs = 750 credits per run. # Sharing # Nodes Nodes are the building blocks of every agent in Pletor. Each node performs one job — generating an image, collecting a text input, applying brand guidelines, routing logic — and you chain them together on the canvas to build complete workflows.
### How nodes work Every node has **inputs** (left side) and **outputs** (right side). You connect them by dragging from one node's output to another node's input. Data flows left to right through your chain. A simple example: **Text Prompt** → **Generate Image** → **Upscale Image** takes a user's instructions, generates a visual, and enhances its resolution — all in one run. Nodes accept different data types depending on their function: text, images, video, audio, or files. The canvas will only let you connect compatible ports.
*** ### Node categories When you open the node picker in the Studio, nodes are organized into three categories. #### Use AI The creative engines — nodes that generate or transform content using AI models. * **AI nodes** — Generate and edit images, video, and audio with AI. Includes Generate Image, Generate Video, Lipsync, Subtitles, Speech, and more. * **Text Assistants** — Run LLMs to generate, rewrite, analyze, or transform text using pre-built or custom instructions. #### Provide Context Nodes that feed information into your workflow. * **Input nodes** — Text Prompt, Upload Image, Upload Video, Upload Audio, Upload File. Collect data from users or provide static assets. * **Brand nodes** — Brand Context, Visual References, Brand Guidelines, Brand Voice, Brand Docs. Keep every output on-brand. * **Sticky Note** — Add notes and documentation directly on the canvas. Doesn't affect execution. #### Automate Nodes that add logic, control flow, and external connections. * **Logic nodes** — Composer, Split Text & List Selector, Prompt Concatenator, Human Review, Merge Videos, Rename Asset, Router. Control how data moves through your agent. * **Integration nodes** — Google Drive, Meta Ads, TikTok, Instagram, LinkedIn. Pull data in or push outputs out. *** ### Tips * **Start simple.** Build a 2-3 node chain first, test it, then add complexity. A Text Prompt → Generate Image → Upscale workflow teaches you the basics in minutes. * **Test individual nodes** before running the full chain. Click any node and hit Run to see its output in isolation. * **Use Text Assistants as glue.** Place these nodes between your inputs and generation nodes to enhance prompts, enforce formatting, or combine multiple inputs into a single instruction. # AI nodes AI nodes are the creative engines of your agent. They generate and transform content using state-of-the-art AI models for images, video, and audio. You'll find these nodes under **Use AI** in the [node picker](/build-agents/studio/toolbar). ### Basics The most important AI nodes are the following: * **Generate text**: Creates written content using large language models (LLMs). Perfect for prompt enhancing, media or written material analysis, ad copy, or any text-based marketing content. * **Generate image**: Produces visual content using the best image generation models available. * **Generate video**: Creates video content using the best video models available. * **Generate audio**: Generates voices or sound design with AI. Others are detailed here: [AI Image](/build-agents/nodes/ai-nodes/ai-image), [AI Video](/build-agents/nodes/ai-nodes/ai-video), [AI Audio](/build-agents/nodes/ai-nodes/ai-audio), [Text Assistants](/build-agents/nodes/ai-nodes/text-assistants). # AI Image Generate, edit, and transform images. These nodes cover everything from text-to-image generation to post-processing operations like upscaling and background removal. ### Available image nodes | Node | What it does | Key inputs | | ----------------------- | --------------------------------------------------------------------- | --------------------------------------------- | | **Generate image** | Create images from text prompts | Text prompt, optional reference images | | **Edit image** | Modify images using text instructions | Source image + edit prompt | | **Upscale image** | Increase image resolution while preserving detail | Source image | | **Composer** | Layer text, images, graphics, and logos into a single composed visual | Multiple images/text layers + layout settings | | **Reframe image** | Resize and reframe images to different dimensions | Source image + target aspect ratio | | **Change camera angle** | Adjust the camera angle of an image using 3D controls | Source image + angle parameters | | **Remove background** | Remove the background from an image, outputting a transparent PNG | Source image | | **Vectorize image** | Convert a raster image to SVG vector format | Source image | #### Tips for AI Image nodes * **Connect Brand System nodes** (Visual References, Brand Guidelines) to your Generate Image node to keep outputs on-brand. * **Chain nodes for production workflows**: Generate Image → Remove Background → Composer is a common pattern for creating product shots with custom backgrounds. * **Use Edit Image for iterations**: instead of regenerating from scratch, edit an existing image to fix specific areas while keeping what works. # AI Video Generate, edit, and process videos. These nodes handle everything from text-to-video generation to post-production tasks like subtitling, upscaling, and background removal. ### Available video nodes | Node | What it does | Key inputs | | --------------------------- | -------------------------------------------------------------- | --------------------------------------- | | **Generate video** | Create videos from text prompts or images | Text prompt, optional first frame image | | **Generate lipsync** | Make characters speak by syncing lip movements to audio | Source video/image + audio/text | | **Edit video** | Modify videos using text instructions | Source video + edit prompt | | **Upscale video** | Increase video resolution | Source video | | **Composer** | Layer text, images, graphics, and video into a composed output | Multiple media layers + layout settings | | **Trim video** | Trim or speed up a video | Source video | | **Reframe video** | Reframe or resize a video to a different aspect ratio. | Source video + target aspect ratio. | | **Remove video background** | Remove the background from a video | Source video | | **Add video subtitles** | Generate and burn subtitles into a video | Source video | | **Extract video frame** | Pull a specific frame from a video as a still image | Source video + frame selection | | **Merge videos** | Combine multiple video clips into one seamless video | Two or more source videos | | **Merge audio & video** | Sync an audio track onto a video | Source video + source audio | | **Remove audio** | Strip the audio track from a video | Source video | #### Tips for AI Video nodes * **Image-to-video is often better than text-to-video**: generate a still image first with Generate Image, then animate it with Generate Video. You get much more control over the visual. * **Extract Video Frame** is useful as a bridge — pull a frame from a video to use as input for image editing or as a reference for generating new content. * **Lipsync works with both video and still images**: you can animate a static portrait photo into a speaking character. # AI Audio Generate speech, sound effects, and lip-synced content using AI audio models. ### Available audio nodes | Node | What it does | Key inputs | | --------------------- | ------------------------------------------------------------ | -------------------------------- | | **Generate audio** | Create audio from a text prompt, from voices to sound design | Audio description | | **Generate speech** | Convert text to natural-sounding speech | Text + voice selection | | **Generate music** | Generate music from a text prompt | Music description | | **Add sound effects** | Generate and add AI sound effects to videos | Source video + sound description | | **Voice changer** | Transform a voice while keeping the original speech | Source audio + voice selection | | **Extract audio** | Get an audio file from a video | Source video | | **Transcribe** | Convert speech into written text | Source audio or video | | **Isolate sound** | Separate a target sound from the rest | Source audio + sound to isolate | #### Tips for AI Audio nodes * **Custom voices (contact us)**: upload your own voice samples to create a consistent brand voice across all your audio content. * **Chain speech → lipsync**: Generate AI Speech to create a voiceover, then feed it into Generate Lipsync to animate a character delivering the script. # Text Assistants Run Large Language Models (LLMs) to generate, rewrite, analyze, or transform text — without writing prompts from scratch. While "Generate Text" nodes come with empty instructions, Text Assistants are pre-built expert prompts paired with powerful LLMs. Instead of engineering prompts yourself, you select an assistant, add your own context, and get production-ready text outputs. ### How it works 1. **Add a Text Assistant node** from the node picker (under Use AI → Text Assistants). 2. **Choose an assistant** — each one is optimized for a specific task (prompt enhancement, ad copy, content analysis, etc.). 3. **Connect inputs** — feed in text, brand context, or other data from upstream nodes. 4. **Configure** — add custom instructions to tailor the assistant's behavior to your use case. 5. **Run** — the assistant processes your inputs through the selected LLM and outputs text. ### What you can do Text Assistants handle a wide range of text tasks within your workflows: * **Enhance prompts** — improve a rough user prompt before it reaches an image or video generation node. * **Generate copy** — write ad copy, social captions, product descriptions, or email content. * **Analyze content** — process uploaded documents, summarize information, or extract key data. * **Transform text** — reformat, translate, or adapt content for different channels or audiences. * **Combine inputs** — merge multiple inputs (user prompt + brand context + reference data) into a single, structured instruction for downstream nodes. ### How to use Assistants {% embed url="" %} ### Tips * **Use Text Assistants as glue between nodes.** Place one between your input and your generation node to process, enhance, or restructure data before it reaches the AI model. * **Refine them to fit your context**. Tweak instructions, connect Brand Voice and Brand Context nodes to ensure the assistant writes in your brand's tone and style. * **Stack multiple assistants** when you need multi-step text processing — e.g., one to analyze a brief, another to write the prompt. * **Try different models** for the same task. Balanced models are fast and cheap for simple transformations; advanced models handle nuanced creative writing better. Check the Text models guide for recommendations. # Input nodes User inputs shape what the AI creates. Input nodes are the starting point for most agents. They define what information users provide when running your agent — text instructions, reference images, video files, audio clips, or documents.
*** ### Available input nodes
NodeWhat it collectsAccepted formatsUse case
Text PromptWritten instructions or briefs from usersFree textCampaign briefs, creative directions, product descriptions, any text-based input
Upload ImageOne or more reference imagesCommon image formats (JPG, PNG, WebP, etc.)Product photos, style references, visual inspiration, logos
Upload VideoVideo files for processing or referenceCommon video formats (MP4, MOV, etc.)Source footage for editing, reference clips, content to transform
Upload AudioAudio filesMP3Custom voiceovers, sound references, audio to sync with video
Upload FileDocuments or data filesPDF, CSV, JSON, TXTBrand books, data sheets, marketing playbooks, product catalogs
*** ### Tips * **Keep inputs minimal.** Every input is friction for the end user. Only ask for what the agent actually needs. * **Combine inputs with Text Assistants.** Place a Text Assistant node after your inputs to merge and structure multiple inputs into a single clean prompt before it hits your AI generation node. * **Label your inputs clearly.** Rename input nodes to describe what the user should provide (e.g., "Product photo" instead of "Upload Image"). * **Use Upload File for rich context.** A PDF brand book gives the AI far more context than a short text prompt — connect it to a Text Assistant to extract the relevant information. # Brand nodes Tailor Pletor agents to your brand. Your brand has a specific look, feel, and voice, and AI-generated content needs to reflect that consistently. Brand system nodes are here to reflect your brand's DNA directly into your agents. Brand nodes inject your brand's identity directly into your agent workflows. When connected to AI nodes, they ensure every generated asset stays consistent with your visual identity, tone of voice, and creative guidelines. You'll find these nodes under **Provide Context → Brand System** in the node picker.
*** ### Available brand nodes
NodeWhat it providesInput typeBest for
Brand ContextCompany name, description, value proposition, target audience, and positioningText fieldsGiving AI models essential context about who you are and what you do
Visual ReferencesBrand assets, product images, or style examples that AI models can referenceImage uploadsMaintaining visual consistency across generated images and videos
Brand GuidelinesDo's and don'ts for creatives and design — your brand's visual and creative rulesTextEnforcing specific style choices, color usage, layout rules, and creative direction
Brand VoiceSample copy, messaging frameworks, and writing examplesTextMatching your brand's communication style in generated text, captions, and scripts
Brand DocsComprehensive brand documentation uploaded as filesPDF, CSV, JSON, TXTSharing complete brand books, marketing playbooks, or detailed product sheets without reformatting
*** ### Tips * **Show, don't tell.** Visual References and Brand Voice work better than abstract descriptions. Upload real examples of your brand's look and writing style rather than trying to describe them in text. * **Layer multiple brand nodes.** Use Brand Context + Visual References + Brand Guidelines together for the strongest brand consistency. Each one adds a different dimension of context. Use one node per set of cohesive visual references. * **Brand nodes automatically serve as context when in App mode**. See more [Apps](/automate/apps). # Logic nodes Automation and logic nodes control how data flows through your agent. They let you split, merge, route, review, and transform content between your AI and input nodes. You'll find these nodes under **Automate → Logic** in the node picker. *** ### Available logic nodes | Node | What it does | Key inputs | Key outputs | | --------------------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------ | --------------------------------------------- | | [**Split Text**](/build-agents/nodes/logic-nodes/split-text-and-list-selector) | Break a text string into separate parts based on a delimiter | Text input + delimiter character | Multiple text outputs (one per split segment) | | [**List Selector**](/build-agents/nodes/logic-nodes/split-text-and-list-selector) | Pick a specific item from a list of text outputs | List of text items + selection index | Single text output | | [**Prompt Concatenator**](/build-agents/nodes/logic-nodes/prompt-concatenator) | Merge multiple text inputs into a single combined prompt | Two or more text inputs | Single merged text output | | [**Human Review**](/build-agents/nodes/logic-nodes/human-review) | Pause the workflow for manual quality control before continuing | Any asset (image, video, text) | Approved or rejected asset | | [**Rename Asset**](/build-agents/nodes/logic-nodes/rename-asset) | Set custom filenames for generated assets | Asset + naming pattern | Same asset with new filename | | **Router** | Reuse any node's output anywhere else in your flow | Any node output | Routed output to multiple downstream nodes | *** ### Split Text & List Selector These two nodes work together for workflows that need to process multiple items from a single text input. **Split Text** takes a block of text and breaks it into parts using a delimiter (like a comma, newline, or custom separator). Each part becomes a separate output that can feed into parallel downstream nodes. **List Selector** picks one specific item from a list by index. Use it after Split Text when you only need one of the split outputs, or to select from any list-type output. **Example flow:** A Text Assistant generates 5 ad headline variations separated by newlines → Split Text breaks them into 5 separate strings → List Selector picks headline #3 → Generate Image uses it as the prompt. See more: [Split text & List selector](/build-agents/nodes/logic-nodes/split-text-and-list-selector) *** ### Prompt Concatenator Merges multiple text inputs into a single prompt. This is useful when you need to combine outputs from different branches of your workflow — like merging a user prompt with brand guidelines and a style description — before feeding them into a generation node. Unlike a Text Assistant (which uses an LLM to intelligently process inputs), the Prompt Concatenator is a simple mechanical join. It's faster, costs no credits, and is predictable — but it won't rephrase or restructure the text. See more: [Prompt concatenator](/build-agents/nodes/logic-nodes/prompt-concatenator) *** ### Human Review Inserts a manual checkpoint into your workflow. When the agent reaches a Human Review node, it pauses and waits for a human to approve or reject the output before continuing. This is essential for production workflows where quality control matters — ad campaigns, client-facing content, or anything where you need a human eye before publishing. See more: [Human review](/build-agents/nodes/logic-nodes/human-review) *** ### Rename Asset Sets custom filenames for your generated assets. Useful when you need organized, predictable file names — especially for workflows that output multiple assets or integrate with external systems like Google Drive. Supports dynamic naming patterns using variables from your workflow (e.g., combining brand name + asset type + date). See more: [Rename asset](/build-agents/nodes/logic-nodes/rename-asset)
*** ### Router The Router lets you reuse any node's output at multiple points in your flow without duplicating the node. Connect a Router to a node's output, then route that output to as many downstream nodes as you need. This keeps your canvas clean and avoids redundant processing — the source node only runs once, but its output is available everywhere the Router connects to.
*** # Split text & List selector Divide a single text into several branches for parallel generations and high-precision storytelling.. ### Split text The Split node takes one text input and breaks it into distinct parts based on a delimiter you define. Each segment then flows through downstream nodes individually. ### List node Display and select from multiple items to create workflow branches. The List node receives multiple text items and presents them as a selectable list. You manually choose which item to process further, giving you control over workflow direction without regenerating content. ### When to use them * **Batch image/video generation**: Split a single AI Text output (e.g., brief) containing multiple prompts into separate prompts, each feeding its own image or video generation node. * **Variation/branch workflows**: Generate multiple prompts once, then branch into separate generation paths based on your selections. For example, run the same base concept through multiple creative directions at once. * **Processing structured content**: Break apart lists, CSV data, or any formatted text into individual items. ### How to use them {% embed url="" %} You can have a look at [this template agent](https://api.pletor.ai/s/f4b54615-b7f3-444e-a7be-34f5a9e32534) to start building with these nodes. ### When to use List vs. Human Review node * **List node**: Choose between multiple different text options generated in the same run. * **Control node**: Pause to review and/or edit/refine output(s) before continuing. # Prompt concatenator Combine multiple text inputs into a single prompt. The Concatenate node merges text from different sources (user prompts, brand guidelines, AI text outputs) into one ordered prompt that feeds into downstream AI generation nodes. ### When to use it * **Standardizing prompt structure**: Ensure every generation follows the same format (e.g., subject first, then style, then technical specs). * **Building complex prompts from multiple sources**: Pull together outputs from several AI Text nodes into one generation-ready prompt. * **Combining user input with brand context**: Merge a creative brief with your brand guidelines into a single, structured prompt. * **Batch workflows**: Process multiple prompt variations in loop mode. ### How it works 1. **Connect your text sources**: Link any nodes that output text (prompts, brand context, AI text) outputs. 2. **Set the order**: Arrange inputs in the sequence you want them to appear in the final prompt. 3. **Done!** {% embed url="" %} You can have a look at [this template agent](https://api.pletor.ai/s/f4b54615-b7f3-444e-a7be-34f5a9e32534) to start building with this node. # Human review Add human decision points when it matters, control AI output quality. Human review nodes pause an agent's steps to let users review, choose between options, or make refinements before continuing. ### How it works When your agent reaches a Human review node during execution in [App mode](/automate/apps), it stops and asks for human intervention. The user can review what's been generated so far, regenerate if needed, or refine inputs before the agent continues its job. This is especially valuable when you want users to have choice and control over the creative process rather than fully automated generation.
#### Adding it in Studio Drop a Human review node anywhere in your workflow where you want execution to pause for a human decision. It accepts the output of the upstream node as its input and passes the selected (or refined) result to the downstream node once the user continues. The node works with **any modality**. It can pause on images, videos, text, or any other asset type your workflow produces, so the review step adapts to whatever the preceding node generates.
#### Use cases * **Pick the best option.** Generate several variations and let the user choose their favorite before committing to a more expensive downstream step, such as selecting a key visual before generating a video from it. * **Discard what doesn't work.** Let users drag unwanted results out of the selection so only the kept assets flow to the next step. * **Review and refine before continuing.** Give users a checkpoint to edit or regenerate an asset, so quality is confirmed at a human gate rather than after the full run completes. * **Control cost on heavy workflows.** Place a review gate before resource-intensive steps (video generation, large batches) so credits are only spent on approved inputs. # Rename asset Sets custom filenames for your generated assets. Useful when you need organized, predictable file names, especially for workflows that output multiple assets or integrate with external systems. Supports dynamic naming patterns built from variables in your workflow (for example, combining brand name, asset type, and date).
### How it works #### Inputs **Assets to rename** — the asset(s) the node will rename, pulled from an upstream node (e.g. an AI Image output). **Naming parts** *(optional)* — other workflow values you want to reference inside the filename, such as an uploaded or reference image. Adding them here makes them available to drop into the naming convention. #### Naming convention Define the filename as a pattern that mixes static text with dynamic variables. Type any fixed text directly (e.g. `t-shirt_`) and insert variables from your naming parts (type "@") to build the rest. A live preview shows the resulting filename and asset before you run the node, so you can confirm the pattern is correct:

Asset renaming 1o1

Variables can be trimmed to a portion of their value using a modifier (e.g. `last 5` keeps the last 5 characters of the source name), which keeps filenames clean when the source value is long.
# Composer Compose elements exactly as needed, for maximum control and consistency. The Composer is your layout engine. It lets you layer multiple elements — images, text overlays, logos, graphics — into a single composed visual, similar to basic design tools. Common use cases include placing a logo on a generated image, adding text overlays to product shots, or assembling multiple generated elements into a final ad creative. The Composer supports both image and video output. Configure layer positions, sizes, and ordering directly in the node's visual editor. This unlocks workflows that were impossible before: * **Localize 20 ads in 20 languages** without rebuilding layouts manually * **A/B test 50 headline variations** without touching a design tool * **Generate seasonal campaign assets on autopilot** ### Quickstart (2 minutes) {% embed url="" %} Think of it as having a design canvas directly inside your agent where you can arrange, layer, and finalize your creatives: * Generate all elements through your agent * Connect them as inputs for the Composer node * Set up your rules and guardrails (layout, typography) * Run the node, let the Composer do its job * Download the finished creatives ### When to use the Composer Use the Composer node when your agent generates multiple elements that need to be combined into a final asset: * **Ad creative production** - Combine product shots, headlines, logos, and CTAs into finished ad formats * **Asset localization** - Create the same creative in multiple languages without rebuilding layouts manually * **Social media templates** - Assemble branded posts with consistent layouts across platforms * **A/B test variations** - Generate dozens of ad variants by swapping elements without manual composition * **Multi-element campaigns** - Bring together background images, product photos, text overlays, and branding ### Timelines
Use timelines in the Composer when your final asset is a video assembled from multiple timed elements: * **Hook testing** - Keep the b-roll, captions, and sound, swap the hook layer to produce variants * **Catalog videos** - One timeline structure runs across every product in your catalog * **Localization** - Swap captions and voiceover per market, layout and pacing hold * **UGC assembly** - Combine hook, b-roll, captions, and sound into one edit {% embed url="" %} A demo agent is [available here](https://api.pletor.ai/s/68e0ac4a-74a2-4ea9-81c6-ef465153a8e7). # Google Drive The Google Drive nodes let your agents interact with files stored in Google Drive — both reading files as inputs and writing generated outputs back to Drive. ### Available nodes | Node | What it does | | ---------------------------- | --------------------------------------------------------------------------------------------------- | | **Import from Google Drive** | Search for and retrieve files from Google Drive to use as inputs in your workflow | | **Export to Google Drive** | Push generated assets (images, videos, documents) from your agent directly to a Google Drive folder | This is especially useful for **automated workflows** where you want generated assets to land in a shared folder automatically, or where source materials live in Drive and need to flow into your agent without manual upload. ### Example workflow: batch product image generation This workflow imports product photos from Google Drive, generates AI variations for each one, and exports the results back to Drive — fully automated. **Flow:** Text Prompt (input folder URL) → **Import from Google Drive** (Loop Mode on) → Text Prompt (fixed prompt instructions) → **Generate Image** → Text Prompt (output folder URL) → **Export to Google Drive** [→ Try this template agent](https://app.pletor.ai/flow/346c73f3-08ff-46eb-bc7e-3dc523977f33)
### Node configuration #### Connecting Google Drive Before using Google Drive nodes, you need to connect your Google account: 1. Add an **Import from Google Drive** or **Export to Google Drive** node to your canvas. 2. Click on the node to open its configuration panel. 3. Click the **Sign in** button with the Google Drive icon. 4. A Google authorization window opens — grant Pletor access to your Drive. 5. Once connected, the panel shows a green **Connected** status with a Sign out option. The connection is secured by [Composio](https://composio.dev/) and persists across sessions — you only need to sign in once.
#### Parameters **Folder URL** The Google Drive folder URL to pull files from or use as a target folder. Connect a Text Prompt node containing the folder link, or paste it directly. **File Type** Filter by file type: Images, Videos, Documents, etc. **Extract** How many files to pull: Last 3 files, Last 5 files, Last 10 files, All files. **Loop Mode** When enabled, the node processes each imported file individually through the downstream chain — one at a time. Essential for batch processing workflows.
#### **Setting up import** 1. Add a **Text Prompt** node and paste your Google Drive folder URL (e.g., `https://drive.google.com/drive/folders/1xsgDSocdr6G...`). 2. Connect the Text Prompt output to the Import node's **Folder URL** input. 3. Set the **File Type** to match your source files (e.g., Images). 4. Set **Extract** to control how many files to pull. 5. Connect the Import node's output to your downstream AI nodes. 6. Hit **Run** — the node pulls files from Drive and passes them through your workflow. #### Setting up Export 1. Add an **Export to Google Drive** node at the end of your workflow. 2. Connect your final AI node's output to the Export node's input. 3. Add a **Text Prompt** node with the destination folder URL and connect it to the Export node's **Folder URL** input. 4. Run your agent — generated files are automatically uploaded to the specified Drive folder. The Export node shows a list of uploaded files with their filenames and sizes once the run completes. *** ### Tips * **Google Drive + Loop Mode is the key to batch processing.** Import a folder of source files, process each one through your AI chain, and export the results — all in one run. * **Use separate Text Prompts for input and output folder URLs.** This keeps your flows clean and makes it easy to change source or destination folders without touching the rest of the chain. * **Make sure your Drive folder is shared or accessible** to the Google account you connected. Private folders that aren't shared with your connected account will return empty results. # Ad & Social nodes (Meta, Tiktok) Extract ads or social content to inform your agent with fresh visual marketing data. The Meta Ads, TikTok, Instagram, and LinkedIn nodes give your agents access to real-time marketing data from major platforms. Use them to pull in competitor ads, trending content, or industry examples as context for your AI nodes. #### Use cases * **Competitor analysis** — pull recent ads from competitors to understand their creative direction, then use that as context for generating your own assets. * **Trend monitoring** — extract trending content formats or themes to inform your creative strategy. * **Style reference** — feed real-world ad examples into your generation nodes as visual or textual inspiration. * **Market research** — gather current campaign examples from your industry to brief your agents with fresh context. ### Available nodes | Node | What it does | Direction | Platform | | --------------------------- | ----------------------------------------------- | ------------ | --------------------------- | | **Meta Ads** | Extract Facebook and Instagram ads and creative | Pull data in | Meta (Facebook / Instagram) | | **TikTok Posts Scraper** | Collect trending content and posts from TikTok | Pull data in | TikTok | | **Instagram Posts Scraper** | Extract posts based on keywords or usernames | Pull data in | Instagram | | **LinkedIn** | Pull B2B ads and industry posts | Pull data in | LinkedIn | #### Best practices * Connect ad/social nodes to a **Text Assistant** with an advanced LLM to analyze and summarize the extracted content before passing it to generation nodes. * **Filter strategically** — focus on the most relevant data rather than pulling everything. * **Combine with Brand System nodes** — use competitor intelligence as reference, but always layer your own brand identity on top. *** ### Tips * **Ad intelligence → Text Assistant → Generate Image** is a powerful chain. Pull competitor ads, have an LLM analyze what makes them effective, then use those insights to generate your own creative. * **Google Drive Upload is ideal for batch workflows.** Combine it with the API to run agents automatically and have outputs land in organized Drive folders. # Apps Build once. Let anyone run it. Apps are the simplest way to put your agents to work. You build the logic in Studio, then deploy it as an app that anyone can use, no technical knowledge needed. Your colleagues, clients, or teammates just open the app, provide their inputs, and get results. You control the quality and consistency; they just prompt and go. ## Why Apps * **Empower your team.** Anyone in your workspace can get the outputs they need, without understanding how the agent works, which models it uses, or how the flow is structured. They just open the app, provide inputs, and get results. * **Guarantee consistency.** The logic, models, and context are baked into the agent. Every run follows the same workflow you designed. * **Speed up your own work.** Even as the agent creator, you don't always want to dive back into Studio. Apps give you a fast lane to run your own agents with a clean, focused interface. * **Remove yourself as a bottleneck** and stop being the person who "runs the AI tool." ## The App experience You can access Apps directly from your home: {% embed url="" %} When someone opens your app, they see a clean interface: a title, a description, and the inputs you've defined. They fill in what's needed (a prompt, an image, or both), hit **Launch**, and the agent does the rest. Results appear directly in the app. Users can review outputs, download what they like, or run the app again with different inputs. ## How to create an App ### Quick tutorial {% embed url="" %} ### Step by step #### 1. Build your agent in Studio Start from scratch or duplicate an existing agent. Connect your nodes, pick your AI models, and test until you're happy with the results. Not sure how Studio works? Check out the [Studio](broken://pages/g1uXQ3dp6DlnKTLOKjvf) section. #### 2. Click "Deploy as app" When your agent is ready, click **Deploy as app** in the top-right corner. This opens the deployment flow.
#### 3. Buid the app form Choose which inputs your app will ask users for. These are pulled from the user prompt nodes in your agent. You can rename them, make some optional and add placeholder text to guide users.
#### 4. Pick your outputs Select which outputs users will see when the app finishes running. You can include all generation nodes or just the ones that matter most.
#### 5. Set app details and visibility Give your app a name and description.
Then choose who can access it: * **Private** — Only you can use it. * **Workspace** — Anyone in your workspace can use it. * **Shared** — Anyone with the link can use it. Hit **Deploy** and your app is live.
### Build a custom form Shape the form around the inputs that matter. Add dropdowns for text, a list of visuals to pick from, so whoever runs the app hands over exactly what your agent needs, nothing more.
A few forms teams are building: a dropdown to ship localized creative in one run, a media slot for product packshots, or preset directions that keep non-technical teammates on-brand. See what it looks like: {% embed url="" %} While defining inputs, click **Configure** on any field to set its options: {% embed url="" %} *** ### Managing your apps Your apps appear in the **Quick create** section on your home screen, under "My Apps." Pletor's pre-built apps are available under "Pletor Apps." To update an app, go back to Studio, make your changes, and redeploy. The app always reflects your latest published version. # Batch Stop running things one at a time. Batch is the production layer of Pletor. A workflow you build in Studio runs one input at a time. Batch takes that same workflow and runs it across every input you have, in a single pass, holding the same standard on the first row and the five-hundredth. {% embed url="" %} The mental model: **build the system once, run it at volume.** You don't rebuild anything for Batch. Any workflow you've already encoded becomes runnable across a whole catalog — from the app, or from an agent through the Pletor MCP. #### 1. Open Batch mode Two ways in: * [**Click here**](https://app.pletor.ai/batch) **or access Batch from your workspace nav** — start a new Batch, then pick the workflow you want to run on. * **From an existing agent in Studio** — switch a workflow you've already built into Batch mode directly. Either way, you're running an existing workflow. Batch is a way to run, not a new thing to build.
#### 2. Prepare your inputs Each row in a Batch is one run of your workflow. * **Drag and drop** a folder of files, or **type inputs free form** to build your set by hand. * **Brand nodes act as context** — your Brand Brain applies to every row, so the whole Batch stays on-brand without per-row setup. * Need the same value everywhere? **Set one input for the whole Batch** instead of repeating it row by row. {% hint style="info" %} **Prepare a Batch from Claude (or any MCP-compatible agent)** The Pletor MCP exposes a `prepare_batch` tool, so an agent can assemble your inputs from data you already have elsewhere — a sheet, an Airtable, a PIM export — and hand the prepared set straight to Batch. You describe what you want batched; the agent builds the rows. No manual entry.\ \ Example: *"Prepare a Batch from my Q2 top performers in Airtable, one row per SKU."* Install the Pletor MCP [here](/automate/pletor-mcp) {% endhint %} #### 3. Run Batch Launch the run. Every row executes your full workflow at once. #### 4. Production starts Once the run begins, Batch produces assets for every row in parallel. You can leave the page; the run continues. #### 5. Review on the same page When assets are ready, you review them where they were produced — no export-and-reimport loop. For each result: * **Keep** what shipped * **Discard** what missed * **Re-run** a row, or **edit** it in place
Review is part of the run, not a separate step. That's what makes a Batch a system instead of a backlog: you run at volume *and* keep control of every output in one place. # Pletor MCP Turn Claude and MCP-compatible agents into your creative workflow orchestrator. Connect Pletor to your favorite AI assistant in one click. Once connected, you can discover workflows, run them, upload assets, and diagnose failures — all from a natural-language conversation. Pletor MCP works with: * **Claude** (Desktop, Web, Code) * **Codex, Cursor**, **VS Code**, and any other MCP-compatible client {% hint style="info" %} **Before you start:** You'll need a Pletor account to use the Pletor MCP. See [Quickstart](/get-started/quickstart). It takes a minute, and you'll connect your AI assistant to it in the next steps. {% endhint %} *** ## Connect in 3 steps {% stepper %} {% step %} ### Open your AI assistant's connector settings * **Claude** → [Customize](https://claude.ai/customize/connectors) → Connectors → *Add custom connector*
* **Cursor / VS Code** → MCP Servers → *Add server* {% endstep %} {% step %} ### Add the Pletor MCP URL Name the connector **Pletor** and paste this URL: ``` https://api.pletor.ai/mcp ``` {% endstep %} {% step %} ### Sign in with your Pletor account Click **Add** → **Connect**. You'll be redirected to log in with your existing Pletor account. Once authorized, the connector is ready. {% endstep %} {% endstepper %} {% hint style="info" %} **Can't find "custom connectors"?** \ \ It's likely your organization does not currently allow for new connectors. Contact your workspace admin. {% endhint %} {% hint style="info" %} **No API keys to manage.** Pletor MCP uses OAuth — your assistant signs in on your behalf and inherits your organization's permissions and credit balance. {% endhint %} *** ## A complete workflow studio inside your AI assistant ### Discover workflows Search your workflow library by name, tag, agent type, or visibility. Ask your assistant *"find a workflow for product photos"* and it will return the right match with its ID, description, and tags — ready to run. ### Run any workflow Trigger a Pletor workflow asynchronously and get a run ID back immediately. Pass inputs as a plain object — your assistant maps natural-language requests onto the workflow's variables. Runs continue in the background while you keep chatting. ### Diagnose failures in one call Ask *"why did my run fail?"* and `diagnose_run` returns a single flat report: the verdict, the failed node, the last successful node, an inputs summary, and a suggested next action. No more chaining three or four tool calls. ### Upload assets from anywhere on the web Drop a public URL — image, video, audio, document — and Pletor ingests it as an asset you can reference in any workflow run. Set visibility to private, shared, or public. ### Browse models and pricing List every available model with its capabilities, generation time, and credit cost. ### Search the docs Get up-to-date guidance straight from `docs.pletor.ai`. Ask *"how do I structure inputs for the image-to-video node?"* and your assistant pulls the relevant excerpt and answers in-context. *** ## From idea to output in one conversation ### Marketing & content teams *"Run my UGC ad workflow on this product photo and give me three variants."*\ Pletor uploads the asset, kicks off the workflow, and surfaces the generated creatives — all in chat. ### E-commerce *"Generate lifestyle shots using the catalog template."*\ Search workflows by tag, run with the right inputs, and get the results without leaving your assistant. ### Agencies & freelancers *"Show me every video workflow my team has built, then run the storyboard one on this brief."*\ Browse, pick, and execute across your whole library in seconds. ### Filmmakers & creators *"Take this character reference and run the cinematic shot workflow with a sunset lighting prompt."*\ Upload, configure, and generate without touching the Pletor UI. *** ## Example prompts ### Discover ``` Find my workflows tagged "video" ``` ``` List public workflows for the standard agent type ``` ``` What image generation models do you support, and which are cheapest? ``` ### Run ``` Run workflow abc-123 with prompt "a cat on a roof at golden hour" ``` ``` Upload https://example.com/product.png and run my "lifestyle shot" workflow with it ``` ``` Generate 3 variants of my UGC ad using this brief: [...] ``` *** ## FAQ
How does Pletor connect to my AI assistant? Pletor exposes an MCP (Model Context Protocol) server at `https://api.pletor.ai/mcp`. Any MCP-compatible client — Claude, Codex, Cursor, VS Code — can connect to it as a remote connector. Auth is handled via OAuth, so you sign in with your Pletor account and never copy-paste keys.
Which assistants are supported? Any client that supports remote MCP servers: Claude (Desktop, Web, Code), Codex with MCPs, Cursor, VS Code, and others as the ecosystem grows.
What can I actually do with it? Nine tools, grouped into four jobs: * **Discover** — `search_workflows`, `list_models`, `search_pletor_docs` * **Inspect** — `get_workflow_definition` * **Run & monitor** — `run_workflow`, `get_flow_run_status`, `diagnose_run`, `get_node_run_result` * **Provide inputs** — `upload_asset`
Do I need an API key? No. Pletor MCP uses OAuth — log in once with your Pletor account and you're connected. Your assistant inherits your organization's workspace, workflows, and credit balance.
How does billing work? Runs and uploads consume credits from your existing Pletor plan, just like the web app. Browsing workflows, inspecting definitions, and searching docs are free. There is no separate MCP subscription.
How long does a run take? Runs are asynchronous. `run_workflow` returns a `flow_run_id` immediately; your assistant polls `diagnose_run` or `get_flow_run_status` until the run reaches `completed`, `failed`, or `canceled`. Duration depends on the workflow — single image nodes finish in seconds, multi-step video workflows can take minutes.
Can I run workflows I built in the Pletor app? Yes. Every workflow in your organization — private, shared, or public — is visible through the MCP. The MCP is a remote control for your existing Pletor workspace, not a separate environment.
Can I upload files from my computer? Today, `upload_asset` takes a public `source_url`. To upload local files, host them on any public URL (S3, Drive, Dropbox link, etc.) and pass that. Direct local-file ingestion is on the roadmap.
Is it secure? Yes. OAuth tokens are scoped to your user and validated against Pletor's auth provider on every request. Tokens never leave your assistant; Pletor only receives the Bearer token the client sends. Asset visibility (`private` / `shared` / `public`) follows the same rules as in the Pletor web app.
# API integrations Embed Pletor directly into your platform or access Pletor programmatically by generating an API key from your account. Want to embed Pletor's agents directly into your product? Our API lets you integrate your agents seamlessly into your platform or workflow. Our API enables: * **Direct agent execution** from your platform * **Custom workflow triggers** based on your application events * **Embedded asset generation** within your user interface ### Availability API keys are available on **paid plans only**. If you're on the free plan, upgrade to unlock API access. ### Generate your API key 1. Go to **Settings → API Keys** ([direct link](https://app.pletor.ai/?settings=api)) 2. Click **Generate API Key** 3. Copy and store your key securely — for security reasons, you won't be able to view it again after closing the dialog ### Quickstart Test your key with a quick request: ```bash curl -X GET "https://api.pletor.ai/api/public/v1/agents" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### Agent skills Skills are reusable building blocks for common Pletor workflows. They follow the Agent Skills specification and can be used with compatible coding assistants. Get the skill here: {% file src="/files/RFoTiz6Rbb2RGFWlvdgU" %} ### Security best practices * Never commit your API key to version control * Don't expose your key in client-side code * Use environment variables in your applications * Rotate your key if you suspect it's been compromised ### Next steps Full API reference [available here](https://docs.pletor.ai/documentation/api-reference). # Connectors Connect your tools once and pull data and assets from where they already live. Connectors link Pletor to the apps your team already works in, so you can bring images, videos, spreadsheet rows, and products into your agents without downloading and re-uploading anything. ## Use cases #### Import files into a Batch In [Batch](/automate/batch), click **Connect** in the header (or **Import** on a column) and pick a source. Choose your Google Drive, Dropbox, or Shopify account, browse your files — with search, sorting, and Drive shortcuts like **My Drive**, **Shared with me**, **Recent**, and **Starred** — then select the files to add.
Imported files are copied into your workspace as assets. Imports run in the background, so large files show a loading state for a moment before they're ready. #### Import rows into a Batch Pick a tables source instead: choose a spreadsheet in Google Sheets, a base and table in Airtable, or your Shopify **Products** table — then preview the rows and import them into your Batch grid. The Shopify Products table gives you each product's title, description, vendor, product type, tags, price, image URL, handle, and status. If a column contains links to images or videos, those links are imported as media assets automatically, ready to use in your runs.
*** ## Add connectors #### Quickstart 1. Open [**Settings**](https://app.pletor.ai/?settings=connectors) and go to **Connectors**. 2. Find the tool you want and click **Connect**. 3. A popup opens on the provider's own sign-in page. Log in and grant access. 4. Once the popup closes, the card shows **Connected** — you're done.
*** #### Available connectors
ConnectorTypeWhat it does
Google DriveFilesPull images & videos straight from your folders.
DropboxFilesPull assets from shared Dropbox folders.
Google SheetsTablesPull rows from your spreadsheets.
AirtableTablesPull records from your Airtable bases.
ShopifyFiles & TablesPull products and media from your Shopify store. More here.
*** #### How connectors work You sign in directly with the provider, so Pletor never sees your password. These connections are handled by [Pipedream](https://pipedream.com/), our secure connection partner, you may see its name in the sign-in window, and your credentials stay with Pipedream rather than being stored by Pletor. Connections are shared at workspace level, with per-user authentication. Access is **read-only**: Pletor imports from your sources and never writes back to them. {% hint style="info" %} If nothing happens when you click **Connect**, check that your browser isn't blocking popups for Pletor. {% endhint %} Imports are **one-time copies**, not live links. Once a file or row is imported, it lives in your workspace as a Pletor asset and won't change if the original does. To pick up changes from the source, just import again. A few practical limits: * Files up to **40 MB** each * Up to **500 rows** per table import * Up to **1,000 media links** imported from a table at once *** #### Disconnecting and reconnecting To disconnect a tool, open **Settings → Connectors** and click **Disconnect** next to the account. Disconnecting takes effect immediately. Everything you've already imported stays in your workspace — disconnecting only stops new imports from that source. {% hint style="info" %} For Google Drive, make sure the Drive checkbox is ticked on Google's consent screen — without it, Pletor can't access your files. {% endhint %}
Does Pletor keep my files or tables in sync with the source? No. Every import is a snapshot taken at that moment. Re-import whenever you want the latest version.
What data can Pletor access? Only what's needed to browse and import: your files and folders for file connectors, and your spreadsheets, bases, or product catalog for table connectors. Shopify access is strictly read-only and limited to products and media — never customer or order data. You can revoke access at any time by disconnecting in Pletor or from the provider's own security settings.
What happens to my flows if I disconnect a tool? Assets and rows you already imported keep working — they're stored in your workspace. Only new imports from that source require reconnecting.
*** ## Connect your Shopify store Shopify asks for couple of extra details before the sign-in popup. > Connecting takes about 10 minutes and requires creating a small custom app in Shopify: this is Shopify's standard way of granting another tool secure, read-only access to your store. #### Step by step * Click **Connect** on the Shopify card. * Enter your shop ID. If your store's URL is `https://my-shop-name.myshopify.com`, your shop ID is `my-shop-name`. (If you don't know your shop ID you can find it here: [Shopify admin → Settings → Domains](https://admin.shopify.com/settings/domains))
* Access the [Shopify Dev Dashboard](https://dev.shopify.com/dashboard/) * **Make sure you are signing to the correct store on Shopify. You can find the current store on the top right of the Shopify Dev Dashboard** * Create the app from the Create app button at the bottom of the page
* In the Create App form, only two fields are necessary to fill in **API access,** copy the following in the correct input: * Scopes: * `read_files,read_products` * Redirect URLs: * [`https://api.pipedream.com/connect/oauth/oa_g5KiBG/callback`](https://api.pipedream.com/connect/oauth/oa_g5KiBG/callback) * The form should look like the following screenshot:
* Then "Release" the app. * Back in Pletor, from the Pipedream when prompted, enter * **Shop ID** — from the 1st Step (e.g. `my-shop-id`) * **Client ID** (from your app's Settings section *see screenshot below*) * **Client Secret**
* You might be prompted twice by Shopify * First to install the app you just created in your shop * Second, to validate the connection to Pletor > Pletor requests **read-only** access to your products and files, it never sees your customers, orders, or payment data, and it never changes anything in your store. #### Troubleshooting
"Access denied for products field" or the preview grid is empty Your app has no access scopes granted ([Shopify docs on access scopes](https://shopify.dev/docs/api/usage/access-scopes)). In the [Dev Dashboard](https://dev.shopify.com/dashboard): 1. Add `read_files,read_products` to the app's access scopes 2. **Release a new app version** 3. In Pletor, **disconnect and reconnect** Shopify All three steps are required — the new scopes are only granted when the app is re-authorized.
I added scopes but nothing changed Scope changes never apply to an existing connection. Release a new app version, then disconnect and reconnect in Pletor so the store re-installs the app with the new permissions.
Shopify says the redirect URI is not authorized / not whitelisted This happens at the very last step, when Shopify checks the callback against your app's configuration. Check these three things in order: 1. **Did you release the app version?** Redirect URL changes only take effect after clicking **Release** in the Dev Dashboard — saving the form is not enough. This is the most common cause. 2. **Is the URL an exact match?** It must be exactly `https://api.pipedream.com/connect/oauth/oa_g5KiBG/callback` — no trailing slash, no extra spaces from copy-paste — and it must be in the **Redirect URLs** field, not the App URL field. 3. **Was the app created in the right place?** It must be created in the [Shopify Dev Dashboard](https://dev.shopify.com/dashboard). Apps created from the Shopify admin under *Settings → Apps → Develop apps* don't support this connection flow. After fixing, release a new version and retry the connection from Pletor.
I can see products but not media (or vice versa) One of the two scopes is missing. Check that bothread\_filesandread\_productsare declared ([scope reference](https://shopify.dev/docs/api/usage/access-scopes)), then release + reconnect.
Nothing happens when I click Connect Your browser is blocking the sign-in popup. Allow popups for app.pletor.ai and try again.
# Zapier/Make/n8n integrations Connect Pletor to your marketing stack. {% hint style="info" %} Currently in Private Beta. {% endhint %} We're working closely with early partners to build integrations with the most popular automation platforms: * [**Zapier**](https://zapier.com/) - Connect Pletor to 5,000+ apps with simple triggers and actions * [**Make**](https://www.make.com/) - Build sophisticated visual workflows that include Pletor agents * [**n8n**](http://n8n.io/) - Create custom automation sequences with our Pletor node [**Book a call with our team**](https://calendly.com/ferdinand-pletor/15-minute-call-with-ferdinand) to discuss how Pletor can fit into your existing automation workflows. # Scheduled agents AI agents working on your behalf, delivering results directly in your inbox. {% hint style="info" %} This feature is only available for Pro & Enterprise users. {% endhint %} Marketing is full of recurring tasks that eat up valuable time: daily social media posts, weekly competitor watch, seasonal campaign visuals, creative brainstorming, etc. These repetitive workflows are perfect candidates for automation. Scheduled agents let you set up these recurring marketing tasks once, then forget about them. Your agents work on your behalf while you focus on strategy and bigger picture initiatives. ### How it works 1. Go to [**your Inbox**](https://app.pletor.ai/inbox).
2. Click "**New Campaign**". 3. **Choose an agent** (pre-built or custom): any published agent can be scheduled. 4. **Set your frequency**: daily or weekly. 5. **Configure inputs** - Provide the parameters your agent needs to work autonomously 6. **All set!**

Example of scheduled Pletor Agents

Your agent will automatically generate fresh content on your schedule. When your scheduled agent completes a task, you'll find the results waiting in your Pletor Inbox. You'll also receive an email notification so you know new assets are ready for review. *** NB: You can always come back to the agent's detailed work afterwards if needed:
# Text models (LLMs) Text models enhance prompts and process context throughout your agents' work. In Pletor, text models' primary role is often behind-the-scenes: refining user inputs, processing brand guidelines, and creating optimized prompts for image and video generation models. They act as intelligent intermediaries that transform raw context into polished instructions for other AI nodes. ## What text model should I pick? The right model depends on your specific workflow requirements. When in doubt, start with a balanced model you already know, and adjust based on your use case and results: | Use case | Recommended models | | ------------------------------------------- | -------------------------------------------- | | Prompt enhancement | Claude Sonnet 4.6, Gemini 3.1 Flash, GPT-5.2 | | Large context or brand guideline processing | Gemini 3.1 Pro, Claude Opus 4.7, GPT-5.5 | | Fast, real-time workflows | Claude Haiku 4.5, Gemini 2.5 Flash Lite | | Resource-conscious workflows | GPT-4.1 Mini | ## Choosing the right model ### Best practices * **Match model to task**: Use faster models for simple prompt crafting, balanced models when you need more creativity. * **Consider context needs**: If your workflow involves extensive brand guidelines or reference materials, choose models with larger context windows. * **Test different models**: The same prompt can yield different styles, experiment to find what works best for your use case. ### Go-to models (for most workflows) Start with these reliable, balanced models that handle the majority of prompt enhancement and context processing tasks: * **Claude Sonnet 4.6** - Smart, efficient, creative model perfect for routine prompt enhancement and context processing in most workflows. * **Gemini 3.0 Flash** - Perfect when speed matters more than complexity or creativity. Ideal for quick prompt generation and real-time workflows. * **GPT-5.2** - Generalist, reliable model performing well across all types of prompt enhancement and simple context processing tasks. ### When working with extensive or multimodal context Select these models for complex briefs and large amounts of context: * **Gemini 3.1 Pro** - Handles complex briefs with extensive brand guidelines material or media creative analysis (including video material). Can process and reference large amounts of context simultaneously. * **Claude Opus 4.7** - Powerful, sophisticated model for complex context processing and advanced prompt optimization requiring deep reasoning. Does not handle videos and takes longer than Sonnet. * **GPT-5.5** - OpenAI's most advanced model with superior reasoning capabilities and enhanced creative output. Similar to Claude Opus. ### When speed is your priority Choose these models when you need fast generation and real-time performance: * **Gemini 2.5 Flash Lite** - Cutting-edge model with enhanced performance and capabilities. Use when you want high-speed agents. * **Claude Haiku 4.5** - A fast, yet great model by Anthropic. * **GPT-4.1 Mini** - Lightweight version optimized for common workflow processing and prompt refinement when resources matter. Delivers poorer results than Gemini 2.0 Flash or GPT 4.1 (at least in our opinion). # Image models We curate the best image generation models specifically for marketing use cases. Rather than chasing every new model release, we focus on proven performers that deliver real value for marketing workflows. Our selection includes models from Google, Seedance, OpenAI, Higgsfield, Ideogram, Runway, Black Forest Labs' Flux; each chosen for their ability to create production-ready marketing assets, not just impressive demos. ## What image model should I pick? #### Go-to models (cover 80% of cases) * [Nano Banana 2](/models/image-models/nano-banana-2) * [GPT Image 2](/models/image-models/gpt-image-2) * [Seedream 5.0 Pro](/models/image-models/seedream-5.0-pro) Works for: product shots, static ads, on-brand assets, character visuals, precise image editing, social media posts & more. Native resolutions from 1K to 4K, with strong aspect-ratio flexibility. #### Use a specialist when... Try the following models when go-to models fall short or you have something specific in mind:
You need...Use:
Fast visual iterations (speed > quality)Nano Banana 2 Lite, Grok Imagine Image
Editorial/inspiration aestheticHiggsfield Soul 2, Recraft v4, Krea 2, Ideogram v4
Strong typography skillsGPT Image 2
More flexible content policiesSeedream 5.0 Pro, Seedream 5.0 Lite
Style-aligned visualsKrea 2, Ideogram v4, Flux 2
Social media postsAny image model + Composer Node
Vector/layout-ready outputRecraft v4
# Nano Banana 2 Lite A better and faster version of Nano Banana. ### Overview Nano Banana 2 Lite is the fastest, most cost-efficient model in the Nano Banana family, built for high-volume and rapid iteration. It replaces [Nano Banana](/models/image-models/nano-banana-+-pro) for most needs. Prefer [Nano Banana 2](/models/image-models/nano-banana-2) or [Pro](/models/image-models/nano-banana-+-pro) for production-grade consistency or high-resolution needs. #### Key updates * **Better consistency vs Nano Banana:** Keeps reliable prompt adherence, strong character consistency, and legible in-image text despite the speed focus. * **Speed:** Text-to-image in <10 seconds. Ideal for fast prototyping, batch drafting, and rapid visual iteration. * **Cost-efficiency:** Same cost as Nano Banana. #### Weaknesses * **1K resolution only**. Use Nano Banana 2 or Pro when you need higher resolutions and complex compositions. * **Fine details:** The smallest text and intricate multi-element scenes are less reliable than on the heavier models. # Nano Banana 2 A cheaper and faster Nano Banana Pro with near-identical quality — plus improved text rendering and world understanding. ## Overview Evolution of [Nano Banana Pro](/models/image-models/nano-banana-+-pro). ### Key Updates * **Near-identical quality at lower cost:** Matches Nano Banana Pro's realism, textures, and proportions at a cheaper price point and faster speed. * **Improved text rendering:** Near-perfect text generation — only the smallest text details are missed. Strong boost for ads, infographics, and text-heavy products. * **Better world understanding:** Requires less guidance and context to produce accurate results. The model infers scene logic more reliably. * **Web search capability:** Can retrieve real-time information to generate up-to-date visuals (e.g., latest sports results on a magazine cover). * **Strong reformatting & infographics:** Handles complex layouts, infographics, and format transformations effectively. * **HEX code support:** Accurately applies specific color codes to elements, on par with Nano Banana Pro. ### Weaknesses * **Camera angle control:** No significant progress vs. previous models, precise camera angle manipulation remains unreliable. * **Complex multi-element compositions:** Combining 5-6 complex products/characters produces near-good but imperfect results. * **Smallest text details:** While text rendering is greatly improved, the very smallest text portions can still be missed. # Nano Banana (+ 🍌 Pro) Revolutionary model that combines generation and editing with exceptional natural language understanding. ## Overview Revolutionary model that combines generation and editing with exceptional natural language understanding. The model is available in two versions: Standard (Nano Banana) & Pro. | Models | Nano Banana | Nano Banana Pro | | ----------------- | --------------------------------------------------------------- | ------------------------------------------------------------- | | Best for | Quick cost-effective edits, image fusion, character consistency | Static ads, layout variants, product renders, high-res assets | | Product rendering | Good | Stellar | | Typography | Basic | Clean, ad-ready | | Resolution | 1080p | Up to 4K (configurable 1K–4K) | ### Strengths for marketers * **Simple, natural language editing**: Make complex edits with simple conversational prompts like "enhance this photo" or "change the background." * **Multi-image fusion**: Seamlessly blend multiple images into cohesive new visuals for product placement and scene creation. * **Character consistency**: Maintain the same person or mascot across different scenes and environments. ### Ideal use cases * **Product placements**: Seamlessly insert products into lifestyle scenes and environments. * **Video ads first frame**: Create compelling opening frames for video ads and social media content. * **Turn photos into ads**: Transform existing photos into polished advertising materials with text and branding. * **Character/mascot campaigns**: Consistent brand characters across multiple marketing materials. * **Multi-step editing**: Complex photo enhancements that would require multiple traditional editing steps. * **Static ad creation** *(Pro):* Generate polished ads with clean typography and multiple layout options. * **Layout variations** *(Pro):* Generate an asset's channel variants in seconds, no rework needed. ### Weaknesses * Variance in image processing - output quality can be inconsistent across different inputs * Sensitivity to text prompts - when used with reference images, requires precise wording to achieve desired results consistently * Limited aspect ratio control based on input images rather than user specification *** ## How to use effectively Nano Banana excels with natural, conversational prompts: ### **Key principles** * Describe the scene, don't list keywords * Use natural language as if talking to a skilled photo editor * Leverage multi-image inputs for fusion and reference * Use preservation instructions: be specific about what you want changed or created (e.g., "identical to the original") * Take advantage of world knowledge for contextual accuracy * If using Auto Aspect Ratios: * driven by text prompt when used as text-to-image * driven by reference(s) images when used as image-to-image ### **Effective prompting patterns**
For image editing `Using the provided image of [subject], please [add/remove/modify] [element] to/from the scene. Ensure the change is [description of how the change should integrate]. Keep [specific elements to preserve] exactly the same.`
For image generation `A photorealistic [shot type] of [subject], [action or expression], set in [environment]. The scene is illuminated by [lighting description], creating a [mood] atmosphere. Captured with a [camera/lens details], emphasizing [key textures and details]. The image should be in a [aspect ratio] format.`
For product photo `Replace [original product] with [new product] from Image 2. Match hand pose, reflections, and [material] specular highlights. Keep label readable and preserve text legibility. No stylization.`
For character consistency `"Same face, hair, makeup, and earrings across all outputs. Keep [subject] identical while changing [environment/action]. Maintain facial features, expression, and clothing exactly as shown."`
For photorealistic results Include details like: * Camera specs: "85mm portrait lens," "shallow depth of field," "f/2.8" * Lighting: "golden hour light," "soft window light," "dramatic rim lighting" * Composition: "close-up portrait," "wide establishing shot," "overhead view" * Technical details: "bokeh background," "natural grain," "high contrast"
For text editing `"Change the text from '[original text]' to '[new text]'. Maintain font weight, curvature, perspective warp, and reflections. Keep brand colors identical. No other changes."`
### Example prompts * **Simple edits**: "Remove the person in the background" or "Make this photo brighter" * **Reference image integration:** "Place the man from Image 2 next to the woman in Image 1. They are seated together, sharing a laugh as they look at a tablet. Keep the ambient lighting and depth of field from Picture 1. Maintain skin tones consistent with the original scene." * **Image fusion**: "Place this product in that lifestyle setting" * **Complex transformations**: "Turn this into black-and-white manga style" * **Multi-step edits**: "Remove everything except the woman and mic", then "make her a 3D character in an office" * **Multi-references**: "Make employee badges using this design template and this photo" * **Control aspect ratio**: "Create a 9:16 Instagram Story version of this ad with neon background and space at top for text." * **Product photography**: "Replace the black bottle with the green 'HULK' can from Image 2. Match hand pose, reflections, and metal specular highlights. Keep label readable and preserve text legibility; no stylization." # GPT Image 2 OpenAI's latest image model. Available in three quality tiers, strongest where text and structure matter. ## Overview OpenAI's latest image model — the first to go toe-to-toe with Nano Banana 2 on quality, resolution, and speed. Where it pulls ahead: anything involving text, layout structure, or brand accuracy. Available in three quality tiers to match the job and the budget. | Quality tier | Low | Medium | High | | ----------------- | ------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------------------ | | Best for | High-volume iterations, drafts, batch generation | Production assets, static ads, UGC-style visuals | Editorial shoots, hero shots, complex compositions with text | | Quality reference | On par with Nano Banana | On par with Nano Banana 2 | On par with Nano Banana Pro | | Text rendering | Clean | Production-ready | Production-ready | ## Strengths for marketers * **Text that works on the first try**: Headlines, CTAs, packaging fine print, dense paragraphs render correctly without Photoshop fixes. * **Strong art direction**: Avoids the over-polished AI look. On par with Nano Banana Pro for editorial outputs. * **Structured layouts**: Treats spatial instructions (grids, infographics, UI mockups) as rules, not suggestions. ### Ideal use cases * **Complex-text product consistency**: Packaging, labels, and product copy rendered legibly across SKUs. * **Product shots**: Production-quality hero shots from a product image and a scene description. * **Editorial photos**: High-end fashion shoots, lifestyle moodboards, multi-frame e-commerce grids with consistent art direction. * **Realistic UGC photos**: iPhone-style product-in-hand shots, ideal for Meta Ads or as first frames for UGC video. * **Static ads**: Banner ads, social graphics, posters with readable headlines, CTAs, and fine print — composed in one pass. #### Weaknesses * **Resizing**: Tends to add elements that weren't in the original creative when resizing or adapting formats. * **Fine product consistency**: Nano Banana Pro still ahead on micro-details when preserving an exact product across edits. * **Content policy**: Not viable for underwear, swimwear, or lingerie brands. * **Precise edits**: Nano Banana Pro is more precise for surgical edits. *** ## How to use effectively GPT Image 2 rewards specific, structured prompts — especially when text or layout is involved. #### Key principles * Be explicit with copy: put exact text in quotes (`"Hold my hand!"`), specify where it appears (header, label, CTA). * Specify layout when structure matters: grids, columns, hierarchy, spacing. * For editorial work, treat prompts like art direction briefs: subject, environment, lighting, camera, atmosphere. * Pick the right quality tier — Low for iteration and drafts, Medium for production assets, High for hero shots and dense text. * For text-heavy assets, keep copy reasonable in length and break dense text into clear lines. * Use reference images for product shots, but expect strict content policy filtering on sensitive verticals. #### Effective prompting patterns
For editorial photos `A photorealistic [shot type] of [subject], [action or expression], set in [environment]. Lighting: [description]. Camera: [lens, angle, framing]. Atmosphere: [reference style, color treatment, era]. Mood: [adjectives]. Composition emphasizes [key textures, details].`
For UGC-style photos `Casual iPhone photograph of [person] holding [product] in [environment]. Natural lighting, slight motion blur, authentic feel — like a real customer post. Product label and branding clearly visible. Composition is unstaged and candid.`
For product shots with packaging `Place the exact product shown in the reference image into the scene below. Preserve the [packaging element]'s typography, label layout, [color] color blocking, the "[wordmark]" exactly as shown. Scene: [environment]. Lighting: [description]. Aesthetic: [reference].`
For static ads with text `A [format] ad for [brand]. Headline: "[exact headline copy]". CTA button: "[exact CTA]". Optional fine print: "[exact text]". Visual: [scene/subject]. Brand colors: [hex or name]. Typography should feel [adjective]. Layout: [hierarchy description].`
For website & UI mockups `Create a [page type] mockup for [brand/product]. Sections: [hero, features, pricing...]. Copy: hero headline "[text]", subheadline "[text]", CTA "[text]". Visual style: [reference], color harmony focused on [color]. Layout should feel [adjective], with [grid/depth instructions].`
For complex-text consistency `Generate [number] variations of [product] keeping all text elements identical: "[wordmark]", "[callout]", "[fine print]". Vary only [scene / lighting / angle]. Maintain font weight, kerning, and color across outputs.`
For multi-frame editorial grids `Create a polished [N]x[N] grid of [shot type] for [brand]. No visible margins or gutters between frames. Brand should feel [adjectives]. Each frame: [subject and action]. Color harmony focused on [color]. Layout should feel intentional, with depth and contrast across frames.`
#### Example prompts * **Editorial moodboard**: "Create a polished 3x3 grid of e-commerce photoshoots for a leather brand. Playful, design-forward, vibrant — Parisian fashion energy meets premium creative tech. Color harmony focused on orange. No visible margins. Each frame intentional, with contrast in body composition and lighting." * **UGC iPhone shot**: "Casual iPhone selfie of a young woman holding \[product] at a sunlit café. Slightly blurred, authentic, real — feels like a customer post. Product label clearly readable. Natural composition, no staging." * **Static ad with copy**: "Square Instagram ad. Headline: 'Soft hands, every day.' CTA: 'Shop now.' Pink and white color blocking. Hand cream tube on a folded white waffle towel, polished concrete background. Spa hotel aesthetic." * **UI mockup**: "Landing page hero for a leather goods brand. Headline: 'Crafted in Paris, made for daily.' Subhead: 'Handmade leather bags, designed to last.' CTA: 'Shop the collection.' Hero image: orange leather tote on neutral background. Layout feels editorial, with generous whitespace." * **Packaging consistency**: "Place the exact tube from the reference image on a polished concrete vanity, beside a printed card reading 'for our guest'. Preserve the typography, the 'Hold my hand!' callout, the pink screw cap exactly as shown. Beige linen background, brushed nickel fittings." * **Multi-page e-commerce mockup**: "Multi-page e-commerce mockup for a leather brand. Playful, design-forward, vibrant. High-end grid with depth and intentionality. Color harmony: orange." # Seedream 5.0 Pro ByteDance's most controllable image model: precise regional edit and multilingual in-image text for production-ready e-commerce and ad creative. ### TL;DR Evolution of [Seedream 4.5](/models/image-models/seedream-4.5). A strong competitor to [Nano Banana 2/Pro](/models/image-models/nano-banana-2-lite) and [GPT Image 2](/models/image-models/gpt-image-2). ### Strengths for marketers * **Multi-image fusion:** combines up to 10 reference images into one coherent shot, placing a product in a model's hands or assembling a bundle from separate SKU photos. * **Precise local edits:** specify an edit region with a selection, point, arrow, box, or coordinates. Only that region changes, everything else stays untouched. * **Exact brand color matching:** accepts explicit hex codes and material specs, restoring the target region with high fidelity across every variant. * **Multilingual in-image text:** natively renders text across 14 languages (Arabic, English, Russian, Indonesian, Spanish, German, Turkish, Portuguese, Malay, Vietnamese, French, Japanese, Korean, Tagalog, Thai), adapted culturally rather than just translated. * **Trusted input for Seedance video:** outputs are recognized as trusted inputs by the Seedance video family, smoothing the product-image to product-video pipeline. ### Ideal use cases * **A/B creative variants:** multiple backgrounds/lighting/layouts of one ad, minutes to rotate. * **On-model try-on:** one model shoot → full apparel listing set, model stays consistent. * **Bundle still-life:** several SKU photos → one gift-set hero image. * **Localized ad copy:** one poster → native in-image text across markets. * **Background swap:** one studio shot → marketplace white, lifestyle, seasonal backdrops, product untouched. * **Seasonal refresh:** one hero asset carried through multiple campaigns, brand colors consistent. * **Material variants:** same product across materials or finishes, same frame and angle. ### Weaknesses * **No 4K:** output tops out at 2K-class (up to \~2048×2048 at 1:1, \~2720×1530 at 16:9). # Seedream 5.0 Lite Bytedance's latest evolution — a strong competitor to Nano Banana models with improved consistency, editing precision, and portrait quality. ## Overview Evolution of [Seedream 4.5](/models/image-models/seedream-4.5). ### Key Updates * **Stronger feature consistency:** Significantly improves consistency for characters, roles, and products across images. Notable enhancements to skin tone preservation, face consistency, and small-sized face stability. * **More precise instruction following & editing:** Enhanced editing capabilities combined with brush input. Better image understanding, deconstruction, and complexity for poster generation. * **Photo editing & portrait retouching:** Remarkable improvements in reference image adherence, original detail preservation, skin texture restoration, and facial feature accuracy. * **Distortion-free product images:** Combined with enhanced consistency, performs better in secondary creation of product images, ensuring the main product remains distortion-free. ### Weaknesses * **Anatomical distortions in complex scenes:** Occasionally struggles with disproportionate human figures or spatial misalignments. Seedream 4.5 is more mature and stable in this regard. * **Max resolution 3K:** Seedream 4.5 supports up to 4K output, while 5.0 Lite maxes out at 3K. * **Dense small-text regression:** While layout hierarchy is better, precision of dense small text may be less sharp than Seedream 4.5. # Seedream 4.5 Bytedance's alternative to Nano Banana when you need superior photography, typography, and/or 4K resolution capabilities. ## Overview Evolution of [Seedream 4.0](/models/image-models/seedream-4.0). ### Key Updates * **Superior Aesthetics:** Produces cinematic visuals with refined lighting and rendering. * **Higher Consistency:** Maintains stable subjects, clear details, and coherent scenes across multiple images. * **Smarter Instruction Following:** Accurately responds to complex prompts with precise visual control and interactive editing. * **Stronger Spatial Understanding:** Generates realistic proportions, object placement, and scene layout. * **Richer World Knowledge:** Creates knowledge-based visuals with accurate scientific and technical reasoning. * **Deeper Industry Application:** Supports professional workflows for e-commerce, film, advertising, gaming, education, interior and architectural design. * **Custom Aspect Ratios**: set your own image dimensions. ### Ideal use cases * **Premium product photography**: Sophisticated product staging and professional-grade shoots for catalogs, e-commerce, and high-value marketing materials. * **Static ads**: Professional advertising creatives that require high resolution and polished visual quality. * **Image editing and asset variations**: Transform existing visuals by adding, removing, or modifying elements. Perfect for creating product variations, seasonal updates, or quick asset adaptations without starting from scratch. * **High-end fashion campaigns**: Complex styling, lighting, and composition requirements for luxury brands and premium fashion marketing. * **Print-quality assets**: Marketing materials requiring ultra-high resolution for billboards, magazine ads, packaging, and other print applications. ### Weaknesses * 4K output increases processing time * Requires clear, detailed prompts for best results # Seedream 4.0 Bytedance's best alternative to Nano Banana when you need superior photography, typography, and/or 4K resolution capabilities. ## Overview Balanced image generation and editing model with 4K resolution output. Excels at complex product photoshoots, sophisticated styling scenarios, static ads generation, and advanced image editing with multi-image input support. ### Strengths for marketers * **Deep, balanced capabilities at an affordable cost**: Can generate static ads, photos, illustrations, and more with consistent quality across different content types. * **Advanced multi-image editing**: Supports complex editing operations (addition, deletion, replacement, modification) and multi-image inputs for combination, style transfer, and composite editing. * **Complex product staging**: Manages sophisticated product arrangements with multiple items, advanced lighting scenarios, and professional-grade compositions that would typically require a professional photographer. * **4K resolution capability**: Generate ultra-high resolution images (up to 4K) perfect for premium digital marketing materials, large-format displays, print campaigns, and any project where image quality is critical. ### Ideal use cases * **Premium product photography**: Sophisticated product staging and professional-grade shoots for catalogs, e-commerce, and high-value marketing materials. * **Static ads**: Professional advertising creatives that require high resolution and polished visual quality. * **Image editing and asset variations**: Transform existing visuals by adding, removing, or modifying elements. Perfect for creating product variations, seasonal updates, or quick asset adaptations without starting from scratch. * **High-end fashion campaigns**: Complex styling, lighting, and composition requirements for luxury brands and premium fashion marketing. * **Print-quality assets**: Marketing materials requiring ultra-high resolution for billboards, magazine ads, packaging, and other print applications. ### Weaknesses * **Quality limitations at lower resolutions**: Facial features may lack detail and typography may look broken when using standard resolution settings. * **Long generation times (in 4K)**: High-resolution requires more generation time. Plan accordingly for time-sensitive projects. ## How to use effectively **General tip — Use 4K**: When your shot includes faces, typography, select custom AR with 4096x4096 resolution to ensure facial features are rendered with appropriate detail and quality. **New image from a prompt** * Use natural language describing **subject + action + environment** * Include **style, color, lighting, or composition** details when aesthetics matter * Wrap text that should appear in the image with **double quotation marks** * Use precise technical terminology for diagrams and educational content Example prompt**:** "A girl in a lavish dress walking under a parasol along a tree-lined path, in the style of a Monet oil painting" **Image editing** * Use **clear, concise instructions** specifying the exact element and desired change * **Addition**: Add new elements (e.g., "Add matching silver earrings and a necklace to the girl") * **Deletion**: Remove unwanted elements (e.g., "Remove the girl's hat") * **Replacement**: Swap objects (e.g., "Replace the bread man with a croissant man") * **Modification**: Transform elements (e.g., "Turn the three robots into transparent crystal, colored red, yellow and green") * **Explicitly mention what should remain unchanged** to avoid unintended modifications **New image from multiple inputs** * **Define the reference target** from each image (character design, style, product features) * **Combination**: Merge elements from different images (dress the character from Image 1 with the outfit from Image 2) * **Style transfer**: Apply the visual style of one image to the content of another * **Reference-based generation**: Extract character design, artistic style, or product features to create new variations * **Clearly specify** what to reference or edit from each image * **Describe the generated scene** with detailed information about layout and specifics
Simple image prompt > *A woman walking on the street, black and white picture*
Product shot prompt > *A professional photo of a person’s leg, cropped at mid-calf, captured mid-stride, with the focus on a pristine white technical sneaker worn on the left foot. The sneaker is positioned on ancient cobblestones of a quiet Copenhagen side street, flanked by understated buildings with pale pastel facades in muted blues and cool greys. Photographed from a low angle, emphasizing the street texture and the sneaker’s form. A 35mm lens perspective creates a subtle wide-angle view. Shallow depth of field ensures a creamy, soft bokeh in the background, making the pastel facades gently blur. Crisp focus is maintained specifically on the intricate texture of the white technical sneaker and its distinct quick-lace system. The wearer’s leg is clad in black tapered pants, which provide a clean contrast, with neutral grey socks visible at the ankle. No other accessories are present. The composition is clean and minimalist, with the cobblestones forming subtle leading lines that guide the eye towards the shoe. Ample negative space surrounds the central subject, ideal for design integration. The overall color palette features cool greys, bright whites, and muted blues, maintaining a true-to-life material representation. No faces or other people are visible. Signage is minimal to non-existent. The image has subtle contrast and avoids heavy saturation, embodying understated Scandinavian simplicity. The lighting is soft, even, and natural overcast Nordic daylight, illuminating the scene gently from above, casting minimal shadows.*
Static ads prompt > *A lifestyle photograph of a charming and iconic Parisian street scene. The image should feature a classic Haussmannian building with wrought iron balconies and flowers, with a traditional café on the ground floor with striped awnings. The atmosphere is soft, dreamy, and authentic, captured in the warm, natural light of a late afternoon, creating an aspirational feel. The composition should leave ample clear space in the upper portion, such as a soft blue sky, for text overlay. Style: sophisticated travel photography, muted color palette, warm tones. Text Overlay Concept: “Paris, comme si vous y habitiez.” Typography: elegant modern serif, white, sentence-case. CTA: “Trouvez votre échange à Paris” inside a rounded, cream-colored button. Typography: clean sans-serif.*
# Recraft v4 A design-focused image generation model with strong editorial aesthetics, native vector output, and production-ready composition, developed by Recraft. ## Overview Recraft V4 excels at generating images with intentional composition, balanced color, and refined detail — what Recraft calls "design taste." Use it when you need visuals that feel art-directed rather than stock-like, especially for brand systems, campaigns, and print-ready assets. The model has two core differentiators: it treats typography as a structural part of the composition (not just an overlay), and it's the only model capable of generating native, editable SVG vector files. ### Strengths for marketers * Strong compositional judgment: intentional negative space, clear hierarchy, and layout-aware outputs ready for headlines and overlays * Native vector generation: production-quality SVG files with real paths, structured layers, and clean geometry * Precise prompt accuracy with prompts up to 10,000 characters * RGB color control: specify exact brand colors and maintain them across generations * Consistent visual identity across campaign-style outputs ### Ideal use cases * **Visual direction:** Create assets to influence downards nodes & models * **Editorial covers:** Art-directed photography with film-like tonal depth * **Vector assets:** Icons, logos, illustrations as production-ready SVGs — no tracing needed * **Branding systems** Cohesive visuals across formats with consistent design language * **Posters & print layouts:** Layout-aware compositions with space for typography and overlays ### Weaknesses * **Complex human dynamics:** Scenes depending on believable interpersonal relationships or gestural accuracy between figures don't land well. The model can render people but struggles with the logic of how people relate to each other in space. * **Does not handle reference images**, limiting image editing, product & character consistency use cases. * **Dense or integrated text accuracy:** Product labels, packaging, multi-element interfaces — the visual rendering can appear fine while the actual copy is wrong. Not reliable where text accuracy inside the image matters. ### Pro tips * Define the final format in your prompt (poster, hero banner, editorial cover) — it helps the model build the right composition from the start * Describe spatial relationships, not just subjects: "centered subject with empty upper third" beats a subject-only description * Use V4 for iteration and exploration (\~10s), V4 Pro for final production assets (\~30s, 2048x2048) # Krea 2 Krea's foundation image model, built for full control over the look, feel, and creative direction of every output. ## Overview Where some models may flatten toward a polished, "safe" aesthetic, Krea 2 holds onto expressive and niche styles. Available in two versions: * **Krea 2** (faster, cheap, consistent) * **Krea 2 Pro** (larger, rawer, stronger on photorealism). ### Strengths for marketers * **Style transfer**: Extract the style from one or several reference images and apply it to outputs, with per-reference strength control — the strongest system on the market for locking brand look. * **Moodboards**: Pass in a moodboard of dozens of images and the model reads the overall direction — palette, texture, mood — applying it even to very simple prompts. * **Tunable creativity**: A `creativity` parameter controls how far the model expands a loose prompt, from `raw` (literal) to `high` (full interpretation). * **Aesthetic diversity**: Renders expressive, niche, and experimental looks without collapsing into a generic AI style. ### Ideal use cases * **Brand-consistent art direction**: Use style references to hold a consistent look across a full set of assets. * **Editorial & illustrative content**: Strong on illustration, anime, and painting for content that needs character. * **Concepting & exploration**: Take a loose direction and get back visuals that spark the next idea. ### Weaknesses * **Resolution capped at 1K** — for large-format or print, pair with an upscaling node. * **Not a typography model** — for text-heavy layouts or precise lettering, route to a text-rendering specialist (Nano Banana, GPT, Seedream). *** ## How to use effectively #### **Key principles** Krea 2 rewards art direction over prompt detail: * Lead with a moodboard or style reference when brand consistency matters. * Tune `creativity` to control expansion — lower it (or use `raw`) when you need the model to stick to your prompt. * Don't over-specify. The model fills the gaps you leave; let it. # Ideogram v4 Ideogram's design-native image model, built for precise control over text, layout, and color in every output. ### Overview Ideogram v4 treats typography, colors and layout as inputs you control. It reads structured JSON prompts — describing every element, its position, and its color — and renders them. The model was trained exclusively on structured captions, so it expects them: prompts written as prose underperform, and the more relationships you pin down, the more grounded the output. ### Strengths for marketers * **In-image text**: Best-in-class typography — multi-line, multi-font lettering rendered cleanly, with each text block placed exactly where you want it. * **Layout control**: Place any element by bounding box. Titles, objects, and text land where you put them, not where the model guesses. * **Color palette conditioning**: Lock exact brand colors with hex codes — up to 16 per image, 5 per element — instead of describing them in words. * **Detail & realism**: Photoreal output with fine texture and accurate lighting alongside the design control. ### Ideal use cases * **Posters & print visuals**: Anything where the text *is* a strong part of the design. * **Editorial & layout-driven content**: Multi-element compositions where placement and hierarchy carry the message. ### Weaknesses * **Needs structured prompts** — plain text prompts underperform. Results come from JSON with explicit elements, colors, and boxes. * **Reference images are style inspiration** — Ideogram reads refs for look and mood, not for exact reproduction. For precise product imagery or character fidelity, route to a dedicated model. *** ## How to use effectively #### Key principles Ideogram v4 rewards structure over prose. Describe the image as data, not a sentence: * **Prompt in JSON.** Wrap every request in the schema: a `high_level_description`, a `style_description` block, and a `compositional_deconstruction` listing each element. The model validates against this format before rendering. * **Type your text.** A `text` element carries the literal string to render plus a separate `desc` for its styling. This is the mechanism behind multi-line, multi-font in-image text. * **Place elements with bounding boxes.** Give any element a `bbox` as `[y_min, x_min, y_max, x_max]` in 0–1000 normalized coordinates, origin at the top-left. Boxes are honored precisely. * **Set color with hex codes.** Use `color_palette` arrays — up to 16 hex values per image, 5 per element — to steer dominant colors directly rather than through descriptive language. #### Example json ```json { "high_level_description": "Retro square poster for a team tasting event, bold red type on salmon pink.", "style_description": { "aesthetics": "Retro, playful, warm.", "color_palette": ["#E8552D", "#F4B9A0"] }, "compositional_deconstruction": { "background": "Solid salmon-pink ground with scattered confetti shapes.", "elements": [ { "type": "text", "bbox": [70, 270, 470, 730], "text": "MANGO\nSAGO\nSOCIAL", "desc": "Bold blocky sans-serif, deep reddish-orange, stacked vertically, slightly distressed." }, { "type": "obj", "desc": "Tall glass of mango sago dessert topped with cream, a whole mango beside it." } ] } } ``` # Grok Imagine Image A frontier video generation model developed by xAI, optimized for speed, cost, and creative iteration. ## Overview xAI's image model with superior prompt understanding. Generates photorealistic or stylized images with precise text comprehension in a few seconds. Available in two modes. Both modes support up to 2K resolution and image editing: * **Standard:** optimized for speed and cost. Best for ideation and rapid iteration. * **Pro:** higher fidelity, improved detail, lighting, composition, and reliable text rendering. Best for final, client-facing outputs. Worse than Nano Banana 2 or GPT Image 2 though. ### **Strengths for marketers** * Very fast generation (a few seconds per image). * Strong prompt understanding and adherence. * Good cinematic character rendering with expressive lighting. * Performs well with stylized aesthetics (anime, cyberpunk, neon). * Supports basic image editing. ### **Ideal use cases** * Rapid creative exploration and ideation. * Mood boards and concept development. * Character portraits for social content. * Stylized illustrations with neon or cinematic lighting. ### **Weaknesses** * No fixed aspect ratio control. * Low resolution (<1K) → requires upscaling for production use. * Limited production-ready features compared to other models. # Higgsfield Soul A specialized AI model optimized for ultra-realistic portrait generation with exceptional fashion and lifestyle capabilities. ## Overview Best choice for UGC-style content and lifestyle photography when you need exceptional photorealism and style versatility. Excels at realistic human features and works great as a starting point for multi-step workflows (e.g., art direction baseline, start frame for video generation). ### Strengths for marketers * **Exceptional photorealism**: Captures skin tones, facial features, and fabric textures with remarkable detail that eliminates the "plastic AI look" * **UGC authenticity**: Generates content that looks like real user-generated photos, perfect for authentic brand storytelling * **Fashion DNA expertise**: Recognizes and accurately renders specific fashion styles, from "Y2K cyber candy colors" to "Maison Margiela deconstructed style" * **Diverse representation**: Maintains natural facial features and expressions across different ethnicities and genders without distortion * **Style presets**: Access to 50+ preset aesthetic templates covering trends like cyberpunk neon, French film realism, and MV-level lighting effects
### Ideal use cases * **UGC-style campaigns**: Create authentic-looking user-generated content for social proof and relatability; use as starting frames for video models and content * **Lifestyle brand content**: Generate realistic portraits for brand storytelling that feel genuine * **Art direction references**: Generate base images that can guide other AI models for consistent visual style * **Influencer-style content**: Produce authentic-looking lifestyle shots for social media campaigns ### Weaknesses * Basic composition skills: Struggles with complex layouts or sophisticated framing * Limited to portrait and lifestyle scenarios - not suitable for product shots or graphic design ### Output samples
*** ## How to use effectively Higgsfield Soul excels with fashion-focused, lifestyle-oriented prompts: **Key tips** * **Leverage the style presets** for instant aesthetic transformations * **Combine with brand context nodes** for consistent styling * **Use as workflow foundation**: Generate base images, then animate with video models or use as style references for other generations #### Example prompts * "UGC-style selfie of young woman trying on vintage jacket, natural lighting, authentic mobile photo aesthetic" * "Portrait of a young woman in Y2K cyber candy colors, glittery PVC jacket, neon lighting, cyberpunk aesthetic" * "Maison Margiela deconstructed style fashion shoot, unfinished seams, split shoulders, minimalist background" * "Casual lifestyle photo of person with coffee, natural expressions, authentic lighting, mobile photography style" * "Tokyo street fashion model under neon lights, Japanese minimalist aesthetic, mobile photography style" # Reve An image generation and editing model with editorial-quality aesthetics, developed by Reve. ## Overview Reve excels at creating editorial-quality visuals with Midjourney-like aesthetics. Use it when you need polished, magazine-worthy images that can serve as creative inspiration or high-end reference material for your campaigns. The model has three core capabilites: generating images from scratch, editing existing images with precision, and creating new compositions from multiple image references. ### **Strengths for marketers** * Premium editorial aesthetic that elevates brand perception * Versatile editing capabilities: add, remove, or modify image elements seamlessly * Multi-image synthesis for creating cohesive visual concepts * Strong artistic direction that produces inspiration-worthy outputs * Consistent high-quality results suitable for client presentations and mood boards ### **Ideal use cases** * **Editorial (fashion) shots**: Generate editorial-style visuals to inspire campaign directions * **Mood board creation**: Produce cohesive visual references for brand aesthetics * **Reference material**: Create polished visuals that guide other model outputs * **Image refinement**: Remove unwanted elements, adjust details, or enhance existing photos * **Concept development**: Combine multiple images to prototype new creative directions ### **Weaknesses** * Higher aesthetic quality may not suit all brand styles (especially casual or gritty brands) * Editorial approach can feel too polished for authentic UGC-style content * Generation time may be longer than other generation models ### Pro tips * Combine with more product-focused models for complete campaign workflows * Experiment with multi-image inputs to develop unique visual concepts that blend brand elements *** # Flux 2 An image generation and editing model developed by Black Forest Labs. Outperformed by newer models on most tasks — see our selection guide. ## Overview Flux 2 is Black Forest Labs' most capable model to date. It combines generation and editing in a single model while delivering production-grade quality with consistent characters and styles across outputs. It's a direct competitor to Nano Banana & Seedream 4.0. ### Strengths for marketers * **Multi-reference support**: Reference up to 10 images simultaneously to maintain strict character, product, and style consistency across generations—no fine-tuning required. * **Production-grade typography**: Renders complex text, infographics, UI mockups, and magazine layouts with legible fine text that works reliably. * **HEX color control**: Specify exact brand colors using HEX codes (e.g., `#FF5733`) for pixel-perfect brand consistency across campaigns. * **Strong prompt adherence**: Follows complex, structured instructions including multi-part prompts and compositional constraints more accurately than previous generations. ### Ideal use cases * **Product photography**: Generate lifestyle shots with consistent products across different angles, lighting, and environments. Combine product images with model shots and backgrounds. * **Brand asset creation**: Create marketing materials with exact brand colors, typography, and visual identity maintained across outputs. * **Fashion shoots**: Combine clothing items, accessories, and style references into cohesive styled outfits on consistent models. * **Editorial content**: Magazine covers, infographics, and layouts with professional text rendering. ### Weaknesses * **Less versatile than competitors**: Nano Banana Pro or Seedream 4.0 do better on most visual marketing tasks. * **Complex scenes**: May struggle with highly complex compositions with many interacting elements. *** ## How to use effectively #### Model versions This model is available in three versions on Pletor: * **Flux 2 Max**: Use when quality matters * **Flux 2**: Balanced quality and speed. * **Flux 2 Turbo**: Use when speed matters (fastest generation for rapid iterations and image edits). #### Prompting Flux 2 is designed for natural language prompting. Unlike older models that required keyword stacking or quality tags, Flux 2 performs best with clear, descriptive sentences.
The prompt framework Use this structure for consistent results: **Subject + Action + Style + Context** * **Subject**: The main focus (person, object, character) * **Action**: What the subject is doing or their pose * **Style**: Artistic approach, medium, or aesthetic * **Context**: Setting, lighting, time, mood, or atmospheric conditions **Example**:\ `"Luxury leather handbag, displayed on marble surface, soft directional lighting, warm amber tones"`
Skip the quality tags Traditional quality tags like "masterpiece, best quality, ultra detailed, 8k" provide minimal benefit with Flux 2. The model's training already includes quality filtering, so focus on describing what you actually want.
Using reference images When using Flux 2 with a single reference image, describe how you want the reference used: `"Product shot of the sneaker from the reference image, placed on urban concrete, dramatic side lighting, clean background"` Flux 2 Flex accepts up to 10 reference images. Reference specific images by index or use the `@` symbol: `"The person from image 1 wearing the jacket from image 2, standing in the environment from image 3, natural lighting, medium shot"` Or with `@` syntax:\ `"A portrait of @image1 wearing the jacket from @image2, set in the location of @image3"`
Using color codes Flux 2 understands HEX codes for exact color matching. Include the color code directly in your prompt: `"Product photography of running shoe, primary color #FF6B35, secondary accents #004E89, white background, overhead lighting"` For complex products with multiple color zones, break down components: `"Ceramic vase with gradient color starting at #02eb3c and finishing at #edfa3c, displayed on marble surface"`
JSON prompting for complex scenes For maximum control over complex generations, Flux 2 accepts structured JSON prompts. This is especially useful for: * Production workflows requiring consistent structure * Precise camera and lighting specifications * Brand work with exact color requirements **Example JSON structure**: ```json { "scene": "Professional studio product photography", "subjects": [ { "description": "Minimalist ceramic coffee mug with steam rising", "position": "Center foreground", "color_palette": ["matte black ceramic"] } ], "style": "Ultra-realistic product photography", "lighting": "Three-point softbox setup, soft diffused highlights", "mood": "Clean, professional, minimalist", "camera": { "angle": "high angle", "distance": "medium shot", "lens-mm": 85, "f-number": "f/5.6" } } ``` You can include JSON directly in your prompt or flatten it into natural language—Flux 2 understands both formats equally well.
# Previous generation image models Earlier models, kept available for existing workflows. For new work, start with the recommended models above. [GPT Image 1.5](/models/image-models/previous-generation-image-models/gpt-image-1.5) [Ideogram v3](/models/image-models/previous-generation-image-models/ideogram-v3) [Ideogram Character](/models/image-models/previous-generation-image-models/ideogram-character) [GPT Image 1](/models/image-models/previous-generation-image-models/gpt-image-1) [Flux Kontext](/models/image-models/previous-generation-image-models/flux-kontext) [Runway Gen4](/models/video-models/previous-generation-video-models/runway-gen4) [Google Imagen-4](/models/image-models/previous-generation-image-models/google-imagen-4) [More image models](/models/image-models/previous-generation-image-models/more-image-models) # GPT Image 1.5 OpenAI's latest image model. Outperformed by newer models on most tasks — see our selection guide. ## Overview Evolution of [GPT Image 1](/models/image-models/previous-generation-image-models/gpt-image-1). Key Updates: * **Improved text rendering:** Handles denser and smaller text with better legibility. * **Better image editing:** Change specific elements without regenerating the entire scene. * **Identity preservation:** Maintains facial likeness and composition across edits. * **Affordable quality:** Low quality mode delivers decent results at minimal cost (1 credit per generation). * **Much faster than GPT Image 1:** Up to 4x faster generations. ### Ideal use cases * **Rapid iterations**: Quick concept exploration using Low quality mode before committing to finals. * **Text-heavy graphics**: Infographics, banners, and visuals requiring legible typography. * **Image editing and asset variations**: Product variants, seasonal updates, localization without starting from scratch. * **Style transfers and try-ons**: Clothing changes, filters, or hairstyle tests while maintaining subject consistency. ### Weaknesses * With the highest quality parameters, it is worse than [Nano Banana Pro](/models/image-models/nano-banana-+-pro) and [Seedream 4.5](/models/image-models/seedream-4.5) (for a similar cost). * Limited aspect ratios (only 3 options vs. 10+ on other models). * 3 reference images maximum. * Yellow tint tendency, images can have a warm color cast by default. Pletor provides a dedicated parameter to remove this effect from generated visuals. * Commercial aesthetic bias: outputs feel polished, less authentic for UGC-style content. *** ## How to use effectively **For fast iterations:** Set quality to "Low" when exploring concepts. You'll get results in seconds at minimal cost, and the output quality is often sufficient for client reviews or internal alignment. **For text-heavy designs:** Put exact copy in "quotes" and describe the typography style. Be specific: "Bold sans-serif, centered, high contrast" helps ensure legibility. Set quality to "High" for dense layouts. **For precise edits:** Make one change at a time rather than rewriting entire prompts. Reference multiple input images by number: "Apply the style from image 1 to the subject in image 2." **For consistent characters:** Always upload reference images when you need identity preservation across multiple generations. The model excels at maintaining facial likeness when given a clear reference. # Ideogram v3 An image generation model developed by Ideogram. Outperformed by newer models on most tasks — see our selection guide. ## Overview Good with brand-consistent graphic design, and simple photorealist visuals. Does not work for product or character consistency use case. ### **Strengths for marketers** * **Brand consistency**: Maintains visual style across campaigns when provided with reference images. * **Text integration**: Handles text within designs better than most models, despite occasional glitches. * **Graphic design skills**: Excellent at layouts, compositions, and promotional materials. * **Realistic rendering**: Good lighting, color control, and professional visual quality. ### **Ideal use cases** * **Ad creatives**: Style-consistent Meta ads and social media advertising. * **On-brand photos**: Lifestyle imagery that matches brand aesthetic and visual identity. * **Simple social media assets** (LinkedIn banners, thumbnails, etc.) * **Graphic Design in general**: small business branding, logo creation, promotional materials. ### **Weaknesses** * Fails at product consistency * Fails at character consistency * More text errors with non-English languages * 3 reference images maximum *** ## How to use effectively Ideogram excels with clear design briefs and style references #### **Key tips** * Provide up to 3 reference images for consistent style * Be specific about text content and placement * Include style descriptors like "modern," "minimalist," "bold" * Stick to English text for best results ### Example prompts * "Social media ad for coffee shop, vintage style, warm colors, include logo" * The text "Pletor Experience" in the center middle. A retro digital-inspired portrait of a young man with a shallow depth of field that blurs the surrounding elements, drawing attention to the expression. The pixelated texture and color palette suggest a vintage digital camera, while the wide aperture lens creates a pleasing bokeh effect, enhancing the modern and innovative artistic style. # Ideogram Character A specialized image generation model developed by Ideogram: creates consistent character variations across different scenes and styles. ## Overview Good choice for maintaining character consistency when you need the same person in multiple scenarios (e.g., AI UGC and avatar creation). ### Strengths for marketers * **Amazing character consistency**: Maintains facial features and identity across all generated variations. * **Automatic detection**: No manual setup - automatically identifies key character features from reference photo. * **Style flexibility**: Adapts characters to new environments while preserving identity. * **Simple workflow**: Single reference image generates unlimited character variations. ### Ideal use cases * **AI UGC content**: Create authentic-looking user testimonials and reviews with consistent characters. * **AI avatars**: Generate brand spokespersons or mascots for campaigns and social media. * **Video reference material**: Create character sheets for AI video generation with consistent appearance. * **Campaign variations**: Same character across different settings for A/B testing. * **Brand storytelling**: Consistent characters for ongoing narrative campaigns. ### Weaknesses * Requires high-quality reference images with clear facial features * Performance degrades with complex poses or extreme viewing angles * Limited to single character variations (not group scenes) * 1 reference image maximum *** ## How to use effectively Ideogram Character works best with clear reference photos and specific scene descriptions: **Key principles** * Use high-quality reference images with clear, well-lit facial features * Keep character poses relatively straightforward in reference photo * Be specific about new environments and contexts * Focus on scene description rather than character modification **Optimal reference images** * Clear facial features with good lighting * Straightforward pose and viewing angle * Unobstructed face (minimal shadows, accessories) * High resolution and sharp focus **Effective prompting** * Describe the new scene, setting, and context * Specify lighting conditions and mood * Include style descriptors if desired * Let the model handle character consistency automatically ### Example prompts * "Same person giving presentation in corporate boardroom, professional attire" * "Character outdoors in park setting, golden hour lighting, relaxed pose, street photography style" * "Place the young woman sketching quietly by the window in a cozy Parisian loft. The loft setting features eclectic furnishings with a mix of vintage and modern styles, herringbone wooden floors, and exposed brick walls adorned with abstract paintings and lush ferns that encapsulate Paris's bohemian charm. Soft afternoon light filters through large windows, casting gentle shadows that accentuate the artistic elements in the room. The composition appears slightly off-center, conveying the serene creativity and personal introspection of a peaceful moment immersed in the artistic ambiance of a Parisian afternoon." *** # GPT Image 1 An image generation model developed by OpenAI. Outperformed by newer models on most tasks — see our selection guide. ## Overview Good choice for simple graphic design and stylized content when you need reliable text rendering. Not great at photorealism but excellent for creative visuals. ### **Strengths for marketers** * **Strong prompt adherence, including text**: Most reliable AI model for generating readable text in images without errors. * **Style consistency**: Maintains visual consistency across campaigns, especially for 3D illustrations and mascots. * **Solid layout and graphic design skills**: Excellent at creating on-brand layouts, logos, and graphic design elements. * **Decent product consistency** (for simple products), requires additional retouch most of the time. * **Creative versatility**: Strong at style transfers, memes, and creative interpretations of concepts. ### **Ideal use cases** * **Ad concepts and drafts**: Quick creative ideas and campaign mockups. * **Simple graphic design**: Flyers, posters, and promotional graphics with reliable text. * **Brand illustrations**: On-brand 3D illustrations and mascot visuals. * **Memes**: Social media content and viral marketing materials. * **Simple charts**: Diagrams and basic infographics with clear labels. ### **Weaknesses** * Hard to control aspect ratio (tendency not to fit into the frame) * Heavy editing can significantly alter the original image * Poor photorealistic quality compared to specialized photo models * Limited aspect ratios * 3 reference images maximum * Signature color bias – images come out with a yellow tint by default. We provide a parameter to remove that:
## Output samples

Ghibli style transfer

Crocheted illustration style transfer

In-context mascot visual

Product illustration for a SaaS

Fake Asics ad

*** ## How to use effectively GPT Image-1 excels with clear, specific prompts: #### **Key tips** * Be explicit about text content - specify exact words and placement * Include style descriptors for consistent branding ("flat design," "corporate style") * Use reference styles for better consistency ("in the style of...") #### Example prompts * "Flat design poster with 'SALE 50% OFF' in bold red letters, minimal background" * "3D cartoon mascot character for tech company, friendly expression, blue and white colors" * "Simple infographic showing three steps, clean modern style, corporate blue theme" # Flux Kontext An image editing model developed by Black Forest Labs. Outperformed by newer models on most tasks — see our selection guide. ## Overview Decent choice for editing existing images with natural language prompts. Good with product shots but worse than latest image models (worse product fidelity, limited resolution, basic art direction). ### Strengths for marketers * **Precise local editing**: Extremely accurate edits to specific parts of images without affecting the rest. * **Product consistency**: Maintains product details across different angles and variations. * **Natural prompts**: Works with simple commands like "change this" or "add that." * **Fast generation**: Under 10 seconds per generation, Max version even faster. * **Text editing**: Strong at swapping signs, labels, and in-image typography (especially Kontext Max). ### Ideal use cases * **Product shots** (if not too complex) * **Model/character consistency**: Maintain same person or mascot across different scenes. * **Post-production edits**: Quick fixes and modifications to existing marketing materials. * **Text replacement**: Update signs, labels, or text within images. ### Weaknesses * Limited to 720p resolution requiring upscaling (we recommend Topaz here) * People and skin details can look artificial without retouching * Basic art direction capabilities compared to some other models (e.g., Runway, Ideogram) * Not suitable for complex graphic design from scratch *** ## How to use effectively #### Model versions This model is available in two versions: * **Pro**: Default version * **Max**: More performant with long prompts & typography, costs more credits #### Prompting Flux Kontext excels with contextual understanding and simple, direct prompts: **Key principles** * Use natural, conversational language to describe changes * Be specific about what to change and what to keep * The model understands image context automatically * Keep prompts focused on one main edit at a time **Effective prompt patterns** * **Object changes**: "Turn the red car blue" or "Change the shirt to green" * **Additions**: "Add a woman standing next to the product" * **Text edits**: "Change the sign to say 'OPEN'" * **Style transfer**: "Make this look like an oil painting" * **Removal**: "Remove the person in the background" **Best practices** * Start with the existing image as your base * Describe only what should change, not what should stay * Use simple, direct language rather than complex descriptions * Test variations with single-word changes for product shots # Runway Gen4 Image An image generation model developed by Runway. Outperformed by newer models on most tasks — see our selection guide. ## Overview Decent choice for product photography and combining multiple images seamlessly. Good photorealism but weak at graphic design. ## **Strengths for marketers** * **Product consistency**: Maintains identical products across different settings and lighting conditions. * **Image compositing**: Seamlessly merges multiple reference images into cohesive new visuals. * **Photorealistic quality**: Professional-grade realism for lifestyle and product photography. * **Refined art direction**: Sophisticated visual styling and atmospheric control. ### **Ideal use cases** * **Product photography**: Professional product shots with sophisticated lighting and backgrounds. * **Model photography**: Lifestyle shots with products in realistic settings. * **Image replacement**: Swap products or elements within existing creative materials. * **Brand photography**: High-end visuals for premium campaigns and marketing materials. * **E-commerce imagery**: Consistent product shots across different environments ### **Weaknesses** * Struggles with product proportions without proper prompt or image guidance * Poor at graphic design elements (text, layouts, typography) * 3 reference images maximum *** ## How to use effectively Gen-4 Image works best with detailed, descriptive prompts using natural language: **Key principles** * Use full sentences with natural language for better control * Start simple, add details gradually through iteration * Focus on visual descriptions, not conversational requests * Avoid negative prompts (say what you want, not what you don't want) **Structure your prompts** * **Subject**: "elegant portrait of a woman," "premium watch" * **Scene/Setting**: "against blue background," "on marble surface" * **Lighting**: "studio lighting," "golden hour," "ethereal warm orange lighting" * **Style/Mood**: "cinematic photograph," "luxury product photography" **Example progression** 1. Simple: "elegant portrait of a woman" 2. Add details: "elegant portrait of a woman draped in flowing tulle veil" 3. Full detail: "elegant portrait of a woman draped in sheer tulle veil against blue background. Close-up, ethereal warm orange lighting, soft focus, baroque painting style" ### Example prompts * "Premium watch on marble surface, studio lighting, luxury product photography" * "modern product photography of perfume in a unique bottle. minimalist, clean. sage green color palette. thoughtfully arranged floral and wood elements. bright lighting accentuates the perfume bottle." * "cinematic still of a woman waiting at a bus stop. dynamic motion blur conveys colorful vehicles passing in a blur. whimsical muted color palette. gentle symmetry. symmetrical composition." # Google Imagen-4 An image generation model developed by Google. Outperformed by newer models on most tasks — see our selection guide. ## Overview Good choice for realistic lifestyle photos and ad concepts when you need consistent style at scale. No reference image support limits brand consistency. ### **Strengths for marketers** * **Excellent prompt adherence**: Follows detailed briefs accurately and consistently. * **Strong photorealism**: High-quality realistic photos and lifestyle imagery. * **Typography skills**: Good text integration and graphic design capabilities. * **Scale consistency**: Maintains style across series when using same prompt structure. * **Speed options**: Fast version generates up to 10x faster than Imagen 3. ### **Ideal use cases** * **Ad concepts**: Fresh creative ideas and campaign visuals. * **Lifestyle photography**: Custom stock photos and realistic lifestyle imagery. * **Social media assets**: LinkedIn banners, thumbnails, and platform graphics. * **Blog illustrations**: Supporting visuals for content marketing. * **Series content**: Multiple images with consistent style and branding. ### **Weaknesses** * Limited customization compared to reference-based models * No image references ⇒ rarely brand consistent + cannot be used for product or character use cases. * Skin textures can still look a bit artificial without upscaling. *** ## How to use effectively #### Model versions This model is available in three versions: * **Standard:** Balanced quality, performance and cost * **Ultra:** Highest quality, costs more credits * **Fast**: Fastest option, lower quality, cost-effective option #### Prompting Imagen-4 performs best with precise, detailed prompts that specify multiple elements: **Key principles** * Be highly specific about subjects, environments, and artistic styles * Specify exact text content and typography style * Include brand colors and visual elements * Describe lighting and mood for lifestyle photos * Use terms like "professional," "commercial," or "advertising style" **Structure detailed prompts** * **Subject**: "young woman with dark hair," "majestic Eastern dragon" * **Setting**: "bustling late-night eatery," "mist-shrouded mountain peak" * **Style**: "atmospheric narrative illustration," "traditional Sumi-e ink wash" * **Details**: "soft overhead lighting," "varying ink densities," "textured color fields" #### Sample prompts * "Professional lifestyle photo of person using laptop in modern coffee shop, natural lighting" * "Fresh ad concept for fitness brand, energetic person exercising outdoors, vibrant colors" * "Sticker design, minimalist and quirky illustration style, showcased on a simple white background. Depicts a generic astronaut figure floating serenely in a zero-gravity pose. The astronaut suit is simplified, possibly rendered in clean white with minimal grey shading lines, lacking specific agency logos or excessive detail. Floating beside or held casually by the astronaut is a single, perfect slice of pepperoni pizza, illustrated with equal simplicity (yellow cheese, red pepperoni circles, brown crust). The style is clean with thin, consistent line work, or flat color shapes." # More image models Alternative models that can be useful in specific situations where cost-effectiveness and specialized capabilities matter more than cutting-edge features. ## Flux Krea A great image generation model developed by Black Forest Labs in collaboration with Krea AI. Best for photorealistic images that avoid the oversaturated "AI look." **Strengths for marketers:** * Exceptional photorealism with accurate skin textures and natural lighting. * Distinctive aesthetics that don't immediately look AI-generated. * Lightning-fast generation speeds. * Dynamic camera angles and expressive color handling. **Ideal use cases:** * Lifestyle photography and natural product shots. * Ad creatives where avoiding the "AI look" is critical. **Weaknesses:** * Complex scene representation is worse than latest state-of-the-art models * May require more specific prompting compared to commercial models. * 3 reference images maximum ## Seededit v3 An image editing model developed by Bytedance. **Strengths for marketers:** * Maintains high fidelity in unedited areas **Ideal use cases:** * Asset seasonality (e.g., background changes, lighting conversion) * Persona visual adaptations (e.g., portrait editing, perspective changes) * Quick asset edit through selective object removal/modification **Prompt examples** * Lighting Changes Prompt: “Change the scene to daytime” Transforms lighting and shadows across the entire scene while preserving all original details. * Object Removal Prompt: “Remove all pedestrians except the middle character” Accurately identifies and removes specified objects including their shadows. * Style Conversion Prompt: “Make the girl look realistic” Converts 2D illustrations to photorealistic images while preserving clothing, accessories, and other details. ## Google Imagen 3 An image generation model developed by Google. Best for lifestyle pictures and simple graphic design. **Strengths for marketers:** * Decent at graphic design, including layouts and complex text. * Photorealism, but slightly less refined than Google Imagen-4 Ultra. * Prompt adherence: has a more literal interpretation vs. Imagen-4 Ultra. **Ideal use cases:** * Simple blog illustrations * Lifestyle photos: build your custom stock image **Weaknesses:** * No image references ⇒ rarely brand consistent + cannot be used for product use cases. * Struggles with complex prompts requiring complex spatial relationships. # Video models We select the most reliable video generation models for marketing applications. Video AI is rapidly evolving. We prioritize models that deliver marketing-ready content over experimental features. Our curated selection focuses on models that can produce professional video assets suitable for campaigns, social media, and advertising. ## What video model should I pick? #### Go-to models — Production-ready flows [Seedance 2.0](/models/video-models/seedance-2.0), [Flux 3](/models/video-models/flux-3), [Kling 3.0](/models/video-models/kling-3.0), [Veo3.1](/models/video-models/google-veo3.1) Use for: multi-subject scenes, cinematic camera work, audio/dialog, multi-rush editing, longer durations, higher fidelity requirements. Use [Seedance 2.5](/models/video-models/seedance-2.5) when you need longer videos (30s one-takes, 60s with extension) and when 720p is good enough. #### Go-to models — Simple flows and quick iterations [Gemini Omni Flash](https://docs.pletor.ai/models/video-models/gemini-omni-flash-1), [Grok Imagine Video 1.5](/models/video-models/grok-imagine-video-1.5), , [Kling 2.6 Pro](/models/video-models/kling-2.6), [Veo3.1 Light](/models/video-models/google-veo3.1), [Seedance 1.5 Pro](/models/video-models/seedance-1.5-pro) Use for: single-subject product shots, simple animations, short clips, camera motion control, start frame/end frame, no audio needed. Fast, cost-efficient, reliable. #### Use a specialist when... Try the following models when go-to models fall short or you have something specific in mind:
You need...Use
>10 second UGC videosSeedance 2.5, Seedance 2.0, Kling 3.0, Sora 2, Veed Fabric
Budget-friendly / high volume / Simple animationsKling 2.5, Seedance 1.5 Pro, Grok Imagine
4K resolutionKling 3.0 4K, Seedance 2.0 4K, FlashVSR Video Upscaler
Precise lipsynced videos / Talking charactersVeed Fabric + Eleven Labs
Animated illustrationsKling 2.5, Seedance Pro, Hailuo 2.3, Grok Imagine
Stop-scrolling creativesSeedance 2.5, Flux 3, Sora 2
Video editingGemini Omni Flash, Happy Horse 1.1
# Seedance 2.5 A state-of the art video generation model developed by ByteDance. ## Overview **Evolution from** [Seedance 2.0](/models/video-models/seedance-2.0). Key upgrades include up to 30-second generations (double the previous ceiling), sharper realism, finer creative control with bold camera moves, massively expanded reference budgets, more languages, and negative prompts that actually hold. The prompt is a script: write with timecodes, end states and transitions, and the model shoots them in one take. Twice the price of Seedance 2.0. > **Note:** Content policies frequently block reference images containing humans, even innocuous ones. See Weaknesses below for workarounds. *** #### Strengths * **30-second one-takes**: Real narrative arcs in a single generation. Pair with video extension for up to 60s final output — minute-long ads in two passes. * **Duration-adaptive scripts**: Shortening the requested length compresses pacing instead of trimming beats. One master script declines cleanly into 30s / 20s / 12s / 8s cuts with no rewriting — the cheapest format-adaptation pipeline on any video model. * **Massive reference budgets**: Up to 30 image references, 10 videos (30s combined), and 10 audio clips (30s combined) per run. * **Lip-synced dialogue in 11 languages**: ZH, EN, ES, ID, MS most heavily optimized; TH, AR, PT, VI, JA, KO fully supported. On-screen text (signage, packaging, captions) can be forced to a target language. * **High-precision editing**: Replace, add, or remove elements in a time window while everything else stays untouched. Audio can be edited independently of visuals. * **Negatives that hold**: "No subtitles, no background music" finally sticks, with the right syntax (see below). #### Ideal use cases * **UGC-style and multi-register spots**: One character across wildly different visual styles via text-only casting. * **Video ads**: 30s TV cut, 15s pre-roll, and 8s paid social from one master script. * **Localized campaigns**: Single-master, multi-market declination with native lip-sync and forced on-screen text language. * **Product films**: Staged, multi-beat narratives with consistent identity and set. * **Surgical video edits**: Swap an object, strip the music, keep everything else frame-identical. #### **Weaknesses** * **Human reference images trip content policies often**, even innocuous ones (headshots, lookbook photos). Workarounds: describe characters in text with a `[CHARACTER]` block; when the exact face is mandatory, use a clean single-subject, neutral-background image and budget re-rolls. * Practical reference limits sit slightly below the on-paper caps: 1–8 distinct subjects from images, 1–5 from video, reference clips of 5–10s, edit sources under 20s. Past these, results can get lottery-like. *** ### How to use effectively **Write a shot plan, not a paragraph.** Structure every prompt as a timeline: `[0-Xs] [action]. End state: [landing frame].` One main action per window — stack two and the model picks one, or blends both badly. **Name references by their order.** Bind each asset with its ordinal (`@Image 1`, `@Image 2`, `@Video 1`) matching input order. **Give every reference a role.** One binding line per asset: `@Image 1 defines 's face, glasses, and denim jacket. Do not use the background.` Several angles of one character means several images, never a collage.
**End states carry continuity.** Each beat's closing frame is what the next beat inherits. Omit it and props teleport, poses reset. **Lock identity explicitly.** Close every prompt with character, wardrobe, and set layout. On long runs: `same face, same hairstyle, same outfit, same body type for the entire video`. **Treat windows as budgets.** A cramped window gets a rushed beat. Size each window to the action; the model paces itself inside it. **The music kill switch.** A plain "no music" often loses. The only directive that reliably holds: `[SOUND] Strictly only naturally occurring sound and foley, no music allowed.` **Write transitions as directives.** `→ WHIP PAN RIGHT on her turn, smears to white, hard cut.` Undescribed junctions are where objects appear and vanish. **Extend conservatively.** Use your base video as a reference and describe only the new material: `Extend the video naturally, [new content only], smooth motion continuity, no hard cuts, nothing appears out of thin air.` The base footage is never regenerated. Ceiling: 60s final. **Audio syntax**: `(music)` · `` · `{dialogue}` · `【subtitles】`. For non-English lines, state language and accent before the dialogue. # Seedance 2.0 A frontier video generation model developed by ByteDance. Direct contender to Kling 3.0 and Veo 3.1. ## Overview **Evolution from** [**Seedance 1.5 Pro**](/models/video-models/seedance-1.5-pro)**:** Key upgrades include up to 15-second generations, native audio with lip-syncing capabilities in 8+ languages, precise text and graphic animation, and a structured prompt format. Available in three versions: * **Seedance 2.0** (highest quality) * **Seedance 2.0 Fast** (faster, cheaper — good enough for most use cases) * **Seedance 2.0 Mini** (an even faster version) > **Note:** Some content policies are still being progressively rolled out. You may encounter restrictions when using human face references as image inputs. *** #### Strengths * **Text & graphic animation**: Animates text, logos, and graphic elements with high fidelity — most video models can't do this. * **Precise prompt adherence**: Follows structured prompts with timestamps accurately. * **Native audio & lip-sync**: Phoneme-level lip-sync across 8+ languages. Dialogue, SFX, and music in one pass. * **Up to 15s generation**: Real narrative development in a single clip. * **Up to 4K resolution**. #### Ideal use cases * **Static ad animation**: Turn finished static ads into video with element-by-element text and graphic animation. * **Motion design**: Kinetic typography, graphic transitions, animated brand assets. * **Video ads**: Multi-cut product videos with consistent branding across shots. * **UGC-style content**: Realistic spokesperson videos with multi-angle cuts and natural dialogue. * **Product explainers**: Detailed human-environment interactions for social content. #### Weaknesses * Content policy restrictions on human face references in image inputs (being progressively lifted). * Character consistency limited for persistent faces across multiple generations. *** ## How to use effectively **Be specific — control every detail.** If your prompt is short, Seedance makes creative decisions for you. Specify camera position, describe the opening frame, choreograph the action, define the ending state. **Use the structured format for complex animations.** For anything with more than two or three moving parts: Task → Overall Motion → Scene → Action (numbered timeline with timestamps). **Tell it what stays still.** Say "the background remains static" or "all elements hold perfectly still after settling." Seedance tends to keep things drifting unless you explicitly stop it. **Text animation tips.** Quote text exactly. Stagger multiple text blocks by 0.3–0.5s. Keep motion simple (fade in, slide in, scale in — avoid rotating). Lock text once it lands. End your prompt with a "Final on-screen text" section listing every visible text element. # Flux 3 Black Forest Labs' first video model. Direct contender to Seedance, Kling and Veo families. ## Overview Black Forest Labs' first cinematic video model: 20-second single-pass clips with native audio, frame-accurate lip-sync in 13+ languages, and keyframe control inside a single generation. The step change is not resolution or motion quality alone. Picture, sound, dialogue, and camera choreography resolve in one pass. No separate audio model, no sync step. > **Note:** Flux 3 takes keyframes, not references. There is no subject or style reference input — control comes from frames placed on a timeline. If you need reference-driven consistency, use Seedance 2.5 or Seedance 2.0. *** #### **Strengths** * **20-second one-takes**: Single generation, no cuts, no stitching. Subjects and geometry hold across large temporal jumps (day to night, season turn). Clips can be chained past 20s. * **Native audio in the same render**: Sound is not a second model and not a post-sync step. Events arrive carrying their own sound on the exact frame. * **Multilingual dialogue with lip-sync**: 13+ languages including English (multiple dialects), French, Spanish, Chinese, Japanese, German, Portuguese, Russian, Italian, Indonesian, Turkish, Hindi, and Punjabi. Mixed-language scenes hold in one take. * **Keyframes as a control surface**: Set a start image, an end frame, or multiple keyframes inside a clip. The model interpolates between them while holding the intended visual language. * **Camera behavior**: Orbits, dolly moves, focus racks, and tracking shots preserve parallax and scene geometry through continuous movement. * **Aesthetic range**: Distinctive spike on nostalgic, retro, and vintage registers — 16mm film grain, archival looks, period-accurate texture. #### **Ideal use cases** * **Cinematic ads**: TV-grade spots with picture, score, and dialogue delivered as one asset. * **Stop-scrolling creative**: Viral-register content in the Sora 2 family, with more directorial control. * **Multilingual campaigns**: One master scene, localized dialogue with accurate lip-sync per market. * **Frame-locked production**: When specific moments must land exactly, set them as keyframes and let the model resolve the space between. #### **Weaknesses** * **Keyframes, not references**: Flux 3 takes frames placed on a timeline rather than reference images for subjects or style. Consistency across separate generations requires reusing keyframes, not references. * **Render time is a few minutes per generation**: Rules it out of fast iteration loops. Explore in a quick model (Gemini Omni Flash, Grok Imagine), then commit the finished idea to Flux 3. * **Longer clips reward longer prompts**: 20 seconds means more decisions, and the model makes the ones you leave open. Underspecified prompts drift. *** ## How to use effectively **Word order is weight.** The model reads the prompt front to back; put the subject and core action first, style and atmosphere after. **Declare absences explicitly.** There are no negative prompts. Instead of "no music", write what is present: "only ambient street sound and footsteps." **Quote dialogue verbatim, with a visible speaker.** Name who talks, put the line in quotes, state the language and accent if not obvious. **Layer audio with verbs, not adjectives.** "Rain hits the awning, a bus hisses past" beats "moody urban soundscape." **Keyframes carry the moments that must land.** Set the frames that have to be exact; size the space between them to the action and let the model pace itself. **Use camera language.** Locked-off, push-in, pull-back, orbit, tracking — the model executes professional cinematography vocabulary literally. # Kling 3.0 A frontier video generation model developed by Kling. ## Overview **Evolution from** [**Kling 2.6**](/models/video-models/kling-2.6)**:** Key upgrades include modular and extended duration (3s → 15s), native multi-shot generation (up to 6 shots), native audio with dialogue and sound effects, stronger subject consistency, and better text preservation in imagery. ### Strengths * **Multi-shot generation**: Create videos with multiple shots with custom duration, framing, dialogues and camera movements per shot. * **Cinematic language**: Understands professional terminology (tracking shots, POV, shot-reverse-shot, macro close-ups, etc.). * **Up to 15-second duration**: Real narrative development in a single generation, with flexible control from 3–15 seconds. * **Stronger consistency & audio**: * Characters, objects, and text (logos, signage) stay stable across shots and camera movements. * Dialogue, ambient sound, and sound effects generated in sync with visuals. * **Better text rendering**: Logos, captions, and branded elements remain sharp and readable throughout the video. * Handles **Start Frame / End Frame**. * **Up to 4K resolution**. ### Ideal use cases * **E-commerce videos**: Professional product shots, sometimes with readable branding and text overlays. * **Narrative ad campaigns**: Complete story arcs with consistent characters and dialogue. * **UGC-style content**: Realistic dialogue-driven videos with natural sound design. ### **Weaknesses** * Premium pricing compared to Kling 2.6 and other competitors. * Language support: works great with English, Spanish, Chinese, Japanese, Korean * Requires more detailed prompting for best results. * Longer generation times for complex multi-shot sequences. *** ## How to use effectively #### **Model versions** This model is available in four versions: * **Standard and Pro**, as usual with Kling models. Use Pro only when you need maximum output quality. * **Elements:** Designed for maximum subject consistency. Each element = one product or one character. Provide a frontal view and optionally side views for best results. Use this when identity preservation across generations is critical (e.g., product catalogs, character series). * **Motion Control**: Gives precise control over camera movements and subject motion in video generation. Use when you need specific trajectories, angles, or choreographed movement rather than relying on the model's default motion interpretation. #### Prompting **Think in shots, not clips.** Describe each shot as part of a sequence. Label shots clearly with framing, subject, and motion. **Anchor subjects early.** Define characters at the beginning and keep descriptions consistent across shots. The model locks in key traits and maintains them throughout. **Describe motion explicitly.** Specify how the camera behaves: tracking, following, freezing, panning (not just what's in the frame). **Use native audio intentionally.** Indicate who is speaking and when. Add tone descriptions for realistic dialogue: ``` [Character A: Lead Detective, controlled serious voice]: "Let's stop pretending." [Character B: Prime Suspect, sharp defensive voice]: "I already told you everything." ``` # Gemini Omni Flash Google's lasted model for video generation and editing. ### Overview Generates from text, image, and video inputs, and lets you refine results through natural language. Best suited for short clips and iterative editing. Caps at 10 seconds. Prefer [Seedance 2.0](/models/video-models/seedance-2.0) or [Kling 3.0](/models/video-models/kling-3.0) for longer durations or production-grade cinematography. #### Key updates * **Multimodal referencing:** Combine text, image, and video inputs in one generation to control composition and maintain consistency. * **Conversational video editing:** Refine and edit videos using natural language, no need to re-generate from a full prompt for small changes. * **Real-world knowledge:** Draws on Gemini's general knowledge (history, biology, narrative logic) to construct more coherent scenes. #### Weaknesses * **10-second cap:** Generations are limited to 10 seconds; longer durations are planned but not yet available. * **Limited aspect ratios**: 16:9 or 9:16. * **Video reference limitation:** Short video references (up to 3s) are accepted by the request schema but aren't correctly processed by the model yet. * **Consistency across scene changes:** Character consistency can degrade during scene changes or panning movements. # Google Veo3.1 A frontier video generation model developed by Google, building on Veo3 with enhanced control and audio capabilities. ## Overview Veo3.1 extends Veo3's photorealistic capabilities with powerful new features: * native audio generation (dialogue, sound effects, music) * First/last frame control for precise transitions * "Ingredients"-based workflows for maintaining consistency across multiple shots Use Veo3.1 when you need complete audio-visual control, multi-shot sequences with consistent characters, or professional-grade video narratives. *** ### Strengths * Complete control over audio-visual narrative through structured prompting * Character and scene consistency across multiple shots using several reference images * Professional cinematography language for precise camera control * Natural dialogue and sound integration without separate audio tools * Multi-shot scene creation within single generations for narrative campaigns ### Ideal use cases * **Narrative ad campaigns**: Create complete story arcs with consistent characters and audio * **Product explainer videos**: Multi-shot sequences showcasing products with professional narration * **Brand storytelling**: Cinematic sequences that maintain visual identity throughout * **UGC-style content**: Realistic dialogue-driven videos with natural sound design * **Social video series**: Consistent characters across multiple episodes * **Testimonial-style ads**: Authentic-feeling videos with scripted dialogue ### Weaknesses * Premium pricing due to advanced features * Longer generation times for complex multi-shot sequences * Requires detailed prompting knowledge for best results * Limited duration options *** ## How to use effectively #### Model versions This model is available in two versions: * **Veo3.1**: Highest quality, best for complex prompts and multi-shot sequences. Premium pricing. * **Veo3.1 Fast**: 2x cheaper, faster generations, suitable for simpler prompts. Still high quality for most use cases. #### Prompting
Veo3.1 Prompting Formula Veo3.1 performs best with structured prompts following this pattern: **Cinematography + Subject + Action + Context + Style & Ambiance** This formula gives you granular control over every aspect of generation: **Cinematography**: Define camera work and shot composition * Camera movement: dolly shot, tracking shot, crane shot, aerial view, slow pan, POV shot * Composition: wide shot, close-up, extreme close-up, low angle, two-shot * Lens & focus: shallow depth of field, wide-angle lens, soft focus, macro lens, deep focus **Subject**: Identify the main character or focal point * Be specific about appearance, clothing, and distinguishing features **Action**: Describe what the subject is doing * Use active verbs and specific movements **Context**: Detail the environment and background elements * Location, time of day, weather, surrounding objects **Style & Ambiance**: Specify artistic direction and mood * Visual style, lighting quality, color palette, era references **Example Prompt**: "Close-up shot, a young chef in a white apron, carefully drizzling golden olive oil over a vibrant caprese salad, in a sunlit rustic kitchen with exposed brick walls and hanging copper pots. Natural morning light streams through a large window, creating soft shadows. Warm, inviting aesthetic with rich color saturation, shot on modern cinema camera."
Audio Direction Control the soundstage with specific audio cues in your prompts: **Dialogue**: Use quotation marks for specific speech * Example: *A woman says, "We have to leave now."* **Sound Effects (SFX)**: Describe sounds with clarity * Example: *SFX: thunder cracks in the distance* **Ambient Noise**: Define the background soundscape * Example: *Ambient noise: the quiet hum of a starship bridge* Audio is automatically generated based on visual content and your prompt specifications.
First and Last Frame Transitions Create smooth transitions between two scenes: 1. Generate your starting frame using another image model 2. Generate a complementary ending frame with a different POV or angle 3. Use Veo3.1's First and Last Frame feature to create the transition video 4. Include dialogue or audio cues in your prompt Example use case: Singer transitions from front-facing close-up to behind-the-shoulder stage view with lyrics as dialogue.
Timestamp Prompting (Advanced) Create multi-shot sequences with precise timing within a single generation: Format: `[HH:MM:SS-HH:MM:SS] Shot description with cinematography, action, emotion, and SFX` Example: ``` [00:00-00:02] Medium shot from behind a young female explorer with a leather satchel and messy brown hair in a ponytail, as she pushes aside a large jungle vine to reveal a hidden path. [00:02-00:04] Reverse shot of the explorer's freckled face, her expression filled with awe as she gazes upon ancient, moss-covered ruins in the background. SFX: The rustle of dense leaves, distant exotic bird calls. [00:04-00:06] Tracking shot following the explorer as she steps into the clearing and runs her hand over the intricate carvings on a crumbling stone wall. Emotion: Wonder and reverence. [00:06-00:08] Wide, high-angle crane shot, revealing the lone explorer standing small in the center of the vast, forgotten temple complex, half-swallowed by the jungle. SFX: A swelling, gentle orchestral score begins to play. ``` This creates a cohesive multi-shot sequence in one generation with proper pacing and visual consistency.
Ingredients to Video (Multi-Shot Consistency) Maintain character and style consistency across multiple shots: 1. Generate your "ingredients" using an image model: character portraits, locations, style references 2. Upload these ingredients as reference images to Veo3.1 3. Prompt for different shots using the same characters and settings 4. Veo3.1 maintains visual consistency across all generated shots Example use case: Film noir detective scene with consistent character appearances across multiple camera angles.
#### Inputs * **Text only**: For generating new videos from descriptions * **Text + 1 Reference Image**: For image-to-video animation * **Text + 2 Images used with First frame and End frame parameters**: For transition videos between scenes * **Text + Multiple Reference Images used as first frame**: For ingredients-based sequences with consistent elements # Grok Imagine Video 1.5 xAI's image-to-video model. Takes a static image and brings it to life with realistic motion and built-in audio. ## Overview Fast and affordable, it suits both quick iteration and high-volume production for simple to advanced use cases. ### Strengths * **Director-level camera control**: Understands cinematic language — pan, tilt, dolly, orbit, tracking, aerial, handheld, push-in. * **Content-aware motion**: Adapts to the input — exaggerated physics for illustrated characters, 360° rotation for products, natural expressions for portraits. * **Native synchronized audio**: Visual and sound produced together — music, effects, ambience, and brief dialogue — with no separate audio editing step. * **Speed and cost**: Affordable enough to iterate freely and to run at volume. ### Ideal use cases * **Product showcases**: Turn a product shot into a 360° rotation or a hero turn with dramatic lighting. * **Video ad first frames**: Animate a static opening frame into a compelling motion intro. * **Character & mascot animation**: Bring illustrated brand characters to life with smooth motion. * **Social content**: Short clips with sound for Reels, TikTok, and feeds, in native vertical or square ratios. ### Weaknesses * **Image-to-video only** — every run needs an input image. For text-to-video, use Grok Imagine Video (non-1.5). * **720p ceiling** — no 1080p or 4K. * **Stability falls off with length** — 5–8s is reliable; 15s clips are more prone to artifacts. * **Preview release** — behavior and availability may change. *** ## How to use effectively The model already sees your image — prompt for motion, not description. **Key principles** * Describe the action, camera move, and atmosphere — not what's already in the frame. * Always specify a shot type and camera movement. * Use specific verbs with intensity modifiers ("racing past at high speed," not "car passing"). * Negative prompts are ignored — describe what you want instead. * Keep it to one subject, one action, one camera move; iterate in small steps. # Happy Horse 1.1 Alibaba's latest video generation model. ## Overview Generates video and synchronized audio together in a single pass with native multilingual lip-sync. Available in both **generation mode** (text-to-video, image-to-video, reference-to-video) and **video edit mode**. Best suited for dialogue-driven and performance scenes where audio-visual sync matters. Prefer Seedance 2.0 or Kling 3.0 for stronger realism, or 4K delivery. ### Key updates * **Native audio in one pass:** Generates dialogue, ambience, music, and Foley alongside the video itself, so sound stays in sync with motion without a separate audio pipeline. * **Multilingual lip-sync:** Matches mouth shapes to spoken phonetics across seven languages (English, Mandarin, Cantonese, Japanese, Korean, German, French). * **Reference images:** Takes up to nine reference images and keeps consistent faces, wardrobe, and identity across a cast, suited to multi-character and ensemble scenes. * **Generation + edit modes:** Works as a generation model (text/image/reference-to-video) and as a video editor, for refining existing clips rather than starting over. * **Nine aspect ratios:** Covers cinematic 21:9 through vertical 9:16 and square, plus 9:21, 5:4, and 4:5. ### Weaknesses * **Resolution cap:** Tops out at 1080p, no 4K tier, unlike Seedance 2.0 or Kling 3.0. # Sora 2 A frontier video generation model developed by OpenAI. ## Overview The most powerful AI video model with native audio generation and perfect lip-sync. Best for creating polished video content and powerful storytelling. ### Strengths * Native audio generation: dialogue with perfect lip-sync, sound effects, and ambient noise, all synchronized with video. * Strong prompt adherence: works well with both simple and detailed prompts, making it accessible for non-experts. * Excellent physics: realistic motion for objects, water, fabric, and character interactions. * Multi-shot consistency: maintains character appearance across different camera angles. ### Ideal use cases * UGC and vlog-style content for social media. * Talking head videos: product demos, testimonials, explainers. * Fashion editorial with dialogue and authentic movement. * Multi-shot storytelling with consistent characters. * Podcast and interview-style content. ### **Weaknesses** * Strict content policy: does not allow for reference images containing human beings, hence limiting consistency. * High cost per generation (but low cost per final asset) *** ## **How to use effectively** #### Model versions * Sora 2: Default, affordable version * Sora 2 Pro: Higher quality, 1080p resolution option, Additional ratios (1024x1792, 1792x1024), more expensive #### Prompting Sora 2 rewards clarity over complexity. You can succeed with simple prompts or go ultra-detailed for precise control. **For simple prompts:** * Set the style upfront: "UGC iPhone selfie, "90s documentary", "cinematic 35mm film" * Describe subject and setting * Add dialogue if needed **For detailed prompts and maximum control, layer these elements:** 1. **Format & Style**: Overall aesthetic (cinematic, UGC, documentary, fashion editorial) 2. **Camera**: Shot type (wide, medium, close-up), angle, movement 3. **Subject**: Appearance, wardrobe, props 4. **Location**: Setting with foreground, midground, background details 5. **Lighting & Palette**: Light quality, direction, and color anchors (3-5 specific colors) 6. **Actions**: Describe in beats or counts, small, specific gestures 7. **Dialogue**: Short, natural lines with speaker labels 8. **Sound**: Ambient noise, diegetic sounds (no music unless specified) **Pro tips:** * Keep one clear camera move and one clear subject action per shot. * For dialogue and scenes: use "time code prompting" (e.g., "\[0-2s]: Extreme close-up of a woman's eye \[2-3] Camera zooms out") * Use image input for product/character/setting consistency * Do not create prompt that are over 2,000 characters. Otherwise, they will get cut off. * Ask language models to write video prompts. Below a system prompt that works well:
LLM instructions for Sora 2 > #### Situation > > You are an expert video prompt engineer specializing in Sora 2 video generation. Your role is to transform user ideas into professional, production-ready video prompts that leverage Sora 2's full capabilities for creating cinematic, coherent, and visually stunning video content. > > #### Task > > The assistant should convert user input into detailed Sora 2 video prompts that specify style, cinematography, actions, timing, lighting, and audio elements. The assistant should structure prompts to maximize control over composition, movement, and aesthetic while maintaining clarity and avoiding ambiguity that could lead to inconsistent outputs. > > NB: > > You should only send back the raw prompt. > > #### Objective > > Generate video prompts that produce high-quality, consistent results on the first attempt by providing precise visual direction, clear action beats, specific camera instructions, and cohesive aesthetic guidance that matches the user's creative vision. > > #### Knowledge > > Core Prompt Architecture:\ > The assistant should structure prompts using this hierarchy:\ > Style declaration (aesthetic, era, film format, overall tone) > > Scene description (environment, characters, props, atmosphere) > > Cinematography (camera shot, lens, depth of field, lighting, mood) > > Actions (specific beats with timing, limited to 1-2 clear movements per shot) > > Dialogue (if applicable, brief and natural) > > Background sound (diegetic audio cues for pacing) > > Specificity Guidelines:\ > Replace vague descriptors ("beautiful," "quickly," "cinematic") with concrete visual details ("wet asphalt with neon reflections," "three steps then stops," "anamorphic 2.0x lens, shallow DOF") > > Describe actions in countable beats (e.g., "takes four steps, pauses, pulls curtain") > > Limit each shot to one clear camera move and one clear subject action > > Specify 3-5 color anchors to maintain palette consistency > > Use precise framing language: "wide establishing shot, eye level" rather than "good angle" > > Camera & Motion Control:\ > Frame types: wide establishing shot, medium close-up, aerial wide shot, over-the-shoulder > > Camera motion: slow dolly-in, tracking left to right, handheld ENG camera, slow arc > > Depth of field: shallow (sharp subject, blurred background) or deep focus (all planes sharp) > > Keep movement simple and singular per shot > > Lighting & Aesthetic:\ > Describe light quality and direction: "soft window light with warm lamp fill, cool rim from hallway" > > Specify lighting sources and their emotional impact > > Maintain consistent lighting logic across related shots > > Use color palette anchors (e.g., "amber, cream, walnut brown") > > Timing & Pacing:\ > 4-second clips accommodate 1-2 short dialogue exchanges or one complete action > > 8-second clips support a few more beats but should remain focused > > Describe timing explicitly: "in the final second," "pauses for two beats" > > Dialogue Integration:\ > Place dialogue in a separate labeled block below scene description > > Keep lines concise and natural > > Label speakers consistently in multi-character scenes > > Match dialogue length to clip duration, use timeframes if relevant > > For silent shots, suggest one small sound cue for rhythm ("distant traffic hiss," "crisp snap") > > Style Variations:\ > Ultra-detailed cinematic: Include format, lenses, filtration, grade, lighting setup, shot rationale > > Standard descriptive: Style + scene + cinematography + actions + dialogue/sound > > Simplified: Direct description with key visual elements (see Example 1-4 format) > > The assistant should adapt detail level based on user needs while maintaining clarity and specificity.\ > Examples\ > Example 1:\ > """tiktok style ugc ad featuring a white woman with curly blond hair wearing a blue velvet shirt at home, hand held pov introducing the perfume, warm tone sunlight through windows, cat jumping on lap and purring at the end"""\ > Example 2:\ > """instagram reel style chanel no 5 perfume ad, featuring a dark skin woman model with straight brown hair, orange warm tone background, cinematic soft high key lighting, slow motion"""\ > Example 3:\ > """instagram reel style chanel no 5 perfume ad, product show reel of perfume placed with props like twigs and leaves, orange warm tone background, cinematic high contrast lighting, slow motion, voice over introducing product\ > shot 1: still shot, dolly in on product\ > shot 2: extreme close up shot on bottle"""\ > Example 4:\ > """\[00:00-00:03] Man says in loser's voice:"I tell people I'm single by choice"\ > \[00:03-00:05] Close-up shot of a girl, who says: "Oh, your choice?"\ > \[00:05-00:07] Close-up shot of a man, who says: "No, theirs!"\ > \[00:07-00:09] Over the shoulder shot - in front of a man - a girl who looks sorry for him\ > \[00:09-00:10] Close-up shot of a man - he starts crying"""\ > Example 5:\ > """Style: 1970s romantic drama, shot on 35 mm film with natural flares, soft focus, and warm halation. Slight gate weave and handheld micro-shake evoke vintage intimacy. Warm Kodak-inspired grade; light halation on bulbs; film grain and soft vignette for period authenticity.\ > At golden hour, a brick tenement rooftop transforms into a small stage. Laundry lines strung with white sheets sway in the wind, catching the last rays of sunlight. Strings of mismatched fairy bulbs hum faintly overhead. A young woman in a flowing red silk dress dances barefoot, curls glowing in the fading light. Her partner — sleeves rolled, suspenders loose — claps along, his smile wide and unguarded. Below, the city hums with car horns, subway tremors, and distant laughter.\ > Cinematography:\ > Camera: medium-wide shot, slow dolly-in from eye level\ > Lens: 40 mm spherical; shallow focus to isolate the couple from skyline\ > Lighting: golden natural key with tungsten bounce; edge from fairy bulbs\ > Mood: nostalgic, tender, cinematic\ > Actions:\ > She spins; her dress flares, catching sunlight. > > Woman (laughing): "See? Even the city dances with us tonight." > > He steps in, catches her hand, and dips her into shadow. > > Man (smiling): "Only because you lead." > > Sheets drift across frame, briefly veiling the skyline before parting again. > > Background Sound:\ > Natural ambience only: faint wind, fabric flutter, street noise, muffled music. No added score.""
#### **Example prompts**
Simple UGC talking head > 90s documentary-style interview. An old Swedish man sits in a study and says, 'I still remember when I was young
Detailed UGC product video > Format & Style: UGC reaction video – authentic, handheld, shot on front iPhone camera. Unfiltered realism, slight overexposure. > > Camera: iPhone 15 Pro front camera in selfie mode. Handheld one-hand, slightly shaky with autofocus pulses. > > Main Subject: Woman, late 20s, expressive. Talking fast, gesturing with a water bottle, exaggerated facial expressions—never taking a sip. > > Wardrobe: Oversized white hoodie, messy hair, natural lighting on face. > > Location: Plain kitchen with daylight through blinds. Visible countertop, out-of-focus fridge in background. > > Lighting: Pure natural light from side window—unbalanced exposure, slight blue cast. > > Actions (0–12s): > > * 0–4s: Lifts bottle close to camera, eyes wide. 'Guys—look at this water. It's literally perfect!' > * 4–8s: Leans closer, whispers. 'I swear—it's so clear it looks fake.' > * 8–12s: Laughs, shakes bottle gently. 'I'm losing it.' > > Sound: Raw phone audio, room echo, fridge hum, breathy laugh. No music.
Fashion editorial > Format & Style: Cinematic fashion editorial – fast-paced studio shoot, glossy modern Vogue energy. > > Camera: ARRI Alexa Mini LF. Mix of dolly tracking, whip-pans, static bursts. > > Subject: Fashion model, bold presence. Structured black leather jacket, high-waisted satin pants, gold statement earrings. > > Location: Minimal studio, soft-gray wall, visible strobe umbrellas. > > Lighting: Strobe bursts + LED fill, warm-cool contrast. > > Actions (0–12s): > > * 0–2s: Model walks toward light, hair caught by fan. Flash burst. > * 2–4s: Turns sharply, hands on hips. Camera whip-pans. > * 4–6s: Close-up on eyes, gold earring swings. Flash burst. > * 8–10s: Leans on stool, fan lifts fabric. Circular camera arc. > * 10–12s: Final reveal, camera rises to eyes. Final flash. > > Dialogue: Photographer (off-screen): 'Yes—hold that! Turn! Flash!' > > Sound: Flash pops, shutter clicks, fan whoosh, fabric ripple. Muted house percussion at 120 BPM."
Comedic product pitch > Comedic cinematic ad – playful, self-aware, minimalist humor with polished commercial pacing. Tone: witty, confident, tongue-in-cheek charm. > > Main Subject(s): A bald man in his 40s, charismatic and expressive, delivering an over-the-top product pitch for a high-end hair dryer. His confidence and comic timing make the irony the central punchline. > > Wardrobe and Props: > > * Wardrobe: sleek black turtleneck, dark jeans, minimalist wristwatch – Steve Jobs-style simplicity. > * Props: shiny silver hair dryer (hero product), mirror, product box with branding, small display table. > * Secondary: microfiber towel, a plant and framed "Before & After" photo used for comedic effect. > > Location & Framing: Modern minimalist bathroom or product studio with clean white tiles and chrome fixtures. > > * Foreground: the hair dryer held up heroically. > * Midground: the bald man centered, confident. > * Background: mirror reflecting him and light bouncing softly from white walls. Camera alternates between tight product close-ups, medium waist-up presenter framing, and a final wide comedic pull-back. > > Lighting & Palette: Soft daylight-balanced key light from camera right; subtle rim light to define silhouette. Color anchors: silver, matte white, black, pale blue, and warm skin tones. Reflections polished but natural; slightly glossy highlights to make the product gleam. > > Continuity Rules: Consistent bright studio lighting, clean reflective surfaces, controlled soft shadows throughout. > > Actions & Camera Beats (0–12 s): 0–4 s — Medium shot: the bald man holds up the hair dryer dramatically, smiling straight into camera. He pauses for effect. 4–8 s — Close-up on the hair dryer's gleaming chrome and buttons; he rotates it slowly like a luxury watch commercial. 8–12 s — Wide pull-back reveals his completely bald head in the mirror behind him. He winks at the camera. Freeze on smirk.
# Seedance 1.5 Pro A frontier video generation model developed by ByteDance: generates video with synchronized dialogue, sound effects, and music in a single pass. ## Overview An excellent video model to generate audio and video simultaneously, no post-production sync needed. Creates perfectly lip-synced dialogue, natural foley, and ambient sound alongside cinematic video. Best for short-form drama, ad spots with voice-over, and any content requiring built-in narration or dialogue across 8+ languages. ### Strengths * **Native audio-video generation**: Dialogue, sound effects, and ambient audio created alongside video: lip movements stay locked to speech, foley stays locked to action. * **Multilingual lip-sync**: Accurate synchronization across English, Spanish, Portuguese, Japanese, Korean, Mandarin, Cantonese, and Indonesian. * **Cinematic camera control**: Full camera grammar: pan, tilt, zoom, dolly, orbit, tracking shots—described directly in your prompt. * **Character consistency**: Faces, clothing, and expressions stay stable across the clip even when camera angle changes. * Handles **Start Frame / End Frame** ### Ideal use cases * Product demos with narration and spatial audio * Talking-head content with accurate lip-sync * Short-form dialogue for TikTok, Reels, or YouTube Shorts * Ad spots with synchronized voice-over and ambient sound * Social teasers and trailers with integrated sound design * Multilingual campaigns without reshoots or redubbing ### Weaknesses * Limited to Chinese and English voice output (other languages auto-translate to English for voice) * Resolution limited to 720p * 12-second maximum duration *** ## How to use effectively #### **Prompting** Write your prompt like a shot description on a call sheet. Include scene, action, dialogue, camera movement, and audio/foley cues. **Prompt structure** * **Scene**: "Modern minimalist kitchen, morning light streaming through large windows" * **Action**: "A woman picks up the coffee mug and takes a sip, smiling with satisfaction" * **Dialogue**: Use quotes — `"This is exactly how I wanted to start my day."` * **Camera**: "Slow push-in from medium shot to close-up on her face" * **Audio/Foley**: "Coffee machine hum fading, soft morning ambience, ceramic clink" Be specific about camera behavior ("locked tripod," "handheld with subtle shake," "smooth orbit right") and include ambient sound cues for best results. # Grok Imagine Video A frontier video generation model developed by xAI, optimized for speed, cost, and creative iteration. ## Overview xAI's state-of-the-art video generation model with native audio capabilities. Animates still images into smooth video while preserving composition and subject identity. Optimized for length flexibility, speed, and cost compared to competitors like Kling, Seedance or Veo. ### Strengths * Highly flexible: video length from 1 to 15 seconds, wide range of aspect ratios. * Native audio generation (dialogue, sound effects) without separate tools. * Extremely fast generation, perfect for brainstorming sessions. * Supports prompt-driven editing to tweak clips without regenerating. * Versatile style interpretation: photorealistic, anime, and illustration. * Budget-friendly ### Ideal use cases * **Simple product animations**: Bring a still product shot to life with subtle motion. * **Campaign storyboarding**: Visualize concepts quickly before committing to production. * **Creative brainstorming**: Explore multiple directions simultaneously at minimal cost. ### **Weaknesses** * Lower resolution than premium models, requires upscaling for high-end production. * Limited control over fine details compared to models like Veo3 or Kling 2.1. # Kling O3/O1 The first unified video model for both video generation and editing. ## Overview Kling O models combines video generation and editing in one model. Generate from text or images, edit existing footage with prompts, and maintain character/product consistency across shots using Elements. #### O3 This model is an evolution of O1, following a similar architecture and prompt patterns. It exists in two versions (as often with Kling models): Standard & Pro. #### O1 This model exists in 3 versions: O1 for quick generation, O1 Edit for modifying existing videos, O1 Reference for maximum creative control with multi-image references. | | Kling 01 | Kling O1 Edit | Kling O1 Reference | | ----------- | ---------------------------------------------------------------------------- | -------------------------------- | --------------------------------------- | | Best for | Quick generation, first iterations | Editing existing videos | Advanced creative control | | Key feature | Start/end frame support | Text-based video editing | Up to 7 image refs (including Elements) | | Use when | You need fast, high-quality results from a reference image (or from scratch) | You want to modify video footage | You need maximum creative control | #### **Strengths** * Strong physics: natural motion, realistic cloth and water behavior. * Start/end frame support for cinematic transitions. * Easy video editing * Precise control with up to 4 image references and Elements (@syntax). #### **Ideal use cases** * **E-commerce b-rolls**: Automate product showcases with infinite variants. * **Seasonal campaigns**: Produce full video sets without a studio day. * **UGC-style content**: A/B test variations at scale. * **Mascot videos**: Consistent character storytelling with Elements. * **Post-production edits**: Swap outfits, change weather, remove objects, all via prompt. #### **Weaknesses** * Fine details (skin, small text) may require retouching. * Complex multi-character scenes can be less stable. * Results depend on clear, specific prompts. *** ## How to use effectively #### Model versions 1. **Use O1 Standard for most use cases.** Use start/end frames for controlled motion (when you need a specific camera move or transition). 2. **Edit videos with O1 Edit (instead of regenerate).** Shot 90% right but wrong lighting? Use o1 Edit to fix it with a prompt like "change to golden hour lighting" rather than starting over. Saves time and credits. 3. **Go further with O1 Reference.** If you need product or character consistency, skip straight to O1 Reference. Upload your assets as Elements and use the @syntax to place them precisely (e.g., "Put @product on a marble counter with soft morning light"). {% hint style="info" %} **Prompt O1 Reference like a pro** In your prompt, use @Image tags for reference images, @Element tags for consistent characters/products, and @Video tags for video references. The more specific you are about how elements interact, the better the result. Structure your prompt as: subject → movement → scene → camera. For example: *"The character from @Element1 walks through the cafe, picks up the coffee cup from @Element2, and takes a sip. Camera follows from behind, then orbits to a front close-up. Warm morning light, cozy atmosphere. Same style as @Image1."* {% endhint %} #### Inputs * O1: Text + Reference image * O1 Edit: Text + Reference Video (for motion transfer or editing) * O1 Reference: Text + Reference Image(s) or Video + Elements (characters, products) # Kling 2.6 A frontier video generation model developed by Kling: combines professional-grade cinematic video with native audio capabilities and advanced camera control. ## Overview First-ever Kling video model with native audio generation, creating complete audio-visual experiences. Creates synchronized voice, dialogue, sound effects, and ambient audio alongside video content. Best for product showcases, lifestyle vlogs, and any content requiring built-in narration or dialogue without separate audio production. ### Strengths * **Native audio-visual synchronization**: Generates perfectly matched dialogue, sound effects, and ambient sounds with video - eliminates need for separate audio production * **Image-to-audio-visual**: Transform static product images into dynamic videos with synchronized voice and sound * **Superior prompt understanding**: Accurately interprets complex creative briefs for coherent audio-visual output ### Ideal use cases * Product demonstrations with professional narration from static images * E-commerce product videos with voice descriptions and ambient sound * Social media content with built-in audio for Instagram, TikTok, YouTube * News-style announcements or updates with broadcast-quality narration * Music videos with synchronized singing or rap performances * Short fake UGC content: lifestyle vlogs, testimonials, unboxing videos with natural dialogue ### Weaknesses * Limited to Chinese and English voice output (other languages auto-translate to English for voice, visuals remain accurate) * Does not support separate start/end frames (single reference image only) * 10-second maximum duration * Video quality heavily dependent on input image resolution for image-to-video *** ## How to use effectively #### Principles Kling 2.6 follows similar prompting principles as [Kling 2.5](/models/video-models/kling-2.5), with adaptations required for sound and audio: * For English speech: use lowercase for normal words, UPPERCASE for acronyms (NASA, CEO) or brand names you want emphasized * Specify voice characteristics before dialogue: "\[Young Caucasian male, sunny voice]" or "\[African-American female host, cheerful voice]" * Add ambient sound instructions: "Background: Soft beauty BGM playing" or "accompanied by the gentle sound of vacuuming" * For music content, describe both the musical style and vocal delivery #### Examples
Product showcases In your prompt, describe both the product and the narrative: > *"In a beauty live-streaming room, warm yellow lighting illuminates the table, with lipstick samples displayed on either side. \[Caucasian beauty influencer] raises a matte dusty rose lipstick. \[Caucasian beauty influencer, sweet and fresh voice] says: 'Perfect for yellow undertones! Brightens the complexion without drying, and the finish looks beautifully soft all day.' Background: Soft beauty BGM playing."*
Lifestyle vlogs Describe the complete scene including environment, character actions, and emotional tone. Specify camera style explicitly: > *"The camera is in vlog close-up style" or "selfie perspective with natural hand movement." For dialogue, write exactly what should be said in quotes within your prompt - the model will generate natural delivery with appropriate pacing and emotion.*
Multi-character dialogue Structure your prompt to clearly distinguish speakers. Use character descriptions before each line of dialogue. For Interview or conversation formats: "\[Character 1 description] says: '\[dialogue].' \[Character 2 description] responds: '\[dialogue].' The camera \[movement description]." The model handles turn-taking naturally when you provide clear speaker attribution.
# Kling 2.5 A frontier video generation model developed by Kling: professional-grade cinematic video with advanced camera control. ## Overview Professional-grade cinematic video generation with advanced camera control and emotional storytelling. Best for narrative content requiring precise direction and realistic physics, without burning credits. ### Strengths * **Advanced camera control** with precise shot types (Dutch angles, tracking shots, drone shots). * **Realistic physics**: natural handling of gravity, shadows, and reflections. * **Wide style compatibility**: photorealistic to 2D anime, illustrations, or painterly styles. * **Stable static shots**: excels at fixed-angle compositions with intentional movement. * **Strong prompt adherence** for cinematic details. * **Emotional depth**: nuanced expressions and body language for narrative content. ### Ideal use cases * Cinematic brand storytelling requiring emotional resonance. * Fashion and lifestyle videos with editorial camera work. * Anime-style videos and illustrated content. * Product videos with controlled camera movements. ### **Weaknesses** * No built-in audio generation. * Complex prompts may require retries. * Does not allow for end frame (vs Kling 2.1 Pro) *** ## **How to use effectively** Structure your prompts with these key elements for best results:
CategoryOptions
Shot SizeWide angle · Medium shot · Close up · Extreme close up · Overhead
LightingSoft · Hard · Warm · Overcast · Sunlit · Silhouette
Camera AngleOver the shoulder · Drone shot · POV · Dutch angle · Tracking shot
Camera MovementMoves left · Dolly zoom in · Pulls back · Static · Handheld
Visual EffectsSlow motion · Camera blur · Lens flare · Time lapse
EmotionHappy · Sad · Angry · Fearful · Surprised · Determined
**Pro tips:** * Be specific about action, style, and camera work. * For image-to-video: describe what should happen, not just what's visible. * Layer descriptions: combine lighting + camera work + emotion for cinematic quality. * Use clear camera language: "zoom in," "wide shot," "overhead angle." ### **Example prompts** **Fashion video:** "A fashion photoshoot inside a pristine white studio. A woman poses confidently, holding a luxury designer bag. The camera employs a dramatic Dutch angle, tilting off balance. Camera rotates vertically around her. Bright diffused lighting highlights textures. Sleek, modern, editorial mood." **Anime style:** "Japanese anime style. A girl with long flowing hair stands on a windy hilltop, cherry blossoms swirling through the air. Camera begins with a wide shot, then slowly zooms in. Soft pastel colors, pinks, light blues, gentle whites, evoking beauty and melancholy." **Product physics:** "A shiny marble ball rolls down a grand stone staircase. Camera follows in a dynamic tracking shot, capturing gentle bounces from step to step. Reflections ripple across the marble's surface. Natural sense of gravity and momentum." # Hailuo 2.3 A frontier video generation model developed by Hailuo, specializing in e-commerce and product-focused content. ## Overview High-quality product videos with lifelike motion and polish. Best for simple e-commerce content and dynamic character animations. ### **Strengths** * Strong prompt adherence for both text and visual instructions. * Advanced physics simulation for realistic fabric, fluid motion, and crowd scenes. * Refined facial expressions and human anatomy rendering across diverse groups. * Faster generation times (at least with the fast version) ### Ideal use cases * Product advertisements for fashion, accessories, tech gadgets, beauty, and lifestyle products. * Anime and illustrative style videos with precise artistic control. * Character-driven narratives requiring emotional depth. * Viral content with choreography components. ### Weaknesses * May still require post-production polish for highest-end commercial work. * Complex multi-product comparisons can be challenging. * Text overlays within generated videos may need verification. *** ## Model parameters #### **Model versions** This model is available in two versions: * **Standard:** Highest quality where realism matters most. Best for final deliverables. * **Fast:** Optimized for speed while maintaining strong quality. Perfect for previews, rapid iteration, and short-form social content. #### **Inputs accepted** * Text * Text + 1 Reference Image (starting frame) #### Output characteristics * **Default Resolution:** 1080p * **Duration options:** 6s, 10s # Previous generation video models Earlier models, kept available for existing workflows. For new work, start with the recommended models above. [Google Veo3](/models/video-models/previous-generation-video-models/google-veo3) [Kling 2.1](/models/video-models/previous-generation-video-models/kling-2.1) [More video models](/models/video-models/previous-generation-video-models/more-video-models) # Kling 2.1 A video generation model developed by Kling: fast and affordable video animation from images. ## Overview Best choice for animating existing images into videos quickly and cost-effectively. Great for product shots, simple lifestyle scenes and mascot animations. ### Strengths * **Speed and cost**: Fastest video generation with budget-friendly pricing. * **Clean product animation**: Crisp product close-ups without visual artifacts. * **Reliable camera motion**: Smooth, natural camera movements and physics. * **Consistent animation**: Excellent at bringing static images to life while maintaining visual consistency. ### Ideal use cases * **Product videos**: Animate product photos into dynamic showcases and demonstrations. * **B-roll content**: Create supporting video content from existing brand imagery. * **Mascot animation**: Bring brand characters and mascots to life from static illustrations. * **E-commerce videos**: Convert product photography into animated showcases for online stores. * **Social media content**: Transform static posts into engaging video content for better reach. ### Weaknesses * Struggles with complex, multi-element scenes * May alter fine details like skin textures or small text on products * Limited to relatively simple animations * Does not handle sound/voice, needs to be coupled with a dedicated node *** ## How to use effectively Structure your prompts with these key elements for best results: 1. Subject + Description: "Woman in red jacket" or "Sleek smartphone" 2. Movement: What action happens - "rotates slowly," "bounces gently," "glides forward" 3. Scene + Setting: Where it happens - "on marble surface," "in modern kitchen" 4. Camera work: "Close-up shot," "tracking movement," "low-angle view" 5. Lighting/Mood: "Soft morning light," "dramatic shadows," "bright studio lighting" **Pro tips:** * Be specific but natural: Write like you're describing a scene to someone * Focus on one main action: Multiple movements can confuse the model * Use cinematic language: Camera angles and lighting descriptions improve quality * Start simple: Basic prompts often work better than overly complex ones ### Example prompts * "Close-up tracking shot: The smartphone slowly rotates on a white surface, camera circles around showing all angles, soft studio lighting" * "Low-angle view: The mascot character waves enthusiastically at the camera, bright cheerful lighting, studio background" * "Side tracking shot: The product moves forward across a marble counter, camera follows smoothly, warm natural lighting" *** ## Model parameters ### **Versions** This model is available in three versions: * **Standard:** Fastest and cheapest version of the model, lower output resolution (720p) * **Pro:** Best for animation of a starting frame (product shots, lifestyle videos, mascot). * **Master**: Best for animation of a starting frame when Kling 2.1 Pro falls short. Most workflows work great with the Pro version. ### **Inputs accepted** * Text + 1 Reference Image (starting frame) ### Output characteristics * **Default Resolution:** * 720p for Standard * 1080p for Pro & Master * **Duration options**: 5s or 10 s * **Available Aspect Ratios:** 1:1, 16:9, 9:16 # Google Veo3 A frontier video generation model developed by Google: creates hyper-realistic videos with integrated audio. ## Overview The most realistic video generation model available. Perfect for creating cinematic content when photorealism and natural audio matter most. ### Strengths for marketers * **Unmatched realism**: Most natural motion, lighting, and physics of any video AI model. * **Built-in audio**: Native voice, music, and sound effects eliminate need for separate audio production (and Pletor node). * **Complex scene handling**: Manages character consistency through visual references, multi-character scenes and intricate visual storytelling. * **Cinematic quality**: Professional-grade output suitable for high-end campaigns. ### Ideal use cases * **High-end video content** when you want maximum realism and integrated sound. For example: * AI UGC & vlog-style content * Podcast and interview content * Lifestyle ad creatives * **Unlock quirky ways** to express your brand (see trends: street interviews, ) ### Weaknesses * Most expensive video model available * Slower generation times (can take several minutes) * Sometimes adds unwanted subtitles to videos *** ## How to use effectively Veo3 excels with detailed, descriptive prompts. Include these elements: 1. **Visual style**: "Cinematic," "documentary style," "stop-motion," etc. 2. **Scene details**: Lighting, environment, atmosphere 3. **Character descriptions**: Appearance, clothing, expressions 4. **Audio elements**: Specific sounds, dialogue, music style 5. **Camera work**: Shot types, movement, angles **Pro tip**: Use "CUT." in your prompt to switch camera angles or change actions within the same video. ### Example prompts * "Cinematic close-up of a barista crafting latte art, steam rising, espresso machine humming in background" * "Documentary style: A tech entrepreneur explaining their app in a modern office, natural lighting, confident tone" * "Stop-motion animation: Coffee beans dancing on a wooden table, playful jazz music" ### With reference images: * "Create a product demonstration video using this lifestyle photo as the starting frame" * "Generate a talking head video starting from this portrait image" * "Cinematic close-up of a barista crafting latte art, steam rising, espresso machine humming in background" * "Documentary style: A tech entrepreneur explaining their app in a modern office, natural lighting, confident tone" * "Stop-motion animation: Coffee beans dancing on a wooden table, playful jazz music" ### Advanced prompting with structured format For complex productions, consider using structured prompting with JSON-like formatting: **Why structured prompts help:** * Better organization of complex scene elements * More precise control over cinematography and audio * Clearer separation of visual and technical requirements * Reduced ambiguity in multi-element scenes **Structure example:** ``` { "description": "Main scene description and action", "style": "cinematic, nostalgic", "camera": "fixed wide angle, 50mm lens", "lighting": "warm natural lighting with soft highlights", "audio": { "music": "gentle acoustic", "sfx": "specific sound effects" }, "motion": "specific movement descriptions" } ``` *** ## Model parameters ### **Versions** This model is available in two versions: * **Standard:** High quality, very expensive * **Fast:** Lower quality, 2x cheaper, faster generations Fast is a good as Veo3 in many cases. Opt for Veo3 Standard for your most complex scenes. ### **Inputs accepted** * Text * Text + 1 Reference Image (starting frame) ### Output characteristics * **Default Resolution:** 1080p * **Duration options**: 8s * **Available Aspect Ratios:** 1:1, 16:9, 9:16 # Runway Gen4 A frontier video generation model developed by Runway: creates cinematic videos with consistent characters and objects. ## TL;DR Top choice for creating professional-quality videos with consistent subjects and movie-like camera work. Perfect when visual consistency matters most. ### Strengths for marketers * **Character consistency**: Maintains the same person, product, or mascot across different scenes and lighting conditions. * **Product consistency**: Place any product in multiple environments while keeping it visually identical. * **Cinematic quality**: Professional camera movements and scene control that rivals traditional filmmaking. ### **Ideal use cases** Scenarios where you have a specific visual you want to animate consistently: * **Product videos**: Show a product in various lifestyle settings with perfect consistency. * **Campaign variations**: Generate multiple scenarios with the same products for performance testing. * **Mascot animation**: Create consistent spokespersons or mascots across multiple video assets. ### Weaknesses * Requires a starting image (can't generate from text alone) * Struggles with overly complex multi-element scenes * Occasional visual glitches or hallucinations * More expensive than simpler animation models *** ## How to use effectively Gen-4 thrives on simplicity and focus. Start simple and build up gradually: 1. **Basic motion**: "The subject turns slowly" 2. **Add camera**: "The subject turns slowly as camera circles around" 3. **Add environment**: "The subject turns slowly as camera circles, dust swirling" 4. **Add style**: "The subject turns slowly as camera circles, dust swirling, cinematic" **Pro tips:** * Focus only on motion - let the image handle the visuals * Use "the subject" or "the product" instead of specific names * Say what should happen, never what shouldn't * Add one new element at a time when iterating ### Example prompts * "The subject turns slowly toward the camera and smiles" * "The product rotates gently while the camera circles around it" * "She raises her hand and waves at the camera" * "The camera slowly pulls back to reveal the full scene" * "The person on the left walks forward. The person on the right waves." *** ## Model parameters ### **Inputs accepted** * Text + 1 Reference Image (starting frame) ### Output characteristics * **Default Resolution:** 1080p * **Duration options**: 5s or 10s * **Available Aspect Ratios:** 1:1, 16:9, 9:16, 3:4, 4:3 # Runway Aleph A frontier video editing model developed by Runway: edits, varies and enhances video footage. ## **TL;DR** Amazing model if you need to edit or vary (AI-generated) video footage without traditional software or video/motion experts. ### **Strengths for marketers** * **Easy editing**: Turn basic or imperfect videos into professional marketing content with simple text prompts. * **Video variations**: Generate different camera angles and variations from a single video. * **Professional VFX**: Remove video backgrounds or add cinematic effects that normally require expensive equipment and specialized teams. ### **Ideal use cases** * **Product showcases**: Add your product to existing lifestyle footage or remove competing products or objects from scenes. * **UGC Ads & social media video content**: Create multiple camera angles from one video for different platform formats. * **Campaign variations**: Generate different versions of the same scene for A/B testing. * **Brand consistency**: Remove unwanted logos, signs, or elements that don't match your brand. ### **Weaknesses** * Only works with existing video (can't create from scratch) * Limited to 5-second clips * Auto-crops videos to fit supported formats *** ## **How to use effectively** Keep prompts simple with two parts: 1. **Action word**: "add," "remove," "change," "replace," "re-light" 2. **What you want**: Clear description of the change ### **Example prompts** * "Remove the person in the background" * "Add rain to the scene" * "Change the lighting to golden hour" * "Replace the blue car with a red one" *** ## Model parameters ### **Inputs accepted** * **Video file** (up to 5 seconds) + **Text prompt** * **Video file** + **Text prompt** + **Reference image** (for style/color guidance) ### Output characteristics * **Resolution**: 1280x720 (HD) * **Duration**: Up to 5 seconds * **Format**: Automatically crops to supported aspect ratios * 16:9 — 1280x720 px * 9:16 — 720x1280 px * 1:1 — 960x960 px * 4:3 — 1104x832 px * 3:4 — 832x1104 px * 21:9 — 1584x672 px # Hedra Character 3 A frontier video generation model developed by Hedra: creates realistic talking head videos with perfect lip-sync. ## TL;DR Best choice for creating talking head videos with realistic speech and expressions. Perfect for AI spokespersons, product explainers, and mascot videos ### Strengths for marketers * **Consistent faces**: Maintains character appearance throughout longer videos. * **Great lip-sync**: Realistic mouth movements that match any audio perfectly. * **Omnimodal processing**: Handles image and audio together for seamless integration. * **Complete control**: Provide your own script and voice for total creative control. ### Ideal use cases Any scenario where you want a face to speak directly to the camera: * **Talking mascots**: Bring brand characters to life with personality and voice (e.g., TikTok short clips). * **AI UGC content**: Create authentic-looking user testimonials and reviews. * **Product explainers**: Have spokespersons explain features and benefits clearly. * **Multilingual campaigns**: Use the same face with different language audio tracks. ### Weaknesses * Limited to talking head scenarios only, full-body movement less stable than facial expressions * Background typically remains static during generation * Requires separate audio file generation, limiting use cases *** ### How to use effectively Prepare well your inputs: provide clear portrait image (start frame), clean audio (script), and descriptive text (facial expressions). **Key tips:** * Use high-quality portrait images with clear facial features * Provide clean, clear audio files for best lip-sync results * Include text descriptions for desired expressions and mood * Keep scripts conversational for realistic delivery *** ## Model parameters ### **Inputs accepted** * Text + 1 Reference Image (starting frame) + 1 audio file (character voice) ### Output characteristics * **Default Resolution:** 720p * **Duration options:** 60s max - depends on the length of your script * **Available Aspect Ratios:** 1:1, 16:9, 9:16 # More video models Alternative models that can be useful in specific situations where cost-effectiveness and specialized capabilities matter more than cutting-edge features. ## Seedance Pro *Multi-shot storytelling leader* * **Strengths:** Great prompt adherence, native multi-shot capabilities with smooth transitions, cinematic camera movements * **Weaknesses:** Performance issues with complex prompts, no native audio * **Use cases:** Multi-shot marketing campaigns (e.g., UGC video), brand storytelling, educational narratives * **Specs:** 480p-1080p resolution, 5-10 seconds, multiple aspect ratios ## Runway Gen4 Video *Decent choice for creating professional-quality videos with consistent subjects and movie-like camera work.* * **Strengths:** Character consistency, product consistency, cinematic quality * **Weaknesses:** Struggles with overly complex multi-element scenes, occasional visual glitches or hallucinations, worse than other state-of-the-art model * **Use cases:** product videos (show a product in various lifestyle settings with perfect consistency), mascot animation (create consistent spokespersons or mascots across multiple video assets). * **Specs:** 1080p resolution, 5s or 10s, multiple aspect ratios ## Hailuo 2 Pro *Physics simulation specialist* * **Strengths:** Exceptional physics simulation and environmental effects (water, fire, smoke), strong character consistency * **Weaknesses:** No audio support, 10-second maximum duration, slower generation times * **Use cases:** Physics-heavy product demos, viral social content, educational physics content * **Specs:** 1080p resolution, 6-10 seconds, multiple aspect ratios ## Runway Aleph AI-powered video editing and variation model * **Strengths:** Easy text-based editing without traditional software, generates multiple camera angles and variations from single video, professional VFX capabilities (background removal, cinematic effects), simple prompt structure * **Weaknesses:** Requires existing video input (can't generate from scratch), limited to 5-second clips, auto-crops to fit supported formats * **Use cases:** Product placement in lifestyle footage, UGC ads with multiple camera angles, campaign A/B testing variations, removing unwanted logos or brand elements, adding VFX effects to existing footage * **How to use effectively:** Keep prompts simple with two parts: action word ("add," "remove," "change," "replace," "re-light") + clear description of the change. Example: "Remove the person in the background" or "Change the lighting to golden hour" * **Specs:** 1280x720 (HD) resolution, up to 5 seconds, auto-crops to supported aspect ratios: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9 ## Kling 2.0 *Extended duration image-to-video* * **Strengths:** Good image-to-video conversion, great character consistency * **Weaknesses:** Much slower generation times, superseded by newer Kling 2.1, struggles with text in videos * **Use cases:** Character animation * **Specs:** 720p native, 5-10 seconds, multiple aspect ratios ## Vidu Q1 *Budget-friendly video generation with animation focus* * **Strengths:** Fastest generation speed and lowest cost structure, excellent for anime-style content and character consistency * **Weaknesses:** Limited to 5-second clips only, less competitive photorealistic quality * **Use cases:** Social media content, anime/illustration videos, rapid prototyping * **Specs:** 1080p resolution, 5 seconds max, multiple aspect ratios # Lip sync models Synchronize audio with video for realistic speaking animations. Lip sync models take existing video footage and match it perfectly with audio input, whether that's recorded voice or AI-generated speech. This eliminates the complex technical work traditionally required for dubbing, multilingual content, or AI avatar creation. Use these models when you need to: * **Dub existing videos** into multiple languages while maintaining natural lip movements * **Animate AI-generated characters** or avatars with realistic speech * **Create talking head content** without filming actual speakers * **Edit dialogue in post-production** without reshooting footage * **Produce multilingual campaigns** using the same visual assets How to choose: * Animating a still image (character referecence, illustration, mascot) → **Veed Fabric 1.0** * Re-syncing existing video to new audio → **Sync Lipsync 2.0** * Portrait-based talking head when neither above fits → **Hedra 3** ### Veed Fabric 1.0 (Popular) *Image-to-video model that animates any image with speech-driven motion* * **Strengths:** Works with any input image that can "speak" (photos, illustrations, mascots, 3D renders), audio drives lip movements plus body/hand/head motion, fast generation for videos up to 1 minute, preserves original image style, combines well with AI voices. * **Weaknesses:** Generation time varies by resolution (1.5-5 minutes for 10-second clips), limited to talking/speaking scenarios * **Use cases:** Product explainer videos with avatars, Facecam UGC-like video content, animated mascot content, multilingual campaigns, podcast clips converted to video * **How to use effectively:** Upload any clear character or product image + provide audio recording or text script (auto-generates voice). * **Specs:** Up to 1 minute duration, resolution: 480p or 720p, aspect ratios: 16:9, 4:3, 1:1, 3:4, 9:16, scaled proportionally for other ratios (based on source image). * **Model versions**: Available in Fast mode for quicker generation. ### Sync Lipsync 2.0 *Lip sync model for realistic audio-visual matching based on a reference video and an audio file* * **Strengths:** Flawless lip sync animation, works with any character type (live-action, animated, AI-generated), preserves speaker's unique style across languages, editable dialogue in post-production * **Weaknesses:** Requires separate video and audio inputs, limited to lip sync functionality only * **Use cases:** Dubbing existing videos, multilingual content creation, AI avatar animations, post-production dialogue editing * **How to use effectively:** Connect your video input (from any video generation model) + audio file (script reading or generated voice) for seamless lip sync matching * **Specs:** Works with any video resolution, output length depends on audio input ### Hedra 3 *Talking-head generator from a portrait image. Lower performance than Veed Fabric.* * **Strengths:** Realistic lip-sync and facial expressions, good character consistency with starting frame, high control over voice and script, handles videos up to 60 seconds * **Weaknesses:** Limited to talking head scenarios, full-body movement less stable than face, background typically static, requires separate audio file generation * **How to use effectively:** Provide high-quality portrait image (starting frame) + clean audio file (script) + text description for desired facial expressions and mood. Keep scripts conversational for realistic delivery * **Specs:** 720p resolution, up to 60 seconds (depends on script length), aspect ratios: 1:1, 16:9, 9:16 # Audio models We integrate state-of-the-art audio models to transform your visual content with professional-grade sound. Audio is often the final piece of your workflow, adding the emotional depth and immersion that turns good content into exceptional content. Whether you're creating UGC videos, product explainers, social ads, or brand storytelling, the right audio transforms how your audience experiences your message. We've curated audio models that balance quality, speed, and control for different marketing needs. ## AI Speech Generate natural, expressive voice content with precise control over emotion, delivery, and tone. ### **ElevenLabs v3** The most expressive text-to-speech model available. ElevenLabs v3 delivers human-like speech with unprecedented emotional range and contextual understanding across 70+ languages. **What makes it exceptional:** * **70+ languages:** Maintain consistent voice quality and personality across all supported languages * **Audio tags:** Control emotion, pacing, and delivery with inline tags like `[excited]`, `[whispers]`, `[laughs]`, `[dramatic]` * **Multi-speaker dialogue:** Generate natural conversations between multiple characters with contextual awareness * **Emotional depth:** Full spectrum of human emotion from subtle nuance to dramatic performance **Best for:** * Explainer videos requiring emotional storytelling * UGC-style voiceovers with authentic human reactions * International campaigns requiring multilingual voice consistency * Podcast intros, outros, and ad reads **How to make the most of it:** 1. **Pick your voice:** Browse our curated voice library, we've shortlisted our favorite voices ("Pletor's picks") for faster selection and iteration:
2. **Test the voice:** Generate a short sample with your brand's typical messaging to verify fit 3. **Enhance with audio tags:** Use our dedicated [Creative Assistant](/build-agents/nodes/ai-nodes/text-assistants) to automatically structure your script with emotion and pacing tags (*or* [*read about them*](https://elevenlabs.io/blog/v3-audiotags) *yourself)*.
4. **Fine-tune:** Adjust the Stability parameter to control consistency (higher = more predictable, lower = more expressive variation) 5. **Couple it with the right video model**, depending on your use case (e.g., [Veed Fabric](https://docs.pletor.ai/ai-model-library/video-models/lip-sync-video-models#veed-fabric-1.0-popular) for UGC videos) *** ## AI Sound Add professional sound design to your video content without manual audio editing. ### **Mirelo 1.5** Mirelo 1.5 analyzes your video content and generates synchronized, professional-grade sound effects automatically, no sound design expertise required. Particularly valuable for AI-generated videos which typically output without audio (or with low quality audio outputs). Transforms silent content into immersive experiences. **What makes it exceptional:** * **Video-aware:** Analyzes visual action to generate contextually appropriate sound effects, with or without any text prompt * **Automatic synchronization:** Sound effects match video timing and intensity * **Long-form support**: Process videos up to 10 minutes * **Professional quality:** Studio-grade SFX without sound designers or audio libraries **Best for:** * (AI-generated) videos that need professional sound design (Sora, Veo, Kling outputs) * Social media content requiring attention-grabbing audio * Video ads where sound effects drive emotional response **When to use Mirelo 1.5:** Use when your video content lacks sound effects or requires professional audio post-production. {% embed url="" %} Mirelo 1.5 output sample {% endembed %} # Upscaling models We integrate the best upscaling models to ensure your assets are pixel-perfect and/or print-ready. Upscaling is often the final step in your workflow: transforming AI-generated images into high-resolution assets suitable for print, large displays, or professional campaigns. We've curated a selection of upscalers that balance quality, speed, and cost for different marketing needs.
ModalityUse caseTop performing models
ImageProduct photography & print assetsMagnific Precision Upscaler v2, Topaz Upscale, Enhancor Image Upscaler
ImageAI art & creative enhancementMagnific Creative Upscaler
ImagePortraits & peopleEnhancor Realistic Skin (v1 or v3)
ImageFast, cost-effective upscalingAuraSR
VideoBalanced upscalingFlashVSR Video Upscaler
# FAQ Quick answers on what Pletor does, how to build with it, and how to work as a team. ### New to Pletor
What can I do with Pletor? Two things: * **Produce assets:** images, video, text, and audio across a wide library of models, all from one workspace. * **Build systems:** agents that produce on repeat. Deploy them as Apps for your team, scale them with Batch, and connect them to your stack through MCP and the API.
Which models are available? Pletor orchestrates the best models across image, video, text, and audio: Google, OpenAI, ByteDance, Kling, Flux, Recraft, ElevenLabs, and more. Pick the right one per task without managing separate accounts. See [Models](/models/text-models).
How can I build good creative agents? Start from scratch, from a template or with a little help from AI. **The principles:** * Start simple. One clear job per agent. * Structure your inputs. A few well-defined inputs beat many loose ones. * Let text models with custom instructions do the heavy lifting. Strong prompting beats complex node graphs. * Pick the right model for the task. Validate the fit by producing a few variants. * Split into as many steps as you need control. Each step is a checkpoint. **The path:** * Pick a template. Browse Templates for your use case and run one as-is to see a result fast. * Customize in Studio. Adjust its nodes: inputs, models, brand, and logic. * When ready, scale your production with [Apps](/automate/apps), [Batch](/automate/batch), [MCP](/automate/pletor-mcp) & more.
How does pricing work? Pletor runs on a credit-led model across different [plans](/). Each plan includes a monthly credit allowance and a set of features. You spend credits as you produce. Visit [Billing & invoices](/how-to.../billing-and-invoices) for more.
### Building your creative system
How can I pick the right model for my need? * When in doubt, start with the go-to models. They handle most jobs well. * Browse the [model library](https://app.notion.com/p/lasqo-ai/LINK) to compare capabilities and pricing. * Otherwise ask the AI assistant. Describe your task and it will recommend a model.
How can I personalize my agents with my brand? Two levers: * **Brand system nodes**: static brand elements baked into the agent. They don't appear as inputs when deployed as an app. * **Your Brain**: set up your Brain once, then use it when building agents. Either through Brain nodes (synced with your Brain's content) or directly in chat by loading your Brain.
How can I iterate without burning credits? * Test with cheap, fast models first. Switch to premium models once the structure works. * Run single steps instead of the full agent while building. * Validate prompts with one output before producing variants. * Work at lower resolutions or shorter durations during drafts, scale up for finals.
How can I make others run my agents? Deploy them as apps. Anyone on your team can then run them through a simple, prompt-driven interface, no Studio access needed. See: [Apps](/automate/apps)
How can I integrate Pletor with external systems? Two ways: API or MCP. Use the API for programmatic integrations inside your own systems or through tools like n8n, Zapier, or Make. See: [API integrations](/automate/api-integrations) Use MCP for conversational integrations, connecting Pletor to agents and AI assistants like Claude. See: [Pletor MCP](/automate/pletor-mcp)
How do I connect Pletor's MCP to Claude? In Claude, go to Settings → Connectors and add a custom connector. Name it Pletor and use this server URL: `https://api.pletor.ai/mcp`. Once connected, Claude can run your Pletor agents directly: [Pletor MCP](/automate/pletor-mcp)
How do I get API access and an API key? API access is available on paid plans. Get your key in [Settings → API](https://app.pletor.ai/?settings=api).
What's the maximum input size in Pletor? 40 MB per file.
### Collaboration
How can I work with my team on Pletor? Collaboration happens at several layers: * **Shared workspace.** Agents and assets in your workspace are shared, everyone builds on the same foundation. * **Apps.** Deploy agents as apps so teammates can run them without touching Studio. * **Brain.** One shared Brain keeps everyone's output on-brand.
Can I invite my team to Pletor? Yes, on all paid plans. Invite teammates to your workspace and they can run your apps, or build alongside you in Studio.
Can I restrict which models my team uses? Yes. Model restrictions are available on Studio and Enterprise plans.
How do I keep a face/character consistent across video shots, and improve lip-sync?
# Copy of Creating with AI ### Quality & control
How do I keep outputs on-brand and consistent?
My product gets distorted, resized, or partially shown — how do I fix it?
How do I put text or my brand font on an image reliably?
How do I stop the model inventing things / control what I don't want?
Does the order of my reference images matter, and will it use all of them?
How do I control background (e.g. white or transparent) and aspect ratio?
### Volume & scale
How can I turn my agent into an app?
### Use cases
Can I add voiceover and background music together, and control volume?
How do I keep a face/character consistent across video shots, and improve lip-sync?
### Capabilities
How can I efficiently resize assets within Pletor?
What's the maximum video length and can I extend it?
What's the maximum input size?
Can I restrict which models my team uses
How do I connect Pletor's MCP to Claude?
How do I get API access and an API key?
# Techniques Practical recipes for consistent, production-grade output: products, characters, scenes, and sets. #### Photography
How to achieve product consistency across generations * Give it several views, not one. A single reference forces the model to imagine every angle it wasn't shown, and it will happily hallucinate a back or a side that doesn't exist. You can Lock the hard facts in a product reference sheet. Views tell the model what the product *looks like*; * Write anti-drift guardrails. For each product, name what the model tends to get wrong and correct it explicitly in the prompt * To do so, you can either : * Create various views of your product to feed the product shot agent * See : T01 - Creating Product Views * And / or collapse views into one reference sheet (easier to maintain) * See : T02 -
How to upscale an image in 4K * You can use the upscale-image node, there are three model providers : * Topaz: the all-rounder. Use it to enlarge an image while staying faithful to the original, with no creative reinterpretation. It's the safe default for clean upscaling; 4x is the reliable sweet spot where detail still holds together. * Magnific: various upscalers. Creative upscaler will improve colors, Rather than just adding pixels, it reconstructs and "reimagines" new detail, textures, and richer color, steered by a text prompt and sliders (Creativity vs. Resemblance). * Enhancor: use it to enhance skin realism. Use it to fix the plastic, waxy look of AI-generated faces: it rebuilds realistic pores, fine hair, and natural skin texture. Reach for it on portraits and close-ups where skin realism is the priority * Use NBP or NB2 in 4K mode or Use Seedream 4.5, or 5 Lite in 4K mode * Using these models with precise upscale instruction can do the job right * With any of these, a well-written, precise upscale instruction does the job, describe what to preserve and what to sharpen, and let the model render the high-res version.
How to maintain consistent characters / models across generations * Character consistency is achieved by giving the downstream model various views of the same person. Including front, side views. Close-ups on the face, etc. If the character has specific teeth, make sure to show him smiling in the views. In general, try to give to models as much context as possible about the person. * To do so, you can: * Create a reference sheet of the face of your character * Create a reference sheet of the body of your model * Then give the model several images of the same character, various views and expressions, with a focus on their face
How to keep color, lighting & camera consistent across a set * Using one key frame to define color, lighting and camera quality accross all frames * Generate one "environment frame" that nails the target look: color grading, lighting setup, camera quality. Then pass it as a reference for every other frame in the set, but scope it explicitly in the prompt to *light, camera and color grading only* (locked instructions), so it doesn't bleed into composition or subject. * Pre-prod with the right prompts and same model * Same model for the whole set, and a shared LOCKED block across all prompts: identical camera body/lens, focal length, aperture, lighting description, grading keywords. Only the VARIABLE part (subject, action, framing) changes between frames. * Exemple : * Post-prod all the images with the same image reference. Using reference frames for color grading * Run all outputs through the same post-prod pass using a single reference frame for color grading. This catches the residual drift that steps 1–2 can't fully prevent. * See T12 - * See T11:
How to build and reuse credible scenes / environments * Generate one hero frame of the place with no subject (or minimal subject): this defines the architecture, materials, light direction and mood. This becomes the canonical reference for the location. * From the master frame, generate complementary views, reverse angle, side view, detail shots, using it as reference. This coverage set proves (and enforces) spatial consistency: recurring elements like windows, furniture or landmarks must reappear coherently across views. * Wide 3/4 angles show floor, walls and ceiling lines converging. This is what sells the space as a real, navigable volume rather than a flat backdrop. Reserve frontal or tight framings for inserts once the geography is established.
#### Video
How to build strong video agents * Storyboard first: generate each key frame as a deliberate shot (framing, angle, moment) rather than hoping the model invents good coverage. Every frame should answer "what does this shot do in the edit?" - establish, action, reaction, insert. Example here: * Chain clips into seamless continuity: use the last frame of a clip as the first frame of the next (or first/last frame conditioning where the model supports it) so motion, light and geography carry over without a visible cut. * When the sequence needs rhythm (chase, montage, product reveal), use models that generate multi-shot sequences in one pass: Seedance R2V or Kling 3.0 handle the cuts internally, which keeps energy and coherence better than stitching independent generations. * Finish with a 4K upscale pass on the assembled video. Generation resolution is a working format — upscaling recovers sharpness, texture and grain uniformity across shots, and masks minor inconsistencies between clips.
How to keep a face/character consistent across video shots * Assemble the character's canonical views: clean face shots (frontal + 3/4), full body, and outfit details. This sheet is the single source of truth, every generation references it, never a previous output (copies of copies drift). * Feed the reference sheet into Seedance's reference-to-video: strong identity retention across shots and camera angles. * Same principle via Kling's Elements: pass the character as a persistent element that survives across generations.
How to generate realistic UGC videos * Start with the script: hook, message, CTA, in the target language. It defines duration, pacing and tone, everything downstream (voice route, performance, even framing) depends on it. Keep it spoken-word natural, not ad copy: UGC that reads like a brief sounds like a brief. * Create a character - Define your creator persona once: face, age, styling, vibe. This is the identity anchor that everything downstream references. * Generate a realistic UGC frame of your character - Place the character in a credible UGC context using the UGC preset: phone-camera look, imperfect framing, natural lighting, real-world setting. This frame sets the amateur aesthetic that sells authenticity. T04 - (preset = UGC) * For the voice : * Native model audio: let the video model generate speech directly — Seedance 2.0 handles many languages well, and native audio comes with lipsync and performance for free. * ElevenLabs voice changer: generate or record a guide track, then transform it with an ElevenLabs voice for full control over timbre and identity — useful when the voice must match a defined persona or stay consistent across a batch. * Use voice changer for audio - T08 - * Generate a realistic voice and micro expressions Sync the character to the VO with lipsync and micro-expressions (blinks, head tilts, hesitations). This is where realism is won or lost — flat faces read as AI instantly.
# Account
I can't log in First try the email login / password reset from the sign-in page. If you used a different method (e.g. Google) originally, use that same method. If it still fails, contact [support](https://tally.so/r/D4Kygl) with the email on your account.
How do I invite or add team members? Open [workspace settings](https://app.pletor.ai/?settings=members) → members and invite by email.
Can I change my authentication method? Not at the moment.
How do I delete my account? Send a delete account request by email to [support](https://tally.so/r/D4Kygl).
# Billing & invoices Manage your plan, credits, and payment details from one place: [**Billing settings**](https://app.pletor.ai/?settings=credits) #### Common questions
Where do I find my invoices? Open [Billing settings](https://app.pletor.ai/?settings=credits). Past invoices and receipts are listed there, downloadable as PDF.
How do credits work? Credits work as a prepaid balance: every run consumes credits, based on the models it uses. Your current balance and usage are shown in [Billing settings](https://app.pletor.ai/?settings=credits).
Do credits expire? It depends on your plan and credit types. * **Monthly credits expire**: unused monthly credits expire after a set time (depending on the [plan](https://www.pletor.ai/pricing)). "Use it or lose it." * **Top-up credits never expire**: these stay until used.
How do I buy more credits or change plan? Once you have a paid plan, you can [top up anytime](https://app.pletor.ai/?settings=credits). Switch plan [here](https://app.pletor.ai/?settings=plans).
How do I update my payment method? Go to [Billing settings](https://app.pletor.ai/?settings=credits), and click "Manage plan". You will then be able to change your payment details.
# Privacy & IP At Pletor, we treat all your data, personal data and creative inputs alike, with the highest standards of transparency, privacy, and security. We comply with the EU GDPR and France's Loi Informatique et Libertés. #### Common questions
Do I own outputs made with Pletor? You own all outputs created through your agents on Pletor. You may use, edit, and distribute them for both personal and commercial purposes, as stated in our Terms and Conditions.
Do you train models on my data? No. We do not use your inputs, outputs, or workflows to train any models, unless you give explicit opt-in consent (for example, when building custom or private fine-tuned models).
How do you handle transparency and traceability? We maintain a detailed record of all actions leading to output generation. This helps demonstrate the creative process in case of any disputes.
How do you use my data? We may use aggregated, anonymized metadata (such as workflow statistics and usage trends) to improve our platform. This does not include your content or identifiable data. We retain it only as long as necessary, in line with applicable laws.
Who is responsible for the inputs I use? You are solely responsible for ensuring that your inputs (e.g., images, text, data) do not infringe on third-party rights. Pletor is not liable for any copyright or intellectual property issues arising from your use of the platform. To reduce potential risks, we encourage the following practices: * Ensure you have the rights to all inputs used across generations. * Avoid prompts that reference specific artists, styles, or movements. * Consider post-editing images to further safeguard against infringement issues.
Can Pletor use my outputs for promotion? With your consent, we may showcase certain outputs for promotional or marketing purposes (e.g., in case studies or on our website). We will always ask for your approval before doing so.
Do you share or sell my data? No. We do not sell or share your data with unauthorized third parties. Only authorized personnel and trusted service providers may access your data for legitimate purposes.
#### Go further * [Pletor Trust Center](https://pletor-ai.notion.site/pletor-trust-center?source=copy_link) * [Pletor — Terms and Conditions of Services](https://www.notion.so/Pletor-Terms-and-Conditions-of-Services-279c9eaadd0d8098a0b9cd61e80c9e80?pvs=21) * [Pletor — Privacy Policy](https://www.notion.so/Pletor-Privacy-Policy-279c9eaadd0d8006b4a2d8918f923784?pvs=21) # Merge videos Combine multiple video clips into a single video asset. The Merge Videos node concatenates video clips in sequence, outputting one video file. Connect multiple video outputs, and the node stitches them together in the order they're connected. {% embed url="" %} #### When to use it * **Multi-scene sequences**: Combine intro, body, and outro clips into one cohesive video. * **Batch-generated content**: Merge product shots or lifestyle clips created in parallel. * **Modular workflows**: Build complex videos from reusable components without manual editing. #### Configuration options * **Transitions**: Add fades, dissolves, or cuts between clips for smoother flow. * **Motion effects**: Apply entrance or exit animations to individual segments. # Advanced nodes # Integrations # Introduction Welcome to the **Pletor API** documentation. Integrate Pletor's AI capabilities directly into your apps and workflows — agent discovery, on-brand asset generation, and real-time execution tracking. #### Key Features * **Agent Discovery** — Browse a catalog of AI agents with detailed descriptions, required inputs, and expected outputs. * **App Discovery** — Browse curated, runnable apps built on top of flows. Apps are an alternative to agents: run them via `POST /app-runs` with an `app_id`. * **Flexible Execution** — Create agent runs via `POST /runs` and app runs via `POST /app-runs`, providing dynamic inputs including uploaded files. * **Asset Management** — Centralized handling for your files: upload, retrieve, and download assets, and organize them with tags, bookmarks, archiving, and deletion. * **Real-Time Tracking** — Monitor executions with live updates and retrieve results as soon as they're ready. * **Secure API Access** — All endpoints are protected with API key authentication. #### Authentication All requests require either an API key in the `X-Api-Key` header, or a Bearer JWT in the `Authorization` header. #### Rate Limits Rate limits are per API key: * **Default**: 2000 requests/minute * **POST /runs** and **POST /app-runs**: 600 requests/minute * **POST /assets/upload**: 600 requests/minute Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. #### Idempotent requests Network calls fail halfway, and a blind retry can start a second run (charging you twice) or upload the same file again. To retry safely, attach an `external_id` to any `POST` and reuse the same value on the retry. * The first request with a key creates the object and returns it, with `external_id` echoed back. * Any later request that reuses the key returns `409 conflict` instead of creating a duplicate. Fetch the original with `GET /runs?external_id=...` (the same filter works on `/app-runs` and `/assets`). * `GET` and `DELETE` don't take a key; repeating those is already safe. A key is **unique per organization and permanent**. Once it has created a run or an upload it stays claimed, even if the run later fails or is canceled, so a genuine re-run needs a new key. Runs and uploads are tracked separately, so the same value can label one run and one upload but not two of either. Generate your own key. A v4 UUID is a good default; keys can be up to 255 characters, and a longer one is rejected with `422`. Keep sensitive data out of it, since it appears in responses. A request that fails validation before the object is created (bad inputs, an oversized key) claims nothing, so you can fix it and retry with the same key. #### Quickstart 1. **List agents or apps** — `GET /agents` or `GET /apps` to find one that fits your use case. 2. **Inspect inputs** — `GET /agents/{id}` or `GET /apps/{id}` to see required inputs and expected outputs. 3. **Upload assets** (if needed) — `POST /assets/upload`. 4. **Create a run** — `POST /runs` with an `agent_id` for agents, or `POST /app-runs` with an `app_id` for apps, plus inputs. 5. **Poll status** — `GET /runs/{run_id}` (agent runs) or `GET /app-runs/{run_id}` (app runs) until completed. 6. **Handle human review** (agent runs, if applicable) — when `awaiting_human_review` is `true`, resolve each entry in `pending_reviews` via `POST /runs/{run_id}/reviews/{review_id}` to resume execution. 7. **Retrieve outputs** — inspect the completed run's `results` array to find generated `asset_id`s and text outputs. 8. **Download assets** — `GET /assets/{asset_id}/download`. # Agents Agents represent specific AI-powered capabilities — on-brand photo generation, UGC video generation, static ads generation, and more. Use these endpoints to discover available agents and inspect their required inputs and expected outputs. Discover AI agents and inspect their input requirements and output types. ## List Agents > List available AI agents with filtering options.\ > \ > This endpoint returns a paginated list of AI agents that can generate various types of\ > content including images, videos, text, and other creative assets.\ > \ > \*\*Filtering Options:\*\*\ > \- \`tags\`: Filter agents by tags (can be provided multiple times)\ > \- \`visibility\`: Filter agents by their visibility status (can be provided multiple times)\ > Options include:\ > \- PRIVATE: Internal organization's agents\ > \- SHARED: Agents shared by the user\ > \- PUBLIC: Pletor public agents\ > By default, only PRIVATE and SHARED agents are returned.\ > \- \`search\`: Search agents by name (case-insensitive)\ > \ > \*\*Pagination Parameters:\*\*\ > \- \`limit\`: Maximum number of items to return (default: 20, max: 100)\ > \- \`cursor\`: Cursor for pagination (optional)\ > \ > \*\*Response:\*\*\ > \- \`data\`: List of agent summaries with basic information including expected inputs\ > \- \`has\_more\`: Indicates if there are more results available\ > \- \`next\_cursor\`: Cursor for the next page of results\ > \ > \*\*Use Case:\*\* This is typically the first endpoint called to discover available agents\ > before getting detailed information or executing them. ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"agents","description":"Discover AI agents and inspect their input requirements and output types."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"FlowVisibility":{"type":"string","enum":["public","shared","private"],"title":"FlowVisibility","description":"Visibility levels for workflows."},"CursorPaginatedResponse_AgentSummary_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AgentSummary"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data","has_more"],"title":"CursorPaginatedResponse[AgentSummary]"},"AgentSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique agent identifier"},"name":{"type":"string","title":"Name","description":"Agent display name"},"description":{"type":"string","title":"Description","description":"Agent description and purpose"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Categorization tags for filtering"},"estimated_cost":{"type":"integer","title":"Estimated Cost","description":"Estimated credit cost per execution"},"visibility":{"$ref":"#/components/schemas/FlowVisibility","description":"Visibility level: PRIVATE, SHARED, or PUBLIC"},"inputs":{"items":{"$ref":"#/components/schemas/AgentInput"},"type":"array","title":"Inputs","description":"All inputs for this agent; check the `required` flag on each to determine which are mandatory"},"has_human_review":{"type":"boolean","title":"Has Human Review","description":"True when this agent includes a human review step that will pause execution until resolved via POST /runs/{run_id}/reviews/{review_id}. Poll GET /runs/{run_id} for `awaiting_human_review` while the run is in progress.","default":false}},"type":"object","required":["id","name","description","estimated_cost","visibility"],"title":"AgentSummary","description":"Lightweight agent summary for list views."},"AgentInput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID to use when providing this input"},"type":{"$ref":"#/components/schemas/NodeType","description":"Input type: text_input, image_input, video_input, file_input, etc."},"description":{"type":"string","title":"Description","description":"Human-readable description of this input"},"required":{"type":"boolean","title":"Required","description":"Whether this input must be provided when creating a run","default":true}},"type":"object","required":["id","type","description"],"title":"AgentInput","description":"Represents an input requirement for an agent."},"NodeType":{"type":"string","enum":["text_input","image_input","file_input","video_input","audio_input","brand_system_input","llm","image_generation","video_generation","text_to_speech","screen_mockup","remove_background","upscale","upscale_video","video_background_removal","extract_video_frame","image_generation_lora","change_aspect_ratio","meta_ads_extractor","image_edit","edit_text","vectorize","image_erase","linkedin_ads_extractor","instagram_posts_extractor","linkedin_posts_extractor","human_review","match_brand_colors","tiktok_extractor","add_logo","video_subtitle","video_concat","video_add_sound","generic_fal","comment","group","composer","googledrive_find_file","googledrive_upload_file","prompt_concatenate","text_split","list_selector","video_edit","router","camera_angle","rename_asset","music_generation","merge_audio_video","trim_speed","extract_audio","remove_audio","isolate_sound","clone_voice","translate_audio","translate_video","transcribe"],"title":"NodeType"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/agents/":{"get":{"tags":["agents"],"summary":"List Agents","description":"List available AI agents with filtering options.\n\nThis endpoint returns a paginated list of AI agents that can generate various types of\ncontent including images, videos, text, and other creative assets.\n\n**Filtering Options:**\n- `tags`: Filter agents by tags (can be provided multiple times)\n- `visibility`: Filter agents by their visibility status (can be provided multiple times)\n Options include:\n - PRIVATE: Internal organization's agents\n - SHARED: Agents shared by the user\n - PUBLIC: Pletor public agents\n By default, only PRIVATE and SHARED agents are returned.\n- `search`: Search agents by name (case-insensitive)\n\n**Pagination Parameters:**\n- `limit`: Maximum number of items to return (default: 20, max: 100)\n- `cursor`: Cursor for pagination (optional)\n\n**Response:**\n- `data`: List of agent summaries with basic information including expected inputs\n- `has_more`: Indicates if there are more results available\n- `next_cursor`: Cursor for the next page of results\n\n**Use Case:** This is typically the first endpoint called to discover available agents\nbefore getting detailed information or executing them.","operationId":"list_agents_agents__get","parameters":[{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Tags"}},{"name":"visibility","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/FlowVisibility"}},{"type":"null"}],"title":"Visibility"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search agents by name","title":"Search"},"description":"Search agents by name"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of items to return","default":20,"title":"Limit"},"description":"Maximum number of items to return"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cursor for pagination (from next_cursor)","title":"Cursor"},"description":"Cursor for pagination (from next_cursor)"},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPaginatedResponse_AgentSummary_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get Agent > Get detailed information about a specific AI agent.\ > \ > This endpoint retrieves comprehensive information about an AI agent, including:\ > \- Agent metadata (name, description, category, tags)\ > \- Input requirements with types\ > \- Output specifications and formats\ > \- Performance metrics and cost estimates\ > \ > \*\*Input Information:\*\*\ > Each agent defines specific inputs it requires:\ > \- \`id\`: Node identifier used when executing the agent\ > \- \`type\`: Input type (text\_input, image\_input, video\_input, file\_input)\ > \- \`description\`: Description of what this input does\ > \ > \*\*Output Information:\*\*\ > Each agent specifies what types of content it generates:\ > \- \`id\`: Node identifier for the output\ > \- \`type\`: Output type (text, images, videos, files, data)\ > \- \`description\`: Description of what this output contains\ > \ > \*\*Performance Metrics:\*\*\ > \- \`estimated\_cost\`: Credit cost estimation for running this agent\ > \ > \*\*Use Case:\*\* Call this endpoint to understand what inputs an agent needs and what\ > outputs it will generate before creating a generation request.\ > \ > \*\*Error Codes:\*\*\ > \- \`404\`: Agent not found or not accessible\ > \- \`422\`: Agent has no active version ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"agents","description":"Discover AI agents and inspect their input requirements and output types."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"Agent":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique agent identifier"},"name":{"type":"string","title":"Name","description":"Agent display name"},"description":{"type":"string","title":"Description","description":"Agent description and purpose"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Categorization tags for filtering"},"inputs":{"items":{"$ref":"#/components/schemas/AgentInput"},"type":"array","title":"Inputs","description":"All inputs for this agent. Use these IDs when creating a run; check the `required` flag on each input to determine which are mandatory"},"outputs":{"items":{"$ref":"#/components/schemas/AgentOutput"},"type":"array","title":"Outputs","description":"Expected outputs. Match these IDs in run results"},"estimated_cost":{"type":"integer","title":"Estimated Cost","description":"Estimated credit cost per execution"},"has_human_review":{"type":"boolean","title":"Has Human Review","description":"True when this agent includes a human review step that will pause execution until resolved via POST /runs/{run_id}/reviews/{review_id}. Poll GET /runs/{run_id} for `awaiting_human_review` while the run is in progress.","default":false}},"type":"object","required":["id","name","description","estimated_cost"],"title":"Agent","description":"Complete representation of an AI agent with its inputs, outputs, and cost."},"AgentInput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID to use when providing this input"},"type":{"$ref":"#/components/schemas/NodeType","description":"Input type: text_input, image_input, video_input, file_input, etc."},"description":{"type":"string","title":"Description","description":"Human-readable description of this input"},"required":{"type":"boolean","title":"Required","description":"Whether this input must be provided when creating a run","default":true}},"type":"object","required":["id","type","description"],"title":"AgentInput","description":"Represents an input requirement for an agent."},"NodeType":{"type":"string","enum":["text_input","image_input","file_input","video_input","audio_input","brand_system_input","llm","image_generation","video_generation","text_to_speech","screen_mockup","remove_background","upscale","upscale_video","video_background_removal","extract_video_frame","image_generation_lora","change_aspect_ratio","meta_ads_extractor","image_edit","edit_text","vectorize","image_erase","linkedin_ads_extractor","instagram_posts_extractor","linkedin_posts_extractor","human_review","match_brand_colors","tiktok_extractor","add_logo","video_subtitle","video_concat","video_add_sound","generic_fal","comment","group","composer","googledrive_find_file","googledrive_upload_file","prompt_concatenate","text_split","list_selector","video_edit","router","camera_angle","rename_asset","music_generation","merge_audio_video","trim_speed","extract_audio","remove_audio","isolate_sound","clone_voice","translate_audio","translate_video","transcribe"],"title":"NodeType"},"AgentOutput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID to match in run results"},"type":{"$ref":"#/components/schemas/DataType","description":"Output data type: text, images, videos, files, audio, or data"},"description":{"type":"string","title":"Description","description":"Human-readable description of this output"}},"type":"object","required":["id","type","description"],"title":"AgentOutput","description":"Represents an output produced by an agent."},"DataType":{"type":"string","enum":["text","images","videos","files","audio","data"],"title":"DataType","description":"Types of data that agents can accept as input or produce as output."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/agents/{agent_id}":{"get":{"tags":["agents"],"summary":"Get Agent","description":"Get detailed information about a specific AI agent.\n\nThis endpoint retrieves comprehensive information about an AI agent, including:\n- Agent metadata (name, description, category, tags)\n- Input requirements with types\n- Output specifications and formats\n- Performance metrics and cost estimates\n\n**Input Information:**\nEach agent defines specific inputs it requires:\n- `id`: Node identifier used when executing the agent\n- `type`: Input type (text_input, image_input, video_input, file_input)\n- `description`: Description of what this input does\n\n**Output Information:**\nEach agent specifies what types of content it generates:\n- `id`: Node identifier for the output\n- `type`: Output type (text, images, videos, files, data)\n- `description`: Description of what this output contains\n\n**Performance Metrics:**\n- `estimated_cost`: Credit cost estimation for running this agent\n\n**Use Case:** Call this endpoint to understand what inputs an agent needs and what\noutputs it will generate before creating a generation request.\n\n**Error Codes:**\n- `404`: Agent not found or not accessible\n- `422`: Agent has no active version","operationId":"get_agent_agents__agent_id__get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` # Apps Apps are curated, runnable applications built on top of flows. Each app exposes a configured set of inputs and produces one or more outputs, packaging a flow into a turnkey experience. Use these endpoints to discover available apps and inspect their required inputs and expected outputs, then run them via \`POST /app-runs\`. Discover and inspect runnable apps built on flows. ## List Apps > List available apps with filtering options.\ > \ > Apps are curated, runnable applications built on top of flows. Each app exposes a\ > set of configured inputs and produces one or more outputs, and can be executed\ > directly via \`POST /app-runs\`.\ > \ > \*\*Filtering Options:\*\*\ > \- \`visibility\`: Filter apps by their visibility status (can be provided multiple times)\ > Options include:\ > \- private: Only visible to the creator\ > \- workspace: Visible to everyone in the creator's organization\ > \- shared: Visible via a shared link\ > \- public: Visible to everyone\ > By default, all apps accessible to the caller are returned.\ > \- \`search\`: Search apps by name or description (case-insensitive)\ > \ > \*\*Pagination Parameters:\*\*\ > \- \`limit\`: Maximum number of items to return (default: 20, max: 100)\ > \- \`cursor\`: Cursor for pagination (optional)\ > \ > \*\*Response:\*\*\ > \- \`data\`: List of app summaries with basic information including expected inputs\ > \- \`has\_more\`: Indicates if there are more results available\ > \- \`next\_cursor\`: Cursor for the next page of results\ > \ > \*\*Use Case:\*\* This is typically the first endpoint called to discover available apps\ > before getting detailed information or executing them. ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"apps","description":"Discover and inspect runnable apps built on flows."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"FlowApplicationVisibility":{"type":"string","enum":["private","workspace","shared","public"],"title":"FlowApplicationVisibility","description":"Visibility levels for flow applications."},"CursorPaginatedResponse_AppSummary_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AppSummary"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data","has_more"],"title":"CursorPaginatedResponse[AppSummary]"},"AppSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Stable app identifier"},"name":{"type":"string","title":"Name","description":"App display name"},"description":{"type":"string","title":"Description","description":"App description and purpose"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url","description":"Public CDN URL for the app thumbnail image"},"visibility":{"$ref":"#/components/schemas/FlowApplicationVisibility","description":"Visibility level: private, workspace, shared, or public"},"estimated_cost":{"type":"integer","title":"Estimated Cost","description":"Estimated credit cost per execution"},"inputs":{"items":{"$ref":"#/components/schemas/AppInput"},"type":"array","title":"Inputs","description":"Required inputs for this app"}},"type":"object","required":["id","name","description","visibility","estimated_cost"],"title":"AppSummary","description":"Lightweight app summary for list views."},"AppInput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID to use when providing this input"},"type":{"$ref":"#/components/schemas/AppInputType","description":"Input type: text, image, video, audio, brand, or file"},"name":{"type":"string","title":"Name","description":"Display name of this input"},"required":{"type":"boolean","title":"Required","description":"Whether this input is mandatory"},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options","description":"Allowed values when the input is a fixed set: label strings for text inputs, asset IDs for media inputs"},"min_selections":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Min Selections","description":"Minimum number of values the caller must provide for this input"},"max_selections":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Selections","description":"Maximum number of values the caller may provide for this input"}},"type":"object","required":["id","type","name","required"],"title":"AppInput","description":"Represents an input requirement for an app."},"AppInputType":{"type":"string","enum":["text","image","video","audio","brand","file"],"title":"AppInputType","description":"Types of inputs an app can accept from a caller."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/apps/":{"get":{"tags":["apps"],"summary":"List Apps","description":"List available apps with filtering options.\n\nApps are curated, runnable applications built on top of flows. Each app exposes a\nset of configured inputs and produces one or more outputs, and can be executed\ndirectly via `POST /app-runs`.\n\n**Filtering Options:**\n- `visibility`: Filter apps by their visibility status (can be provided multiple times)\n Options include:\n - private: Only visible to the creator\n - workspace: Visible to everyone in the creator's organization\n - shared: Visible via a shared link\n - public: Visible to everyone\n By default, all apps accessible to the caller are returned.\n- `search`: Search apps by name or description (case-insensitive)\n\n**Pagination Parameters:**\n- `limit`: Maximum number of items to return (default: 20, max: 100)\n- `cursor`: Cursor for pagination (optional)\n\n**Response:**\n- `data`: List of app summaries with basic information including expected inputs\n- `has_more`: Indicates if there are more results available\n- `next_cursor`: Cursor for the next page of results\n\n**Use Case:** This is typically the first endpoint called to discover available apps\nbefore getting detailed information or executing them.","operationId":"list_apps_apps__get","parameters":[{"name":"visibility","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/FlowApplicationVisibility"}},{"type":"null"}],"title":"Visibility"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search apps by name or description","title":"Search"},"description":"Search apps by name or description"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of items to return","default":20,"title":"Limit"},"description":"Maximum number of items to return"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cursor for pagination (from next_cursor)","title":"Cursor"},"description":"Cursor for pagination (from next_cursor)"},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPaginatedResponse_AppSummary_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get App > Get detailed information about a specific app.\ > \ > This endpoint retrieves comprehensive information about an app, including:\ > \- App metadata (name, description, avatar, visibility)\ > \- Input requirements with types\ > \- Output specifications and formats\ > \- Estimated cost per execution\ > \ > \*\*Input Information:\*\*\ > Each app defines specific inputs it requires:\ > \- \`id\`: Node identifier used when executing the app\ > \- \`type\`: Input type (text, image, video, audio, brand, file)\ > \- \`name\`: Display name of this input\ > \- \`required\`: Whether the input is mandatory\ > \- \`options\`, \`min\_selections\`, \`max\_selections\`: Constraints for fixed-set inputs\ > \ > \*\*Output Information:\*\*\ > Each app specifies what types of content it generates:\ > \- \`id\`: Node identifier for the output\ > \- \`type\`: Output type (text, images, videos, files, audio, data)\ > \- \`description\`: Description of what this output contains\ > \ > \*\*Performance Metrics:\*\*\ > \- \`estimated\_cost\`: Credit cost estimation for running this app\ > \ > \*\*Use Case:\*\* Call this endpoint to understand what inputs an app needs and what\ > outputs it will generate before creating a run.\ > \ > \*\*Error Codes:\*\*\ > \- \`404\`: App not found or not accessible\ > \- \`422\`: App has no associated flow definition ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"apps","description":"Discover and inspect runnable apps built on flows."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"App":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Stable app identifier"},"name":{"type":"string","title":"Name","description":"App display name"},"description":{"type":"string","title":"Description","description":"App description and purpose"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url","description":"Public CDN URL for the app thumbnail image"},"visibility":{"$ref":"#/components/schemas/FlowApplicationVisibility","description":"Visibility level: private, workspace, shared, or public"},"inputs":{"items":{"$ref":"#/components/schemas/AppInput"},"type":"array","title":"Inputs","description":"Required inputs for this app. Use these IDs when creating a run"},"outputs":{"items":{"$ref":"#/components/schemas/AppOutput"},"type":"array","title":"Outputs","description":"Expected outputs. Match these IDs in run results"},"estimated_cost":{"type":"integer","title":"Estimated Cost","description":"Estimated credit cost per execution"}},"type":"object","required":["id","name","description","visibility","estimated_cost"],"title":"App","description":"Complete representation of a runnable app with its inputs, outputs, and cost."},"FlowApplicationVisibility":{"type":"string","enum":["private","workspace","shared","public"],"title":"FlowApplicationVisibility","description":"Visibility levels for flow applications."},"AppInput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID to use when providing this input"},"type":{"$ref":"#/components/schemas/AppInputType","description":"Input type: text, image, video, audio, brand, or file"},"name":{"type":"string","title":"Name","description":"Display name of this input"},"required":{"type":"boolean","title":"Required","description":"Whether this input is mandatory"},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options","description":"Allowed values when the input is a fixed set: label strings for text inputs, asset IDs for media inputs"},"min_selections":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Min Selections","description":"Minimum number of values the caller must provide for this input"},"max_selections":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Selections","description":"Maximum number of values the caller may provide for this input"}},"type":"object","required":["id","type","name","required"],"title":"AppInput","description":"Represents an input requirement for an app."},"AppInputType":{"type":"string","enum":["text","image","video","audio","brand","file"],"title":"AppInputType","description":"Types of inputs an app can accept from a caller."},"AppOutput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID to match in run results"},"type":{"$ref":"#/components/schemas/DataType","description":"Output data type: text, images, videos, files, audio, or data"},"description":{"type":"string","title":"Description","description":"Human-readable description of this output"}},"type":"object","required":["id","type","description"],"title":"AppOutput","description":"Represents an output produced by an app."},"DataType":{"type":"string","enum":["text","images","videos","files","audio","data"],"title":"DataType","description":"Types of data that agents can accept as input or produce as output."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/apps/{app_id}":{"get":{"tags":["apps"],"summary":"Get App","description":"Get detailed information about a specific app.\n\nThis endpoint retrieves comprehensive information about an app, including:\n- App metadata (name, description, avatar, visibility)\n- Input requirements with types\n- Output specifications and formats\n- Estimated cost per execution\n\n**Input Information:**\nEach app defines specific inputs it requires:\n- `id`: Node identifier used when executing the app\n- `type`: Input type (text, image, video, audio, brand, file)\n- `name`: Display name of this input\n- `required`: Whether the input is mandatory\n- `options`, `min_selections`, `max_selections`: Constraints for fixed-set inputs\n\n**Output Information:**\nEach app specifies what types of content it generates:\n- `id`: Node identifier for the output\n- `type`: Output type (text, images, videos, files, audio, data)\n- `description`: Description of what this output contains\n\n**Performance Metrics:**\n- `estimated_cost`: Credit cost estimation for running this app\n\n**Use Case:** Call this endpoint to understand what inputs an app needs and what\noutputs it will generate before creating a run.\n\n**Error Codes:**\n- `404`: App not found or not accessible\n- `422`: App has no associated flow definition","operationId":"get_app_apps__app_id__get","parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"App Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/App"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` # Runs Runs are executions of agents. The typical workflow: discover an agent, inspect its required inputs, upload any necessary assets, create a run with matching inputs, poll its status, and retrieve generated outputs once complete. App executions live under App Runs. Create, monitor, and cancel agent executions. ## List Runs > List agent execution runs with filtering options.\ > \ > This endpoint returns a paginated list of agent execution runs with their\ > current status and basic metadata. App runs are listed separately via\ > \`GET /app-runs\`.\ > \ > \*\*Filtering Options:\*\*\ > \- \`status\`: Filter by execution status (in\_progress, completed, failed, canceled)\ > \- \`external\_id\`: Filter to runs you tagged with this reference id at creation.\ > Use this to check whether you already started a run for a given item before\ > starting another.\ > \ > \*\*Pagination Parameters:\*\*\ > \- \`limit\`: Maximum number of items to return (default: 20, max: 100)\ > \- \`cursor\`: Cursor for pagination (optional)\ > \ > \*\*Response:\*\*\ > \- \`data\`: List of run summaries with basic information\ > \- \`has\_more\`: Indicates if there are more results available\ > \- \`next\_cursor\`: Cursor for the next page of results\ > \ > \*\*Use Case:\*\* Monitor multiple executions and their status overview. ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"runs","description":"Create, monitor, and cancel agent executions."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"FlowRunStatus":{"type":"string","enum":["in_progress","completed","failed","canceled"],"title":"FlowRunStatus","description":"Execution status of a workflow run."},"CursorPaginatedResponse_RunSummary_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/RunSummary"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data","has_more"],"title":"CursorPaginatedResponse[RunSummary]"},"RunSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique run identifier"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id","description":"ID of the agent that was executed"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"Client-supplied reference id provided at creation, if any"},"status":{"$ref":"#/components/schemas/FlowRunStatus","description":"Current execution state"},"progress":{"type":"number","maximum":1,"minimum":0,"title":"Progress","description":"Completion progress from 0.0 to 1.0","default":0},"awaiting_human_review":{"type":"boolean","title":"Awaiting Human Review","description":"True when the run has paused on one or more human review nodes. Fetch GET /runs/{run_id} to inspect pending reviews.","default":false},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the run was created"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When execution started"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When execution finished"},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Total credits consumed by this run"}},"type":"object","required":["id","agent_id","status","created_at"],"title":"RunSummary","description":"Lightweight run summary for list views."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/runs/":{"get":{"tags":["runs"],"summary":"List Runs","description":"List agent execution runs with filtering options.\n\nThis endpoint returns a paginated list of agent execution runs with their\ncurrent status and basic metadata. App runs are listed separately via\n`GET /app-runs`.\n\n**Filtering Options:**\n- `status`: Filter by execution status (in_progress, completed, failed, canceled)\n- `external_id`: Filter to runs you tagged with this reference id at creation.\n Use this to check whether you already started a run for a given item before\n starting another.\n\n**Pagination Parameters:**\n- `limit`: Maximum number of items to return (default: 20, max: 100)\n- `cursor`: Cursor for pagination (optional)\n\n**Response:**\n- `data`: List of run summaries with basic information\n- `has_more`: Indicates if there are more results available\n- `next_cursor`: Cursor for the next page of results\n\n**Use Case:** Monitor multiple executions and their status overview.","operationId":"list_runs_runs__get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/FlowRunStatus"},{"type":"null"}],"title":"Status"}},{"name":"external_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of items to return","default":20,"title":"Limit"},"description":"Maximum number of items to return"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cursor for pagination (from next_cursor)","title":"Cursor"},"description":"Cursor for pagination (from next_cursor)"},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPaginatedResponse_RunSummary_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Create Run > Create and start a new agent execution run.\ > \ > This endpoint launches the execution of an AI agent with the provided inputs.\ > The execution runs asynchronously, allowing you to monitor progress and retrieve\ > results when complete.\ > \ > \*\*Idempotency with \`external\_id\`:\*\* Optionally pass an \`external\_id\` (e.g. your\ > own order or job id). It is \*\*unique per organization\*\*: the first request with\ > a given key starts the run; any later write reusing that key — including a\ > dropped-response retry — is rejected with \*\*\`409 conflict\`\*\* instead of starting\ > (and charging) a duplicate. To fetch the run a key already created, use\ > \`GET /runs?external\_id=...\`. The id is echoed on every run response.\ > \ > \- Scope: per organization, across \*\*all\*\* runs (agent and app share the key\ > space) and \*\*all\*\* statuses — a key, once used, stays used.\ > \- On \`409\`, do \*\*not\*\* keep retrying the create; \`GET /runs?external\_id=\` to\ > retrieve the existing run. To start a genuinely new run, use a new \`external\_id\`.\ > \ > \*\*How to Build Inputs:\*\*\ > \ > 1\. \*\*First, get agent details\*\*: Call \`GET /agents/{agent\_id}\` to retrieve the agent configuration\ > 2\. \*\*Examine the \`inputs\` array\*\*: Each object defines what input the agent expects:\ > \- \`id\`: Use this as the \`id\` in your input object\ > \- \`type\`: Determines the input format (see below)\ > \- \`description\`: Explains what this input does\ > \ > 3\. \*\*Format inputs based on type\*\*:\ > \ > \*\*Text Inputs\*\* (\`text\_input\` type):\ > \`\`\`json\ > {\ > "id": "text\_input\_node\_id",\ > "value": "Your text content here"\ > }\ > \`\`\`\ > \ > \*\*Asset Inputs\*\* (\`image\_input\`, \`video\_input\`, \`file\_input\` types):\ > \`\`\`json\ > {\ > "id": "image\_input\_node\_id",\ > "value": {\ > "asset\_ids": \["uuid1", "uuid2"]\ > }\ > }\ > \`\`\`\ > Note: Upload assets first via \`POST /assets/upload\` to get the UUIDs\ > \ > \*\*Complete Example Workflow:\*\*\ > \ > 1\. Get agent configuration:\ > \`\`\`bash\ > GET /agents/550e8400-e29b-41d4-a716-446655440000\ > \# Response shows inputs: \[\ > \# {"id": "uuid-1", "type": "text\_input", "description": "Product description"},\ > \# {"id": "uuid-2", "type": "image\_input", "description": "Company logo"}\ > \# ]\ > \`\`\`\ > \ > 2\. Upload assets if needed:\ > \`\`\`bash\ > POST /assets/upload\ > \# Response: {"id": "asset-uuid-123", ...}\ > \`\`\`\ > \ > 3\. Create run with matching inputs:\ > \`\`\`json\ > {\ > "agent\_id": "550e8400-e29b-41d4-a716-446655440000",\ > "inputs": \[\ > {\ > "id": "uuid-1",\ > "value": "Create a marketing banner for a tech startup"\ > },\ > {\ > "id": "uuid-2",\ > "value": {\ > "asset\_ids": \["asset-uuid-123"]\ > }\ > }\ > ]\ > }\ > \`\`\`\ > \ > \*\*Response:\*\*\ > \- Run object with execution details and initial status\ > \- Use \`id\` field to monitor progress via \`GET /runs/{run\_id}\`\ > \ > \*\*Running an app instead?\*\* Apps have their own surface — use \`POST /app-runs\`\ > with an \`app\_id\`. See the Apps and App Runs sections.\ > \ > \*\*Error Codes:\*\*\ > \- \`400\`: Invalid input format or missing required inputs\ > \- \`404\`: Agent not found or not accessible ````json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"runs","description":"Create, monitor, and cancel agent executions."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"RunCreateRequest":{"properties":{"agent_id":{"type":"string","format":"uuid","title":"Agent Id","description":"ID of the agent to execute"},"inputs":{"items":{"$ref":"#/components/schemas/RunInput"},"type":"array","title":"Inputs","description":"Inputs for the agent. Get required inputs from GET /agents/{id}"},"external_id":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"External Id","description":"Optional client-supplied reference id (e.g. your order or job id, max 255 chars). Unique per organization: reusing one returns 409 conflict — so a dropped-response retry never creates a duplicate. Echoed on every run and filterable via GET /runs?external_id= to fetch it. Use a new id per run."}},"type":"object","required":["agent_id"],"title":"RunCreateRequest","description":"Request to create and start a new agent execution run."},"RunInput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID that this input targets"},"value":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"}],"title":"Value","description":"Input value: plain text string for text inputs, or {\"asset_ids\": [\"uuid\"]} for asset inputs"}},"type":"object","required":["id","value"],"title":"RunInput","description":"Represents an input provided to a run.\n\nShared by agent runs and app runs: both pipelines accept the same wire shape."},"Run":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique run identifier"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id","description":"ID of the agent being executed"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"Client-supplied reference id provided at creation, if any"},"status":{"$ref":"#/components/schemas/FlowRunStatus","description":"Current execution state: in_progress, completed, failed, or canceled"},"progress":{"type":"number","maximum":1,"minimum":0,"title":"Progress","description":"Completion progress from 0.0 to 1.0","default":0},"current_node":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Node","description":"Type of the node currently executing (e.g. image_generation, llm). Only present while status is in_progress"},"awaiting_human_review":{"type":"boolean","title":"Awaiting Human Review","description":"True when the run has paused on one or more human review nodes and is waiting for a decision via POST /runs/{run_id}/reviews/{review_id}. While true, `status` remains `in_progress`.","default":false},"pending_reviews":{"items":{"$ref":"#/components/schemas/PendingReview"},"type":"array","title":"Pending Reviews","description":"Human review steps currently waiting for a decision. Empty unless `awaiting_human_review` is true."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the run was created"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When execution started"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When execution finished"},"inputs":{"items":{"$ref":"#/components/schemas/RunInput"},"type":"array","title":"Inputs","description":"Inputs provided for this run"},"results":{"items":{"$ref":"#/components/schemas/RunResult"},"type":"array","title":"Results","description":"Output results, populated when status is completed"},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Total credits consumed by this run"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if the run failed"},"failure_reason":{"anyOf":[{"$ref":"#/components/schemas/FailureReason"},{"type":"null"}],"description":"Categorized failure reason (timeout, content_policy, insufficient_credits, invalid_input, provider_error, provider_auth_required, canceled, unknown). Present when status is failed."}},"type":"object","required":["id","agent_id","status","created_at"],"title":"Run","description":"Complete representation of an agent execution run."},"FlowRunStatus":{"type":"string","enum":["in_progress","completed","failed","canceled"],"title":"FlowRunStatus","description":"Execution status of a workflow run."},"PendingReview":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Identifier of the pending review. Use this as `review_id` when calling POST /runs/{run_id}/reviews/{review_id} to resume execution."},"node_id":{"type":"string","title":"Node Id","description":"ID of the human review node inside the agent definition"},"reviewed_node_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reviewed Node Type","description":"Type of the upstream node whose output is being reviewed (e.g. image_generation, llm). May be null for legacy reviews."},"reviewed_output_type":{"anyOf":[{"$ref":"#/components/schemas/DataType"},{"type":"null"}],"description":"Business-friendly type of the output under review (text, images, videos, audio, files, data)."},"proposed_output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"string"},{"type":"null"}],"title":"Proposed Output","description":"Output produced by the upstream node(s) that is being reviewed. Submit this back (optionally edited) as `output` when approving. To discard items, submit only the ones you want to keep — omitted items are dropped. At least one item must be kept."},"can_edit_outputs":{"type":"boolean","title":"Can Edit Outputs","description":"Whether the agent definition allows editing the proposed output before approval.","default":false},"can_generate_more":{"type":"boolean","title":"Can Generate More","description":"Whether the agent definition allows regenerating the upstream output (decision=retry).","default":false},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the review was opened"}},"type":"object","required":["id","node_id","created_at"],"title":"PendingReview","description":"A human review step that is currently waiting for a decision."},"DataType":{"type":"string","enum":["text","images","videos","files","audio","data"],"title":"DataType","description":"Types of data that agents can accept as input or produce as output."},"RunResult":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID that produced this result"},"type":{"$ref":"#/components/schemas/DataType","description":"Type of the result data"},"value":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Value","description":"Result content: text string, list of asset UUIDs, or structured data"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Human-readable description of the result"}},"type":"object","required":["id","type"],"title":"RunResult","description":"Represents a result produced by a run.\n\nShared by agent runs and app runs: both pipelines emit the same wire shape."},"FailureReason":{"type":"string","enum":["timeout","content_policy","insufficient_credits","invalid_input","provider_error","provider_auth_required","canceled","unknown"],"title":"FailureReason","description":"Stable, client-facing categories for why a run failed. A curated public\nview over the internal `NodeFailureReason`; internal-only causes collapse to\n`unknown` so the public contract stays stable as internals change."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/runs/":{"post":{"tags":["runs"],"summary":"Create Run","description":"Create and start a new agent execution run.\n\nThis endpoint launches the execution of an AI agent with the provided inputs.\nThe execution runs asynchronously, allowing you to monitor progress and retrieve\nresults when complete.\n\n**Idempotency with `external_id`:** Optionally pass an `external_id` (e.g. your\nown order or job id). It is **unique per organization**: the first request with\na given key starts the run; any later write reusing that key — including a\ndropped-response retry — is rejected with **`409 conflict`** instead of starting\n(and charging) a duplicate. To fetch the run a key already created, use\n`GET /runs?external_id=...`. The id is echoed on every run response.\n\n- Scope: per organization, across **all** runs (agent and app share the key\n space) and **all** statuses — a key, once used, stays used.\n- On `409`, do **not** keep retrying the create; `GET /runs?external_id=` to\n retrieve the existing run. To start a genuinely new run, use a new `external_id`.\n\n**How to Build Inputs:**\n\n1. **First, get agent details**: Call `GET /agents/{agent_id}` to retrieve the agent configuration\n2. **Examine the `inputs` array**: Each object defines what input the agent expects:\n - `id`: Use this as the `id` in your input object\n - `type`: Determines the input format (see below)\n - `description`: Explains what this input does\n\n3. **Format inputs based on type**:\n\n**Text Inputs** (`text_input` type):\n```json\n{\n \"id\": \"text_input_node_id\",\n \"value\": \"Your text content here\"\n}\n```\n\n**Asset Inputs** (`image_input`, `video_input`, `file_input` types):\n```json\n{\n \"id\": \"image_input_node_id\",\n \"value\": {\n \"asset_ids\": [\"uuid1\", \"uuid2\"]\n }\n}\n```\nNote: Upload assets first via `POST /assets/upload` to get the UUIDs\n\n**Complete Example Workflow:**\n\n1. Get agent configuration:\n```bash\nGET /agents/550e8400-e29b-41d4-a716-446655440000\n# Response shows inputs: [\n# {\"id\": \"uuid-1\", \"type\": \"text_input\", \"description\": \"Product description\"},\n# {\"id\": \"uuid-2\", \"type\": \"image_input\", \"description\": \"Company logo\"}\n# ]\n```\n\n2. Upload assets if needed:\n```bash\nPOST /assets/upload\n# Response: {\"id\": \"asset-uuid-123\", ...}\n```\n\n3. Create run with matching inputs:\n```json\n{\n \"agent_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"inputs\": [\n {\n \"id\": \"uuid-1\",\n \"value\": \"Create a marketing banner for a tech startup\"\n },\n {\n \"id\": \"uuid-2\",\n \"value\": {\n \"asset_ids\": [\"asset-uuid-123\"]\n }\n }\n ]\n}\n```\n\n**Response:**\n- Run object with execution details and initial status\n- Use `id` field to monitor progress via `GET /runs/{run_id}`\n\n**Running an app instead?** Apps have their own surface — use `POST /app-runs`\nwith an `app_id`. See the Apps and App Runs sections.\n\n**Error Codes:**\n- `400`: Invalid input format or missing required inputs\n- `404`: Agent not found or not accessible","operationId":"create_run_runs__post","parameters":[{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ```` ## Get Run > Get detailed information about a specific agent execution run.\ > \ > This endpoint retrieves comprehensive information about an execution run,\ > including real-time status, progress, inputs, and results when available.\ > \ > \*\*Monitoring Workflow:\*\*\ > 1\. Create run via \`POST /runs\`\ > 2\. Poll this endpoint to monitor progress\ > 3\. If \`awaiting\_human\_review\` becomes \`true\`, inspect \`pending\_reviews\`\ > and resolve each via \`POST /runs/{run\_id}/reviews/{review\_id}\` to\ > resume execution\ > 4\. Stop polling when status becomes "completed", "failed", or "canceled"\ > 5\. Extract results from the \`results\` array when status is "completed"\ > \ > \*\*Progress Tracking:\*\*\ > \- \`status\`: Current execution state\ > \- \`progress\`: Completion percentage (0.0 to 1.0)\ > \- \`awaiting\_human\_review\`: \`true\` when the run is paused on a human\ > review node; \`status\` stays \`in\_progress\` in this case\ > \- \`pending\_reviews\`: List of review steps awaiting a decision\ > \- \`created\_at\`: When execution started\ > \- \`completed\_at\`: When execution finished (if applicable)\ > \ > \*\*How to Retrieve Results:\*\*\ > \ > When the run status becomes "completed", the \`results\` array contains the agent outputs.\ > Call \`GET /agents/{agent\_id}\` and examine the \`outputs\` array to understand what\ > results to expect, then match results to outputs by \`id\`:\ > \ > \*\*Text Results\*\*: Use \`value\` directly as string.\ > \ > \*\*Asset Results\*\* (images/videos/audio): \`value\` is an array of asset UUIDs.\ > Resolve each via \`GET /assets/{id}\` and fetch the \`url\` field.\ > \ > \*\*Cost Information:\*\*\ > \- \`cost\`: Total credits consumed by the execution\ > \ > \*\*Error Handling:\*\*\ > \- \`error\`: Error message if execution failed\ > \- \`failure\_reason\`: Categorized failure cause\ > \ > \*\*Error Codes:\*\*\ > \- \`404\`: Run not found or not accessible ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"runs","description":"Create, monitor, and cancel agent executions."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"Run":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique run identifier"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id","description":"ID of the agent being executed"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"Client-supplied reference id provided at creation, if any"},"status":{"$ref":"#/components/schemas/FlowRunStatus","description":"Current execution state: in_progress, completed, failed, or canceled"},"progress":{"type":"number","maximum":1,"minimum":0,"title":"Progress","description":"Completion progress from 0.0 to 1.0","default":0},"current_node":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Node","description":"Type of the node currently executing (e.g. image_generation, llm). Only present while status is in_progress"},"awaiting_human_review":{"type":"boolean","title":"Awaiting Human Review","description":"True when the run has paused on one or more human review nodes and is waiting for a decision via POST /runs/{run_id}/reviews/{review_id}. While true, `status` remains `in_progress`.","default":false},"pending_reviews":{"items":{"$ref":"#/components/schemas/PendingReview"},"type":"array","title":"Pending Reviews","description":"Human review steps currently waiting for a decision. Empty unless `awaiting_human_review` is true."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the run was created"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When execution started"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When execution finished"},"inputs":{"items":{"$ref":"#/components/schemas/RunInput"},"type":"array","title":"Inputs","description":"Inputs provided for this run"},"results":{"items":{"$ref":"#/components/schemas/RunResult"},"type":"array","title":"Results","description":"Output results, populated when status is completed"},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Total credits consumed by this run"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if the run failed"},"failure_reason":{"anyOf":[{"$ref":"#/components/schemas/FailureReason"},{"type":"null"}],"description":"Categorized failure reason (timeout, content_policy, insufficient_credits, invalid_input, provider_error, provider_auth_required, canceled, unknown). Present when status is failed."}},"type":"object","required":["id","agent_id","status","created_at"],"title":"Run","description":"Complete representation of an agent execution run."},"FlowRunStatus":{"type":"string","enum":["in_progress","completed","failed","canceled"],"title":"FlowRunStatus","description":"Execution status of a workflow run."},"PendingReview":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Identifier of the pending review. Use this as `review_id` when calling POST /runs/{run_id}/reviews/{review_id} to resume execution."},"node_id":{"type":"string","title":"Node Id","description":"ID of the human review node inside the agent definition"},"reviewed_node_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reviewed Node Type","description":"Type of the upstream node whose output is being reviewed (e.g. image_generation, llm). May be null for legacy reviews."},"reviewed_output_type":{"anyOf":[{"$ref":"#/components/schemas/DataType"},{"type":"null"}],"description":"Business-friendly type of the output under review (text, images, videos, audio, files, data)."},"proposed_output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"string"},{"type":"null"}],"title":"Proposed Output","description":"Output produced by the upstream node(s) that is being reviewed. Submit this back (optionally edited) as `output` when approving. To discard items, submit only the ones you want to keep — omitted items are dropped. At least one item must be kept."},"can_edit_outputs":{"type":"boolean","title":"Can Edit Outputs","description":"Whether the agent definition allows editing the proposed output before approval.","default":false},"can_generate_more":{"type":"boolean","title":"Can Generate More","description":"Whether the agent definition allows regenerating the upstream output (decision=retry).","default":false},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the review was opened"}},"type":"object","required":["id","node_id","created_at"],"title":"PendingReview","description":"A human review step that is currently waiting for a decision."},"DataType":{"type":"string","enum":["text","images","videos","files","audio","data"],"title":"DataType","description":"Types of data that agents can accept as input or produce as output."},"RunInput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID that this input targets"},"value":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"}],"title":"Value","description":"Input value: plain text string for text inputs, or {\"asset_ids\": [\"uuid\"]} for asset inputs"}},"type":"object","required":["id","value"],"title":"RunInput","description":"Represents an input provided to a run.\n\nShared by agent runs and app runs: both pipelines accept the same wire shape."},"RunResult":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID that produced this result"},"type":{"$ref":"#/components/schemas/DataType","description":"Type of the result data"},"value":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Value","description":"Result content: text string, list of asset UUIDs, or structured data"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Human-readable description of the result"}},"type":"object","required":["id","type"],"title":"RunResult","description":"Represents a result produced by a run.\n\nShared by agent runs and app runs: both pipelines emit the same wire shape."},"FailureReason":{"type":"string","enum":["timeout","content_policy","insufficient_credits","invalid_input","provider_error","provider_auth_required","canceled","unknown"],"title":"FailureReason","description":"Stable, client-facing categories for why a run failed. A curated public\nview over the internal `NodeFailureReason`; internal-only causes collapse to\n`unknown` so the public contract stays stable as internals change."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/runs/{run_id}":{"get":{"tags":["runs"],"summary":"Get Run","description":"Get detailed information about a specific agent execution run.\n\nThis endpoint retrieves comprehensive information about an execution run,\nincluding real-time status, progress, inputs, and results when available.\n\n**Monitoring Workflow:**\n1. Create run via `POST /runs`\n2. Poll this endpoint to monitor progress\n3. If `awaiting_human_review` becomes `true`, inspect `pending_reviews`\n and resolve each via `POST /runs/{run_id}/reviews/{review_id}` to\n resume execution\n4. Stop polling when status becomes \"completed\", \"failed\", or \"canceled\"\n5. Extract results from the `results` array when status is \"completed\"\n\n**Progress Tracking:**\n- `status`: Current execution state\n- `progress`: Completion percentage (0.0 to 1.0)\n- `awaiting_human_review`: `true` when the run is paused on a human\n review node; `status` stays `in_progress` in this case\n- `pending_reviews`: List of review steps awaiting a decision\n- `created_at`: When execution started\n- `completed_at`: When execution finished (if applicable)\n\n**How to Retrieve Results:**\n\nWhen the run status becomes \"completed\", the `results` array contains the agent outputs.\nCall `GET /agents/{agent_id}` and examine the `outputs` array to understand what\nresults to expect, then match results to outputs by `id`:\n\n**Text Results**: Use `value` directly as string.\n\n**Asset Results** (images/videos/audio): `value` is an array of asset UUIDs.\nResolve each via `GET /assets/{id}` and fetch the `url` field.\n\n**Cost Information:**\n- `cost`: Total credits consumed by the execution\n\n**Error Handling:**\n- `error`: Error message if execution failed\n- `failure_reason`: Categorized failure cause\n\n**Error Codes:**\n- `404`: Run not found or not accessible","operationId":"get_run_runs__run_id__get","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Cancel Run > Cancel an ongoing agent execution run.\ > \ > This endpoint allows you to cancel an execution that is currently running\ > or pending. Once cancelled, the execution cannot be resumed.\ > \ > \*\*Behavior:\*\*\ > \- Only running or pending executions can be cancelled\ > \- Completed or failed executions cannot be cancelled\ > \- Cancellation may take a few seconds to take effect\ > \ > \*\*Error Codes:\*\*\ > \- \`404\`: Run not found or not accessible ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"runs","description":"Create, monitor, and cancel agent executions."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/runs/{run_id}":{"delete":{"tags":["runs"],"summary":"Cancel Run","description":"Cancel an ongoing agent execution run.\n\nThis endpoint allows you to cancel an execution that is currently running\nor pending. Once cancelled, the execution cannot be resumed.\n\n**Behavior:**\n- Only running or pending executions can be cancelled\n- Completed or failed executions cannot be cancelled\n- Cancellation may take a few seconds to take effect\n\n**Error Codes:**\n- `404`: Run not found or not accessible","operationId":"cancel_run_runs__run_id__delete","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Submit Review > Resolve a pending human review and resume an execution.\ > \ > When an agent includes a human review step, the run pauses on that node\ > and \`awaiting\_human\_review\` becomes \`true\` on \`GET /runs/{run\_id}\`. Each\ > waiting step is listed in the run's \`pending\_reviews\` array. Submit a\ > decision here to resume.\ > \ > \*\*Discovering pending reviews\*\*\ > \ > 1\. Poll \`GET /runs/{run\_id}\` until \`awaiting\_human\_review\` is \`true\`.\ > 2\. Inspect the \`pending\_reviews\` array. Use a review's \`id\` as\ > \`review\_id\` in this endpoint's path.\ > 3\. The \`proposed\_output\` field of each review is what the upstream node\ > generated. Submit it back as \`output\` (optionally edited) to approve.\ > \ > \*\*Decisions\*\*\ > \ > \- \`approve\`: continue execution. The \`output\` body field is required and\ > must match the shape of \`proposed\_output\`:\ > \- Image / video / audio reviews: \`{"asset\_ids": \["..."]}\`.\ > \- Text-prompt reviews: \`{"prompts": \["..."]}\`.\ > To discard items, approve with only the ones you want to keep — omitted\ > items are dropped. At least one item must be kept (an empty \`output\` is\ > rejected with \`400\`).\ > \- \`retry\`: re-run the upstream node(s) to produce a new candidate output.\ > The run goes back to "in progress"; poll again to retrieve the new\ > \`pending\_reviews\` entry once it's ready. \`output\` is ignored.\ > \ > \*\*Examples\*\*\ > \ > Approve an image review using the proposed assets:\ > \`\`\`json\ > {\ > "decision": "approve",\ > "output": {\ > "asset\_ids": \[\ > "asset-uuid-001",\ > "asset-uuid-002"\ > ]\ > }\ > }\ > \`\`\`\ > \ > Discard some of the proposed assets by approving with only the kept subset:\ > \`\`\`json\ > {"decision": "approve", "output": {"asset\_ids": \["asset-uuid-001"]}}\ > \`\`\`\ > \ > Retry to regenerate the upstream output:\ > \`\`\`json\ > {"decision": "retry"}\ > \`\`\`\ > \ > \*\*Error Codes:\*\*\ > \- \`400\`: Missing \`output\`, or an empty \`output\` (nothing kept), when\ > decision is \`approve\`.\ > \- \`404\`: Run not found, or no pending review with that ID on this run.\ > \- \`409\`: The review is no longer waiting (already submitted, or the run\ > finished/failed/was canceled). ````json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"runs","description":"Create, monitor, and cancel agent executions."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"SubmitReviewRequest":{"properties":{"decision":{"$ref":"#/components/schemas/ReviewDecision","description":"`approve` resumes execution using the (optionally edited) output. `retry` re-runs the upstream node(s) to produce a new candidate output."},"output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"string"},{"type":"null"}],"title":"Output","description":"Output to use when continuing execution. Required when decision is `approve`. Ignored when decision is `retry`. Must match the shape of `proposed_output` ({\"asset_ids\": [...]} for image/video/audio reviews, or {\"prompts\": [...]} for text-prompt reviews). To discard items, submit only the ones you want to keep; the rest are dropped. At least one item is required — an empty output is rejected."}},"type":"object","required":["decision"],"title":"SubmitReviewRequest","description":"Request to resolve a pending human review."},"ReviewDecision":{"type":"string","enum":["approve","retry"],"title":"ReviewDecision","description":"Possible decisions when responding to a pending human review."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/runs/{run_id}/reviews/{review_id}":{"post":{"tags":["runs"],"summary":"Submit Review","description":"Resolve a pending human review and resume an execution.\n\nWhen an agent includes a human review step, the run pauses on that node\nand `awaiting_human_review` becomes `true` on `GET /runs/{run_id}`. Each\nwaiting step is listed in the run's `pending_reviews` array. Submit a\ndecision here to resume.\n\n**Discovering pending reviews**\n\n1. Poll `GET /runs/{run_id}` until `awaiting_human_review` is `true`.\n2. Inspect the `pending_reviews` array. Use a review's `id` as\n `review_id` in this endpoint's path.\n3. The `proposed_output` field of each review is what the upstream node\n generated. Submit it back as `output` (optionally edited) to approve.\n\n**Decisions**\n\n- `approve`: continue execution. The `output` body field is required and\n must match the shape of `proposed_output`:\n - Image / video / audio reviews: `{\"asset_ids\": [\"...\"]}`.\n - Text-prompt reviews: `{\"prompts\": [\"...\"]}`.\n To discard items, approve with only the ones you want to keep — omitted\n items are dropped. At least one item must be kept (an empty `output` is\n rejected with `400`).\n- `retry`: re-run the upstream node(s) to produce a new candidate output.\n The run goes back to \"in progress\"; poll again to retrieve the new\n `pending_reviews` entry once it's ready. `output` is ignored.\n\n**Examples**\n\nApprove an image review using the proposed assets:\n```json\n{\n \"decision\": \"approve\",\n \"output\": {\n \"asset_ids\": [\n \"asset-uuid-001\",\n \"asset-uuid-002\"\n ]\n }\n}\n```\n\nDiscard some of the proposed assets by approving with only the kept subset:\n```json\n{\"decision\": \"approve\", \"output\": {\"asset_ids\": [\"asset-uuid-001\"]}}\n```\n\nRetry to regenerate the upstream output:\n```json\n{\"decision\": \"retry\"}\n```\n\n**Error Codes:**\n- `400`: Missing `output`, or an empty `output` (nothing kept), when\n decision is `approve`.\n- `404`: Run not found, or no pending review with that ID on this run.\n- `409`: The review is no longer waiting (already submitted, or the run\n finished/failed/was canceled).","operationId":"submit_review_runs__run_id__reviews__review_id__post","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}},{"name":"review_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Review Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitReviewRequest"}}}},"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ```` # App Runs App runs are executions of apps. The workflow mirrors agent runs: discover an app, inspect its required inputs, upload any necessary assets, create a run with matching inputs, poll its status, and retrieve the app's curated outputs once complete. Create, monitor, and cancel app executions. ## List App Runs > List app execution runs with filtering options.\ > \ > This endpoint returns a paginated list of app execution runs with their current\ > status and basic metadata. Agent runs are listed separately via \`GET /runs\`.\ > \ > \*\*Filtering Options:\*\*\ > \- \`status\`: Filter by execution status (in\_progress, completed, failed, canceled)\ > \- \`external\_id\`: Filter to runs you tagged with this reference id at creation.\ > Use this to check whether you already started a run for a given item before\ > starting another.\ > \ > \*\*Pagination Parameters:\*\*\ > \- \`limit\`: Maximum number of items to return (default: 20, max: 100)\ > \- \`cursor\`: Cursor for pagination (optional)\ > \ > \*\*Response:\*\*\ > \- \`data\`: List of app-run summaries with basic information\ > \- \`has\_more\`: Indicates if there are more results available\ > \- \`next\_cursor\`: Cursor for the next page of results ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"app-runs","description":"Create, monitor, and cancel app executions."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"FlowRunStatus":{"type":"string","enum":["in_progress","completed","failed","canceled"],"title":"FlowRunStatus","description":"Execution status of a workflow run."},"CursorPaginatedResponse_AppRunSummary_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AppRunSummary"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data","has_more"],"title":"CursorPaginatedResponse[AppRunSummary]"},"AppRunSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique run identifier"},"app_id":{"type":"string","format":"uuid","title":"App Id","description":"Stable ID of the app that was executed"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"Client-supplied reference id provided at creation, if any"},"status":{"$ref":"#/components/schemas/FlowRunStatus","description":"Current execution state"},"progress":{"type":"number","maximum":1,"minimum":0,"title":"Progress","description":"Completion progress from 0.0 to 1.0","default":0},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the run was created"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When execution started"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When execution finished"},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Total credits consumed by this run"}},"type":"object","required":["id","app_id","status","created_at"],"title":"AppRunSummary","description":"Lightweight app-run summary for list views."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/app-runs/":{"get":{"tags":["app-runs"],"summary":"List App Runs","description":"List app execution runs with filtering options.\n\nThis endpoint returns a paginated list of app execution runs with their current\nstatus and basic metadata. Agent runs are listed separately via `GET /runs`.\n\n**Filtering Options:**\n- `status`: Filter by execution status (in_progress, completed, failed, canceled)\n- `external_id`: Filter to runs you tagged with this reference id at creation.\n Use this to check whether you already started a run for a given item before\n starting another.\n\n**Pagination Parameters:**\n- `limit`: Maximum number of items to return (default: 20, max: 100)\n- `cursor`: Cursor for pagination (optional)\n\n**Response:**\n- `data`: List of app-run summaries with basic information\n- `has_more`: Indicates if there are more results available\n- `next_cursor`: Cursor for the next page of results","operationId":"list_app_runs_app_runs__get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/FlowRunStatus"},{"type":"null"}],"title":"Status"}},{"name":"external_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of items to return","default":20,"title":"Limit"},"description":"Maximum number of items to return"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cursor for pagination (from next_cursor)","title":"Cursor"},"description":"Cursor for pagination (from next_cursor)"},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPaginatedResponse_AppRunSummary_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Create App Run > Create and start a new app execution run.\ > \ > This endpoint launches the execution of an app with the provided inputs. The\ > execution runs asynchronously, allowing you to monitor progress and retrieve\ > results when complete.\ > \ > \*\*Idempotency with \`external\_id\`:\*\* Optionally pass an \`external\_id\` (e.g. your\ > own order or job id). It is \*\*unique per organization\*\*: the first request with\ > a given key starts the run; any later write reusing that key — including a\ > dropped-response retry — is rejected with \*\*\`409 conflict\`\*\* instead of starting\ > (and charging) a duplicate. To fetch the run a key already created, use\ > \`GET /app-runs?external\_id=...\`. The id is echoed on every app-run response.\ > \ > \- Scope: per organization, across \*\*all\*\* runs (agent and app share the key\ > space) and \*\*all\*\* statuses — a key, once used, stays used.\ > \- On \`409\`, do \*\*not\*\* keep retrying the create; \`GET /app-runs?external\_id=\` to\ > retrieve the existing run. To start a genuinely new run, use a new \`external\_id\`.\ > \ > \*\*How to Build Inputs:\*\*\ > \ > 1\. \*\*First, get app details\*\*: Call \`GET /apps/{app\_id}\` to retrieve the app\ > configuration.\ > 2\. \*\*Examine the \`inputs\` array\*\*: Each object defines what input the app expects:\ > \- \`id\`: Use this as the \`id\` in your input object\ > \- \`type\`: text, image, video, audio, brand, or file\ > \- \`required\`: whether the input is mandatory\ > \- \`options\` / \`min\_selections\` / \`max\_selections\`: constraints for fixed-set inputs\ > \ > \*\*Text Inputs:\*\*\ > \`\`\`json\ > {"id": "text\_input\_node\_id", "value": "Your text content here"}\ > \`\`\`\ > \ > \*\*Asset Inputs\*\* (image / video / audio / file):\ > \`\`\`json\ > {"id": "image\_input\_node\_id", "value": {"asset\_ids": \["uuid1", "uuid2"]}}\ > \`\`\`\ > Upload assets first via \`POST /assets/upload\` to get the UUIDs.\ > \ > \*\*Example:\*\*\ > \`\`\`json\ > {\ > "app\_id": "550e8400-e29b-41d4-a716-446655440000",\ > "inputs": \[\ > {"id": "uuid-1", "value": "Create a marketing banner for a tech startup"}\ > ]\ > }\ > \`\`\`\ > \ > \*\*Curated contract:\*\* only the inputs advertised by \`GET /apps/{app\_id}\` are\ > accepted. Unknown input ids, missing required inputs, and values that violate an\ > input's \`options\` / \`min\_selections\` / \`max\_selections\` are rejected with \`400\`.\ > The completed run's \`results\` contain only the app's curated outputs — never the\ > underlying flow's internal nodes.\ > \ > \*\*Response:\*\*\ > \- AppRun object with execution details and initial status\ > \- Use \`id\` to monitor progress via \`GET /app-runs/{run\_id}\`\ > \ > \*\*Error Codes:\*\*\ > \- \`400\`: Invalid input format, missing required inputs, or values outside constraints\ > \- \`404\`: App not found or not accessible ````json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"app-runs","description":"Create, monitor, and cancel app executions."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"AppRunCreateRequest":{"properties":{"app_id":{"type":"string","format":"uuid","title":"App Id","description":"Stable ID of the app to execute"},"inputs":{"items":{"$ref":"#/components/schemas/RunInput"},"type":"array","title":"Inputs","description":"Inputs for the app. Get required inputs from GET /apps/{id}"},"external_id":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"External Id","description":"Optional client-supplied reference id (e.g. your order or job id, max 255 chars). Unique per organization: reusing one returns 409 conflict — so a dropped-response retry never creates a duplicate. Echoed on every app run and filterable via GET /app-runs?external_id= to fetch it. Use a new id per run."}},"type":"object","required":["app_id"],"title":"AppRunCreateRequest","description":"Request to create and start a new app execution run."},"RunInput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID that this input targets"},"value":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"}],"title":"Value","description":"Input value: plain text string for text inputs, or {\"asset_ids\": [\"uuid\"]} for asset inputs"}},"type":"object","required":["id","value"],"title":"RunInput","description":"Represents an input provided to a run.\n\nShared by agent runs and app runs: both pipelines accept the same wire shape."},"AppRun":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique run identifier"},"app_id":{"type":"string","format":"uuid","title":"App Id","description":"Stable ID of the app being executed"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"Client-supplied reference id provided at creation, if any"},"status":{"$ref":"#/components/schemas/FlowRunStatus","description":"Current execution state: in_progress, completed, failed, or canceled"},"progress":{"type":"number","maximum":1,"minimum":0,"title":"Progress","description":"Completion progress from 0.0 to 1.0","default":0},"current_node":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Node","description":"Type of the node currently executing (e.g. image_generation, llm). Only present while status is in_progress"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the run was created"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When execution started"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When execution finished"},"inputs":{"items":{"$ref":"#/components/schemas/RunInput"},"type":"array","title":"Inputs","description":"Inputs provided for this run"},"results":{"items":{"$ref":"#/components/schemas/RunResult"},"type":"array","title":"Results","description":"Curated app outputs, populated when status is completed"},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Total credits consumed by this run"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if the run failed"},"failure_reason":{"anyOf":[{"$ref":"#/components/schemas/FailureReason"},{"type":"null"}],"description":"Categorized failure reason (timeout, content_policy, insufficient_credits, invalid_input, provider_error, provider_auth_required, canceled, unknown). Present when status is failed."}},"type":"object","required":["id","app_id","status","created_at"],"title":"AppRun","description":"Complete representation of an app execution run."},"FlowRunStatus":{"type":"string","enum":["in_progress","completed","failed","canceled"],"title":"FlowRunStatus","description":"Execution status of a workflow run."},"RunResult":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID that produced this result"},"type":{"$ref":"#/components/schemas/DataType","description":"Type of the result data"},"value":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Value","description":"Result content: text string, list of asset UUIDs, or structured data"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Human-readable description of the result"}},"type":"object","required":["id","type"],"title":"RunResult","description":"Represents a result produced by a run.\n\nShared by agent runs and app runs: both pipelines emit the same wire shape."},"DataType":{"type":"string","enum":["text","images","videos","files","audio","data"],"title":"DataType","description":"Types of data that agents can accept as input or produce as output."},"FailureReason":{"type":"string","enum":["timeout","content_policy","insufficient_credits","invalid_input","provider_error","provider_auth_required","canceled","unknown"],"title":"FailureReason","description":"Stable, client-facing categories for why a run failed. A curated public\nview over the internal `NodeFailureReason`; internal-only causes collapse to\n`unknown` so the public contract stays stable as internals change."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/app-runs/":{"post":{"tags":["app-runs"],"summary":"Create App Run","description":"Create and start a new app execution run.\n\nThis endpoint launches the execution of an app with the provided inputs. The\nexecution runs asynchronously, allowing you to monitor progress and retrieve\nresults when complete.\n\n**Idempotency with `external_id`:** Optionally pass an `external_id` (e.g. your\nown order or job id). It is **unique per organization**: the first request with\na given key starts the run; any later write reusing that key — including a\ndropped-response retry — is rejected with **`409 conflict`** instead of starting\n(and charging) a duplicate. To fetch the run a key already created, use\n`GET /app-runs?external_id=...`. The id is echoed on every app-run response.\n\n- Scope: per organization, across **all** runs (agent and app share the key\n space) and **all** statuses — a key, once used, stays used.\n- On `409`, do **not** keep retrying the create; `GET /app-runs?external_id=` to\n retrieve the existing run. To start a genuinely new run, use a new `external_id`.\n\n**How to Build Inputs:**\n\n1. **First, get app details**: Call `GET /apps/{app_id}` to retrieve the app\n configuration.\n2. **Examine the `inputs` array**: Each object defines what input the app expects:\n - `id`: Use this as the `id` in your input object\n - `type`: text, image, video, audio, brand, or file\n - `required`: whether the input is mandatory\n - `options` / `min_selections` / `max_selections`: constraints for fixed-set inputs\n\n**Text Inputs:**\n```json\n{\"id\": \"text_input_node_id\", \"value\": \"Your text content here\"}\n```\n\n**Asset Inputs** (image / video / audio / file):\n```json\n{\"id\": \"image_input_node_id\", \"value\": {\"asset_ids\": [\"uuid1\", \"uuid2\"]}}\n```\nUpload assets first via `POST /assets/upload` to get the UUIDs.\n\n**Example:**\n```json\n{\n \"app_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"inputs\": [\n {\"id\": \"uuid-1\", \"value\": \"Create a marketing banner for a tech startup\"}\n ]\n}\n```\n\n**Curated contract:** only the inputs advertised by `GET /apps/{app_id}` are\naccepted. Unknown input ids, missing required inputs, and values that violate an\ninput's `options` / `min_selections` / `max_selections` are rejected with `400`.\nThe completed run's `results` contain only the app's curated outputs — never the\nunderlying flow's internal nodes.\n\n**Response:**\n- AppRun object with execution details and initial status\n- Use `id` to monitor progress via `GET /app-runs/{run_id}`\n\n**Error Codes:**\n- `400`: Invalid input format, missing required inputs, or values outside constraints\n- `404`: App not found or not accessible","operationId":"create_app_run_app_runs__post","parameters":[{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppRunCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppRun"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ```` ## Get App Run > Get detailed information about a specific app execution run.\ > \ > This endpoint retrieves comprehensive information about an app run, including\ > real-time status, progress, inputs, and curated results when available.\ > \ > \*\*Monitoring Workflow:\*\*\ > 1\. Create run via \`POST /app-runs\`\ > 2\. Poll this endpoint to monitor progress\ > 3\. Stop polling when status becomes "completed", "failed", or "canceled"\ > 4\. Extract results from the \`results\` array when status is "completed"\ > \ > \*\*How to Retrieve Results:\*\*\ > Call \`GET /apps/{app\_id}\` and examine the \`outputs\` array, then match results to\ > outputs by \`id\`. Asset results (images/videos/audio/files) are arrays of asset\ > UUIDs — resolve each via \`GET /assets/{id}\` and fetch the \`url\` field.\ > \ > \*\*Error Codes:\*\*\ > \- \`404\`: Run not found or not accessible ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"app-runs","description":"Create, monitor, and cancel app executions."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"AppRun":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique run identifier"},"app_id":{"type":"string","format":"uuid","title":"App Id","description":"Stable ID of the app being executed"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"Client-supplied reference id provided at creation, if any"},"status":{"$ref":"#/components/schemas/FlowRunStatus","description":"Current execution state: in_progress, completed, failed, or canceled"},"progress":{"type":"number","maximum":1,"minimum":0,"title":"Progress","description":"Completion progress from 0.0 to 1.0","default":0},"current_node":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Node","description":"Type of the node currently executing (e.g. image_generation, llm). Only present while status is in_progress"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the run was created"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When execution started"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When execution finished"},"inputs":{"items":{"$ref":"#/components/schemas/RunInput"},"type":"array","title":"Inputs","description":"Inputs provided for this run"},"results":{"items":{"$ref":"#/components/schemas/RunResult"},"type":"array","title":"Results","description":"Curated app outputs, populated when status is completed"},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Total credits consumed by this run"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if the run failed"},"failure_reason":{"anyOf":[{"$ref":"#/components/schemas/FailureReason"},{"type":"null"}],"description":"Categorized failure reason (timeout, content_policy, insufficient_credits, invalid_input, provider_error, provider_auth_required, canceled, unknown). Present when status is failed."}},"type":"object","required":["id","app_id","status","created_at"],"title":"AppRun","description":"Complete representation of an app execution run."},"FlowRunStatus":{"type":"string","enum":["in_progress","completed","failed","canceled"],"title":"FlowRunStatus","description":"Execution status of a workflow run."},"RunInput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID that this input targets"},"value":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"}],"title":"Value","description":"Input value: plain text string for text inputs, or {\"asset_ids\": [\"uuid\"]} for asset inputs"}},"type":"object","required":["id","value"],"title":"RunInput","description":"Represents an input provided to a run.\n\nShared by agent runs and app runs: both pipelines accept the same wire shape."},"RunResult":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID that produced this result"},"type":{"$ref":"#/components/schemas/DataType","description":"Type of the result data"},"value":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Value","description":"Result content: text string, list of asset UUIDs, or structured data"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Human-readable description of the result"}},"type":"object","required":["id","type"],"title":"RunResult","description":"Represents a result produced by a run.\n\nShared by agent runs and app runs: both pipelines emit the same wire shape."},"DataType":{"type":"string","enum":["text","images","videos","files","audio","data"],"title":"DataType","description":"Types of data that agents can accept as input or produce as output."},"FailureReason":{"type":"string","enum":["timeout","content_policy","insufficient_credits","invalid_input","provider_error","provider_auth_required","canceled","unknown"],"title":"FailureReason","description":"Stable, client-facing categories for why a run failed. A curated public\nview over the internal `NodeFailureReason`; internal-only causes collapse to\n`unknown` so the public contract stays stable as internals change."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/app-runs/{run_id}":{"get":{"tags":["app-runs"],"summary":"Get App Run","description":"Get detailed information about a specific app execution run.\n\nThis endpoint retrieves comprehensive information about an app run, including\nreal-time status, progress, inputs, and curated results when available.\n\n**Monitoring Workflow:**\n1. Create run via `POST /app-runs`\n2. Poll this endpoint to monitor progress\n3. Stop polling when status becomes \"completed\", \"failed\", or \"canceled\"\n4. Extract results from the `results` array when status is \"completed\"\n\n**How to Retrieve Results:**\nCall `GET /apps/{app_id}` and examine the `outputs` array, then match results to\noutputs by `id`. Asset results (images/videos/audio/files) are arrays of asset\nUUIDs — resolve each via `GET /assets/{id}` and fetch the `url` field.\n\n**Error Codes:**\n- `404`: Run not found or not accessible","operationId":"get_app_run_app_runs__run_id__get","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppRun"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Cancel App Run > Cancel an ongoing app execution run.\ > \ > This endpoint allows you to cancel an execution that is currently running or\ > pending. Once cancelled, the execution cannot be resumed.\ > \ > \*\*Behavior:\*\*\ > \- Only running or pending executions can be cancelled\ > \- Completed or failed executions cannot be cancelled\ > \- Cancellation may take a few seconds to take effect\ > \ > \*\*Error Codes:\*\*\ > \- \`404\`: Run not found or not accessible ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"app-runs","description":"Create, monitor, and cancel app executions."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/app-runs/{run_id}":{"delete":{"tags":["app-runs"],"summary":"Cancel App Run","description":"Cancel an ongoing app execution run.\n\nThis endpoint allows you to cancel an execution that is currently running or\npending. Once cancelled, the execution cannot be resumed.\n\n**Behavior:**\n- Only running or pending executions can be cancelled\n- Completed or failed executions cannot be cancelled\n- Cancellation may take a few seconds to take effect\n\n**Error Codes:**\n- `404`: Run not found or not accessible","operationId":"cancel_app_run_app_runs__run_id__delete","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` --- [Next Page](/llms-full.txt/1)