Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pixy.art/llms.txt

Use this file to discover all available pages before exploring further.

​
Add the SDK

Load the Pixy embed SDK on the page where you want to launch the editor. 
<script src="https://app.pixy.art/embed/sdk"></script>
Use the SDK when your app needs an onExport callback. Use the iframe fallback only when you do not need a callback into your app.

​
Choose a launch scenario

Every embed launch needs an embedKey and one source for the editor:
  • pass designId to open an existing design
  • pass designId with openAsCopy: true to create a new design from an existing design
  • pass width and height to start from a blank canvas
Do not mix designId with width and height. If you pass a designId, the editor uses that design path. Public template IDs returned by the Templates API are copy-only in Embed: pass the template id as designId and set openAsCopy: true.
Use this when the user should continue editing the same saved design.Behavior:
  • opens the design identified by designId
  • does not create a copy before loading
  • save/export returns the same design id through onExport
  • use the returned designId to reopen the same design later
<script src="https://app.pixy.art/embed/sdk"></script>
<div id="pixy" style="width: 100%; height: 900px;"></div>
<script>
  window.Pixy.mount('#pixy', {
    embedKey: 'YOUR_EMBED_KEY',
    designId: 'YOUR_DESIGN_ID',
    saveButtonLabel: 'Save',
    onExport: (result) => {
      console.log(result.designId)
      console.log(result.files)
    },
  })
</script>
Use this for saved user projects, drafts, or any workflow where reopening the design should continue from the previous state.
Use this when an existing design should behave like a template. This is required when the source designId is a public template returned by the Templates API.Behavior:
  • looks up the source design by designId
  • creates a new design copy when the editor loads, even before the user exports
  • opens the new copied design, not the original source design
  • keeps the original source design unchanged
  • save/export returns the new copied design id through onExport
  • every launch with openAsCopy: true creates another new copy
<script src="https://app.pixy.art/embed/sdk"></script>
<div id="pixy" style="width: 100%; height: 900px;"></div>
<script>
  window.Pixy.mount('#pixy', {
    embedKey: 'YOUR_EMBED_KEY',
    designId: 'YOUR_TEMPLATE_DESIGN_ID',
    openAsCopy: true,
    saveButtonLabel: 'Use design',
    onExport: (result) => {
      console.log(result.designId)
      console.log(result.files)
    },
  })
</script>
Store the returned result.designId if the user should continue editing that copy later. To reopen that saved copy, launch with the returned designId and leave openAsCopy off.Your app receives the copied design id only after onExport runs. If the user opens the editor and closes it without saving, the copy may already exist in Pixy, but your app will not receive that new id.
Use this when the editor should start with an empty design.Behavior:
  • creates a new design with the provided width and height
  • does not require a template or existing design
  • creates the blank design when the editor loads, even before the user exports
  • save/export returns the new design id through onExport
  • use the returned designId to reopen the design later
<script src="https://app.pixy.art/embed/sdk"></script>
<div id="pixy" style="width: 100%; height: 900px;"></div>
<script>
  window.Pixy.mount('#pixy', {
    embedKey: 'YOUR_EMBED_KEY',
    width: 1080,
    height: 1350,
    saveButtonLabel: 'Save',
    onExport: (result) => {
      console.log(result.designId)
      console.log(result.files)
    },
  })
</script>
You must provide both width and height for a blank canvas.Your app receives the new blank design id only after onExport runs. If the user opens the editor and closes it without saving, the design may already exist in Pixy, but your app will not receive that new id.

​
Optional User ID

Pass userId when you want Pixy to associate the opened or newly created design with a user from your app. This is not a Pixy user id and does not need to exist in Pixy. It is stored as embed metadata and can be used later with the Automation API designs endpoint. 
window.Pixy.mount('#pixy', {
  embedKey: 'YOUR_EMBED_KEY',
  userId: 'YOUR_APP_USER_ID',
  designId: 'YOUR_DESIGN_ID',
  onExport: (result) => {
    console.log(result.designId)
    console.log(result.files)
  },
})
Use the same optional userId value when listing designs through the Automation API. 
GET /api/v1/designs?userId=YOUR_APP_USER_ID
Authorization: Bearer YOUR_API_KEY
If userId is omitted, the design is still saved and can still be listed without a user filter.

​
Appearance

The launch scenario controls which design opens. Inline and modal only control how the editor appears.
Inline mounts the editor inside your page. In inline mode, the editor stays open after save.
window.Pixy.mount('#pixy', {
  embedKey: 'YOUR_EMBED_KEY',
  designId: 'YOUR_DESIGN_ID',
  saveButtonLabel: 'Schedule',
  onExport: (result) => {
    console.log(result)
  },
})

​
Export Callback

When onExport is provided, the embedded editor shows a Save button that sends the export result back to your app. onExport receives the render id, the saved design id, duration, and uploaded export files. Set saveButtonLabel to customize the button text for your workflow. The label is limited to 32 characters. For example, use Schedule when your app opens a scheduler after receiving the exported files. 
{
  id: 'YOUR_RENDER_ID',
  designId: 'SAVED_DESIGN_ID',
  duration: 1240,
  files: [
    {
      mimetype: 'image/png',
      url: 'https://cdn.pixy.art/...',
      width: 1080,
      height: 1080,
      size: 245182,
    },
  ],
}
Important details:
  • result.designId is the design that was actually saved
  • for a normal existing design, this is the original designId
  • for openAsCopy: true, this is the new copied design id
  • for a blank canvas, this is the new blank design id
  • each successful embed save consumes credits based on the number of exported files

​
Iframe Fallback

Use a plain iframe only when you do not need onExport. 
<iframe
  src="https://app.pixy.art/embed/editor?embedKey=YOUR_EMBED_KEY&designId=YOUR_DESIGN_ID"
  width="100%"
  height="720"
  style="border:0;"
></iframe>