python/resources/moderations/methods/create/index.md

Create moderation

moderations.create(ModerationCreateParams**kwargs) -> ModerationCreateResponse

post /moderations

Create moderation

Parameters

input: Union[str, Sequence[str], Iterable[ModerationMultiModalInputParam]]

Input (or inputs) to classify. Can be a single string, an array of strings, or an array of multi-modal input objects similar to other models.
- str
  
  A string of text to classify for moderation.
- Sequence[str]
  
  An array of strings to classify for moderation.
- Iterable[ModerationMultiModalInputParam]
  
  An array of multi-modal inputs to the moderation model.
model: Optional[Union[str, ModerationModel]]

The content moderation model you would like to use. Learn more in the moderation guide, and learn about available models here.
- str
- Literal["omni-moderation-latest", "omni-moderation-2024-09-26", "text-moderation-latest", "text-moderation-stable"]
  - "omni-moderation-latest"
  - "omni-moderation-2024-09-26"
  - "text-moderation-latest"
  - "text-moderation-stable"

Returns

class ModerationCreateResponse: …

Represents if a given text input is potentially harmful.
- id: str
  
  The unique identifier for the moderation request.
- model: str
  
  The model used to generate the moderation results.
- results: List[Moderation]
  
  A list of moderation objects.
  - categories: Categories
    
    A list of the categories, and whether they are flagged or not.
    - harassment: bool
      
      Content that expresses, incites, or promotes harassing language towards any target.
    - harassment_threatening: bool
      
      Harassment content that also includes violence or serious harm towards any target.
    - hate: bool
      
      Content that expresses, incites, or promotes hate based on race, gender, ethnicity, religion, nationality, sexual orientation, disability status, or caste. Hateful content aimed at non-protected groups (e.g., chess players) is harassment.
    - hate_threatening: bool
      
      Hateful content that also includes violence or serious harm towards the targeted group based on race, gender, ethnicity, religion, nationality, sexual orientation, disability status, or caste.
    - illicit: Optional[bool]
      
      Content that includes instructions or advice that facilitate the planning or execution of wrongdoing, or that gives advice or instruction on how to commit illicit acts. For example, "how to shoplift" would fit this category.
    - illicit_violent: Optional[bool]
      
      Content that includes instructions or advice that facilitate the planning or execution of wrongdoing that also includes violence, or that gives advice or instruction on the procurement of any weapon.
    - self_harm: bool
      
      Content that promotes, encourages, or depicts acts of self-harm, such as suicide, cutting, and eating disorders.
    - self_harm_instructions: bool
      
      Content that encourages performing acts of self-harm, such as suicide, cutting, and eating disorders, or that gives instructions or advice on how to commit such acts.
    - self_harm_intent: bool
      
      Content where the speaker expresses that they are engaging or intend to engage in acts of self-harm, such as suicide, cutting, and eating disorders.
    - sexual: bool
      
      Content meant to arouse sexual excitement, such as the description of sexual activity, or that promotes sexual services (excluding sex education and wellness).
    - sexual_minors: bool
      
      Sexual content that includes an individual who is under 18 years old.
    - violence: bool
      
      Content that depicts death, violence, or physical injury.
    - violence_graphic: bool
      
      Content that depicts death, violence, or physical injury in graphic detail.
  - category_applied_input_types: CategoryAppliedInputTypes
    
    A list of the categories along with the input type(s) that the score applies to.
    - harassment: List[Literal["text"]]
      
      The applied input type(s) for the category 'harassment'.
      - "text"
    - harassment_threatening: List[Literal["text"]]
      
      The applied input type(s) for the category 'harassment/threatening'.
      - "text"
    - hate: List[Literal["text"]]
      
      The applied input type(s) for the category 'hate'.
      - "text"
    - hate_threatening: List[Literal["text"]]
      
      The applied input type(s) for the category 'hate/threatening'.
      - "text"
    - illicit: List[Literal["text"]]
      
      The applied input type(s) for the category 'illicit'.
      - "text"
    - illicit_violent: List[Literal["text"]]
      
      The applied input type(s) for the category 'illicit/violent'.
      - "text"
    - self_harm: List[Literal["text", "image"]]
      
      The applied input type(s) for the category 'self-harm'.
      - "text"
      - "image"
    - self_harm_instructions: List[Literal["text", "image"]]
      
      The applied input type(s) for the category 'self-harm/instructions'.
      - "text"
      - "image"
    - self_harm_intent: List[Literal["text", "image"]]
      
      The applied input type(s) for the category 'self-harm/intent'.
      - "text"
      - "image"
    - sexual: List[Literal["text", "image"]]
      
      The applied input type(s) for the category 'sexual'.
      - "text"
      - "image"
    - sexual_minors: List[Literal["text"]]
      
      The applied input type(s) for the category 'sexual/minors'.
      - "text"
    - violence: List[Literal["text", "image"]]
      
      The applied input type(s) for the category 'violence'.
      - "text"
      - "image"
    - violence_graphic: List[Literal["text", "image"]]
      
      The applied input type(s) for the category 'violence/graphic'.
      - "text"
      - "image"
  - category_scores: CategoryScores
    
    A list of the categories along with their scores as predicted by model.
    - harassment: float
      
      The score for the category 'harassment'.
    - harassment_threatening: float
      
      The score for the category 'harassment/threatening'.
    - hate: float
      
      The score for the category 'hate'.
    - hate_threatening: float
      
      The score for the category 'hate/threatening'.
    - illicit: float
      
      The score for the category 'illicit'.
    - illicit_violent: float
      
      The score for the category 'illicit/violent'.
    - self_harm: float
      
      The score for the category 'self-harm'.
    - self_harm_instructions: float
      
      The score for the category 'self-harm/instructions'.
    - self_harm_intent: float
      
      The score for the category 'self-harm/intent'.
    - sexual: float
      
      The score for the category 'sexual'.
    - sexual_minors: float
      
      The score for the category 'sexual/minors'.
    - violence: float
      
      The score for the category 'violence'.
    - violence_graphic: float
      
      The score for the category 'violence/graphic'.
  - flagged: bool
    
    Whether any of the below categories are flagged.

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
moderation = client.moderations.create(
    input="I want to kill them.",
)
print(moderation.id)

