back
loading skill details...
Turn a photo or a text prompt into a real 3D model: a textured mesh you can drop into a game engine, AR scene, or product viewer. Use when the user says "mak...
--- name: image-to-3d-asset description: > Turn a photo or a text prompt into a real 3D model: a textured mesh you can drop into a game engine, AR scene, or product viewer. Use when the user says "make this into a 3D model", "turn this photo into 3D", "I need a GLB", "a game-ready asset", "3D-print this", "text to 3D", or wants a mesh with real topology and PBR materials, not a render or a turntable video. --- # Image-to-3D asset Produce a real 3D model from a single photo, a few photos, or a text description: a mesh with usable topology and PBR materials, returned as a **GLB file** that loads straight into a game engine, an AR scene, or a web viewer. The lever is a clean input (image-to-3D for fidelity, text-to-3D for invention) plus the topology and budget settings that match where the asset will be used. ## Inputs to collect - **The reference image(s)** if the user has them. One clean shot is enough, and up to four or five views of the *same* object improve fidelity. (Ask only if none provided and no prompt either.) - **Or a text description** of the object when no reference exists: what it is, its shape, and what it's made of. - **Where the asset is used:** game/real-time, AR, hero render, product viewer, or 3D print. This drives topology, polygon budget, and texture resolution. - **Will it be rigged or animated?** Decides quad vs raw topology and whether to force a T/A pose. ## Models - **Default: Rodin Gen-2** (`hyper3d:rodin@gen-2`). Production-ready meshes, the richest control surface (mesh mode, polygon budget, HighPack 4K, T/A pose, PBR vs baked). Best general pick. - **Cheaper/faster alt: Meshy-6** (`meshy:meshy@6`). Clean geometry, low-poly and symmetry control, image-enhancement toggle. Good for volume and game assets. - **Other strong picks: Hunyuan 3D 3.1 Pro** (`tencent:hunyuan-3d@3.1-pro`) and **Tripo 3D v3.1** (`tripo:v3.1@0`). Both do image-to-3D and text-to-3D, with Tripo the lowest-cost tier. - Confirm the live model + its schema via `runware-models` + `runware-run` before calling. Control fields differ per model, so never copy one model's `settings` onto another without checking. ## Workflow 1. Resolve the model schema (`runware-run`) and confirm the input field, the `settings` it allows, and that the model is `live`. 2. Provide the input. Image-to-3D goes under `inputs.images` (URL, base64, data URI, or a UUID from a prior task or the Image Upload API). Text-to-3D goes under `positivePrompt`. A request runs in **one mode at a time**. 3. Run **`taskType: "3dInference"` asynchronously.** 3D generation takes time, so the call returns a `taskUUID`. Poll `getResponse` until it reports terminal. Do not block a single sync call on it. 4. Read the result at **`outputs.files[].url`**, which is the GLB. Download it or hand the URL to a viewer. 5. Review the mesh (see Quality bar). If topology or budget is wrong for the target, adjust `settings` and rerun, don't post-process blindly. ## Technique - **Image-to-3D for fidelity, text-to-3D for invention.** When a reference exists, use it: it anchors the silhouette and surface to something concrete and the result is predictable. Reach for text-to-3D only for shapes you can describe but can't photograph. - **Isolate the subject.** A clean reconstruction needs **one object, evenly lit, on a plain background**. Busy backgrounds or a second item in frame split the model's attention and the mesh comes back soft. Crop tight before sending. - **Lead multi-view sets with your best angle.** Up to five images (Rodin) or four (Meshy) of the same object help, and the **first image seeds the materials**, so put the most representative, best-lit view first. Keep every view to the same subject, a turnaround, not a mix of objects. - **2D art works too.** Image-to-3D reconstructs from a flat illustration or concept art, giving the character a back it never showed. Simple, clearly-outlined art reconstructs more cleanly than busy or heavily-shaded drawings. - **Prompt for form, not photography.** In text-to-3D, name the object, its overall shape, its style, and what it's made of. Skip the camera and lighting language that belongs in an image prompt, because you light and frame the mesh yourself. The more the asset matters, the more the prompt should say, a bare `"a chair"` is invented from scratch. - **Topology follows the downstream job.** Quad-dominant topology deforms cleanly when rigged and subdivides for smoothing, so it's the default for anything that moves. Raw/triangulated is denser and more irregular, suited to static hero props or meshes you'll retopologize yourself. - **Match the budget to where the asset is seen.** Faceted low-poly is right for background props and mobile, while smooth high-poly earns its weight on hero and close-up assets. See `runware-prompting` for writing the text-to-3D prompt itself. Fill in this brief before building the request, then map each line to `settings`. `quality` and `polyCount` are mutually exclusive, so pick one. ``` Object: <what it is> Source: <image (inputs.images) | text (positivePrompt)> Mesh mode: <Quad (rig/animate) | Raw (static/retopo)> Budget: <quality preset (high/medium/low/extra-low) | polyCount (one or the other, never both)> Materials: <PBR (relights in engine) | baked (Shaded) | both (All)> ``` Load `references/examples.md` for three worked recipes (photo-to-product, text-to-shape, low-poly game asset) with full requests and the GLB result shape. ## Parameters that matter - `inputs.images` is the image-to-3D input. Rodin accepts up to **5**, Meshy up to **4**. First image seeds materials. - `positivePrompt` is the text-to-3D input. Meshy caps it at **600 characters**. Mutually exclusive with `inputs.images`. - **Rodin `settings.meshMode`**: `Quad` (default, rig/animate, subdivides cleanly) vs `Raw` (static/retopo, denser triangulated detail). Raw mode clears add-ons. - **Rodin `settings.quality` XOR `settings.polyCount`** are *mutually exclusive*, and sending both is a validation error. Presets `high`/`medium`/`low`/`extra-low` map to fixed face counts that depend on mesh mode. Use `polyCount` for a hard engine budget (Quad 1,000 to 200,000, Raw 500 to 1,000,000). - **Rodin `settings.addons: ["HighPack"]`** gives ~16× face count and 4K textures (vs default 2K), Quad only, roughly triples cost. Reserve for hero assets and close-ups. - **Rodin `settings.taPose: true`** forces a neutral T/A pose for humanoids you'll rig. No effect on props or creatures. - **Rodin `settings.material`**: `PBR` (default, relights correctly in engines) vs `Shaded` (lighting baked into the texture, for viewers that won't relight) vs `All` (both). `settings.hdTexture` raises texture quality independently. - **Rodin `settings.useOriginalAlpha: true`** uses a cutout's alpha as the silhouette instead of edge detection. Image input only. - **Rodin `settings.boundingBox: [Y, Z, X]`** caps max dimensions so a set of props shares scale. - **Meshy `settings.imageEnhancement: false`** skips the photo cleanup pass for already-polished renders or stylized assets, so the model works from your image untouched. No effect in text-to-3D. - `seed` fixes a result to reproduce or deliberately vary it (Rodin: 0 to 65535). Confirm exact field names and ranges against the live schema (`runware-run`), never guess. ## Quality bar - The result is a valid **GLB** at `outputs.files[].url`, with the mesh and PBR materials packed together, that loads in your target engine/viewer. - The silhouette and surface match the reference (image-to-3D) or the described form (text-to-3D), with no melted or lumpy approximation. - Topology fits the downstream job: Quad if it will be rigged or animated, Raw only for static or retopo-bound assets. - Polygon budget suits where the asset is seen: low-poly for background/mobile, high-poly or HighPack only where close inspection earns it. - `quality` and `polyCount` were not sent together. For rigged characters, a T/A pose was used. ## Related skills `runware-run`, `runware-models`, `runware-prompting`; `product-photography` (clean single-object reference shots that reconstruct well, or the same product across stills).
don't have the plugin yet? install it then click "run inline in claude" again.
added explicit decision points for model choice, mesh mode, budget control, materials, HighPack, T/A pose, multi-view ordering, and error handling; split vague inputs into structured parameters with edge cases; expanded procedure into 8 distinct, measurable steps with async polling; added validation checks and output contract with GLB file guarantees; clarified mutually exclusive fields (quality vs polyCount, images vs prompt) and edge cases (rate limits, auth expiry, empty outputs, task timeout).
produce a real 3D model from a single photo, a few photos, or a text description: a mesh with usable topology and PBR materials, returned as a GLB file that loads straight into a game engine, an AR scene, or a web viewer. use this skill when the user says "make this into a 3D model", "turn this photo into 3D", "I need a GLB", "a game-ready asset", "3D-print this", "text to 3D", or wants a mesh with real topology and PBR materials, not a render or a turntable video.
RUNWARE_API_KEY. scope: 3D model generation, task polling.runware-run and runware-models for the chosen model (Rodin Gen-2, Meshy-6, Hunyuan 3D 3.1 Pro, or Tripo 3D v3.1). control fields differ per model; never reuse settings across models without validation.Resolve the model. call runware-run with taskType: "models" to fetch the live 3D model list and confirm your chosen model (default: Rodin Gen-2, slug hyper3d:rodin@gen-2) is live. extract its full schema, input fields, allowed settings keys, ranges, and data types.
Gather and validate inputs. collect the reference image(s) (up to 5 for Rodin, up to 4 for Meshy) or the text prompt (mutually exclusive). if image-to-3D, ensure the subject is isolated, evenly lit, on a plain background, and (if multiple views) all the same object. if text-to-3D, confirm the description names the object, shape, style, and material; remove camera/lighting language. confirm target use case (game, AR, hero, viewer, print) and rig/animation intent.
Build the brief. fill in the one-pager:
Map the brief to settings. create the request object. for image-to-3D, populate inputs.images with the image array (URLs or base64). for text-to-3D, populate positivePrompt. build settings from the model schema, mapping the brief to control fields (e.g., meshMode: "Quad", quality: "high"). never send both quality and polyCount in the same request; they are mutually exclusive and will fail validation.
Submit the async task. call runware-run with taskType: "3dInference", the full request payload, and isAsync: true. the API returns a taskUUID. do not block or wait for synchronous completion; 3D generation takes 30 seconds to several minutes.
Poll for completion. call runware-run with taskType: "getResponse" and the taskUUID. poll every 5 to 10 seconds until the response reports a terminal state (completed, failed, or error). if the task exceeds 15 minutes, abort and ask the user to retry (edge case: backend timeout or model overload).
Extract the GLB. when the task is completed, read outputs.files[]. locate the object with fileType: "glb" or filename ending in .glb. extract the url field. this is the downloadable 3D mesh with materials packed in.
Validate the output. download and inspect the GLB in a viewer (three.js, babylon.js, or a game engine) to confirm the silhouette, surface detail, and topology match the brief. check polygon count, material quality (PBR vs baked), and whether the mesh is quad-dominant or raw, as specified. if the result is unsatisfactory, do not post-process; instead, adjust settings (topology, budget, materials, or for image input, try imageEnhancement: false) and rerun from step 4.
Image-to-3D vs text-to-3D. if the user has a reference photo or can provide one, use image-to-3D: it anchors the silhouette and surface to something concrete and the result is predictable. reach for text-to-3D only for shapes the user can describe but cannot photograph (e.g., a fantastical creature, a product concept that doesn't exist yet).
Mesh mode: Quad vs Raw. if the asset will be rigged for animation or skeletal deformation, use meshMode: "Quad" (default). quad-dominant topology deforms cleanly and subdivides for smoothing. if the asset is static (a hero prop, a product, something you'll retopologize yourself), use meshMode: "Raw": denser and more irregular, suited to static geometry. note: Raw mode on Rodin disables add-ons like HighPack.
Budget control: quality preset vs polyCount. if you know the target engine's polygon budget (e.g., a mobile game allows 50k faces per asset), use polyCount: 50000. if you only know the use case (hero asset, background prop), use a quality preset (high/medium/low/extra-low). never send both in the same request. confirm exact ranges against the live model schema: Rodin Quad ranges 1,000 to 200,000, Raw ranges 500 to 1,000,000. Meshy is preset-only.
Materials: PBR vs Shaded vs All. if the target engine relights geometry in real-time (game engines, AR viewers, 3D product viewers), use material: "PBR" (default): the model will be physically correct and respond to new lighting. if the target is a static viewer or baked lightmap viewer (lightweight web embed, some AR viewers), use material: "Shaded": lighting is baked into the texture. if uncertain or the asset will be used in multiple contexts, use material: "All" to get both.
HighPack add-on for hero assets. if the asset is close-up (a product hero, a game character's face), use addons: ["HighPack"] to enable ~16× face count and 4K textures (vs default 2K). this roughly triples cost and is Quad-only. skip it for background props, low-poly game assets, or 3D prints where detail doesn't justify the cost.
T/A pose for humanoids. if the asset is a humanoid character and will be rigged for skeletal animation, use taPose: true to force a neutral T or A pose, easing the rigging process. ignore this setting for props, creatures, or non-humanoid characters.
Multi-view image order. when supplying multiple reference images (up to 5 for Rodin, up to 4 for Meshy), the first image seeds the materials and sets the tone. lead with your best angle (most representative, best-lit, most detail visible). follow with turnaround views or additional angles of the same object. do not mix different objects or switch subjects mid-sequence.
Model choice. default to Rodin Gen-2 (hyper3d:rodin@gen-2) for production assets: it has the richest control surface (mesh mode, polygon budget, HighPack, T/A pose, PBR vs baked). use Meshy-6 (meshy:meshy@6) for faster turnaround or volume workflows (it's cheaper and has low-poly/symmetry toggles). consider Hunyuan 3D 3.1 Pro or Tripo 3D v3.1 if Rodin is unavailable or if the user has a strong preference; always confirm the live schema before submitting.
API rate limits and auth expiry. if the API returns a 429 (rate limit) or 401 (auth expired), back off and retry after the rate-limit window, or refresh the API key. if a task hangs beyond 15 minutes, the backend is likely overloaded or has timed out; advise the user to retry later.
Empty or failed output. if the task completes but outputs.files[] is empty or the GLB is corrupt (fails to load in a viewer), the generation failed silently. ask the user to check the input (is the image clear? is the prompt unambiguous?) and resubmit. if the same input fails twice, try adjusting the model, toggling imageEnhancement, or simplifying the prompt.
outputs.files[].url. GLB is a self-contained, game-engine-ready format that bundles geometry, topology, normals, UVs, and PBR textures (or baked shaded textures) into a single file.material: "PBR"), or baked shading (if material: "Shaded"), or both (if material: "All"). texture resolution is 2K by default, 4K with HighPack add-on.quality preset or the specified polyCount. if quality: "high" was used on a Quad mesh, expect ~100k faces; low expects ~10k. detail is smooth and appropriate to the target use case (high-poly for hero/close-up, low-poly for background/mobile).boundingBox was specified, all dimensions stay within that limit, useful for cohesive asset sets.