Moderations - NanoGPT API Documentation

cURL

curl --request POST \
  --url https://nano-gpt.com/api/v1/moderations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": "Text to classify for safety.",
  "model": "moderation-model-id"
}
'

{
  "id": "modr_...",
  "model": "moderation-model-id",
  "results": [
    {
      "flagged": false,
      "categories": {
        "category_name": false
      },
      "category_scores": {
        "category_name": 0.01
      }
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 100,
    "total_tokens": 112
  }
}

POST

moderations

cURL

curl --request POST \
  --url https://nano-gpt.com/api/v1/moderations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": "Text to classify for safety.",
  "model": "moderation-model-id"
}
'

{
  "id": "modr_...",
  "model": "moderation-model-id",
  "results": [
    {
      "flagged": false,
      "categories": {
        "category_name": false
      },
      "category_scores": {
        "category_name": 0.01
      }
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 100,
    "total_tokens": 112
  }
}

Overview

Use POST /api/v1/moderations to classify text, image, or mixed content for safety before you store, display, or send user-generated content to another model endpoint. The endpoint is synchronous and returns an OpenAI-compatible moderation response shape where practical. It is a paid API feature and bills proportionally to usage with no separate minimum charge.

Endpoint

POST https://nano-gpt.com/api/v1/moderations

Authentication

An API key is required.

Authorization: Bearer YOUR_API_KEY
x-api-key: YOUR_API_KEY

Model Selection

The model field is optional. If omitted, NanoGPT uses the default moderation model. Available input types, batch support, context limits, and pricing depend on the selected model. Use Moderation Models before choosing a model instead of hardcoding capabilities.

Request Body

Field	Type	Required	Description
`model`	string	No	Moderation model ID. Omit to use the default moderation model.
`input`	string, array, or content parts	Yes	Content to classify.

Input Examples

Single Text Input

{
  "model": "moderation-model-id",
  "input": "Text to classify."
}

Batch Text Input

{
  "model": "moderation-model-id",
  "input": [
    "First item to classify.",
    "Second item to classify."
  ]
}

Batch support can vary by model. If a selected model does not support batched input, the API returns an error before billing.

Text Content Part

{
  "model": "moderation-model-id",
  "input": [
    {
      "type": "text",
      "text": "Text to classify."
    }
  ]
}

Image Input

{
  "model": "moderation-model-id",
  "input": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.png"
      }
    }
  ]
}

Image support depends on the selected model. Text-only models reject image input before billing.

Example

curl https://nano-gpt.com/api/v1/moderations \
  -H "Authorization: Bearer $NANOGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moderation-model-id",
    "input": "Text to classify for safety."
  }'

Response

{
  "id": "modr_...",
  "model": "moderation-model-id",
  "results": [
    {
      "flagged": false,
      "categories": {
        "category_name": false
      },
      "category_scores": {
        "category_name": 0.01
      }
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 100,
    "total_tokens": 112
  }
}

Field	Description
`flagged`	`true` when the selected model classifies the content as unsafe.
`categories`	Category-level boolean results. Exact category names are model-dependent.
`category_scores`	Category-level confidence scores when available. Exact category names are model-dependent.
`usage`	Token usage used for billing and diagnostics.

Billing

The endpoint is paid and bills proportionally to usage. There is no extra minimum charge. General billing behavior:

Input tokens are billed according to the selected moderation model’s input rate.
Output tokens may be billed when the selected model returns billable classification output.
NanoGPT performs a preflight balance check before dispatching the request.
The final charge is based on measured or estimated usage recorded for the completed request.
Pricing details are returned by GET /api/v1/moderation-models.

Rate Limits And Access Controls

The endpoint uses standard NanoGPT API authentication, balance checks, API-key limits, and account/team access controls.

API keys can be subject to model allowlists.
API keys can be subject to spending and token limits.
Team billing and team restrictions apply where configured.
Requests can be rate limited.

Errors

Errors follow the standard NanoGPT/OpenAI-compatible error shape:

{
  "error": {
    "message": "Invalid request parameters. Please check your input and try again.",
    "type": "invalid_request_error",
    "code": "unsupported_input_modality",
    "param": "input"
  }
}

Status	Code	Meaning
400	`empty_input`	The request did not include moderatable text or image content.
400	`unsupported_input_modality`	The selected model does not support the submitted input type.
400	`unsupported_batch_input`	The selected model does not support batched input.
400	`context_length_exceeded`	The input is too large for the selected model.
401	`missing_api_key` or `invalid_api_key`	Authentication failed.
402	varies	The account does not have enough balance.
403	`paid_features_disabled`	Paid API features are disabled for the account.
404	`model_not_found`	The requested moderation model does not exist or is unavailable.
429	`rate_limit_exceeded`	The caller exceeded a rate limit.
503	`provider_error` or similar	The upstream moderation service was temporarily unavailable or returned an invalid response.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Parameters for creating a moderation classification

input

required

Content to classify

Example:

"Text to classify for safety."

model

string

Moderation model ID. Omit to use the default moderation model.

Example:

"moderation-model-id"

Response

Moderation classification response

string

required

Moderation request identifier

Example:

"modr_..."

model

string

required

Moderation model used for classification

Example:

"moderation-model-id"

results

object[]

required

Moderation results for each classified input

Show child attributes

usage

object

Token usage used for billing and diagnostics

Show child attributes

Moderation Models AI Detection

Documentation Index

​Overview

​Endpoint

​Authentication

​Model Selection

​Request Body

​Input Examples

​Single Text Input

​Batch Text Input

​Text Content Part

​Image Input

​Example

​Response

​Billing

​Rate Limits And Access Controls

​Errors

Authorizations

Body

Response

Overview

Endpoint

Authentication

Model Selection

Request Body

Input Examples

Single Text Input

Batch Text Input

Text Content Part

Image Input

Example

Response

Billing

Rate Limits And Access Controls

Errors