Scan Prompt

Run a Waffo content safety check on a user’s text prompt before your product generates an image or video. The response carries a verdict in the action field — continue to generation only when it is allow. The check is stateless and does not retain the prompt text after returning.

POST /v1/actions/verification/scan-prompt

Authentication: API Key

Request Body

Field	Type	Required	Description
`prompt`	string	Yes	The user’s generation prompt (1-10000 characters)
`locale`	string	No	Language hint for the check — one of `ja`, `en`, `zh`
`semantic`	string	No	Semantic-scoring mode — one of `off`, `shadow`, `enforce`

semantic controls the optional semantic-scoring layer: off disables it, shadow scores without affecting the verdict, and enforce lets the score influence the verdict. When omitted, the service applies its default mode.

Example Request

import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

const { data } = await client.contentSafety.scanPrompt({
  prompt: "A serene mountain landscape at sunset",
  locale: "en",
  semantic: "enforce",
});

if (data.action === "allow") {
  // safe to generate
}

// Uses callApi() helper from authentication.mdx
const result = await callApi("POST", "/v1/actions/verification/scan-prompt", {
  prompt: "A serene mountain landscape at sunset",
  locale: "en",
  semantic: "enforce",
});
console.log(result.data.action);     // => "allow"
console.log(result.data.reasonCode); // => "allowed"

// Uses callApi() helper from authentication.mdx
String body = """
    {"prompt":"A serene mountain landscape at sunset","locale":"en","semantic":"enforce"}""";

String response = callApi("POST", "/v1/actions/verification/scan-prompt", body);
System.out.println(response);
// => {"data":{"action":"allow","reasonCode":"allowed","matchedCategories":[],...}}

# Uses call_api() helper from authentication.mdx
result = call_api("POST", "/v1/actions/verification/scan-prompt", {
    "prompt": "A serene mountain landscape at sunset",
    "locale": "en",
    "semantic": "enforce",
})
data = result["data"]
print(data["action"])     # => "allow"
print(data["reasonCode"]) # => "allowed"

// Uses callAPI() helper from authentication.mdx
body := map[string]interface{}{
    "prompt":   "A serene mountain landscape at sunset",
    "locale":   "en",
    "semantic": "enforce",
}
result, err := callAPI("POST", "/v1/actions/verification/scan-prompt", body)
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(result))
// => {"data":{"action":"allow","reasonCode":"allowed","matchedCategories":[],...}}

// Uses call_api() helper from authentication.mdx
let body = serde_json::json!({
    "prompt": "A serene mountain landscape at sunset",
    "locale": "en",
    "semantic": "enforce"
});
let result = call_api("POST", "/v1/actions/verification/scan-prompt", &body).await?;
println!("{}", result);
// => {"data":{"action":"allow","reasonCode":"allowed","matchedCategories":[],...}}

/* Uses call_api() helper from authentication.mdx */
const char *body = "{\"prompt\":\"A serene mountain landscape at sunset\",\"locale\":\"en\",\"semantic\":\"enforce\"}";
char *response = call_api("POST", "/v1/actions/verification/scan-prompt", body);
printf("%s\n", response);
free(response);

// Uses callApi() helper from authentication.mdx
std::string body = R"({"prompt":"A serene mountain landscape at sunset","locale":"en","semantic":"enforce"})";
std::string response = callApi("POST", "/v1/actions/verification/scan-prompt", body);
std::cout << response << std::endl;
// => {"data":{"action":"allow","reasonCode":"allowed","matchedCategories":[],...}}

MERCHANT_ID="MER_2aUyqjCzEIiEcYMKj7TZtw"
TIMESTAMP=$(date +%s)
BODY='{"prompt":"A serene mountain landscape at sunset","locale":"en","semantic":"enforce"}'
BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 -binary | base64 -w 0)
CANONICAL_REQUEST="POST
/v1/actions/verification/scan-prompt
$TIMESTAMP
$BODY_HASH"

SIGNATURE=$(echo -n "$CANONICAL_REQUEST" | openssl dgst -sha256 -sign private_key.pem | base64 -w 0)

curl -X POST "https://api.waffo.ai/v1/actions/verification/scan-prompt" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: $MERCHANT_ID" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -d "$BODY"

MERCHANT_ID="MER_2aUyqjCzEIiEcYMKj7TZtw"
TIMESTAMP=$(date +%s)
BODY='{"prompt":"A serene mountain landscape at sunset","locale":"en","semantic":"enforce"}'
BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 -binary | base64 -w 0)
CANONICAL_REQUEST="POST
/v1/actions/verification/scan-prompt
$TIMESTAMP
$BODY_HASH"

SIGNATURE=$(echo -n "$CANONICAL_REQUEST" | openssl dgst -sha256 -sign private_key.pem | base64 -w 0)

wget -qO- "https://api.waffo.ai/v1/actions/verification/scan-prompt" \
  --header="Content-Type: application/json" \
  --header="X-Merchant-Id: $MERCHANT_ID" \
  --header="X-Timestamp: $TIMESTAMP" \
  --header="X-Signature: $SIGNATURE" \
  --post-data="$BODY"

Success Response (200)

{
  "data": {
    "action": "allow",
    "reasonCode": "allowed",
    "matchedCategories": [],
    "requestId": "REQ_2aUyqjCzEIiEcYMKj7TZtw",
    "semanticStatus": "scored"
  }
}

Response Fields

Field	Type	Description
`action`	string	Verdict: `allow`, `review`, or `block`. Continue to generation only on `allow`.
`reasonCode`	string	Machine-readable reason: `allowed`, `review_required`, `restricted_content`, or `service_degraded`
`matchedCategories`	string[]	Restricted categories the prompt matched; empty when the verdict is `allow`
`requestId`	string	Identifier for this check; include it when referencing the request in an appeal
`semanticStatus`	string	State of the semantic-scoring layer: `disabled`, `scored`, `shadow_scored`, `provider_error`, etc.

Verdict handling

`action`	Recommended handling
`allow`	Call your generation model as normal.
`review`	Hold the request and retry later; a decision usually resolves within about 1 hour.
`block`	Do not generate. Show a friendly message such as “This content doesn’t meet our usage guidelines.”

When the moderation service is temporarily unavailable, the check returns action: "review" with reasonCode: "service_degraded" so that nothing is generated without a verdict. Retry the request rather than generating on a degraded response.

Errors

Retry policy: Never retry 4xx — fix the request and resubmit. Retry 5xx with exponential backoff (start 5s, max 3 attempts).

Status	`errors[0].message`	What it means	Recommended handling
400	`Missing required field: prompt`	`prompt` is absent from the body	Fix the input and resubmit.
400	`Prompt cannot be empty or contain only whitespace`	`prompt` is empty after trimming	Fix the input and resubmit.
400	`Prompt cannot exceed 10000 characters`	`prompt` is longer than 10000 characters	Shorten the prompt and resubmit.
400	`Invalid locale. Must be one of: ja, en, zh`	`locale` is not a supported value	Use a supported `locale` and resubmit.
400	`Invalid semantic mode. Must be one of: off, shadow, enforce`	`semantic` is not a supported value	Use a supported `semantic` value and resubmit.

Screen prompts before generation and continue only on allow. For full coverage, add an output-stage check as described in AIGC compliance.

Overview

Auth

Merchant API (API Key)

Customer Portal API (Session Token)

GraphQL

Request Body

Example Request

Success Response (200)

Response Fields

Verdict handling

Errors

​Request Body

​Example Request

​Success Response (200)

​Response Fields

​Verdict handling

​Errors

Request Body

Example Request

Success Response (200)

Response Fields

Verdict handling

Errors