Response

{
  "id": "id",
  "model": "model",
  "results": [
    {
      "categories": {
        "harassment": true,
        "harassment/threatening": true,
        "hate": true,
        "hate/threatening": true,
        "illicit": true,
        "illicit/violent": true,
        "self-harm": true,
        "self-harm/instructions": true,
        "self-harm/intent": true,
        "sexual": true,
        "sexual/minors": true,
        "violence": true,
        "violence/graphic": true
      },
      "category_applied_input_types": {
        "harassment": [
          "text"
        ],
        "harassment/threatening": [
          "text"
        ],
        "hate": [
          "text"
        ],
        "hate/threatening": [
          "text"
        ],
        "illicit": [
          "text"
        ],
        "illicit/violent": [
          "text"
        ],
        "self-harm": [
          "text"
        ],
        "self-harm/instructions": [
          "text"
        ],
        "self-harm/intent": [
          "text"
        ],
        "sexual": [
          "text"
        ],
        "sexual/minors": [
          "text"
        ],
        "violence": [
          "text"
        ],
        "violence/graphic": [
          "text"
        ]
      },
      "category_scores": {
        "harassment": 0,
        "harassment/threatening": 0,
        "hate": 0,
        "hate/threatening": 0,
        "illicit": 0,
        "illicit/violent": 0,
        "self-harm": 0,
        "self-harm/instructions": 0,
        "self-harm/intent": 0,
        "sexual": 0,
        "sexual/minors": 0,
        "violence": 0,
        "violence/graphic": 0
      },
      "flagged": true
    }
  ]
}

Single string

from openai import OpenAI
client = OpenAI()

moderation = client.moderations.create(input="I want to kill them.")
print(moderation)

Response

