Phone video to 3D with the Twinbly API
Turn a phone recording into a 3D Gaussian splat for your own website or application. Twinbly handles cloud processing; your product supplies the customer experience and a compatible 3D viewer. The official twinbly npm package includes a CLI and a local MCP server for coding assistants.
This example uses the CLI to make the API workflow concrete. Your backend can use the same HTTP operations without sending customers through Twinbly's upload interface. Legend Guide is an example of a product built around Twinbly's processing and output.
What you need
- Node.js 22+, the official tools and a normal MP4 or MOV recording of a static subject or space. This example is for flat phone video, not a reframed 360 recording.
- A processing API key in your authorized local environment as
TWINBLY_API_KEY. Never put it in a prompt, browser bundle or native application binary. - Wallet funds before a paid start. Installation, help and tool discovery need no key; planning needs a key but does not create a job, upload or start processing.
1. Capture overlap, not just a panorama
Move around the subject or through the space slowly, showing the same surfaces from several positions. Keep the scene still and exposure consistent. Turning the camera from one spot does not capture the depth views needed for reconstruction. Start with a small area; one short recording is not a guarantee of a complete building. Follow the capture guide.
2. Choose the frames to process
The CLI's video workflow requires explicit timestamps in seconds. It does not automatically choose the best moments from your footage. Use sharp, overlapping frames, and keep the declared count equal to the timestamp count. Timestamps must be inside your actual recording.
For an illustrative recording at least 60 seconds long, this command writes phone-video.json selecting one frame per second, from 0 through 59. Replace that selection for your capture; 60 frames is an example, not a quality target. For a MOV file use inputType: "mov" instead.
node -e 'const fs=require("node:fs"); const frameTimestamps=Array.from({length:60},(_,i)=>i); fs.writeFileSync("phone-video.json",JSON.stringify({inputType:"video",recipe:{engine:"lichtfeld",iterations:10000,targetMegapixels:2,frameTimestamps},analysis:{schemaVersion:2,capture:{actualFrameCount:frameTimestamps.length}}},null,2)+"\n")'
The iteration and resolution settings are illustrative. A longer capture or different settings may cost more; check the returned estimate and adjustments rather than treating this example as a fixed-price recipe.
3. Plan without spending
Install the pinned package and inspect the plan for your actual local file:
npm install --global twinbly@0.1.1
twinbly version
twinbly capabilities
twinbly plan --request phone-video.json --file walkthrough.mp4
Configure your key before plan using the private environment instructions. The plan validates the request through an unpaid API dry run and saves a private local workflow. Review feasibility, cost, confidence, ranges, warnings and adjustments. This step does not inspect visual quality or prove that the capture will reconstruct successfully.
For a dated illustration, on November 17, 2026 (Mountain time), the live API accepted this 60-frame request in both quote and unpaid dry-run checks: $0.80 USD estimated, with low confidence. The quote returned a $0.80–$1.63 range and 28 estimated processing minutes. No capture was uploaded or processed for this check; these are estimates, not a bill, deadline or promise that another video will cost the same.
Save the returned workflowId. A quote is not a hard spending cap or a completion deadline. If the estimate is too high, choose fewer useful frames or different settings, then request another plan and review the tradeoff before approving. Do not simply lower the declared count while uploading a different planned selection.
4. Upload, then explicitly approve
Run one command at a time using that workflow ID:
twinbly create --workflow YOUR_WORKFLOW_ID
twinbly upload --workflow YOUR_WORKFLOW_ID
twinbly review-start --workflow YOUR_WORKFLOW_ID
Creation reserves a job and upload destination. Uploading sends the capture; neither command starts paid training. Inspect the latest estimate from review-start. Only if you approve, use its one-use token within 15 minutes:
twinbly start --workflow YOUR_WORKFLOW_ID --approve YOUR_REVIEW_TOKEN
Keep the returned job ID. Do not automate approval or repeat a paid start after a timeout. Use reconcile --workflow YOUR_WORKFLOW_ID to inspect an uncertain create/start; follow the recovery instructions.
5. Retrieve output and use your own viewer
twinbly status --job YOUR_JOB_ID
twinbly downloads --job YOUR_JOB_ID
Training completion and conversion readiness are separate. Inspect which files and bundles are actually available. PLY and converted formats such as SOG, SPZ or streamed bundles depend on the job and conversion; a format name in documentation does not guarantee that file is ready for your capture.
When ready to use the result privately, request links explicitly:
twinbly downloads --job YOUR_JOB_ID --include-links
Choose a renderer that supports the returned format, and have your backend authorize each customer's access. For a streamed bundle, keep the manifest and all relative sibling files reachable together. A signed manifest alone is not enough. Signed links expire; obtain fresh ones through the authenticated downloads operation. Hosted asset links, when supplied, may remain accessible after API-key revocation, so handle them as access-bearing links.
This workflow does not automatically publish a public Twinbly scene or return a ready-to-embed public tour. You can present the assets in your own interface. If you want Twinbly's ready-made viewer, use the separate publishing and embedding workflow and its plan requirements.
Pricing, limits and storage
| Question | What to plan for |
|---|---|
| Is there a fixed price per scene? | No. Get an estimate for the actual selected frames and settings. The returned customer estimate already includes the service charge; do not double it. Actual processing cost is recorded at completion. |
| What is the minimum payment? | The wallet's minimum top-up is $5 USD. That is account funding, not a minimum charge for each job. A job can cost less; unused wallet balance remains for later work. |
| Is there a monthly API subscription requirement? | The documented self-service processing path uses your account's wallet. Publishing capacity and embed branding have separate app-plan rules; see pricing. |
| How many frames? | The CLI accepts 1–5,000 selected frames at the schema level. The service can impose lower limits for the requested settings; inspect feasibility, limits and adjustments. Acceptance of a count is not a promise of reconstruction quality. |
| Video duration, resolution and file size? | Quote the selected frames, not every encoded video frame. This guide does not promise a universal maximum duration, source resolution or upload size. Use the current API schema and unpaid plan for the request; neither proves that arbitrary video bytes will decode or upload. The CLI uses a resumable upload when available; its single-PUT fallback is limited to 32 MiB. |
| How long are results kept? | Link expiration and artifact retention are different. A hosted link without a timed expiry is not a permanent-storage guarantee. Keep your original capture and download a backup of results you need; check service terms and agree retention needs before depending on the service as an archive. |
| Does a completed job include a public embed? | No automatic scene publication. Your app can render the output, or you can publish through the separate Twinbly workflow. |
Use a coding assistant
Give your assistant this guide and the integration brief. A local MCP host can perform the same steps using structured tools; paid starts need a supported confirmation form. Ordinary browser-only chat is not automatically connected to this local server. Consumer capture links, automatic account setup and capped-payment checkout are not part of this example.
The example request is checked against the tool schema. It is not a newly processed demonstration capture or a promise of visual quality. Validate your chosen viewer and capture with your own explicitly approved test before offering it to customers.