API reference

atlasTextToImage

Submit the atlasTextToImage task

POST/api/v2/tasks:atlasTextToImage

Authentication WLT-Api-Key

Generate world-oriented image inputs from a prompt, then persist the operation ID and the resolved prompt and seed. Read the guide.

Query parameters

waitboolean

Block for the operation to finish before returning, up to the server wait cap. Returns the Operation either way — done with a response if it finished in time, otherwise still running.

Defaultfalse

Headers

Idempotency-Keystring | null

Optional idempotency key.

Lengthlength <= 128

Request body

application/jsonRequired

Body of POST /api/v2/tasks:atlasTextToImage.

webhookUrlstring | null

Where Marble POSTs one signed task.succeeded or task.failed event when this operation finishes; retried for 24 hours. Verify the signature with the public keys at /.well-known/webhooks/jwks.json. Cannot be combined with ?wait=true. https on port 443 only, no IP literals. Developer API only.

Lengthlength <= 2048

purgeContentOnOperationCompletionboolean | null

Purge this operation's outputs and the transient uploads it consumed one hour after it finishes. Omitted, the account's setting applies; true raises it for this operation; false is refused when the account already purges. Uploads in the library are never purged by an operation.

promptstringrequired

Text prompt to generate from.

Length1 <= length

aspectRatiostring | null

Output width-to-height ratio. Omit for the model default.

Value in"16:9", "9:16", "4:3", "3:4", "1:1"

enhancePromptboolean

Whether to enhance the prompt before generation. Defaults to true.

Defaulttrue

seedinteger | null

Optional RNG seed.

numStepsinteger | null

Diffusion step count.

Range1 <= value <= 100

numSamplesinteger | null

Number of images to generate.

Range1 <= value <= 4

returnDepthboolean

Also estimate depth per image (metric, single-view): every frame in frames then carries a depth buffer and the camera it was estimated under.

Defaultfalse

Responses

`201`

Successful Response

application/json

Long-running operation whose successful terminal response has type AtlasTextToImageResponse. This is the common Operation envelope with a task-specific response type, not a separate operation resource.

idstringrequired

Short operation id used in /operations/{operation} paths.

ownerIdstringrequired

Account that owns the operation.

metadataobject | null

Task information and optional progress details. Use metadata.task to interpret a generic operation response, and use done to determine completion.

donebooleanrequired

Whether the operation is terminal. When true, a non-null error indicates failure; otherwise the operation succeeded.

errorOperationError | null

Failure details when done is true and the task failed; null while running and after success.

expiresAtSecsinteger | null

Task execution deadline as Unix seconds, when one is exposed. This is not an asset URL expiration.

createdAtSecsinteger | null

Unix seconds when the operation was accepted.

responseAtlasTextToImageResponse | null

AtlasTextToImageResponse result when done is true and the task succeeded; null while running and after failure.

namestringrequired

Full resource name for the operation.

For project operations: accounts/{account}/projects/{project}/operations/{operation}. Operation paths accept the short id.

`422`

Validation Error

application/json

detailarray<ValidationError>

Request example

cURL

curl --request POST \  --url 'https://api.atlas-beta.worldlabs.ai/api/v2/tasks:atlasTextToImage?wait=true' \  --header "WLT-Api-Key: $WLT_API_KEY" \  --header 'Idempotency-Key: request-001' \  --header 'Content-Type: application/json' \  --data '{  "prompt": "A cinematic world with clear depth and no people",  "enhancePrompt": true,  "returnDepth": false}'

Response example201 · JSON

1{2  "id": "op_01jexample000000000000000000",3  "ownerId": "acct_01jexample00000000000000000",4  "metadata": null,5  "done": false,6  "error": null,7  "expiresAtSecs": 1789415864,8  "createdAtSecs": 1789412264,9  "response": null,10  "name": "accounts/acct_01jexample00000000000000000/projects/project_example/operations/op_01jexample000000000000000000"11}

Completed operation

1{2  "id": "op_01jexample000000000000000000",3  "ownerId": "acct_01jexample00000000000000000",4  "metadata": null,5  "done": true,6  "error": null,7  "expiresAtSecs": 1789415864,8  "createdAtSecs": 1789412264,9  "response": {10    "frames": [11      {12        "imageAsset": {13          "assetId": "asset_01jexample000000000000000",14          "url": "https://example.com/imageAsset.png"15        },16        "maskAsset": {17          "assetId": "asset_01jexample000000000000000",18          "url": "https://example.com/maskAsset.png"19        },20        "camera": {21          "extrinsics": {22            "position": [23              1,24              1,25              126            ],27            "quaternion": [28              1,29              1,30              1,31              132            ],33            "coordinateSystem": "rub"34          },35          "intrinsics": {36            "fx": 1,37            "fy": 1,38            "cx": 1,39            "cy": 1,40            "width": 1280,41            "height": 72042          }43        },44        "depth": {45          "confidenceAsset": {46            "assetId": "asset_01jexample000000000000000",47            "url": "https://example.com/confidenceAsset.png"48          },49          "logDepthAsset": {50            "assetId": "asset_01jexample000000000000000",51            "url": "https://example.com/logDepthAsset.exr"52          },53          "zMin": 1,54          "zMax": 155        }56      }57    ],58    "promptUsed": "A cinematic world with clear depth, coherent geometry, and no people",59    "promptsUsed": [60      "string"61    ],62    "aspectRatio": "16:9"63  },64  "name": "accounts/acct_01jexample00000000000000000/projects/project_example/operations/op_01jexample000000000000000000"65}