Skip to content
Shootika Docs

Request a scene

POST
/scenes
curl --request POST \
  --url https://api.shootika.com/v1/scenes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "model_id": "example", "style": "example", "pose": "example" }'

Asks for the scene made of one model, one style and one pose. If your store already has that scene, it is returned with status 200 (and a failed one is requested again). Otherwise a new scene starts being prepared and is returned with status 201 and status: generating. It can take a minute or more. Poll GET /scenes/{scene_id} until the status is ready, then start a shoot with it.

Send an Idempotency-Key to make a retry safe. Only 2xx answers are stored and replayed, for 24 hours. A request still running under the same key answers 409 idempotency_in_progress, and a claim older than 5 minutes is treated as abandoned.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
>= 1 characters <= 255 characters

A unique string you choose, 1 to 255 characters, for this request. Repeating the request with the same key and the same body replays the first answer for 24 hours instead of doing the work again. Only 2xx answers are stored. Using the same key with a different request answers 409 idempotency_conflict.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
model_id
required

A model id from GET /models.

string
style
required

A style key from GET /styles.

string
pose
required

One of that model’s poses.

string
Examplegenerated
{
  "model_id": "example",
  "style": "example",
  "pose": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

Your store already had this scene. It is returned as it is.

Media typeapplication/json
object
scene
required
object
id
required
string format: uuid
model
required
object
id
required
string format: uuid
name
required
string
style
required

The style key from GET /styles. A scene made from one of your own uploaded scenes carries that style’s ref: key, the same value you pass to POST /scenes.

string
pose
required
string
status
required
string
Allowed values: ready generating failed
image
required
Any of:
object
webp
required
string format: uri
jpg
required
string format: uri
Example
{
  "scene": {
    "status": "ready"
  }
}

201

Section titled “201”

The scene was requested and is being prepared.

Media typeapplication/json
object
scene
required
object
id
required
string format: uuid
model
required
object
id
required
string format: uuid
name
required
string
style
required

The style key from GET /styles. A scene made from one of your own uploaded scenes carries that style’s ref: key, the same value you pass to POST /scenes.

string
pose
required
string
status
required
string
Allowed values: ready generating failed
image
required
Any of:
object
webp
required
string format: uri
jpg
required
string format: uri
Example
{
  "scene": {
    "status": "ready"
  }
}

400

Section titled “400”

bad_request: the request could not be read, for example a multipart body with no boundary.

Media typeapplication/json
object
error
required

What went wrong. Read code in your software; message is for people.

object
code
required
string
Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error
message
required

A plain sentence for a person.

string
details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object
key
additional properties
any
Example
{
  "error": {
    "code": "api_not_enabled"
  }
}

401

Section titled “401”

unauthorized: the Authorization header is missing, or the key is not valid or has been revoked.

Media typeapplication/json
object
error
required

What went wrong. Read code in your software; message is for people.

object
code
required
string
Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error
message
required

A plain sentence for a person.

string
details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object
key
additional properties
any
Example
{
  "error": {
    "code": "api_not_enabled"
  }
}

403

Section titled “403”

api_not_enabled when the API is not switched on for your store yet, store_uninstalled when the store has uninstalled Shootika, or forbidden when the key is not allowed to do that.

Media typeapplication/json
object
error
required

What went wrong. Read code in your software; message is for people.

object
code
required
string
Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error
message
required

A plain sentence for a person.

string
details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object
key
additional properties
any
Example
{
  "error": {
    "code": "api_not_enabled"
  }
}

404

Section titled “404”

not_found: that model does not exist or cannot be used by your store.

Media typeapplication/json
object
error
required

What went wrong. Read code in your software; message is for people.

object
code
required
string
Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error
message
required

A plain sentence for a person.

string
details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object
key
additional properties
any
Example
{
  "error": {
    "code": "api_not_enabled"
  }
}

405

Section titled “405”

method_not_allowed: this address does not accept that method. The Allow header lists the ones it does.

Media typeapplication/json
object
error
required

What went wrong. Read code in your software; message is for people.

object
code
required
string
Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error
message
required

A plain sentence for a person.

string
details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object
key
additional properties
any
Example
{
  "error": {
    "code": "api_not_enabled"
  }
}

Headers

Section titled “Headers”
Allow
string

409

Section titled “409”

idempotency_conflict when the key was used for a different request, or idempotency_in_progress when the same key is still running.

Media typeapplication/json
object
error
required

What went wrong. Read code in your software; message is for people.

object
code
required
string
Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error
message
required

A plain sentence for a person.

string
details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object
key
additional properties
any
Example
{
  "error": {
    "code": "api_not_enabled"
  }
}

422

Section titled “422”

validation_error when a field is missing, or when the style or the pose is not one this model can take. The details name the fields.

Media typeapplication/json
object
error
required

What went wrong. Read code in your software; message is for people.

object
code
required
string
Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error
message
required

A plain sentence for a person.

string
details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object
key
additional properties
any
Example
{
  "error": {
    "code": "api_not_enabled"
  }
}

429

Section titled “429”

rate_limited: more than 120 requests in a minute with this key. Wait the number of seconds in Retry-After.

Media typeapplication/json
object
error
required

What went wrong. Read code in your software; message is for people.

object
code
required
string
Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error
message
required

A plain sentence for a person.

string
details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object
key
additional properties
any
Example
{
  "error": {
    "code": "api_not_enabled"
  }
}

Headers

Section titled “Headers”
Retry-After
integer

500

Section titled “500”

internal_error: something went wrong on our side. Try again.

Media typeapplication/json
object
error
required

What went wrong. Read code in your software; message is for people.

object
code
required
string
Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error
message
required

A plain sentence for a person.

string
details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object
key
additional properties
any
Example
{
  "error": {
    "code": "api_not_enabled"
  }
}

503

Section titled “503”

service_busy: Shootika is busy right now. Try again in a moment.

Media typeapplication/json
object
error
required

What went wrong. Read code in your software; message is for people.

object
code
required
string
Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error
message
required

A plain sentence for a person.

string
details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object
key
additional properties
any
Example
{
  "error": {
    "code": "api_not_enabled"
  }
}

Headers

Section titled “Headers”
Retry-After
integer