openapi: 3.0.0
info:
title: OpenAI Assistants Moderations API
description: The Assistants API allows you to build AI assistants within your own applications. An Assistant has instructions and can leverage models, tools, and knowledge to respond to user queries. The Assistants API currently supports three types of tools - Code Interpreter, Retrieval, and Function calling. In the future, we plan to release more OpenAI-built tools, and allow you to provide your own tools on our platform.
version: 2.0.0
termsOfService: https://openai.com/policies/terms-of-use
contact:
name: OpenAI Support
url: https://help.openai.com/
license:
name: MIT
url: https://github.com/openai/openai-openapi/blob/master/LICENSE
servers:
- url: https://api.openai.com/v1
security:
- ApiKeyAuth: []
tags:
- name: Moderations
description: Given text and/or image inputs, classifies if those inputs are potentially harmful.
paths:
/moderations:
post:
operationId: createModeration
tags:
- Moderations
summary: 'Classifies if text and/or image inputs are potentially harmful. Learn
more in the [moderation guide](/docs/guides/moderation).
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateModerationRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateModerationResponse'
x-oaiMeta:
name: Create moderation
group: moderations
examples:
- title: Single string
request:
curl: "curl https://api.openai.com/v1/moderations \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"input\": \"I want to kill them.\"\n }'\n"
python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=os.environ.get(\"OPENAI_API_KEY\"), # This is the default and can be omitted\n)\nmoderation = client.moderations.create(\n input=\"I want to kill them.\",\n)\nprint(moderation.id)"
javascript: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const moderation = await openai.moderations.create({ input: \"I want to kill them.\" });\n\n console.log(moderation);\n}\nmain();\n"
csharp: "using System;\nusing System.ClientModel;\n\nusing OpenAI.Moderations;\n\nModerationClient client = new(\n model: \"omni-moderation-latest\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nClientResult<ModerationResult> moderation = client.ClassifyText(\"I want to kill them.\");\n"
node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted\n});\n\nconst moderation = await client.moderations.create({ input: 'I want to kill them.' });\n\nconsole.log(moderation.id);"
go: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/openai/openai-go\"\n\t\"github.com/openai/openai-go/option\"\n)\n\nfunc main() {\n\tclient := openai.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tmoderation, err := client.Moderations.New(context.TODO(), openai.ModerationNewParams{\n\t\tInput: openai.ModerationNewParamsInputUnion{\n\t\t\tOfString: openai.String(\"I want to kill them.\"),\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", moderation.ID)\n}\n"
java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.moderations.ModerationCreateParams;\nimport com.openai.models.moderations.ModerationCreateResponse;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n ModerationCreateParams params = ModerationCreateParams.builder()\n .input(\"I want to kill them.\")\n .build();\n ModerationCreateResponse moderation = client.moderations().create(params);\n }\n}"
ruby: 'require "openai"
openai = OpenAI::Client.new(api_key: "My API Key")
moderation = openai.moderations.create(input: "I want to kill them.")
puts(moderation)'
response: "{\n \"id\": \"modr-AB8CjOTu2jiq12hp1AQPfeqFWaORR\",\n \"model\": \"text-moderation-007\",\n \"results\": [\n {\n \"flagged\": true,\n \"categories\": {\n \"sexual\": false,\n \"hate\": false,\n \"harassment\": true,\n \"self-harm\": false,\n \"sexual/minors\": false,\n \"hate/threatening\": false,\n \"violence/graphic\": false,\n \"self-harm/intent\": false,\n \"self-harm/instructions\": false,\n \"harassment/threatening\": true,\n \"violence\": true\n },\n \"category_scores\": {\n \"sexual\": 0.000011726012417057063,\n \"hate\": 0.22706663608551025,\n \"harassment\": 0.5215635299682617,\n \"self-harm\": 2.227119921371923e-6,\n \"sexual/minors\": 7.107352217872176e-8,\n \"hate/threatening\": 0.023547329008579254,\n \"violence/graphic\": 0.00003391829886822961,\n \"self-harm/intent\": 1.646940972932498e-6,\n \"self-harm/instructions\": 1.1198755256458526e-9,\n \"harassment/threatening\": 0.5694745779037476,\n \"violence\": 0.9971134662628174\n }\n }\n ]\n}\n"
- title: Image and text
request:
curl: "curl https://api.openai.com/v1/moderations \\\n -X POST \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"omni-moderation-latest\",\n \"input\": [\n { \"type\": \"text\", \"text\": \"...text to classify goes here...\" },\n {\n \"type\": \"image_url\",\n \"image_url\": {\n \"url\": \"https://example.com/image.png\"\n }\n }\n ]\n }'\n"
python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=os.environ.get(\"OPENAI_API_KEY\"), # This is the default and can be omitted\n)\nmoderation = client.moderations.create(\n input=\"I want to kill them.\",\n)\nprint(moderation.id)"
javascript: "import OpenAI from \"openai\";\nconst openai = new OpenAI();\n\nconst moderation = await openai.moderations.create({\n model: \"omni-moderation-latest\",\n input: [\n { type: \"text\", text: \"...text to classify goes here...\" },\n {\n type: \"image_url\",\n image_url: {\n url: \"https://example.com/image.png\"\n // can also use base64 encoded image URLs\n // url: \"data:image/jpeg;base64,abcdefg...\"\n }\n }\n ],\n});\n\nconsole.log(moderation);\n"
node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted\n});\n\nconst moderation = await client.moderations.create({ input: 'I want to kill them.' });\n\nconsole.log(moderation.id);"
go: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/openai/openai-go\"\n\t\"github.com/openai/openai-go/option\"\n)\n\nfunc main() {\n\tclient := openai.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tmoderation, err := client.Moderations.New(context.TODO(), openai.ModerationNewParams{\n\t\tInput: openai.ModerationNewParamsInputUnion{\n\t\t\tOfString: openai.String(\"I want to kill them.\"),\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", moderation.ID)\n}\n"
java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.moderations.ModerationCreateParams;\nimport com.openai.models.moderations.ModerationCreateResponse;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n ModerationCreateParams params = ModerationCreateParams.builder()\n .input(\"I want to kill them.\")\n .build();\n ModerationCreateResponse moderation = client.moderations().create(params);\n }\n}"
ruby: 'require "openai"
openai = OpenAI::Client.new(api_key: "My API Key")
moderation = openai.moderations.create(input: "I want to kill them.")
puts(moderation)'
response: "{\n \"id\": \"modr-0d9740456c391e43c445bf0f010940c7\",\n \"model\": \"omni-moderation-latest\",\n \"results\": [\n {\n \"flagged\": true,\n \"categories\": {\n \"harassment\": true,\n \"harassment/threatening\": true,\n \"sexual\": false,\n \"hate\": false,\n \"hate/threatening\": false,\n \"illicit\": false,\n \"illicit/violent\": false,\n \"self-harm/intent\": false,\n \"self-harm/instructions\": false,\n \"self-harm\": false,\n \"sexual/minors\": false,\n \"violence\": true,\n \"violence/graphic\": true\n },\n \"category_scores\": {\n \"harassment\": 0.8189693396524255,\n \"harassment/threatening\": 0.804985420696006,\n \"sexual\": 1.573112165348997e-6,\n \"hate\": 0.007562942636942845,\n \"hate/threatening\": 0.004208854591835476,\n \"illicit\": 0.030535955153511665,\n \"illicit/violent\": 0.008925306722380033,\n \"self-harm/intent\": 0.00023023930975076432,\n \"self-harm/instructions\": 0.0002293869201073356,\n \"self-harm\": 0.012598046106750154,\n \"sexual/minors\": 2.212566909570261e-8,\n \"violence\": 0.9999992735124786,\n \"violence/graphic\": 0.843064871157054\n },\n \"category_applied_input_types\": {\n \"harassment\": [\n \"text\"\n ],\n \"harassment/threatening\": [\n \"text\"\n ],\n \"sexual\": [\n \"text\",\n \"image\"\n ],\n \"hate\": [\n \"text\"\n ],\n \"hate/threatening\": [\n \"text\"\n ],\n \"illicit\": [\n \"text\"\n ],\n \"illicit/violent\": [\n \"text\"\n ],\n \"self-harm/intent\": [\n \"text\",\n \"image\"\n ],\n \"self-harm/instructions\": [\n \"text\",\n \"image\"\n ],\n \"self-harm\": [\n \"text\",\n \"image\"\n ],\n \"sexual/minors\": [\n \"text\"\n ],\n \"violence\": [\n \"text\",\n \"image\"\n ],\n \"violence/graphic\": [\n \"text\",\n \"image\"\n ]\n }\n }\n ]\n}\n"
components:
schemas:
CreateModerationResponse:
type: object
description: Represents if a given text input is potentially harmful.
properties:
id:
type: string
description: The unique identifier for the moderation request.
model:
type: string
description: The model used to generate the moderation results.
results:
type: array
description: A list of moderation objects.
items:
type: object
properties:
flagged:
type: boolean
description: Whether any of the below categories are flagged.
categories:
type: object
description: A list of the categories, and whether they are flagged or not.
properties:
hate:
type: boolean
description: 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:
type: boolean
description: 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.
harassment:
type: boolean
description: Content that expresses, incites, or promotes harassing language towards any target.
harassment/threatening:
type: boolean
description: Harassment content that also includes violence or serious harm towards any target.
illicit:
anyOf:
- type: boolean
description: 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.
- type: 'null'
illicit/violent:
anyOf:
- type: boolean
description: 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.
- type: 'null'
self-harm:
type: boolean
description: Content that promotes, encourages, or depicts acts of self-harm, such as suicide, cutting, and eating disorders.
self-harm/intent:
type: boolean
description: 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.
self-harm/instructions:
type: boolean
description: 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.
sexual:
type: boolean
description: 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:
type: boolean
description: Sexual content that includes an individual who is under 18 years old.
violence:
type: boolean
description: Content that depicts death, violence, or physical injury.
violence/graphic:
type: boolean
description: Content that depicts death, violence, or physical injury in graphic detail.
required:
- hate
- hate/threatening
- harassment
- harassment/threatening
- illicit
- illicit/violent
- self-harm
- self-harm/intent
- self-harm/instructions
- sexual
- sexual/minors
- violence
- violence/graphic
category_scores:
type: object
description: A list of the categories along with their scores as predicted by model.
properties:
hate:
type: number
description: The score for the category 'hate'.
hate/threatening:
type: number
description: The score for the category 'hate/threatening'.
harassment:
type: number
description: The score for the category 'harassment'.
harassment/threatening:
type: number
description: The score for the category 'harassment/threatening'.
illicit:
type: number
description: The score for the category 'illicit'.
illicit/violent:
type: number
description: The score for the category 'illicit/violent'.
self-harm:
type: number
description: The score for the category 'self-harm'.
self-harm/intent:
type: number
description: The score for the category 'self-harm/intent'.
self-harm/instructions:
type: number
description: The score for the category 'self-harm/instructions'.
sexual:
type: number
description: The score for the category 'sexual'.
sexual/minors:
type: number
description: The score for the category 'sexual/minors'.
violence:
type: number
description: The score for the category 'violence'.
violence/graphic:
type: number
description: The score for the category 'violence/graphic'.
required:
- hate
- hate/threatening
- harassment
- harassment/threatening
- illicit
- illicit/violent
- self-harm
- self-harm/intent
- self-harm/instructions
- sexual
- sexual/minors
- violence
- violence/graphic
category_applied_input_types:
type: object
description: A list of the categories along with the input type(s) that the score applies to.
properties:
hate:
type: array
description: The applied input type(s) for the category 'hate'.
items:
type: string
enum:
- text
x-stainless-const: true
hate/threatening:
type: array
description: The applied input type(s) for the category 'hate/threatening'.
items:
type: string
enum:
- text
x-stainless-const: true
harassment:
type: array
description: The applied input type(s) for the category 'harassment'.
items:
type: string
enum:
- text
x-stainless-const: true
harassment/threatening:
type: array
description: The applied input type(s) for the category 'harassment/threatening'.
items:
type: string
enum:
- text
x-stainless-const: true
illicit:
type: array
description: The applied input type(s) for the category 'illicit'.
items:
type: string
enum:
- text
x-stainless-const: true
illicit/violent:
type: array
description: The applied input type(s) for the category 'illicit/violent'.
items:
type: string
enum:
- text
x-stainless-const: true
self-harm:
type: array
description: The applied input type(s) for the category 'self-harm'.
items:
type: string
enum:
- text
- image
self-harm/intent:
type: array
description: The applied input type(s) for the category 'self-harm/intent'.
items:
type: string
enum:
- text
- image
self-harm/instructions:
type: array
description: The applied input type(s) for the category 'self-harm/instructions'.
items:
type: string
enum:
- text
- image
sexual:
type: array
description: The applied input type(s) for the category 'sexual'.
items:
type: string
enum:
- text
- image
sexual/minors:
type: array
description: The applied input type(s) for the category 'sexual/minors'.
items:
type: string
enum:
- text
x-stainless-const: true
violence:
type: array
description: The applied input type(s) for the category 'violence'.
items:
type: string
enum:
- text
- image
violence/graphic:
type: array
description: The applied input type(s) for the category 'violence/graphic'.
items:
type: string
enum:
- text
- image
required:
- hate
- hate/threatening
- harassment
- harassment/threatening
- illicit
- illicit/violent
- self-harm
- self-harm/intent
- self-harm/instructions
- sexual
- sexual/minors
- violence
- violence/graphic
required:
- flagged
- categories
- category_scores
- category_applied_input_types
required:
- id
- model
- results
x-oaiMeta:
name: The moderation object
example: "{\n \"id\": \"modr-0d9740456c391e43c445bf0f010940c7\",\n \"model\": \"omni-moderation-latest\",\n \"results\": [\n {\n \"flagged\": true,\n \"categories\": {\n \"harassment\": true,\n \"harassment/threatening\": true,\n \"sexual\": false,\n \"hate\": false,\n \"hate/threatening\": false,\n \"illicit\": false,\n \"illicit/violent\": false,\n \"self-harm/intent\": false,\n \"self-harm/instructions\": false,\n \"self-harm\": false,\n \"sexual/minors\": false,\n \"violence\": true,\n \"violence/graphic\": true\n },\n \"category_scores\": {\n \"harassment\": 0.8189693396524255,\n \"harassment/threatening\": 0.804985420696006,\n \"sexual\": 1.573112165348997e-6,\n \"hate\": 0.007562942636942845,\n \"hate/threatening\": 0.004208854591835476,\n \"illicit\": 0.030535955153511665,\n \"illicit/violent\": 0.008925306722380033,\n \"self-harm/intent\": 0.00023023930975076432,\n \"self-harm/instructions\": 0.0002293869201073356,\n \"self-harm\": 0.012598046106750154,\n \"sexual/minors\": 2.212566909570261e-8,\n \"violence\": 0.9999992735124786,\n \"violence/graphic\": 0.843064871157054\n },\n \"category_applied_input_types\": {\n \"harassment\": [\n \"text\"\n ],\n \"harassment/threatening\": [\n \"text\"\n ],\n \"sexual\": [\n \"text\",\n \"image\"\n ],\n \"hate\": [\n \"text\"\n ],\n \"hate/threatening\": [\n \"text\"\n ],\n \"illicit\": [\n \"text\"\n ],\n \"illicit/violent\": [\n \"text\"\n ],\n \"self-harm/intent\": [\n \"text\",\n \"image\"\n ],\n \"self-harm/instructions\": [\n \"text\",\n \"image\"\n ],\n \"self-harm\": [\n \"text\",\n \"image\"\n ],\n \"sexual/minors\": [\n \"text\"\n ],\n \"violence\": [\n \"text\",\n \"image\"\n ],\n \"violence/graphic\": [\n \"text\",\n \"image\"\n ]\n }\n }\n ]\n}\n"
CreateModerationRequest:
type: object
properties:
input:
description: '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.
'
oneOf:
- type: string
description: A string of text to classify for moderation.
default: ''
example: I want to kill them.
- type: array
description: An array of strings to classify for moderation.
items:
type: string
default: ''
example: I want to kill them.
- type: array
description: An array of multi-modal inputs to the moderation model.
items:
oneOf:
- type: object
description: An object describing an image to classify.
properties:
type:
description: Always `image_url`.
type: string
enum:
- image_url
x-stainless-const: true
image_url:
type: object
description: Contains either an image URL or a data URL for a base64 encoded image.
properties:
url:
type: string
description: Either a URL of the image or the base64 encoded image data.
format: uri
example: https://example.com/image.jpg
required:
- url
required:
- type
- image_url
- type: object
description: An object describing text to classify.
properties:
type:
description: Always `text`.
type: string
enum:
- text
x-stainless-const: true
text:
description: A string of text to classify.
type: string
example: I want to kill them
required:
- type
- text
model:
description: 'The content moderation model you would like to use. Learn more in
[the moderation guide](/docs/guides/moderation), and learn about
available models [here](/docs/models#moderation).
'
nullable: false
default: omni-moderation-latest
example: omni-moderation-2024-09-26
anyOf:
- type: string
- type: string
enum:
- omni-moderation-latest
- omni-moderation-2024-09-26
- text-moderation-latest
- text-moderation-stable
x-oaiTypeLabel: string
required:
- input
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
x-oaiMeta:
groups:
- id: audio
title: Audio
description: 'Learn how to turn audio into text or text into audio.
Related guide: [Speech to text](/docs/guides/speech-to-text)
'
sections:
- type: endpoint
key: createSpeech
path: createSpeech
- type: endpoint
key: createTranscription
path: createTranscription
- type: endpoint
key: createTranslation
path: createTranslation
- id: chat
title: Chat
description: 'Given a list of messages comprising a conversation, the model will return a response.
Related guide: [Chat Completions](/docs/guides/text-generation)
'
sections:
- type: endpoint
key: createChatCompletion
path: create
- type: object
key: CreateChatCompletionResponse
path: object
- type: object
key: CreateChatCompletionStreamResponse
path: streaming
- id: embeddings
title: Embeddings
description: 'Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms.
Related guide: [Embeddings](/docs/guides/embeddings)
'
sections:
- type: endpoint
key: createEmbedding
path: create
- type: object
key: Embedding
path: object
- id: fine-tuning
title: Fine-tuning
description: 'Manage fine-tuning jobs to tailor a model to your specific training data.
Related guide: [Fine-tune models](/docs/guides/fine-tuning)
'
sections:
- type: endpoint
key: createFineTuningJob
path: create
- type: endpoint
key: listPaginatedFineTuningJobs
path: list
- type: endpoint
key: listFineTuningEvents
path: list-events
- type: endpoint
key: retrieveFineTuningJob
path: retrieve
- type: endpoint
key: cancelFineTuningJob
path: cancel
- type: object
key: FineTuningJob
path: object
- type: object
key: FineTuningJobEvent
path: event-object
- id: files
title: Files
description: 'Files are used to upload documents that can be used with features like [Assistants](/docs/api-reference/assistants) and [Fine-tuning](/docs/api-reference/fine-tuning).
'
sections:
- type: endpoint
key: createFile
path: create
- type: endpoint
key: listFiles
path: list
- type: endpoint
key: retrieveFile
path: retrieve
- type: endpoint
key: deleteFile
path: delete
- type: endpoint
key: downloadFile
path: retrieve-contents
- type: object
key: OpenAIFile
path: object
- id: images
title: Images
description: 'Given a prompt and/or an input image, the model will generate a new image.
Related guide: [Image generation](/docs/guides/images)
'
sections:
- type: endpoint
key: createImage
path: create
- type: endpoint
key: createImageEdit
path: createEdit
- type: endpoint
key: createImageVariation
path: createVariation
- type: object
key: Image
path: object
- id: models
title: Models
description: 'List and describe the various models available in the API. You can refer to the [Models](/docs/models) documentation to understand what models are available and the differences between them.
'
sections:
- type: endpoint
key: listModels
path: list
- type: endpoint
key: retrieveModel
path: retrieve
- type: endpoint
key: deleteModel
path: delete
- type: object
key: Model
path: object
- id: moderations
title: Moderations
description: 'Given a input text, outputs if the model classifies it as violating OpenAI''s content policy.
Related guide: [Moderations](/docs/guides/moderation)
'
sections:
- type: endpoint
key: createModeration
path: create
- type: object
key: CreateModerationResponse
path: object
- id: assistants
title: Assistants
beta: true
description: 'Build assistants that can call models and use tools to perform tasks.
[Get started with the Assistant
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openai/refs/heads/main/openapi/openai-moderations-api-openapi.yml