Skip to content
Figur

Dispatch a background-generator workflow

POST
/v1/background-generator
curl --request POST \
  --url https://example.com/v1/background-generator \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "image_model": "example", "eval_enabled": true, "resolution": "example", "aspect_ratio": "example", "seed": 1, "on_technical_failure": "example", "display_name": "", "authoring": { "display_name": "example", "setting": "studio_set", "photographic_register": "real_photo", "topology": { "preset": "seamless_sweep", "custom_text": "example" }, "subject_zone": { "preset": "near_rear_plane", "custom_text": "example" }, "supported_crops": [ "full" ], "ground": { "preset": "seamless", "custom_text": "example" }, "light": { "preset": "soft_frontal", "custom_text": "example" }, "palette": [ "example" ], "scene_anchors": [ "example" ], "surface_character": "example" }, "background_public_id": "example", "scene_type": "example", "mood": "example", "dominant_colors": [ "example" ], "metadata": {}, "pilot_brand": "example" }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
X-Shopify-Hmac-Sha256
Any of:
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
BackgroundGeneratorRequest

POST /v1/background-generator — canonical v1 or legacy background generation.

object
image_model
Any of:
string
eval_enabled
Any of:
boolean
resolution
Any of:
string
aspect_ratio
Any of:
string
seed
Any of:
integer
on_technical_failure
Any of:
string
display_name
Display Name
string
""
authoring
Any of:
BackgroundAuthoringInput

The high-leverage public brief for a reusable physical Background.

object
display_name
required
Display Name
string
>= 1 characters <= 128 characters
setting
required
Setting
string
Allowed values: studio_set indoor_location outdoor_location
photographic_register
required
Photographic Register
string
Allowed values: real_photo film_photo studio_set render
topology
required
BackgroundTopologyChoice

One bounded background topology choice with a controlled escape hatch.

object
preset
required
Preset
string
Allowed values: seamless_sweep shallow_wall rear_plane_room courtyard_veranda street_path textile_installation open_location custom
custom_text
Any of:
string
>= 3 characters <= 240 characters
subject_zone
required
BackgroundSubjectZoneChoice
object
preset
required
Preset
string
Allowed values: near_rear_plane framed_between_sides shallow_patio receding_path central_open custom
custom_text
Any of:
string
>= 3 characters <= 240 characters
supported_crops
required
Supported Crops
Array<string>
>= 1 items <= 3 items
Allowed values: full three_quarter torso
ground
required
BackgroundGroundChoice
object
preset
required
Preset
string
Allowed values: seamless stone_paving plaster_tile wood earth_grass custom
custom_text
Any of:
string
>= 3 characters <= 240 characters
light
required
BackgroundLightChoice
object
preset
required
Preset
string
Allowed values: soft_frontal soft_side_daylight overcast warm_directional_sun quiet_low_key custom
custom_text
Any of:
string
>= 3 characters <= 240 characters
palette
required
Palette
Array<string>
>= 1 items <= 3 items
scene_anchors
required
Scene Anchors
Array<string>
>= 2 items <= 4 items
surface_character
Any of:
string
>= 3 characters <= 240 characters
background_public_id
Any of:
string
>= 26 characters <= 26 characters
scene_type
Any of:
string
mood
Any of:
string
dominant_colors
Dominant Colors
Array<string>
metadata
Metadata
object
key
additional properties
any
pilot_brand
Any of:
string

Responses

Section titled “Responses”

202

Section titled “202”

Successful Response

Media typeapplication/json
WorkflowAcceptedResponse

Returned synchronously from any POST /v1/{name} (202).

object
request_id
required
Request Id

26-char ULID — correlates with the row in credit_operations.

string
job_id
required
Any of:
string
status
JobStatus

Studio’s job status at submit time. Almost always NOT_STARTED in this 202.

string
default: NOT_STARTED
Allowed values: NOT_STARTED SUCCESS FAILURE IN_PROGRESS
credits_cost
required
Credits Cost

Credits deducted from the calling client. Refunded automatically on any failure path.

integer
Example
{
  "status": "NOT_STARTED"
}

422

Section titled “422”

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}