Moderations

Create moderation

moderations.create(**kwargs) -> ModerationCreateResponse

post /moderations

Classifies if text and/or image inputs are potentially harmful. Learn more in the moderation guide.

Parameters

input: String | Array[String] | Array[ModerationMultiModalInput]

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.
- String = String
  
  A string of text to classify for moderation.
- UnionMember1 = Array[String]
  
  An array of strings to classify for moderation.
- ModerationMultiModalArray = Array[ModerationMultiModalInput]
  
  An array of multi-modal inputs to the moderation model.
  - class ModerationImageURLInput
    
    An object describing an image to classify.
    - image_url: ImageURL{ url}
      
      Contains either an image URL or a data URL for a base64 encoded image.
      - url: String
        
        Either a URL of the image or the base64 encoded image data.
    - type: :image_url
      
      Always image_url.
      - :image_url
  - class ModerationTextInput
    
    An object describing text to classify.
    - text: String
      
      A string of text to classify.
    - type: :text
      
      Always text.
      - :text
model: String | ModerationModel

The content moderation model you would like to use. Learn more in the moderation guide, and learn about available models here.
- String = String
- ModerationModel = :"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: String
  
  The unique identifier for the moderation request.
- model: String
  
  The model used to generate the moderation results.
- results: Array[Moderation]
  
  A list of moderation objects.
  - categories: Categories{ harassment, harassment_threatening, hate, 10 more}
    
    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: 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: 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{ harassment, harassment_threatening, hate, 10 more}
    
    A list of the categories along with the input type(s) that the score applies to.
    - harassment: Array[:text]
      
      The applied input type(s) for the category 'harassment'.
      - :text
    - harassment_threatening: Array[:text]
      
      The applied input type(s) for the category 'harassment/threatening'.
      - :text
    - hate: Array[:text]
      
      The applied input type(s) for the category 'hate'.
      - :text
    - hate_threatening: Array[:text]
      
      The applied input type(s) for the category 'hate/threatening'.
      - :text
    - illicit: Array[:text]
      
      The applied input type(s) for the category 'illicit'.
      - :text
    - illicit_violent: Array[:text]
      
      The applied input type(s) for the category 'illicit/violent'.
      - :text
    - self_harm: Array[:text | :image]
      
      The applied input type(s) for the category 'self-harm'.
      - :text
      - :image
    - self_harm_instructions: Array[:text | :image]
      
      The applied input type(s) for the category 'self-harm/instructions'.
      - :text
      - :image
    - self_harm_intent: Array[:text | :image]
      
      The applied input type(s) for the category 'self-harm/intent'.
      - :text
      - :image
    - sexual: Array[:text | :image]
      
      The applied input type(s) for the category 'sexual'.
      - :text
      - :image
    - sexual_minors: Array[:text]
      
      The applied input type(s) for the category 'sexual/minors'.
      - :text
    - violence: Array[:text | :image]
      
      The applied input type(s) for the category 'violence'.
      - :text
      - :image
    - violence_graphic: Array[:text | :image]
      
      The applied input type(s) for the category 'violence/graphic'.
      - :text
      - :image
  - category_scores: CategoryScores{ harassment, harassment_threatening, hate, 10 more}
    
    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

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

moderation = openai.moderations.create(input: "I want to kill them.")

puts(moderation)

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
    }
  ]
}

Domain Types

Moderation

class Moderation
- categories: Categories{ harassment, harassment_threatening, hate, 10 more}
  
  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: 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: 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{ harassment, harassment_threatening, hate, 10 more}
  
  A list of the categories along with the input type(s) that the score applies to.
  - harassment: Array[:text]
    
    The applied input type(s) for the category 'harassment'.
    - :text
  - harassment_threatening: Array[:text]
    
    The applied input type(s) for the category 'harassment/threatening'.
    - :text
  - hate: Array[:text]
    
    The applied input type(s) for the category 'hate'.
    - :text
  - hate_threatening: Array[:text]
    
    The applied input type(s) for the category 'hate/threatening'.
    - :text
  - illicit: Array[:text]
    
    The applied input type(s) for the category 'illicit'.
    - :text
  - illicit_violent: Array[:text]
    
    The applied input type(s) for the category 'illicit/violent'.
    - :text
  - self_harm: Array[:text | :image]
    
    The applied input type(s) for the category 'self-harm'.
    - :text
    - :image
  - self_harm_instructions: Array[:text | :image]
    
    The applied input type(s) for the category 'self-harm/instructions'.
    - :text
    - :image
  - self_harm_intent: Array[:text | :image]
    
    The applied input type(s) for the category 'self-harm/intent'.
    - :text
    - :image
  - sexual: Array[:text | :image]
    
    The applied input type(s) for the category 'sexual'.
    - :text
    - :image
  - sexual_minors: Array[:text]
    
    The applied input type(s) for the category 'sexual/minors'.
    - :text
  - violence: Array[:text | :image]
    
    The applied input type(s) for the category 'violence'.
    - :text
    - :image
  - violence_graphic: Array[:text | :image]
    
    The applied input type(s) for the category 'violence/graphic'.
    - :text
    - :image
- category_scores: CategoryScores{ harassment, harassment_threatening, hate, 10 more}
  
  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.

Moderation Image URL Input

class ModerationImageURLInput

An object describing an image to classify.
- image_url: ImageURL{ url}
  
  Contains either an image URL or a data URL for a base64 encoded image.
  - url: String
    
    Either a URL of the image or the base64 encoded image data.
- type: :image_url
  
  Always image_url.
  - :image_url

Moderation Model

ModerationModel = :"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"

ModerationMultiModalInput = ModerationImageURLInput | ModerationTextInput

