Images and scenes

Create a scene

POST /v1/scenes needs a prompt. sourceAssetId is optional.

{
  "prompt": "Create a simple navigable clay scene",
  "externalRef": "your-optional-record-id"
}

The prompt is 1–4000 UTF-8 characters. externalRef is optional, 1–200 characters when present, and unique among your active scenes. Use an internal record ID, not an email address or other personal data.

Generate and persist a canonical lowercase UUID v4 for Idempotency-Key before submitting. Persist the returned operation ID before replying to your caller.

Start from an image

Send a multipart file to POST /v1/image-assets. Smore validates the actual bytes rather than trusting the filename or declared content type.

Source images must be:

• PNG, JPEG, or WebP
• At most 20 MiB
• At most 6144 pixels per side and 24 megapixels
• At least 1280×720 for scene creation
• Within 1% of 16:9 for scene creation

The response contains an image asset ID and validated metadata. Unattached uploads expire after 24 hours. Smore keeps an asset after a scene uses it. Add the asset to the create body:

{
  "sourceAssetId": "image-asset-id",
  "prompt": "Preserve the composition and create a navigable clay blockout",
  "externalRef": "your-optional-record-id"
}

You can also attach a source image later from the studio chat.

Poll the operation

GET /v1/operations/{operationId} returns one of:

• processing with Retry-After
• succeeded with a scene ID and version
• failed with a safe structured error

The result never includes Smore’s scene artifact or provider output.

Recover by external reference

If local response state is lost after the idempotency window, an exact lookup can recover a created scene:

GET /v1/scenes?externalRef=your-optional-record-id

This endpoint is an exact lookup, not a list or search operation.

Delete

DELETE /v1/scenes/{sceneId} immediately disables server access and revokes active embed sessions. It returns 204 for every syntactically valid ID, including unknown and cross-organization IDs.