Validation

Validation is an optional suitability check for image inputs. It asks whether an image is likely to produce a good 3D world: level camera, enough scene context, clean image quality, no heavy overlays, and similar pipeline-specific concerns.

It is not a safety system. Unsafe content is handled by Moderation, which runs independently.

Options

POST /v1/worlds accepts a validation object:

{
  "validation": {
    "skip": false,
    "error_on_fail": false
  }
}

Field	Default	Meaning
skip	true	Skip the suitability VLM check. This is the v1 default to save latency and cost.
error_on_fail	false	When skip: false, return 422 VALIDATION_FAILED for blocking issues instead of continuing with warnings. Ignored when skip: true.

Advisory mode

Set skip: false and leave error_on_fail: false when you want validation feedback without blocking generation:

curl -sX POST "https://api.spaitial.ai/v1/worlds" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "type": "url",
      "image_url": "https://example.com/room.jpg"
    },
    "validation": {
      "skip": false,
      "error_on_fail": false
    }
  }'

The job proceeds when validation finds warnings. Completed job responses and webhook payloads may include:

{
  "validation": {
    "passed": true,
    "issues": [
      {
        "code": "low_quality",
        "severity": "warning",
        "message": "Image quality looks borderline — sharper, higher-resolution photos usually produce better worlds."
      }
    ]
  }
}

The validation field is omitted when there are no validation warnings.

Strict mode

Set error_on_fail: true when you want blocking validation issues to reject the request before the job starts:

curl -sX POST "https://api.spaitial.ai/v1/worlds" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "type": "file_id",
      "file_id": "file_abc123"
    },
    "validation": {
      "skip": false,
      "error_on_fail": true
    }
  }'

Blocking failures return 422:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "This image is not suitable for 3D world generation.",
    "details": {
      "validation": {
        "passed": false,
        "issues": [
          {
            "code": "watermark_or_label",
            "severity": "error",
            "message": "There appears to be a watermark, logo, or caption overlay in the image. A clean image you own (without any overlays) usually works best."
          }
        ]
      },
      "fix_options": [
        {
          "id": "remove_text_overlays",
          "issue_code": "watermark_or_label",
          "label": "Remove watermarks and overlays",
          "description": "Logos, captions, or UI chrome will be inpainted out."
        }
      ]
    }
  }
}

Issue shape

Validation issues use the same shape in job results, webhook payloads, and strict-mode error details:

{
  "code": "extreme_viewpoint",
  "severity": "warning",
  "message": "The camera angle looks a bit unusual. Eye-level shots with a visible horizon usually produce the best results."
}

severity is warning for advisory issues and error for blockers.

Common issue codes

Code	What it means
extreme_viewpoint	The camera is straight up/down, heavily tilted, aerial, fisheye, or already equirectangular.
watermark_or_label	Text overlays, watermarks, logos, captions, UI chrome, or labels may get baked into the world.
tight_space	The image has too little surrounding scene context for robust extrapolation.
low_quality	The image is blurry, low-resolution, heavily compressed, noisy, or poorly exposed.
non_scene	The input looks like a portrait, product shot, document, chart, UI screenshot, or other non-environment image.
people_present	People are visible; the pipeline prefers empty static scenes.
other	The validator found another suitability issue.

When validation is skipped

Validation is skipped when validation.skip is true or omitted. Some internally generated sources, such as text-to-image outputs and already-fixed inputs, also skip the suitability check because they have already gone through a controlled flow.

Panorama inputs also skip validation. Set is_pano: true on a url, base64, or file_id input only when you are providing an equirectangular 360 panorama:

{
  "input": {
    "type": "file_id",
    "file_id": "file_pano123",
    "is_pano": true
  },
  "validation": {
    "skip": false,
    "error_on_fail": true
  }
}

The API trusts the pano flag and ignores the validation object for that request.

Moderation still runs. A request can skip validation and still fail with MODERATION_REJECTED.