Moderation

Moderation is the safety gate that runs before user-controlled content reaches the generation pipeline. It is separate from Validation: moderation blocks unsafe content; validation checks whether an otherwise safe image is likely to produce a good 3D world.

What is checked

Input flow	What moderation checks
POST /v1/files	Uploaded image bytes before the file is stored.
POST /v1/worlds with input.type: "file_id"	Reuses the moderation stamp from the uploaded file when it is still fresh.
POST /v1/worlds with input.type: "url"	The fetched image before generation starts.
POST /v1/worlds with input.type: "base64"	The decoded inline image before generation starts.
POST /v1/worlds with input.type: "text"	The text prompt before prompt-to-image generation.
POST /v1/panoramas/edit	The edit prompt, the source panorama, and up to 3 optional reference images before the edit runs.

Image and text moderation uses the NSFW classifier. If moderation fails, no world job is started and the input is not sent downstream for generation.

Validation flags do not bypass moderation

validation.skip only controls the quality/suitability VLM check. Content moderation still runs for API inputs. Panorama inputs with is_pano: true also skip suitability validation, but still follow the same moderation path as their url, base64, or file_id input type. Edited panoramas (panorama_id) are pre-moderated by POST /v1/panoramas/edit before they can be used to create a world.

Rejection shape

Moderation failures return 403 with MODERATION_REJECTED:

{
  "error": {
    "code": "MODERATION_REJECTED",
    "message": "Image failed moderation"
  }
}

Branch on error.code, not the message. The message is intentionally human-readable and may change.

Example: uploaded file rejected

curl -sX POST "https://api.spaitial.ai/v1/files" \
  -H "Authorization: Bearer $API_KEY" \
  -F "[email protected]"

{
  "error": {
    "code": "MODERATION_REJECTED",
    "message": "Image failed moderation"
  }
}

Example: text prompt rejected

curl -sX POST "https://api.spaitial.ai/v1/worlds" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "type": "text",
      "prompt": "..."
    }
  }'

{
  "error": {
    "code": "MODERATION_REJECTED",
    "message": "Prompt failed moderation"
  }
}

Operational behavior

• Moderation runs before generation work and before credits are consumed for rejected content.
• Uploaded files are moderated before the file_id is returned.
• file_id world requests use the upload's moderation stamp instead of asking you to resubmit bytes.
• Panorama edits are moderated before credits are committed. If moderation rejects an edit prompt or reference image, no panorama artifact is created.
• Moderation metadata is kept server-side for auditing and freshness checks; the public API only exposes the stable rejection envelope.
• Moderation provider failures are treated as server errors. Retry 5xx responses with backoff and an Idempotency-Key on mutating endpoints like POST /v1/worlds and POST /v1/panoramas/edit.

Related errors

HTTP	error.code	Meaning
403	MODERATION_REJECTED	Input content was blocked by moderation.
403	FORBIDDEN	Your key is valid but lacks the endpoint's required scope.
500	INTERNAL_ERROR	Moderation or another internal service failed unexpectedly.

If content is safe but structurally poor for 3D generation, use Validation instead of expecting a moderation error.