An object describing an image to classify.
- class ModerationImageURLInput
  
  An object describing an image to classify.
  - image_url: ImageURL{ url}
    
    Contains either an image URL or a data URL for a base64 encoded image.
    - url: String
      
      Either a URL of the image or the base64 encoded image data.
  - type: :image_url
    
    Always image_url.
    - :image_url
- class ModerationTextInput
  
  An object describing text to classify.
  - text: String
    
    A string of text to classify.
  - type: :text
    
    Always text.
    - :text

Moderation Text Input

class ModerationTextInput

An object describing text to classify.
- text: String
  
  A string of text to classify.
- type: :text
  
  Always text.
  - :text

Moderation Create Response

class ModerationCreateResponse

Represents if a given text input is potentially harmful.
- id: String
  
  The unique identifier for the moderation request.
- model: String
  
  The model used to generate the moderation results.
- results: Array[Moderation]
  
  A list of moderation objects.
  - categories: Categories{ harassment, harassment_threatening, hate, 10 more}
    
    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: 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: 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{ harassment, harassment_threatening, hate, 10 more}
    
    A list of the categories along with the input type(s) that the score applies to.
    - harassment: Array[:text]
      
      The applied input type(s) for the category 'harassment'.
      - :text
    - harassment_threatening: Array[:text]
      
      The applied input type(s) for the category 'harassment/threatening'.
      - :text
    - hate: Array[:text]
      
      The applied input type(s) for the category 'hate'.
      - :text
    - hate_threatening: Array[:text]
      
      The applied input type(s) for the category 'hate/threatening'.
      - :text
    - illicit: Array[:text]
      
      The applied input type(s) for the category 'illicit'.
      - :text
    - illicit_violent: Array[:text]
      
      The applied input type(s) for the category 'illicit/violent'.
      - :text
    - self_harm: Array[:text | :image]
      
      The applied input type(s) for the category 'self-harm'.
      - :text
      - :image
    - self_harm_instructions: Array[:text | :image]
      
      The applied input type(s) for the category 'self-harm/instructions'.
      - :text
      - :image
    - self_harm_intent: Array[:text | :image]
      
      The applied input type(s) for the category 'self-harm/intent'.
      - :text
      - :image
    - sexual: Array[:text | :image]
      
      The applied input type(s) for the category 'sexual'.
      - :text
      - :image
    - sexual_minors: Array[:text]
      
      The applied input type(s) for the category 'sexual/minors'.
      - :text
    - violence: Array[:text | :image]
      
      The applied input type(s) for the category 'violence'.
      - :text
      - :image
    - violence_graphic: Array[:text | :image]
      
      The applied input type(s) for the category 'violence/graphic'.
      - :text
      - :image
  - category_scores: CategoryScores{ harassment, harassment_threatening, hate, 10 more}
    
    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.

ruby/resources/moderations/index.md +99 −4

6 6

7**post** `/moderations`7**post** `/moderations`

8 8

~~9Create moderation~~9Classifies if text and/or image inputs are potentially harmful. Learn

10more in the [moderation guide](https://platform.openai.com/docs/guides/moderation).

10 11

11### Parameters12### Parameters

12 13

27 28

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

29 30

31 - `class ModerationImageURLInput`

33 An object describing an image to classify.

35 - `image_url: ImageURL{ url}`

37 Contains either an image URL or a data URL for a base64 encoded image.

39 - `url: String`

41 Either a URL of the image or the base64 encoded image data.

43 - `type: :image_url`

45 Always `image_url`.

47 - `:image_url`

49 - `class ModerationTextInput`

51 An object describing text to classify.

53 - `text: String`

55 A string of text to classify.

57 - `type: :text`

59 Always `text`.

61 - `:text`

30- `model: String | ModerationModel`63- `model: String | ModerationModel`

31 64

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

588 621

589### Moderation Image URL Input622### Moderation Image URL Input

590 623

591- `ModerationImageURLInput = untyped`624- `class ModerationImageURLInput`

625

626 An object describing an image to classify.

627

628 - `image_url: ImageURL{ url}`

629

630 Contains either an image URL or a data URL for a base64 encoded image.

631

632 - `url: String`

633

634 Either a URL of the image or the base64 encoded image data.

635

636 - `type: :image_url`

637

638 Always `image_url`.

639

640 - `:image_url`

592 641

593### Moderation Model642### Moderation Model

594 643

604 653

605### Moderation Multi Modal Input654### Moderation Multi Modal Input

606 655

607- `ModerationMultiModalInput = untyped`656- `ModerationMultiModalInput = ModerationImageURLInput | ModerationTextInput`

657

658 An object describing an image to classify.

659

660 - `class ModerationImageURLInput`

661

662 An object describing an image to classify.

663

664 - `image_url: ImageURL{ url}`

665

666 Contains either an image URL or a data URL for a base64 encoded image.

667

668 - `url: String`

669

670 Either a URL of the image or the base64 encoded image data.

671

672 - `type: :image_url`

673

674 Always `image_url`.

675

676 - `:image_url`

677

678 - `class ModerationTextInput`

679

680 An object describing text to classify.

681

682 - `text: String`

683

684 A string of text to classify.

685

686 - `type: :text`

687

688 Always `text`.

689

690 - `:text`

608 691

609### Moderation Text Input692### Moderation Text Input

610 693

611- `ModerationTextInput = untyped`694- `class ModerationTextInput`

695

696 An object describing text to classify.

697

698 - `text: String`

699

700 A string of text to classify.

701

702 - `type: :text`

703

704 Always `text`.

705

706 - `:text`

612 707

613### Moderation Create Response708### Moderation Create Response

614 709