--- title: "Refine Visuals" method: POST path: "/questionnaires/jobs/{job_id}/refine" tags: ["questionnaires"] --- # Refine Visuals `POST /questionnaires/jobs/{job_id}/refine` ## Request - Base URL: `https://api.threadchain.pro` (the document declares no server; this is the origin it was published from) - URL: `https://api.threadchain.pro/questionnaires/jobs/{job_id}/refine` - Auth: OAuth 2 - Password - Token URL: `auth/token` Submit a refinement request for a specific render. Supports three types of refinement inputs (all optional, but at least one required): 1. Comment/note: Text feedback describing desired changes 2. Annotated image: Original render with circles/marks showing WHERE to make changes 3. Reference image: Separate image showing WHAT the user wants (style, color, design reference) These can be used together or separately. This endpoint: - Validates the job is in 'awaiting_review' status - Validates refinement count hasn't exceeded limit (max per side, tracked separately for 3D vs 2D) - Uploads images to storage (if provided) - Triggers regeneration of the specified render **asset=3d (default) — Clothing:** refining **front** also regenerates **back** 3D when ``pair_mode=paired``; refining **back** can sync **front** when paired. Use ``pair_mode=single`` to update only the selected side. Stored 2D flat URLs are cleared whenever 3D is refined so Phase 2 can rebuild flats from the latest 3Ds. **asset=2d:** refines **outer** technical **2D** flats only. Separate per-side limit. **Clothing** paired refresh (front↔back) is controlled by ``pair_mode``. Inner 2D, POM overlays, and BOM callout images are cleared when 2D is refined; 3D URLs are not modified. Returns updated job status. Allowed callers: session owner (the designer) or an admin. ## Path parameters - `job_id` string, uuid, required ## Query parameters - `background_tasks` unknown ## Request body `multipart/form-data` - BodyRefineVisualsQuestionnairesJobsJobIdRefinePost - `side` string, required: 'front' or 'back' - `comment` string: Optional: Refinement instructions/notes - `annotated_image` string, binary, nullable: Optional: Original render with circles/marks showing WHERE to change - `reference_image` string, binary, nullable: Optional: Reference image showing WHAT to change to - `reference_images` string[], nullable: Optional: up to 4 reference images (Prompt Me); the first is the main one - `asset` string: Which asset to refine: '3d' (review-phase 3D renders) or '2d' (outer technical flats). - `refine_mode` string: Which refine prompt to use: 'oval' (circled regions), 'freehand' (drawn marks), 'reference' (reference image as target), 'text' (notes only). - `pair_mode` string: Whether to refresh the opposite side for consistency: 'single' (this side only) or 'paired' (multi-turn sync of front/back). Clothing only. - `from_techpack` boolean: Edit 3D from an active tech pack: update 3D renders only; preserve workspace assets. - `erase_artwork` boolean: Eraser sub-tool was used to build the mask: prune Artwork Table rows for this side on completion. ## Response `200` Successful Response - GetJobStatusResponse - `job_id` string, uuid, required - `session_id` string, uuid, required - `status` 'queued' | 'processing' | 'awaiting_size_studio' | 'awaiting_review' | 'awaiting_3d_start' | 'awaiting_3d_review' | 'awaiting_construction' | 'workspace_active' | 'completed' | 'failed', required - `progress` integer, required - `brand_id` string, uuid, nullable - `manufacturer_ids` string[] - `brand` TechPackBrandSummary: Compact brand reference returned alongside a tech pack. - `id` string, uuid, required - `name` string, required - `manufacturer_id` string, uuid, nullable - `contact_email` string, nullable: Brand org owner's email; surfaced for manufacturer-side dashboards. - `manufacturers` TechPackManufacturerSummary[] - `id` string, uuid, required - `company_name` string, nullable - `factory_name` string, nullable - `result_url` string, nullable - `preview_url` string, nullable - `front_3d_url` string, nullable - `back_3d_url` string, nullable - `left_3d_url` string, nullable - `right_3d_url` string, nullable - `front_2d_url` string, nullable - `back_2d_url` string, nullable - `left_2d_url` string, nullable - `right_2d_url` string, nullable - `inner_front_2d_url` string, nullable - `inner_back_2d_url` string, nullable - `pom_overlay_outer_front_url` string, nullable - `pom_overlay_outer_back_url` string, nullable - `pom_overlay_inner_front_url` string, nullable - `pom_overlay_inner_back_url` string, nullable - `bom_callout_giq_outer_front_url` string, nullable - `bom_callout_giq_outer_back_url` string, nullable - `bom_callout_giq_inner_front_url` string, nullable - `bom_callout_giq_inner_back_url` string, nullable - `bom_callout_nogiq_outer_front_url` string, nullable - `bom_callout_nogiq_outer_back_url` string, nullable - `bom_callout_nogiq_inner_front_url` string, nullable - `bom_callout_nogiq_inner_back_url` string, nullable - `refinement_count_front` integer - `refinement_count_back` integer - `refinement_count_left` integer - `refinement_count_right` integer - `refinement_count_2d_front` integer - `refinement_count_2d_back` integer - `refinement_count_2d_left` integer - `refinement_count_2d_right` integer - `share_code` string, nullable - `public_share_view_count` integer - `last_public_share_view_at` string, date-time, nullable - `error_message` string, nullable - `released_at` string, date-time, nullable - `created_at` string, date-time, required - `started_at` string, date-time, nullable - `completed_at` string, date-time, nullable - `manufacturer_completed_at` string, date-time, nullable - `download_url` string, nullable - `refinement_payload` object, nullable - `flat2d_regenerate_count` integer - `flat2d_regenerate_payload` object, nullable - `techpack_import_status` string, nullable - `techpack_import_step` string, nullable - `generation_step` string, nullable - `techpack_import_incomplete` boolean, nullable - `techpack_import_unresolved_required` integer, nullable - `techpack_import_draft_acknowledged` boolean, nullable - `entitlements` object, nullable ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/threadchain/apis/threadchain-backend.md) - [All operations](https://skmtc.dev/threadchain/apis/threadchain-backend/llms.txt) - [OpenAPI document](https://skmtc.dev/threadchain/apis/threadchain-backend/revisions/8ee288a7e6bd?raw)