Interactive composition and editing

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:

{
  "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
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
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.