How to use - Pixy API Docs

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

Existing design

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',
    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.

Existing design as a copy

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,
    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.

Blank canvas

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,
    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.

For optional per-launch fields like userId, saveButtonLabel, and imageUrls, see Optional parameters. 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.

Appearance

The launch scenario controls which design opens. Inline and modal only control how the editor appears.

Inline

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)
  },
})

Modal

Modal opens the editor in an overlay. In modal mode, a successful save calls onExport and then closes the modal automatically.

<script src="https://app.pixy.art/embed/sdk"></script>
<button id="open-pixy">Open editor</button>
<script>
  const pixy = window.Pixy.create({
    embedKey: 'YOUR_EMBED_KEY',
    designId: 'YOUR_DESIGN_ID',
    saveButtonLabel: 'Schedule',
    onExport: (result) => {
      console.log(result)
    },
  })

  document
    .getElementById('open-pixy')
    .addEventListener('click', () => pixy.open())
</script>

Export Callback

When onExport is provided, the embedded editor shows an Export button that sends the export result back to your app. onExport receives the render id, the saved design id, duration, and uploaded export files. Use saveButtonLabel when you need the save button to match your workflow. For details, see Optional parameters.

{
  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>

​Add the SDK

​Choose a launch scenario

​Appearance

​Export Callback

​Iframe Fallback

Add the SDK

Choose a launch scenario

Appearance

Export Callback

Iframe Fallback