---
title: "Interactive composition and editing"
description: "Plan an asset, refine its Physics brief and select references without automatically starting a prototype."
---

Interactive compositions separate planning, review, prototype generation and SimReady conversion. All endpoints below require customer authentication; detail operations enforce ownership. They return composition state under `data`. Planning, editing and reference-image generation currently do not reserve prototype credits.

## Start and answer

`POST /api/compositions/start` accepts JSON `{ "input": "your asset idea" }` or multipart with `input` and optional repeated `images` files. Input must be nonempty and at most 2000 characters. Interactive start accepts zero to four JPEG/PNG/WebP files, each at most 10 MB; unlike automatic `/generate`, two or three images are allowed.

The `201` response contains `data.id`, `questions`, `enough_info`, source images and messages. It is an interactive composition, not a finished prototype. `workflow` can be null.

`POST /api/compositions/:id/answer` accepts an `answers` array. Use the question IDs and option values returned by the service:

```json
{
  "answers": [
    { "question_id": "returned-question-id", "values": ["returned-option"], "custom": "additional context" }
  ]
}
```

The response may ask another round of questions (`stage=questions`, `enough_info=false`) or return a drafted prompt (`stage=draft`). The Physics brief remains a separate step.

## Refine and plan

| Endpoint | Body | Requirement / behavior |
| --- | --- | --- |
| `POST /api/compositions/:id/message` | `{ "message": "requested refinement" }` | Existing draft required; message is nonempty, at most 2000 characters. Revises the draft and may clear linked conversion/Tripo references |
| `POST /api/compositions/:id/brief` | `{}` | Existing draft required. Plans the Physics brief, sets composition ready and can return `prompt_revised=true` |
| `PATCH /api/compositions/:id` | Editable fields below | Direct normalized edit; no planning call or prototype start |

The message endpoint refuses a conversation with 40 stored messages using `429`. This is a conversation-length limit, not a transient request-rate limit. Retrying after a delay does not shorten the conversation.

## Direct editable fields

| Field | Contract |
| --- | --- |
| `draft_prompt` | Trimmed string, at most 1024 characters; this differs from the 2000-character seed input |
| `negative_prompt` | Trimmed string, at most 255 characters |
| `generation_method` | `auto`, `procedural` (Build), `generative` (Tripo Generate) |
| `tripo_params` | `model_version`, `pbr` boolean, `geometry_quality=standard|detailed`, `smart_low_poly` boolean |
| `asset_brief` | Replacement object with the supported schema below; merge with the current brief to preserve unedited fields |

Supported Tripo model versions at this release are `v3.1-20260211`, `v3.0-20250812`, `v2.5-20250123`. Face limit is platform-fixed at 50000, or 20000 with smart low-poly; texture quality is platform-fixed to detailed. Custom `face_limit`/`texture_quality` values do not become user controls.

Method changes and prototype input changes conflict with active attempts (`409`). Changing a recorded method clears existing generation, geometry/artifact and linked-job state. Changed draft/negative prompt/Tripo parameters clear linked conversion and Tripo model references. Do not assume every edit clears Build source: inspect the returned composition. A later new prototype attempt can charge separately.

### Physics brief schema

The brief is normalized as a replacement, not a deep partial patch. Its prompt fields are derived from the effective top-level `draft_prompt` and `negative_prompt`. Unrecognized fields are not retained.

| Field | Supported content |
| --- | --- |
| `asset_class` | Current `rigid` or `articulated`; legacy `deformable` normalizes to rigid, `mixed` to articulated, recording `simplified_from` |
| `generation_plan` | `recommended_method=procedural|generative`, `confidence=high|medium|low`, `reason` ≤500 characters, `requirements`, `limitations` (up to 5 strings, ≤300 each). Recommendations are normalized against capabilities; returned `capability_version` is generated |
| `confidence`, `reasoning`, `simplified_from` | Confidence clamped to 0–1; reasoning ≤500 characters; legacy simplification source `deformable`/`mixed` |
| `articulation_hint` | Up to 12 `{name,joint_type,range_deg,travel_frac}` entries. Joint types revolute/prismatic/continuous; revolute range 1–360 degrees, prismatic travel fraction 0.05–1.5; names ≤60 characters |
| `declared` | Finite `mass_kg`, `volume_m3`; `dimensions_m` with `length`, `width`, `height`; source strings `mass_source`, `volume_source`, `dimensions_source` (≤100); `dimensions_axes_declared` (up to 3); `partial_dimensions_m` (up to 12 `{name,value}` with finite values); `materials` (up to 12 strings, ≤80); `fixed_base` boolean |
| `proportion_contract` | Optional normalized image-proportion object described below |
| `context_conflicts` | Up to 12 strings, each ≤300 characters |

Generation-plan requirements are `moving_parts`, `functional_cavities`, `positioned_cutouts`, `thin_walls`, `fit_critical`, `separate_components`, `controlled_dimensions`, `organic_shape`, `crafted_shape`, `surface_detail`. Working articulation requires Build. A rigid classification alone does not select Generate. Legacy deformable/mixed fields do not enable deformable simulation; normalized `deformable_kind` is null and `independent_parts` false for current classes.

`proportion_contract` contains version 1, `reference_index` (0–7), `projection` (`front`, `side`, `top`, `three_quarter`, `unknown`), `object_bounds` and confidence (0–1). Bounds are normalized `[x,y,width,height]` within the image, not dimensions in metres. `features` contains 1–10 `{name,shape,bounds,confidence,observation}` entries; shape is rect/ellipse/line/point/freeform and observation ≤180 characters. `ratios` contains up to 12 `{name,numerator,denominator,value,confidence}` entries, value 0–10. `limitations` contains up to 5 strings, each ≤180 characters. Invalid/no-feature contracts normalize to null.

## Reference images

`POST /api/compositions/:id/prerender` requires a draft and accepts optional `instruction` (≤2000 characters) and `mode`. `mode=fresh` generates a fresh reference; default `edit` edits an existing base when one and an instruction exist, otherwise generates a reference from the draft/source context. The `201` response adds `data.prerender` with numeric media `id`, URL and image prompt. This is a reference image, not a prototype.

`POST /api/compositions/:id/prerender/select` accepts ordered `{ "media_ids": [123,456] }` or a single `media_id`. IDs must belong to the composition's source images or prerenders (`422` otherwise). Duplicates are removed, order retained, first image becomes primary, and an empty array clears selection. Selection clears linked conversion/Tripo references; it does not generate geometry. Media IDs and composition IDs are different identifiers.

For prototype creation, revision and conversion, see [Compose an asset](/compositions/generate).