{
  "id": "modr-AB8CjOTu2jiq12hp1AQPfeqFWaORR",
  "model": "text-moderation-007",
  "results": [
    {
      "flagged": true,
      "categories": {
        "sexual": false,
        "hate": false,
        "harassment": true,
        "self-harm": false,
        "sexual/minors": false,
        "hate/threatening": false,
        "violence/graphic": false,
        "self-harm/intent": false,
        "self-harm/instructions": false,
        "harassment/threatening": true,
        "violence": true
      },
      "category_scores": {
        "sexual": 0.000011726012417057063,
        "hate": 0.22706663608551025,
        "harassment": 0.5215635299682617,
        "self-harm": 2.227119921371923e-6,
        "sexual/minors": 7.107352217872176e-8,
        "hate/threatening": 0.023547329008579254,
        "violence/graphic": 0.00003391829886822961,
        "self-harm/intent": 1.646940972932498e-6,
        "self-harm/instructions": 1.1198755256458526e-9,
        "harassment/threatening": 0.5694745779037476,
        "violence": 0.9971134662628174
      }
    }
  ]
}

Image and text

from openai import OpenAI
client = OpenAI()

response = client.moderations.create(
    model="omni-moderation-latest",
    input=[
        {"type": "text", "text": "...text to classify goes here..."},
        {
            "type": "image_url",
            "image_url": {
                "url": "https://example.com/image.png",
                # can also use base64 encoded image URLs
                # "url": "data:image/jpeg;base64,abcdefg..."
            }
        },
    ],
)

print(response)

Response

{
  "id": "modr-0d9740456c391e43c445bf0f010940c7",
  "model": "omni-moderation-latest",
  "results": [
    {
      "flagged": true,
      "categories": {
        "harassment": true,
        "harassment/threatening": true,
        "sexual": false,
        "hate": false,
        "hate/threatening": false,
        "illicit": false,
        "illicit/violent": false,
        "self-harm/intent": false,
        "self-harm/instructions": false,
        "self-harm": false,
        "sexual/minors": false,
        "violence": true,
        "violence/graphic": true
      },
      "category_scores": {
        "harassment": 0.8189693396524255,
        "harassment/threatening": 0.804985420696006,
        "sexual": 1.573112165348997e-6,
        "hate": 0.007562942636942845,
        "hate/threatening": 0.004208854591835476,
        "illicit": 0.030535955153511665,
        "illicit/violent": 0.008925306722380033,
        "self-harm/intent": 0.00023023930975076432,
        "self-harm/instructions": 0.0002293869201073356,
        "self-harm": 0.012598046106750154,
        "sexual/minors": 2.212566909570261e-8,
        "violence": 0.9999992735124786,
        "violence/graphic": 0.843064871157054
      },
      "category_applied_input_types": {
        "harassment": [
          "text"
        ],
        "harassment/threatening": [
          "text"
        ],
        "sexual": [
          "text",
          "image"
        ],
        "hate": [
          "text"
        ],
        "hate/threatening": [
          "text"
        ],
        "illicit": [
          "text"
        ],
        "illicit/violent": [
          "text"
        ],
        "self-harm/intent": [
          "text",
          "image"
        ],
        "self-harm/instructions": [
          "text",
          "image"
        ],
        "self-harm": [
          "text",
          "image"
        ],
        "sexual/minors": [
          "text"
        ],
        "violence": [
          "text",
          "image"
        ],
        "violence/graphic": [
          "text",
          "image"
        ]
      }
    }
  ]
}

python/resources/moderations/methods/create/index.md +537 −0 created

1## Create moderation

3`moderations.create(ModerationCreateParams**kwargs) -> ModerationCreateResponse`

5**post** `/moderations`

7Create moderation

9### Parameters

11- `input: Union[str, Sequence[str], Iterable[ModerationMultiModalInputParam]]`

13 Input (or inputs) to classify. Can be a single string, an array of strings, or

14 an array of multi-modal input objects similar to other models.

16 - `str`

18 A string of text to classify for moderation.

20 - `Sequence[str]`

22 An array of strings to classify for moderation.

24 - `Iterable[ModerationMultiModalInputParam]`

26 An array of multi-modal inputs to the moderation model.

28- `model: Optional[Union[str, ModerationModel]]`

30 The content moderation model you would like to use. Learn more in

