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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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.