---
title: "Create a new Studio session"
method: POST
path: "/api/v1/studio/create-session"
tags: ["Studio"]
---

# Create a new Studio session

`POST /api/v1/studio/create-session`

## Request

- Base URL: `https://api.sudomock.com`
- URL: `https://api.sudomock.com/api/v1/studio/create-session`
- Auth: API key in header `x-api-key`

Generates an opaque session token for the Studio iframe on WooCommerce, custom storefronts, and Shopify storefronts that call through the App Proxy. No unauthenticated access. API key never leaves the server.

## Request body

- CreateSessionRequest
  - `mockup_type` 'psd' | '2d', nullable: Which editor the session opens, psd or 2d.
  - `session_kind` 'setup' | 'customize', nullable: What the session is for, setup or customize.
  - `mockup_uuid` string, nullable: UUID of the mockup to customize
  - `product_id` string, nullable: Product ID from the platform
  - `variant_id` string, nullable: Variant ID from the platform
  - `allowed_origin` string, nullable: HTTPS origin of the page that embeds the editor.
  - `config` StudioConfigPatch
    - `primaryColor` string, nullable: Primary color of the editor interface.
    - `accentColor` string, nullable: Accent color for highlights and active states in the editor.
    - `backgroundColor` string, nullable: Background color of the editor.
    - `panelBackground` string, nullable: Background color of the editor panels.
    - `textColor` string, nullable: Color of the text in the editor.
    - `borderColor` string, nullable: Color of the borders and dividers in the editor.
    - `successColor` string, nullable: Color the editor uses to confirm a completed action.
    - `borderRadius` integer, nullable: Corner radius of the editor controls, in pixels.
    - `logoUrl` string, nullable: HTTPS address of the logo shown in the editor header.
    - `fontFamily` string, nullable: Font family the editor uses for its own text.
    - `headerText` string, nullable: Title shown in the editor header.
    - `uploadText` string, nullable: Prompt shown in the editor upload area.
    - `secondaryActionLabel` string, nullable: Label on the editor secondary action button.
    - `loadingText` string, nullable: Text shown while the primary action is running.
    - `successText` string, nullable: Text shown once the primary action succeeds.
    - `psdPrimaryActionLabel` string, nullable: Label on the primary action button in the PSD editor.
    - `twoDSetupPrimaryActionLabel` string, nullable: Label on the primary action button in a photo mockup setup session.
    - `twoDCustomizePrimaryActionLabel` string, nullable: Label on the primary action button in a photo mockup customize session.
    - `psdShowAdjustments` boolean, nullable: Shows or hides the image adjustment controls in the PSD editor.
    - `psdShowColorOverlay` boolean, nullable: Shows or hides the color overlay control in the PSD editor.
    - `psdShowTextLayers` boolean, nullable: Shows or hides the text layer controls in the PSD editor.
    - `psdShowFitMode` boolean, nullable: Shows or hides the fit mode control in the PSD editor.
    - `psdShowPosition` boolean, nullable: Shows or hides the position controls in the PSD editor.
    - `psdShowSize` boolean, nullable: Shows or hides the size controls in the PSD editor.
    - `psdShowRotation` boolean, nullable: Shows or hides the rotation control in the PSD editor.
    - `psdShowFlip` boolean, nullable: Shows or hides the flip controls in the PSD editor.
    - `psdShowExportOptions` boolean, nullable: Shows or hides the export options in the PSD editor.
    - `psdShowZoomControls` boolean, nullable: Shows or hides the zoom controls in the PSD editor.
    - `psdShowUndoRedo` boolean, nullable: Shows or hides the undo and redo controls in the PSD editor.
    - `psdAutoRender` boolean, nullable: Renders a new preview after each change in the PSD editor.
    - `psdAutoRenderDelay` integer, nullable: Milliseconds the PSD editor waits after a change before it renders.
    - `autoDesignCallback` boolean, nullable: Reports design changes to your page while the shopper edits.
    - `psdLayout` 'full' | 'compact', nullable: Layout of the PSD editor, full or compact.
    - `twoDShowArtwork` boolean, nullable: Shows or hides the artwork upload control in the photo mockup editor.
    - `twoDShowFill` boolean, nullable: Shows or hides the fill color control in the photo mockup editor.
    - `twoDShowBlend` boolean, nullable: Shows or hides the blend mode control in the photo mockup editor.
    - `twoDShowOpacity` boolean, nullable: Shows or hides the opacity control in the photo mockup editor.
    - `twoDShowTransform` boolean, nullable: Shows or hides the transform controls in the photo mockup editor.
    - `twoDShowZoom` boolean, nullable: Shows or hides the zoom controls in the photo mockup editor.
    - `twoDShowExport` boolean, nullable: Shows or hides the export options in the photo mockup editor.
    - `twoDShowBackgroundRemoval` boolean, nullable: Shows or hides the background removal control in the photo mockup editor.
    - `colorPalette` PaletteColour[], nullable: Named colors the product comes in, and the only ones the editor offers.
      - `hex` string, required: Color value as a #rrggbb hex string.
      - `label` string, nullable: Your own name for this color.
    - `showClose` boolean, nullable: Shows or hides the close button in the editor header.
    - `theme` 'light' | 'dark', nullable: Theme the editor opens in, light or dark.
    - `locale` 'en' | 'tr', nullable: Language the editor panel is shown in.
    - `maxFileSize` integer, nullable: Largest upload the editor accepts, in megabytes.
  - `action_id` string, nullable: Your own routing identifier for the action this session completes.
  - `artwork` union: Optional session-locked artwork: a list with one entry per target, up to 8. A single object is also accepted and locks one target. Every target must belong to the explicitly bound mockup, and no target may repeat. Base64 takes precedence over url. The customer may edit placement and appearance but cannot replace, remove, add, or retarget artwork.
    - StudioArtworkInput[]
      - `target_uuid` string, required: Smart Object id for PSD. For a photo mockup, either a saved print area id or a product surface id. The same field accepts both.
      - `url` string, nullable: HTTPS artwork URL. Ignored when base64 is also supplied.
      - `base64` string, nullable: Canonical raw base64 artwork, up to 64 MB decoded. Takes precedence when url is also supplied.
      - `placement` StudioSeedPlacement: Where a locked design starts, in the units of the region that holds it. Every length here is a percentage of the target's own region (the print area's bounding box for a photo mockup, the Smart Object's embedded frame for PSD), because that is the one denominator both sides already have without a second round trip. Offsets run from the region CENTRE, positive right and down, and the unit lives in the field name so a reader who has only ever seen an example still cannot mistake it for pixels. ``box`` is one branch or the other, never a mixture: a width with no height is not a smaller request, it is an unanswerable one, and the branch makes it unsendable rather than merely rejected. This is a starting point, not a lock. The customer may move it afterwards.
        - `box` union, required: How large the design starts: an allowance, or the box itself.
          - StudioSeedAutoBox: An allowance. The artwork keeps its own proportions inside it.
            - `mode` 'auto', required: Marks this box as an allowance the design fits inside.
            - `coverage` integer, required: Percentage of the target region the design is allowed to fill.
          - StudioSeedManualBox: The box itself. The only spelling that can carry a ratio of its own.
            - `mode` 'manual', required: Marks this box as an explicit width and height.
            - `width_percent` number, required: Percentage of the target region's WIDTH.
            - `height_percent` number, required: Percentage of the target region's HEIGHT.
        - `fit` 'fill' | 'fit' | 'crop': How the artwork's pixels meet the box.
        - `offset_x_percent` number: Percentage of the region WIDTH, from the region centre, positive right.
        - `offset_y_percent` number: Percentage of the region HEIGHT, from the region centre, positive down.
        - `rotation` number: Degrees about the box centre, clockwise positive.
        - `flip_horizontal` boolean: Flip artwork horizontally (left-right mirror)
        - `flip_vertical` boolean: Flip artwork vertically (top-bottom mirror)
      - `adjustments` StudioSeedAdjustments: How a design looks when the editor opens it. One spelling for both target kinds, because this is a request rather than a report: the merchant asks for an opening appearance and the session either honours it or refuses to open. Which keys a target can honour differs, and a key the target cannot honour refuses the session, the same way an unsupported placement does. Nothing carries a default. A placement can afford them because `box` is required, so that object never exists half-filled; this one has no required key at all, so a default would be a value the merchant never sent, echoed back as though they had. The bounds are the ones the editor's own controls span, not the wider set the finished image accepts. Seeding a brightness the control cannot reach opens a session whose preview disagrees with its result from the first frame, and the shopper, the only person present, has no way to know. Such a seed is refused, as an unsupported placement is.
        - `brightness` integer, nullable: Brightness, -100 to 100. Omit for the editor's own.
        - `contrast` integer, nullable: Contrast, -100 to 100. Omit for the editor's own.
        - `saturation` integer, nullable: Saturation, -100 to 100. Omit for the editor's own.
        - `vibrance` integer, nullable: Vibrance, -100 to 100. Omit for the editor's own.
        - `opacity` integer, nullable: Opacity, 0 to 100. Omit for the editor's own.
        - `blur` number, nullable: Blur, 0 to 20, in half steps. Omit for the editor's own.
        - `blend_mode` 'multiply' | 'normal' | 'screen' | 'lighten' | 'soft_light' | 'overlay' | 'darken', nullable: How the artwork sits on the product surface. Photo targets only. Omit for the editor's own.
    - StudioArtworkInput
      - `target_uuid` string, required: Smart Object id for PSD. For a photo mockup, either a saved print area id or a product surface id. The same field accepts both.
      - `url` string, nullable: HTTPS artwork URL. Ignored when base64 is also supplied.
      - `base64` string, nullable: Canonical raw base64 artwork, up to 64 MB decoded. Takes precedence when url is also supplied.
      - `placement` StudioSeedPlacement: Where a locked design starts, in the units of the region that holds it. Every length here is a percentage of the target's own region (the print area's bounding box for a photo mockup, the Smart Object's embedded frame for PSD), because that is the one denominator both sides already have without a second round trip. Offsets run from the region CENTRE, positive right and down, and the unit lives in the field name so a reader who has only ever seen an example still cannot mistake it for pixels. ``box`` is one branch or the other, never a mixture: a width with no height is not a smaller request, it is an unanswerable one, and the branch makes it unsendable rather than merely rejected. This is a starting point, not a lock. The customer may move it afterwards.
        - `box` union, required: How large the design starts: an allowance, or the box itself.
          - StudioSeedAutoBox: An allowance. The artwork keeps its own proportions inside it.
            - `mode` 'auto', required: Marks this box as an allowance the design fits inside.
            - `coverage` integer, required: Percentage of the target region the design is allowed to fill.
          - StudioSeedManualBox: The box itself. The only spelling that can carry a ratio of its own.
            - `mode` 'manual', required: Marks this box as an explicit width and height.
            - `width_percent` number, required: Percentage of the target region's WIDTH.
            - `height_percent` number, required: Percentage of the target region's HEIGHT.
        - `fit` 'fill' | 'fit' | 'crop': How the artwork's pixels meet the box.
        - `offset_x_percent` number: Percentage of the region WIDTH, from the region centre, positive right.
        - `offset_y_percent` number: Percentage of the region HEIGHT, from the region centre, positive down.
        - `rotation` number: Degrees about the box centre, clockwise positive.
        - `flip_horizontal` boolean: Flip artwork horizontally (left-right mirror)
        - `flip_vertical` boolean: Flip artwork vertically (top-bottom mirror)
      - `adjustments` StudioSeedAdjustments: How a design looks when the editor opens it. One spelling for both target kinds, because this is a request rather than a report: the merchant asks for an opening appearance and the session either honours it or refuses to open. Which keys a target can honour differs, and a key the target cannot honour refuses the session, the same way an unsupported placement does. Nothing carries a default. A placement can afford them because `box` is required, so that object never exists half-filled; this one has no required key at all, so a default would be a value the merchant never sent, echoed back as though they had. The bounds are the ones the editor's own controls span, not the wider set the finished image accepts. Seeding a brightness the control cannot reach opens a session whose preview disagrees with its result from the first frame, and the shopper, the only person present, has no way to know. Such a seed is refused, as an unsupported placement is.
        - `brightness` integer, nullable: Brightness, -100 to 100. Omit for the editor's own.
        - `contrast` integer, nullable: Contrast, -100 to 100. Omit for the editor's own.
        - `saturation` integer, nullable: Saturation, -100 to 100. Omit for the editor's own.
        - `vibrance` integer, nullable: Vibrance, -100 to 100. Omit for the editor's own.
        - `opacity` integer, nullable: Opacity, 0 to 100. Omit for the editor's own.
        - `blur` number, nullable: Blur, 0 to 20, in half steps. Omit for the editor's own.
        - `blend_mode` 'multiply' | 'normal' | 'screen' | 'lighten' | 'soft_light' | 'overlay' | 'darken', nullable: How the artwork sits on the product surface. Photo targets only. Omit for the editor's own.

## Response `200`

Successful Response

- CreateSessionResponse
  - `success` true: True when the session was created.
  - `mockup_type` 'psd' | '2d', required: Which editor this session opens, psd or 2d.
  - `session` string, required: Opaque token the editor is opened with.
  - `expires_in` integer, required: Seconds the session stays valid while it sits idle.
  - `message_session_id` string, required: Identifier your page matches every editor message against.
  - `bootstrap_secret` string, required: One-time secret your page sends to complete the handshake.

---

[API](https://skmtc.dev/sudomock/apis/sudomock-api.md) · [All operations](https://skmtc.dev/sudomock/apis/sudomock-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sudomock/apis/sudomock-api/revisions/c1cc24006c60?raw)