Text to image

atlasTextToImage generates image inputs from a text prompt for Marble 2 world workflows.

Access-dependent preview: POST /api/v2/tasks:atlasTextToImage is available to enabled Marble 2 beta accounts, and its request may change while the model is being updated.

When to use it

Use atlasTextToImage when you want a convenient world-oriented starting image inside the Marble pipeline. Describe a coherent place, its layout, materials, lighting, time of day, and camera viewpoint.

1{2  "prompt": "A quiet stone courtyard at blue hour, arched walkways, warm window light, wide eye-level view",3  "aspectRatio": "16:9",4  "seed": 7,5  "numSamples": 16}

Optional controls include aspectRatio, enhancePrompt, seed, numSteps, and numSamples. Start with defaults, change one control at a time, and record the prompt, seed, and operation ID with any later tasks that use the image.

When numSamples is greater than 1, each image uses independent noise. If seed is provided, sample i uses seed + i. With enhancePrompt set to false, repeating the request reproduces the full set.

aspectRatio accepts 16:9, 9:16, 4:3, 3:4, or 1:1, and falls back to 1:1 when omitted.

Prompt enhancement is enabled by default. Set enhancePrompt to false when you need the submitted wording to reach the model unchanged.

Image quality guidance

Prompt for a world:

• Describe one navigable environment rather than a collage of unrelated subjects.
• State spatial relationships: what is foreground, background, left, right, enclosed, or open.
• Prefer a clear, wide viewpoint with visible surfaces and depth cues.
• Avoid prominent text, split screens, crowds, fast motion, and large close-up people when the image will feed a world model.
• Higher detail prompts lead to better generations.

Marble models are strongest on worlds and environments. Humans and dynamic objects are not yet their strongest subjects; see Best practices.

Enterprise customers with a repeated visual domain can work with World Labs to fine-tune and improve our text-to-image model for their specific use case. Contact your World Labs account representative with representative prompts, desired outputs, and evaluation criteria.

For downstream Atlas tasks such as Preview, Chisel, and Reconstruct, higher-quality input images generally produce better results. You can compare images from different providers to evaluate the resulting world quality.

Handle the operation

The task returns a long-running operation. A successful terminal response contains one frame per generated image, the prompt used for generation, and the output aspect ratio. Follow the Assets guide to download or reuse the images, and save the operation ID for troubleshooting.

Example completed output

After the operation reports done: true, its task-specific result is in operation.response:

1{2  "frames": [3    {4      "imageAsset": {5        "assetId": "asset_example",6        "url": "https://example.com/generated-0.png"7      }8    }9  ],10  "promptUsed": "A quiet stone courtyard at blue hour with coherent architectural depth",11  "aspectRatio": "16:9"12}

When returnDepth is true, every frame also carries the camera its depth was estimated under and a depth buffer.

Always confirm the live request and response in the API reference before shipping an integration.

Prompt enhancement for multiple images

With enhancePrompt: true (the default), each output image gets an independently expanded version of your original prompt. Multiple outputs can therefore differ in composition and scene details as well as image sampling. The response's promptsUsed array matches frames in order; promptUsed contains the first image's prompt for compatibility. Older results may have an empty promptsUsed.

To generate variations from one fixed caption, submit that caption as prompt and set enhancePrompt: false. The same caption then applies to every image. The seed controls image sampling; it does not guarantee identical prompt expansions from the language model.