31 [the moderation guide](https://platform.openai.com/docs/guides/moderation), and learn about

32 available models [here](https://platform.openai.com/docs/models#moderation).

34 - `str`

36 - `Literal["omni-moderation-latest", "omni-moderation-2024-09-26", "text-moderation-latest", "text-moderation-stable"]`

38 - `"omni-moderation-latest"`

40 - `"omni-moderation-2024-09-26"`

42 - `"text-moderation-latest"`

44 - `"text-moderation-stable"`

46### Returns

48- `class ModerationCreateResponse: …`

50 Represents if a given text input is potentially harmful.

52 - `id: str`

54 The unique identifier for the moderation request.

56 - `model: str`

58 The model used to generate the moderation results.

60 - `results: List[Moderation]`

62 A list of moderation objects.

64 - `categories: Categories`

66 A list of the categories, and whether they are flagged or not.

68 - `harassment: bool`

70 Content that expresses, incites, or promotes harassing language towards any target.

72 - `harassment_threatening: bool`

74 Harassment content that also includes violence or serious harm towards any target.

76 - `hate: bool`

78 Content that expresses, incites, or promotes hate based on race, gender, ethnicity, religion, nationality, sexual orientation, disability status, or caste. Hateful content aimed at non-protected groups (e.g., chess players) is harassment.

80 - `hate_threatening: bool`

82 Hateful content that also includes violence or serious harm towards the targeted group based on race, gender, ethnicity, religion, nationality, sexual orientation, disability status, or caste.

84 - `illicit: Optional[bool]`

86 Content that includes instructions or advice that facilitate the planning or execution of wrongdoing, or that gives advice or instruction on how to commit illicit acts. For example, "how to shoplift" would fit this category.

88 - `illicit_violent: Optional[bool]`

90 Content that includes instructions or advice that facilitate the planning or execution of wrongdoing that also includes violence, or that gives advice or instruction on the procurement of any weapon.

92 - `self_harm: bool`

94 Content that promotes, encourages, or depicts acts of self-harm, such as suicide, cutting, and eating disorders.

96 - `self_harm_instructions: bool`

98 Content that encourages performing acts of self-harm, such as suicide, cutting, and eating disorders, or that gives instructions or advice on how to commit such acts.

100 - `self_harm_intent: bool`

101

102 Content where the speaker expresses that they are engaging or intend to engage in acts of self-harm, such as suicide, cutting, and eating disorders.

103

104 - `sexual: bool`

105

106 Content meant to arouse sexual excitement, such as the description of sexual activity, or that promotes sexual services (excluding sex education and wellness).

107

108 - `sexual_minors: bool`

109

110 Sexual content that includes an individual who is under 18 years old.

111

112 - `violence: bool`

113

114 Content that depicts death, violence, or physical injury.

115

116 - `violence_graphic: bool`

117

118 Content that depicts death, violence, or physical injury in graphic detail.

119

120 - `category_applied_input_types: CategoryAppliedInputTypes`

121

122 A list of the categories along with the input type(s) that the score applies to.

123

124 - `harassment: List[Literal["text"]]`

125

126 The applied input type(s) for the category 'harassment'.

127

128 - `"text"`

129

130 - `harassment_threatening: List[Literal["text"]]`

131

132 The applied input type(s) for the category 'harassment/threatening'.

133

134 - `"text"`

135

136 - `hate: List[Literal["text"]]`

137

138 The applied input type(s) for the category 'hate'.

139

140 - `"text"`

141

142 - `hate_threatening: List[Literal["text"]]`

143

144 The applied input type(s) for the category 'hate/threatening'.

145

146 - `"text"`

147

148 - `illicit: List[Literal["text"]]`

149

150 The applied input type(s) for the category 'illicit'.

151

152 - `"text"`

153

154 - `illicit_violent: List[Literal["text"]]`

155

156 The applied input type(s) for the category 'illicit/violent'.

157

158 - `"text"`

159

160 - `self_harm: List[Literal["text", "image"]]`

161

162 The applied input type(s) for the category 'self-harm'.

163

164 - `"text"`

165

166 - `"image"`

167

168 - `self_harm_instructions: List[Literal["text", "image"]]`

169

170 The applied input type(s) for the category 'self-harm/instructions'.

171

172 - `"text"`

173

174 - `"image"`

175

176 - `self_harm_intent: List[Literal["text", "image"]]`

177

178 The applied input type(s) for the category 'self-harm/intent'.

179

180 - `"text"`

181

182 - `"image"`

183

184 - `sexual: List[Literal["text", "image"]]`

185

186 The applied input type(s) for the category 'sexual'.

187

188 - `"text"`

189

190 - `"image"`

191

192 - `sexual_minors: List[Literal["text"]]`

193

194 The applied input type(s) for the category 'sexual/minors'.

195

196 - `"text"`

197

198 - `violence: List[Literal["text", "image"]]`

199

200 The applied input type(s) for the category 'violence'.

201

202 - `"text"`

203

204 - `"image"`

205

206 - `violence_graphic: List[Literal["text", "image"]]`

207

208 The applied input type(s) for the category 'violence/graphic'.

209

210 - `"text"`

211

212 - `"image"`

213

214 - `category_scores: CategoryScores`

215

216 A list of the categories along with their scores as predicted by model.

217

218 - `harassment: float`

219

220 The score for the category 'harassment'.

221

222 - `harassment_threatening: float`

223

224 The score for the category 'harassment/threatening'.

225

226 - `hate: float`

227

228 The score for the category 'hate'.

229

230 - `hate_threatening: float`

231

232 The score for the category 'hate/threatening'.

233

234 - `illicit: float`

235

236 The score for the category 'illicit'.

237

238 - `illicit_violent: float`

239

240 The score for the category 'illicit/violent'.

241

242 - `self_harm: float`

243

244 The score for the category 'self-harm'.

245

246 - `self_harm_instructions: float`

247

248 The score for the category 'self-harm/instructions'.

249

250 - `self_harm_intent: float`

251

252 The score for the category 'self-harm/intent'.

253

254 - `sexual: float`

255

256 The score for the category 'sexual'.

257

258 - `sexual_minors: float`

259

260 The score for the category 'sexual/minors'.

261

262 - `violence: float`

263

264 The score for the category 'violence'.

265

266 - `violence_graphic: float`

267

268 The score for the category 'violence/graphic'.

269

270 - `flagged: bool`

271

272 Whether any of the below categories are flagged.

273

274### Example

275

276```python

277import os

278from openai import OpenAI

279

280client = OpenAI(

281 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted

282)

283moderation = client.moderations.create(

284 input="I want to kill them.",

285)

286print(moderation.id)

287```

288

289#### Response

290

291```json

292{

293 "id": "id",

294 "model": "model",

295 "results": [

296 {

297 "categories": {

298 "harassment": true,

299 "harassment/threatening": true,

300 "hate": true,

301 "hate/threatening": true,

302 "illicit": true,

303 "illicit/violent": true,

304 "self-harm": true,

305 "self-harm/instructions": true,

306 "self-harm/intent": true,

307 "sexual": true,

308 "sexual/minors": true,

309 "violence": true,

310 "violence/graphic": true

311 },

312 "category_applied_input_types": {

313 "harassment": [

314 "text"

315 ],

316 "harassment/threatening": [

317 "text"

318 ],

319 "hate": [

320 "text"

321 ],

322 "hate/threatening": [

323 "text"

324 ],

325 "illicit": [

326 "text"

327 ],

328 "illicit/violent": [

329 "text"

330 ],

331 "self-harm": [

332 "text"

333 ],

334 "self-harm/instructions": [

335 "text"

336 ],

337 "self-harm/intent": [

338 "text"

339 ],

340 "sexual": [

341 "text"

342 ],

343 "sexual/minors": [

344 "text"

345 ],

346 "violence": [

347 "text"

348 ],

349 "violence/graphic": [

350 "text"

351 ]

352 },

353 "category_scores": {

354 "harassment": 0,

355 "harassment/threatening": 0,

356 "hate": 0,

357 "hate/threatening": 0,

358 "illicit": 0,

359 "illicit/violent": 0,

360 "self-harm": 0,

361 "self-harm/instructions": 0,

362 "self-harm/intent": 0,

363 "sexual": 0,

364 "sexual/minors": 0,

365 "violence": 0,

366 "violence/graphic": 0

367 },

368 "flagged": true

369 }

370 ]

371}

372```

373

374### Single string

375

376```python

377from openai import OpenAI

378client = OpenAI()

379

380moderation = client.moderations.create(input="I want to kill them.")

381print(moderation)

382```

383

384#### Response

385

386```json

387{

388 "id": "modr-AB8CjOTu2jiq12hp1AQPfeqFWaORR",

389 "model": "text-moderation-007",

390 "results": [

391 {

392 "flagged": true,

393 "categories": {

394 "sexual": false,

395 "hate": false,

396 "harassment": true,

397 "self-harm": false,

398 "sexual/minors": false,

399 "hate/threatening": false,

400 "violence/graphic": false,

401 "self-harm/intent": false,

402 "self-harm/instructions": false,

403 "harassment/threatening": true,

404 "violence": true

405 },

406 "category_scores": {

407 "sexual": 0.000011726012417057063,

408 "hate": 0.22706663608551025,

409 "harassment": 0.5215635299682617,

410 "self-harm": 2.227119921371923e-6,

411 "sexual/minors": 7.107352217872176e-8,

412 "hate/threatening": 0.023547329008579254,

413 "violence/graphic": 0.00003391829886822961,

414 "self-harm/intent": 1.646940972932498e-6,

415 "self-harm/instructions": 1.1198755256458526e-9,

416 "harassment/threatening": 0.5694745779037476,

417 "violence": 0.9971134662628174

418 }

419 }

420 ]

421}

422```

423

424### Image and text

425

426```python

427from openai import OpenAI

428client = OpenAI()

429

430response = client.moderations.create(

431 model="omni-moderation-latest",

432 input=[

433 {"type": "text", "text": "...text to classify goes here..."},

434 {

435 "type": "image_url",

436 "image_url": {

437 "url": "https://example.com/image.png",

438 # can also use base64 encoded image URLs

439 # "url": "data:image/jpeg;base64,abcdefg..."

440 }

441 },

442 ],

443)

444

445print(response)

446```

447

448#### Response

449

450```json

451{

452 "id": "modr-0d9740456c391e43c445bf0f010940c7",

453 "model": "omni-moderation-latest",

454 "results": [

455 {

456 "flagged": true,

457 "categories": {

458 "harassment": true,

459 "harassment/threatening": true,

460 "sexual": false,

461 "hate": false,

462 "hate/threatening": false,

463 "illicit": false,

464 "illicit/violent": false,

465 "self-harm/intent": false,

466 "self-harm/instructions": false,

467 "self-harm": false,

468 "sexual/minors": false,

469 "violence": true,

470 "violence/graphic": true

471 },

472 "category_scores": {

473 "harassment": 0.8189693396524255,

474 "harassment/threatening": 0.804985420696006,

475 "sexual": 1.573112165348997e-6,

476 "hate": 0.007562942636942845,

477 "hate/threatening": 0.004208854591835476,

478 "illicit": 0.030535955153511665,

479 "illicit/violent": 0.008925306722380033,

480 "self-harm/intent": 0.00023023930975076432,

481 "self-harm/instructions": 0.0002293869201073356,

482 "self-harm": 0.012598046106750154,

483 "sexual/minors": 2.212566909570261e-8,

484 "violence": 0.9999992735124786,

485 "violence/graphic": 0.843064871157054

486 },

487 "category_applied_input_types": {

488 "harassment": [

489 "text"

490 ],

491 "harassment/threatening": [

492 "text"

493 ],

494 "sexual": [

495 "text",

496 "image"

497 ],

498 "hate": [

499 "text"

500 ],

501 "hate/threatening": [

502 "text"

503 ],

504 "illicit": [

505 "text"

506 ],

507 "illicit/violent": [

508 "text"

509 ],

510 "self-harm/intent": [

511 "text",

512 "image"

513 ],

514 "self-harm/instructions": [

515 "text",

516 "image"

517 ],

518 "self-harm": [

519 "text",

520 "image"

521 ],

522 "sexual/minors": [

523 "text"

524 ],

525 "violence": [

526 "text",

527 "image"

528 ],

529 "violence/graphic": [

530 "text",

531 "image"

532 ]

533 }

534 }

535 ]

536}

537```

python/resources/moderations/methods/create/index.md 2026-07-07 08:02 UTC to 2026-07-09 20:58 UTC

Create moderation

Parameters

Returns

Example

Response

Single string

Response

Image and text

Response