Pular para o conteúdo
Referência de API
Referência de API

OpenAI Responses

Enviar uma requisição pela operação Responses compatível com OpenAI do RunAPI.

Ver Markdown
01

Visão geral

Use a operação Responses compatível com OpenAI do RunAPI com um modelo compatível e os formatos de requisição e resposta do protocolo.

Início rápido

  1. Crie uma Chave de API e defina-a como RUNAPI_API_KEY.
  2. Escolha um modelo compatível, depois envie os parâmetros de caminho e o corpo JSON documentados.
  3. Leia a resposta JSON ou os eventos enviados pelo servidor exibidos para esta operação e trate os erros de protocolo.

Endpoint

POST /v1/responses
URL base
https://runapi.ai
Versão do contrato
v1
Autenticação preferida
Authorization: Bearer YOUR_API_TOKEN
02

Portadores de autenticação

O RunAPI aceita cada carrier listado abaixo. Os exemplos gerados usam o cabeçalho preferido do protocolo.

header - Preferido
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

Modelos compatíveis

Abra uma página de modelo para ver preços atuais, limites de taxa e detalhes de uso comercial.

Mostrar 58 modelos compatíveis
04

Contrato de solicitação

Corpo JSON

Apenas os campos com evidências de suporte tanto no protocolo público quanto no RunAPI são listados. Campos adicionais no corpo JSON são repassados diretamente.

Corpo JSON13 campos
input["string", "array"]
Opcional

Texto, itens de mensagem ou resultados de ferramentas fornecidos ao modelo.

instructions["string", "null"]
Opcional

Instruções de sistema ou de desenvolvedor para esta resposta.

max_output_tokens["integer", "null"]
Opcional

Número máximo de tokens de saída, incluindo tokens visíveis e de raciocínio.

modelstring
Obrigatório

Identificador de modelo do RunAPI retornado pelo catálogo de modelos compatível.

moderation["object", "null"]
Opcional

Retornar sinais de moderação independentes para a entrada atual e a saída completa.

moderation.modelstring
Obrigatório Valores permitidos: omni-moderation-latest
moderation.policy["object", "null"]
Opcional
moderation.policy.input["object", "null"]
Opcional
moderation.policy.input.modestring
Obrigatório Valores permitidos: score, block
moderation.policy.output["object", "null"]
Opcional
moderation.policy.output.modestring
Obrigatório Valores permitidos: score, block
stream["boolean", "null"]
Opcional

Retornar eventos de Responses tipados como server-sent events.

Padrão: false
toolsarray
Opcional

Ferramentas que o modelo pode chamar.

Exemplo de solicitação

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

Resposta síncrona

HTTP 200

Esquema

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

Exemplo

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

Evento SSE: output_text_delta

text/event-stream

Esquema

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

Exemplo

JSON 
{
  "content_index": 0,
  "delta": "Hello",
  "item_id": "msg_example",
  "output_index": 0,
  "type": "response.output_text.delta"
}
07

Evento SSE: completed

text/event-stream

Esquema

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

Exemplo

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

Erro de protocolo: invalid_request

HTTP 400

Esquema

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

Exemplo

JSON 
{
  "error": {
    "code": null,
    "message": "input must be a string or an array",
    "param": "input",
    "type": "invalid_request_error"
  }
}
09

Uso

Esquema

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

Exemplo

JSON 
{
  "input_tokens": 12,
  "output_tokens": 8,
  "total_tokens": 20
}
10

Exemplos de Código Gerados

Cada exemplo em cURL, JavaScript e Python envia a requisição validada deste contrato sem exigir um SDK específico do protocolo.

Instalar

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())