# Build an application with the Twinbly processing API

Give this brief to your coding assistant along with the product you want to build. Twinbly provides an HTTP API, a downloadable CLI and a local stdio MCP server. Use the [installation guide](https://www.twinbly.com/developers#cli-mcp) for the versioned Node.js 22+ executable, checksum and host configuration. This brief is documentation; no hosted MCP endpoint or general SDK package is included.

## Authoritative sources

- [CLI and MCP overview](https://www.twinbly.com/developers/cli-mcp): available downloads, connection choices and limits.
- [Developer guide](https://www.twinbly.com/developers/guide.md): authentication, example requests, recovery and limits. [Web version](https://www.twinbly.com/developers)
- [Live OpenAPI schema](https://rg-splats.web.app/v1/openapi.json): exact request and response contracts. Operations marked planned or first-party are not general third-party capabilities.
- [Legend Guide case study](https://www.twinbly.com/developers/legend-guide.md): a real application using processing and hosted output with its own interface.
- [Create a processing API key](https://www.twinbly.com/dashboard/developers/keys), [wallet](https://www.twinbly.com/dashboard/settings), [pricing](https://www.twinbly.com/pricing) and [service terms](https://www.twinbly.com/terms).
- [Input preparation](https://www.twinbly.com/learn/processing-workflows) and [requirements](https://www.twinbly.com/learn/preparation/requirements.md).

## Local development tools

The CLI and MCP server share a processing workflow: plan, create, upload, explicitly approve paid start, inspect status and retrieve available outputs. Use the self-service processing key in the host environment, choose an input folder for MCP and store workflow state in a private local unsynced folder. Do not invent npm package names or a hosted MCP URL.

Use the guide’s exact commands and request schema. MCP paid start requires form elicitation in the host; without it, use CLI review-start and explicit start approval. A local tool validates its supported subset of the API. For broader operations, use the documented HTTP contract. Neither tool automatically publishes a Twinbly scene.

## Implementation task

Build a branded application that accepts a supported capture, shows the processing estimate, obtains the customer's spending decision, uploads the capture, follows the job and presents the available 3D result. Adapt the interface to the product; do not assume it must look like Twinbly.

Read the guide and current schema before writing requests. Explain unsupported assumptions instead of inventing endpoints or distribution names. Use the application's existing language, framework and HTTP client. The processing base URL is `https://rg-splats.web.app/v1`.

### Architecture and account ownership

- Keep the processing credential in a trusted backend or authorized local runtime as `TWINBLY_API_KEY`, sent to the processing API in `X-API-Key`. Never place it in browser JavaScript, a native binary, a repository, a shared prompt or logs.
- Use a processing key from the `rgs_` family. A `tbly_` read-only scene token cannot start processing. If no key is configured, provide setup instructions and stop before authenticated requests; never ask the user to paste a key into chat.
- A self-service processing key acts for the Twinbly account that owns it and spends that account's wallet. Omit `userId`; do not use it to impersonate your application's customers. Your backend must authenticate each customer, map customer records to job IDs and authorize every access. Never proxy arbitrary job IDs supplied by a client without that ownership check.
- Your app owns its user accounts, customer billing, branded UI and publication controls. This brief does not introduce per-customer Twinbly credentials, a payment reseller service or a new license.
- For web or native display, choose a renderer compatible with the actual output you retrieve. An embedded Twinbly viewer is a different option with its own publication and plan requirements. Do not imply that the processing API includes Twinbly's complete browser editor or a native viewer SDK.

### Workflow

1. Validate the chosen input against the current schema. Use actual frame count and dimensions when quoting. Do not assume every web upload/preflight feature is exposed to third-party keys.
2. Inspect feasibility, adjustments and estimated cost. Show the estimate and obtain authorization before paid work. A quote is not a hard spending cap or a guaranteed duration. Unknown affordability is not permission to spend.
3. Validate creation with `dryRun: true` when appropriate. Assign and persist a unique `captureId` for the intended job. After a successful create, persist `jobId` before proceeding. A dry run is not a live processing test.
4. Upload bytes using the returned destination, method and required headers. Do not forward the processing key to storage. Use the returned resumable session for large files and confirm complete upload before starting. A remote agent cannot read a user's local path without an explicit local helper or upload handoff; a supported manifest is another option for eligible remote inputs.
5. Start the existing job only after the spending decision and upload are confirmed. Persist that decision. Stop on insufficient funds or billing unavailability; report the problem accurately.
6. Poll with bounded backoff and honor retry guidance. If using webhooks, verify signatures according to the schema and keep polling as recovery. Handle failed, cancelled, unknown and timed-out states explicitly.
7. Fetch result links through the authenticated downloads operation. Check readiness for the required format separately from training completion. Refresh expired links and preserve relative sibling-file resolution for streamed multi-file assets. Do not construct result URLs from job IDs or treat `gs://` identifiers as public downloads.
8. Present the result in your own UI, or use the appropriate separate publishing workflow for a Twinbly scene. A processed job is not automatically a public page. Make sharing an explicit product decision.

### Recovery and data handling

- Do not blindly retry creation or restart processing after a timeout. Recover the original `captureId`/`jobId` and reconcile state first. The current create contract is not universally idempotent; repeating creation after processing starts can create another job.
- Do not automatically rerun failed processing, request additional conversion, cancel work or publish results. Each needs the caller's intended action and any applicable spending decision.
- Redact credentials, signed URLs and upload capabilities from logs and support messages. Store only the private state required to recover your workflow.
- API-key revocation does not necessarily invalidate previously issued asset URLs. Decide how your product controls result access and retention.
- Runtime clipping is not guaranteed to remove hidden geometry from exported assets. Verify exports before making a redaction or privacy claim.

## Acceptance checks

Before calling the integration complete, demonstrate:

- A missing/invalid key and an unfunded account produce actionable setup errors.
- Declining the estimate never starts processing.
- An interrupted upload resumes or reports a recoverable error for the same job.
- Lost create/start responses do not trigger duplicate paid jobs.
- One customer cannot read or mutate another customer's job through your backend.
- Training completion with a missing/pending conversion does not show a broken success state.
- The chosen output renders with the intended web/native viewer; label this as tested only on platforms actually exercised.
- Expired result links refresh, terminal failures stop polling, and logs contain no credentials or signed URLs.

Use mocks or fixtures for failure paths. Perform a live paid test only with explicit authorization for the chosen input and cost. Report what was verified, what was simulated and what remains incomplete. Include setup instructions, operation coverage and remaining limitations with the implementation.
