API Reference
OpenAI Responses
Send a request through RunAPI's OpenAI-compatible Responses operation.
01
Overview
Use RunAPI's OpenAI-compatible Responses operation with a compatible model and the protocol's request and response shapes.
Quick start
- Create an API key and set it as RUNAPI_API_KEY.
- Choose a compatible model, then send the documented path parameters and JSON body.
- Read the JSON response or server-sent events shown for this operation, and handle protocol errors.
Endpoint
- Base URL
https://runapi.ai- Contract version
v1- Preferred authentication
Authorization: Bearer YOUR_API_TOKEN
02
Authentication carriers
RunAPI accepts each carrier listed below. Generated samples use the protocol's preferred header.
- header - Preferred
Authorization: Bearer YOUR_API_TOKEN- header
x-api-key: YOUR_API_TOKEN- header
x-goog-api-key: YOUR_API_TOKEN- query
?key=YOUR_API_TOKEN
03
Compatible models
Open a model page for current pricing, rate limits, and commercial-usage details.
Show 59 compatible models
- claude-fable-5-1
- claude-fable-5
- claude-sonnet-5
- claude-opus-5
- claude-opus-4-8
- claude-opus-4-7
- claude-opus-4-6
- claude-sonnet-4-6
- claude-opus-4-5-20251101
- claude-sonnet-4-5-20250929
- claude-haiku-4-5-20251001
- claude-opus-4-1-20250805
- gpt-5.5
- gpt-5.5-pro
- gpt-5.4
- gpt-5.4-mini
- gpt-5.4-nano
- gpt-5.4-pro
- gpt-5.3-codex
- gpt-5.3-codex-spark
- gpt-4o-mini
- gpt-5.6-luna
- gpt-5.6-sol
- gpt-5.6-terra
- gpt-6-astra
- gemini-3.6-flash
- gemini-3.5-flash
- gemini-3.1-pro-preview
- gemini-3-flash-preview
- gemini-2.5-pro
- gemini-2.5-flash
- deepseek-v4-flash-vision-exp
- deepseek-v4-pro
- deepseek-v4-flash
- glm-5.2
- glm-5.1
- glm-5-turbo
- glm-5
- glm-4.7
- glm-4.6
- glm-4.5
- glm-4.5-air
- kimi-k3
- kimi-k2.7-code
- kimi-k2.6
- kimi-k2.5
- MiniMax-M3
- MiniMax-M2.7
- MiniMax-M2.7-highspeed
- MiniMax-M2.5
- MiniMax-M2.5-highspeed
- MiniMax-M2.1
- MiniMax-M2
- mimo-v2.5-pro
- mimo-v2.5
- grok-4.20-0309-non-reasoning
- grok-4.6
- grok-4.5
- grok-4.3
04
JSON bodyRequest contract
Only fields with both public protocol and RunAPI support evidence are listed. Additional JSON body fields are passed through.
JSON body13 fields
input["string", "array"]
Optional
Text, message items, or tool results provided to the model.
instructions["string", "null"]
Optional
System or developer instructions for this response.
max_output_tokens["integer", "null"]
Optional
Maximum number of output tokens, including visible and reasoning tokens.
modelstring
Required
RunAPI model identifier returned by the compatible model catalog.
moderation["object", "null"]
Optional
Return independent moderation signals for the current input and complete output.
moderation.modelstring
Required
Allowed values:
omni-moderation-latest
moderation.policy["object", "null"]
Optional
moderation.policy.input["object", "null"]
Optional
moderation.policy.input.modestring
Required
Allowed values:
score, block
moderation.policy.output["object", "null"]
Optional
moderation.policy.output.modestring
Required
Allowed values:
score, block
stream["boolean", "null"]
Optional
Return typed Responses events as server-sent events.
Default:false
toolsarray
Optional
Tools the model may call.
Request example
JSON
{
"input": "Summarize one practical improvement for an API deployment.",
"model": "gpt-5.4",
"moderation": {
"model": "omni-moderation-latest",
"policy": {
"input": {
"mode": "score"
},
"output": {
"mode": "block"
}
}
}
}05
HTTP 200
Synchronous response
Schema
JSON
{
"additionalProperties": true,
"properties": {
"id": {
"type": "string"
},
"model": {
"type": "string"
},
"moderation": {
"additionalProperties": true,
"properties": {
"input": {
"oneOf": [
{
"additionalProperties": true,
"properties": {
"categories": {
"additionalProperties": true,
"type": "object"
},
"category_applied_input_types": {
"additionalProperties": true,
"type": "object"
},
"category_scores": {
"additionalProperties": true,
"type": "object"
},
"flagged": {
"type": "boolean"
},
"model": {
"const": "omni-moderation-latest",
"type": "string"
},
"type": {
"const": "moderation_result",
"type": "string"
}
},
"required": [
"type",
"model",
"flagged",
"categories",
"category_scores",
"category_applied_input_types"
],
"type": "object"
},
{
"additionalProperties": true,
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"type": {
"const": "error",
"type": "string"
}
},
"required": [
"type",
"code",
"message"
],
"type": "object"
}
]
},
"output": {
"oneOf": [
{
"additionalProperties": true,
"properties": {
"categories": {
"additionalProperties": true,
"type": "object"
},
"category_applied_input_types": {
"additionalProperties": true,
"type": "object"
},
"category_scores": {
"additionalProperties": true,
"type": "object"
},
"flagged": {
"type": "boolean"
},
"model": {
"const": "omni-moderation-latest",
"type": "string"
},
"type": {
"const": "moderation_result",
"type": "string"
}
},
"required": [
"type",
"model",
"flagged",
"categories",
"category_scores",
"category_applied_input_types"
],
"type": "object"
},
{
"additionalProperties": true,
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"type": {
"const": "error",
"type": "string"
}
},
"required": [
"type",
"code",
"message"
],
"type": "object"
}
]
}
},
"required": [
"input",
"output"
],
"type": "object"
},
"object": {
"const": "response",
"type": "string"
},
"output": {
"type": "array"
},
"status": {
"type": "string"
},
"usage": {
"additionalProperties": true,
"properties": {
"input_tokens": {
"type": "integer"
},
"output_tokens": {
"type": "integer"
},
"total_tokens": {
"type": "integer"
}
},
"required": [
"input_tokens",
"output_tokens",
"total_tokens"
],
"type": "object"
}
},
"required": [
"id",
"object",
"status",
"model",
"output"
],
"type": "object"
}Example
JSON
{
"id": "resp_example",
"model": "gpt-5.4",
"moderation": {
"input": {
"categories": {
"sexual": false,
"violence": true
},
"category_applied_input_types": {
"sexual": [
"text"
],
"violence": [
"text"
]
},
"category_scores": {
"sexual": 0.0002,
"violence": 0.96
},
"flagged": true,
"model": "omni-moderation-latest",
"type": "moderation_result"
},
"output": {
"categories": {
"sexual": false,
"violence": false
},
"category_applied_input_types": {
"sexual": [
"text"
],
"violence": [
"text"
]
},
"category_scores": {
"sexual": 0.0002,
"violence": 0.0001
},
"flagged": false,
"model": "omni-moderation-latest",
"type": "moderation_result"
}
},
"object": "response",
"output": [
{
"content": [
{
"annotations": [],
"text": "Hello! How can I help today?",
"type": "output_text"
}
],
"id": "msg_example",
"role": "assistant",
"status": "completed",
"type": "message"
}
],
"status": "completed",
"usage": {
"input_tokens": 12,
"output_tokens": 8,
"total_tokens": 20
}
}06
text/event-stream
SSE event: output_text_delta
Schema
JSON
{
"additionalProperties": true,
"properties": {
"content_index": {
"type": "integer"
},
"delta": {
"type": "string"
},
"item_id": {
"type": "string"
},
"output_index": {
"type": "integer"
},
"type": {
"const": "response.output_text.delta",
"type": "string"
}
},
"required": [
"type",
"item_id",
"output_index",
"content_index",
"delta"
],
"type": "object"
}Example
JSON
{
"content_index": 0,
"delta": "Hello",
"item_id": "msg_example",
"output_index": 0,
"type": "response.output_text.delta"
}07
text/event-stream
SSE event: completed
Schema
JSON
{
"additionalProperties": true,
"properties": {
"response": {
"additionalProperties": true,
"properties": {
"id": {
"type": "string"
},
"model": {
"type": "string"
},
"moderation": {
"additionalProperties": true,
"properties": {
"input": {
"oneOf": [
{
"additionalProperties": true,
"properties": {
"categories": {
"additionalProperties": true,
"type": "object"
},
"category_applied_input_types": {
"additionalProperties": true,
"type": "object"
},
"category_scores": {
"additionalProperties": true,
"type": "object"
},
"flagged": {
"type": "boolean"
},
"model": {
"const": "omni-moderation-latest",
"type": "string"
},
"type": {
"const": "moderation_result",
"type": "string"
}
},
"required": [
"type",
"model",
"flagged",
"categories",
"category_scores",
"category_applied_input_types"
],
"type": "object"
},
{
"additionalProperties": true,
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"type": {
"const": "error",
"type": "string"
}
},
"required": [
"type",
"code",
"message"
],
"type": "object"
}
]
},
"output": {
"oneOf": [
{
"additionalProperties": true,
"properties": {
"categories": {
"additionalProperties": true,
"type": "object"
},
"category_applied_input_types": {
"additionalProperties": true,
"type": "object"
},
"category_scores": {
"additionalProperties": true,
"type": "object"
},
"flagged": {
"type": "boolean"
},
"model": {
"const": "omni-moderation-latest",
"type": "string"
},
"type": {
"const": "moderation_result",
"type": "string"
}
},
"required": [
"type",
"model",
"flagged",
"categories",
"category_scores",
"category_applied_input_types"
],
"type": "object"
},
{
"additionalProperties": true,
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"type": {
"const": "error",
"type": "string"
}
},
"required": [
"type",
"code",
"message"
],
"type": "object"
}
]
}
},
"required": [
"input",
"output"
],
"type": "object"
},
"object": {
"const": "response",
"type": "string"
},
"output": {
"type": "array"
},
"status": {
"type": "string"
},
"usage": {
"additionalProperties": true,
"properties": {
"input_tokens": {
"type": "integer"
},
"output_tokens": {
"type": "integer"
},
"total_tokens": {
"type": "integer"
}
},
"required": [
"input_tokens",
"output_tokens",
"total_tokens"
],
"type": "object"
}
},
"required": [
"id",
"object",
"status",
"model",
"output",
"usage"
],
"type": "object"
},
"type": {
"const": "response.completed",
"type": "string"
}
},
"required": [
"type",
"response"
],
"type": "object"
}Example
JSON
{
"response": {
"id": "resp_example",
"model": "gpt-5.4",
"moderation": {
"input": {
"categories": {
"sexual": false,
"violence": true
},
"category_applied_input_types": {
"sexual": [
"text"
],
"violence": [
"text"
]
},
"category_scores": {
"sexual": 0.0002,
"violence": 0.96
},
"flagged": true,
"model": "omni-moderation-latest",
"type": "moderation_result"
},
"output": {
"categories": {
"sexual": false,
"violence": false
},
"category_applied_input_types": {
"sexual": [
"text"
],
"violence": [
"text"
]
},
"category_scores": {
"sexual": 0.0002,
"violence": 0.0001
},
"flagged": false,
"model": "omni-moderation-latest",
"type": "moderation_result"
}
},
"object": "response",
"output": [
{
"content": [
{
"annotations": [],
"text": "Hello! How can I help today?",
"type": "output_text"
}
],
"id": "msg_example",
"role": "assistant",
"status": "completed",
"type": "message"
}
],
"status": "completed",
"usage": {
"input_tokens": 12,
"output_tokens": 8,
"total_tokens": 20
}
},
"type": "response.completed"
}08
HTTP 400
Protocol error: invalid_request
Schema
JSON
{
"additionalProperties": true,
"properties": {
"error": {
"additionalProperties": true,
"properties": {
"code": {
"type": [
"string",
"null"
]
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"type": {
"type": "string"
}
},
"required": [
"message",
"type"
],
"type": "object"
}
},
"required": [
"error"
],
"type": "object"
}Example
JSON
{
"error": {
"code": null,
"message": "input must be a string or an array",
"param": "input",
"type": "invalid_request_error"
}
}09
Usage
Schema
JSON
{
"additionalProperties": true,
"properties": {
"input_tokens": {
"type": "integer"
},
"output_tokens": {
"type": "integer"
},
"total_tokens": {
"type": "integer"
}
},
"required": [
"input_tokens",
"output_tokens",
"total_tokens"
],
"type": "object"
}Example
JSON
{
"input_tokens": 12,
"output_tokens": 8,
"total_tokens": 20
}10
Generated Code Samples
Each cURL, JavaScript, and Python sample sends the validated request from this contract without requiring a protocol-specific SDK.
Install
Shell
pip install requests
PYTHON
import requests
response = requests.post(
"https://runapi.ai/v1/responses",
headers={"Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json"},
json={"model": "gpt-5.4", "input": "Summarize one practical improvement for an API deployment.", "moderation": {"model": "omni-moderation-latest", "policy": {"input": {"mode": "score"}, "output": {"mode": "block"}}}}
)
response.raise_for_status()
print(response.json())