> ## Documentation Index
> Fetch the complete documentation index at: https://docs.estudjo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create, Update, and Archive Custom Scenes in estudjo

> Build reusable scene prompt templates in estudjo. Learn how to create, update, list, and archive your own scenes for consistent AI generations.

Custom scenes let you define reusable prompt templates scoped to specific AI models and product categories. Once created, reference a scene by its `scene_id` in any generation request — this keeps your prompts consistent across products and makes bulk generation straightforward.

## Scene Management Flow

<Steps>
  <Step title="List available scenes">
    Retrieve all scenes available to your account, including both predefined scenes provided by estudjo and any scenes you have created.

    ```bash theme={null}
    curl https://v1.api.estudjo.com/scenes \
      -H 'X-Api-Key: YOUR_API_KEY'
    ```

    Each entry in the response includes `name`, `scene_id`, and `type` (`predefined` or `user_created`).
  </Step>

  <Step title="Inspect a scene">
    To view the full details of a scene you created — including its `description` and `prompt` — fetch it by ID. This endpoint is only available for `user_created` scenes.

    ```bash theme={null}
    curl https://v1.api.estudjo.com/scenes/7c1e2f4a-9b3d-4e5f-8a6b-1c2d3e4f5a6b \
      -H 'X-Api-Key: YOUR_API_KEY'
    ```

    ```json theme={null}
    {
      "success": true,
      "data": {
        "name": "Bright Minimalist Studio",
        "scene_id": "7c1e2f4a-9b3d-4e5f-8a6b-1c2d3e4f5a6b",
        "description": "Clean studio look for apparel",
        "prompt": "A bright minimalist studio with soft daylight"
      }
    }
    ```
  </Step>

  <Step title="Create a scene">
    Send a `POST` request with a name, target models and categories, and the prompt text.

    ```bash theme={null}
    curl -X POST https://v1.api.estudjo.com/scenes \
      -H 'X-Api-Key: YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
        "name": "Bright Minimalist Studio",
        "models": ["estudjo/eco"],
        "categories": ["womens-clothing"],
        "prompt": "A bright minimalist studio with soft daylight",
        "description": "Clean studio look for apparel"
      }'
    ```

    The response includes the server-generated `scene_id`:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "name": "Bright Minimalist Studio",
        "scene_id": "7c1e2f4a-9b3d-4e5f-8a6b-1c2d3e4f5a6b",
        "type": "user_created"
      }
    }
    ```

    <Note>
      The `scene_id` is generated server-side and is permanent — save it to use in generation requests.
    </Note>
  </Step>

  <Step title="Use the scene in a generation">
    Pass the `scene_id` as the `scene` field in your `POST /generate` request body:

    ```json theme={null}
    {
      "scene": "7c1e2f4a-9b3d-4e5f-8a6b-1c2d3e4f5a6b"
    }
    ```

    See [Generate Image](/docs/guides/generate-image) or [Generate Video](/docs/guides/generate-video) for full request examples.
  </Step>

  <Step title="Update a scene">
    You can update the `name`, `description`, and `prompt` of a scene at any time. The `models`, `categories`, and `scene_id` are immutable and cannot be changed after creation.

    ```bash theme={null}
    curl -X PUT https://v1.api.estudjo.com/scenes/7c1e2f4a-9b3d-4e5f-8a6b-1c2d3e4f5a6b \
      -H 'X-Api-Key: YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{ "name": "Bright Minimalist Studio v2", "prompt": "Updated prompt text." }'
    ```
  </Step>

  <Step title="Archive a scene">
    When you no longer need a scene, archive it with a `DELETE` request.

    ```bash theme={null}
    curl -X DELETE https://v1.api.estudjo.com/scenes/7c1e2f4a-9b3d-4e5f-8a6b-1c2d3e4f5a6b \
      -H 'X-Api-Key: YOUR_API_KEY'
    ```

    ```json theme={null}
    { "success": true, "data": { "status": "archived" } }
    ```

    <Warning>
      Archiving is **permanent** — there is no restore endpoint. Archived scenes cannot be used in new generation requests.
    </Warning>
  </Step>
</Steps>

## Validation Rules

Keep these constraints in mind when creating or updating scenes:

* **Name** must be at least **5 characters** long
* **Prompt** cannot be empty
* **`models` and `categories`** are set at creation time and cannot be updated afterward