Best practices

Marble 2 models do especially well on worlds: spaces, environments, architecture, landscapes, and the relationships between surfaces. They are not yet as strong on humans or dynamic objects. Design inputs and product promises around that boundary, and evaluate your own target distribution before launch.

Choose world-first inputs

• Use sharp images with a clear environment and enough visible surfaces to establish depth.
• Prefer wide or medium views over extreme close-ups.
• Keep exposure, white balance, and scene state consistent across views.
• Capture overlapping viewpoints with translation, not only rotation, when geometry or metric scale matters.
• Remove frames with blur, heavy occlusion, or unrelated locations.

Crowds, close-up people, articulated motion, vehicles in motion, water in motion, and objects that change pose between views can reduce consistency. People can still appear in an input, but they should not be the main quality target for the current beta.

Build small, observable pipelines

Treat each task as one durable job:

1. Validate media and request shape locally.
2. Upload reusable or private inputs as project assets.
3. Submit once with an idempotency key.
4. Persist the operation ID.
5. Wait or poll until terminal.
6. Store output asset IDs and the input operation trace.

Do not hide several uncontrolled retries inside one product action. Expose a job state to your application so users can leave and return while work runs.

Preserve coordinate conventions

Camera-bearing schemas state their coordinate convention. Marble outputs use OpenGL/Three.js right-up-back (rub) unless the live schema says otherwise. Convert once at your system boundary and test with a known camera rather than sprinkling axis flips through rendering code.

Protect media and secrets

• Keep API keys server-side and scope one key to one deployed service.
• Use project assets for private media.

Pin integrations to the live beta contract

The selected account's API reference is generated from the same Marble 2 schemas as the service and filtered to reachable tasks. Use it when generating clients. Older World API v1 and Marble 4 examples are not compatible contracts.

During beta, keep schema generation and a small end-to-end request in CI. Treat new optional fields as additive, and fail clearly if a task disappears from an account rather than silently falling back to another model.