python/resources/moderations/methods/create/index.md +0 −570 deleted
File Deleted View Diff
1## Create moderation
2
3`moderations.create(ModerationCreateParams**kwargs) -> ModerationCreateResponse`
4
5**post** `/moderations`
6
7Classifies if text and/or image inputs are potentially harmful. Learn
8more in the [moderation guide](https://platform.openai.com/docs/guides/moderation).
9
10### Parameters
11
12- `input: Union[str, Sequence[str], Iterable[ModerationMultiModalInputParam]]`
13
14 Input (or inputs) to classify. Can be a single string, an array of strings, or
15 an array of multi-modal input objects similar to other models.
16
17 - `str`
18
19 A string of text to classify for moderation.
20
21 - `Sequence[str]`
22
23 An array of strings to classify for moderation.
24
25 - `Iterable[ModerationMultiModalInputParam]`
26
27 An array of multi-modal inputs to the moderation model.
28
29 - `class ModerationImageURLInput: …`
30
31 An object describing an image to classify.
32
33 - `image_url: ImageURL`
34
35 Contains either an image URL or a data URL for a base64 encoded image.
36
37 - `url: str`
38
39 Either a URL of the image or the base64 encoded image data.
40
41 - `type: Literal["image_url"]`
42
43 Always `image_url`.
44
45 - `"image_url"`
46
47 - `class ModerationTextInput: …`
48
49 An object describing text to classify.
50
51 - `text: str`
52
53 A string of text to classify.
54
55 - `type: Literal["text"]`
56
57 Always `text`.
58
59 - `"text"`
60
61- `model: Optional[Union[str, ModerationModel]]`
62
63 The content moderation model you would like to use. Learn more in
64 [the moderation guide](https://platform.openai.com/docs/guides/moderation), and learn about
65 available models [here](https://platform.openai.com/docs/models#moderation).
66
67 - `str`
68
69 - `Literal["omni-moderation-latest", "omni-moderation-2024-09-26", "text-moderation-latest", "text-moderation-stable"]`
70
71 - `"omni-moderation-latest"`
72
73 - `"omni-moderation-2024-09-26"`
74
75 - `"text-moderation-latest"`
76
77 - `"text-moderation-stable"`
78
79### Returns
80
81- `class ModerationCreateResponse: …`
82
83 Represents if a given text input is potentially harmful.
84
85 - `id: str`
86
87 The unique identifier for the moderation request.
88
89 - `model: str`
90
91 The model used to generate the moderation results.
92
93 - `results: List[Moderation]`
94
95 A list of moderation objects.
96
97 - `categories: Categories`
98
99 A list of the categories, and whether they are flagged or not.
100
101 - `harassment: bool`
102
103 Content that expresses, incites, or promotes harassing language towards any target.
104
105 - `harassment_threatening: bool`
106
107 Harassment content that also includes violence or serious harm towards any target.
108
109 - `hate: bool`
110
111 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.
112
113 - `hate_threatening: bool`
114
115 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.
116
117 - `illicit: Optional[bool]`
118
119 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.
120
121 - `illicit_violent: Optional[bool]`
122
123 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.
124
125 - `self_harm: bool`
126
127 Content that promotes, encourages, or depicts acts of self-harm, such as suicide, cutting, and eating disorders.
128
129 - `self_harm_instructions: bool`
130
131 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.
132
133 - `self_harm_intent: bool`
134
135 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.
136
137 - `sexual: bool`
138
139 Content meant to arouse sexual excitement, such as the description of sexual activity, or that promotes sexual services (excluding sex education and wellness).
140
141 - `sexual_minors: bool`
142
143 Sexual content that includes an individual who is under 18 years old.
144
145 - `violence: bool`
146
147 Content that depicts death, violence, or physical injury.
148
149 - `violence_graphic: bool`
150
151 Content that depicts death, violence, or physical injury in graphic detail.
152
153 - `category_applied_input_types: CategoryAppliedInputTypes`
154
155 A list of the categories along with the input type(s) that the score applies to.
156
157 - `harassment: List[Literal["text"]]`
158
159 The applied input type(s) for the category 'harassment'.
160
161 - `"text"`
162
163 - `harassment_threatening: List[Literal["text"]]`
164
165 The applied input type(s) for the category 'harassment/threatening'.
166
167 - `"text"`
168
169 - `hate: List[Literal["text"]]`
170
171 The applied input type(s) for the category 'hate'.
172
173 - `"text"`
174
175 - `hate_threatening: List[Literal["text"]]`
176
177 The applied input type(s) for the category 'hate/threatening'.
178
179 - `"text"`
180
181 - `illicit: List[Literal["text"]]`
182
183 The applied input type(s) for the category 'illicit'.
184
185 - `"text"`
186
187 - `illicit_violent: List[Literal["text"]]`
188
189 The applied input type(s) for the category 'illicit/violent'.
190
191 - `"text"`
192
193 - `self_harm: List[Literal["text", "image"]]`
194
195 The applied input type(s) for the category 'self-harm'.
196
197 - `"text"`
198
199 - `"image"`
200
201 - `self_harm_instructions: List[Literal["text", "image"]]`
202
203 The applied input type(s) for the category 'self-harm/instructions'.
204
205 - `"text"`
206
207 - `"image"`
208
209 - `self_harm_intent: List[Literal["text", "image"]]`
210
211 The applied input type(s) for the category 'self-harm/intent'.
212
213 - `"text"`
214
215 - `"image"`
216
217 - `sexual: List[Literal["text", "image"]]`
218
219 The applied input type(s) for the category 'sexual'.
220
221 - `"text"`
222
223 - `"image"`
224
225 - `sexual_minors: List[Literal["text"]]`
226
227 The applied input type(s) for the category 'sexual/minors'.
228
229 - `"text"`
230
231 - `violence: List[Literal["text", "image"]]`
232
233 The applied input type(s) for the category 'violence'.
234
235 - `"text"`
236
237 - `"image"`
238
239 - `violence_graphic: List[Literal["text", "image"]]`
240
241 The applied input type(s) for the category 'violence/graphic'.
242
243 - `"text"`
244
245 - `"image"`
246
247 - `category_scores: CategoryScores`
248
249 A list of the categories along with their scores as predicted by model.
250
251 - `harassment: float`
252
253 The score for the category 'harassment'.
254
255 - `harassment_threatening: float`
256
257 The score for the category 'harassment/threatening'.
258
259 - `hate: float`
260
261 The score for the category 'hate'.
262
263 - `hate_threatening: float`
264
265 The score for the category 'hate/threatening'.
266
267 - `illicit: float`
268
269 The score for the category 'illicit'.
270
271 - `illicit_violent: float`
272
273 The score for the category 'illicit/violent'.
274
275 - `self_harm: float`
276
277 The score for the category 'self-harm'.
278
279 - `self_harm_instructions: float`
280
281 The score for the category 'self-harm/instructions'.
282
283 - `self_harm_intent: float`
284
285 The score for the category 'self-harm/intent'.
286
287 - `sexual: float`
288
289 The score for the category 'sexual'.
290
291 - `sexual_minors: float`
292
293 The score for the category 'sexual/minors'.
294
295 - `violence: float`
296
297 The score for the category 'violence'.
298
299 - `violence_graphic: float`
300
301 The score for the category 'violence/graphic'.
302
303 - `flagged: bool`
304
305 Whether any of the below categories are flagged.
306
307### Example
308
309```python
310import os
311from openai import OpenAI
312
313client = OpenAI(
314 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
315)
316moderation = client.moderations.create(
317 input="I want to kill them.",
318)
319print(moderation.id)
320```
321
322#### Response
323
324```json
325{
326 "id": "id",
327 "model": "model",
328 "results": [
329 {
330 "categories": {
331 "harassment": true,
332 "harassment/threatening": true,
333 "hate": true,
334 "hate/threatening": true,
335 "illicit": true,
336 "illicit/violent": true,
337 "self-harm": true,
338 "self-harm/instructions": true,
339 "self-harm/intent": true,
340 "sexual": true,
341 "sexual/minors": true,
342 "violence": true,
343 "violence/graphic": true
344 },
345 "category_applied_input_types": {
346 "harassment": [
347 "text"
348 ],
349 "harassment/threatening": [
350 "text"
351 ],
352 "hate": [
353 "text"
354 ],
355 "hate/threatening": [
356 "text"
357 ],
358 "illicit": [
359 "text"
360 ],
361 "illicit/violent": [
362 "text"
363 ],
364 "self-harm": [
365 "text"
366 ],
367 "self-harm/instructions": [
368 "text"
369 ],
370 "self-harm/intent": [
371 "text"
372 ],
373 "sexual": [
374 "text"
375 ],
376 "sexual/minors": [
377 "text"
378 ],
379 "violence": [
380 "text"
381 ],
382 "violence/graphic": [
383 "text"
384 ]
385 },
386 "category_scores": {
387 "harassment": 0,
388 "harassment/threatening": 0,
389 "hate": 0,
390 "hate/threatening": 0,
391 "illicit": 0,
392 "illicit/violent": 0,
393 "self-harm": 0,
394 "self-harm/instructions": 0,
395 "self-harm/intent": 0,
396 "sexual": 0,
397 "sexual/minors": 0,
398 "violence": 0,
399 "violence/graphic": 0
400 },
401 "flagged": true
402 }
403 ]
404}
405```
406
407### Single string
408
409```python
410from openai import OpenAI
411client = OpenAI()
412
413moderation = client.moderations.create(input="I want to kill them.")
414print(moderation)
415```
416
417#### Response
418
419```json
420{
421 "id": "modr-AB8CjOTu2jiq12hp1AQPfeqFWaORR",
422 "model": "text-moderation-007",
423 "results": [
424 {
425 "flagged": true,
426 "categories": {
427 "sexual": false,
428 "hate": false,
429 "harassment": true,
430 "self-harm": false,
431 "sexual/minors": false,
432 "hate/threatening": false,
433 "violence/graphic": false,
434 "self-harm/intent": false,
435 "self-harm/instructions": false,
436 "harassment/threatening": true,
437 "violence": true
438 },
439 "category_scores": {
440 "sexual": 0.000011726012417057063,
441 "hate": 0.22706663608551025,
442 "harassment": 0.5215635299682617,
443 "self-harm": 2.227119921371923e-6,
444 "sexual/minors": 7.107352217872176e-8,
445 "hate/threatening": 0.023547329008579254,
446 "violence/graphic": 0.00003391829886822961,
447 "self-harm/intent": 1.646940972932498e-6,
448 "self-harm/instructions": 1.1198755256458526e-9,
449 "harassment/threatening": 0.5694745779037476,
450 "violence": 0.9971134662628174
451 }
452 }
453 ]
454}
455```
456
457### Image and text
458
459```python
460from openai import OpenAI
461client = OpenAI()
462
463response = client.moderations.create(
464 model="omni-moderation-latest",
465 input=[
466 {"type": "text", "text": "...text to classify goes here..."},
467 {
468 "type": "image_url",
469 "image_url": {
470 "url": "https://example.com/image.png",
471 # can also use base64 encoded image URLs
472 # "url": "data:image/jpeg;base64,abcdefg..."
473 }
474 },
475 ],
476)
477
478print(response)
479```
480
481#### Response
482
483```json
484{
485 "id": "modr-0d9740456c391e43c445bf0f010940c7",
486 "model": "omni-moderation-latest",
487 "results": [
488 {
489 "flagged": true,
490 "categories": {
491 "harassment": true,
492 "harassment/threatening": true,
493 "sexual": false,
494 "hate": false,
495 "hate/threatening": false,
496 "illicit": false,
497 "illicit/violent": false,
498 "self-harm/intent": false,
499 "self-harm/instructions": false,
500 "self-harm": false,
501 "sexual/minors": false,
502 "violence": true,
503 "violence/graphic": true
504 },
505 "category_scores": {
506 "harassment": 0.8189693396524255,
507 "harassment/threatening": 0.804985420696006,
508 "sexual": 1.573112165348997e-6,
509 "hate": 0.007562942636942845,
510 "hate/threatening": 0.004208854591835476,
511 "illicit": 0.030535955153511665,
512 "illicit/violent": 0.008925306722380033,
513 "self-harm/intent": 0.00023023930975076432,
514 "self-harm/instructions": 0.0002293869201073356,
515 "self-harm": 0.012598046106750154,
516 "sexual/minors": 2.212566909570261e-8,
517 "violence": 0.9999992735124786,
518 "violence/graphic": 0.843064871157054
519 },
520 "category_applied_input_types": {
521 "harassment": [
522 "text"
523 ],
524 "harassment/threatening": [
525 "text"
526 ],
527 "sexual": [
528 "text",
529 "image"
530 ],
531 "hate": [
532 "text"
533 ],
534 "hate/threatening": [
535 "text"
536 ],
537 "illicit": [
538 "text"
539 ],
540 "illicit/violent": [
541 "text"
542 ],
543 "self-harm/intent": [
544 "text",
545 "image"
546 ],
547 "self-harm/instructions": [
548 "text",
549 "image"
550 ],
551 "self-harm": [
552 "text",
553 "image"
554 ],
555 "sexual/minors": [
556 "text"
557 ],
558 "violence": [
559 "text",
560 "image"
561 ],
562 "violence/graphic": [
563 "text",
564 "image"
565 ]
566 }
567 }
568 ]
569}
570```