Responses API

​

Endpoint Information

• URL: /v1/responses
• Method: POST
• Authentication: Required (x-api-key header or Authorization: Bearer <key>)
• Rate Limiting: Subject to tier-based rate limits
• API reference: Create a response (OpenAI-compatible, non-streaming)

​

Quick Start

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SWARMS_API_KEY"],
    base_url="https://api.swarms.world/v1",
)

resp = client.responses.create(
    model="gpt-5.4-mini",
    instructions="Answer with one word.",
    input="What is the capital of Italy?",
    max_output_tokens=20,
)
print(resp.output_text)                       # Rome
print(resp.status, resp.usage.total_tokens)   # completed 26

curl -X POST https://api.swarms.world/v1/responses \
  -H "x-api-key: $SWARMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "instructions": "Answer with one word.",
    "input": "What is the capital of Italy?",
    "max_output_tokens": 20
  }'

{
  "id": "resp_9248029bf8ed48bda5a2b82563fdfbeb",
  "object": "response",
  "created_at": 1793722935,
  "model": "gpt-5.4-mini",
  "status": "completed",
  "incomplete_details": null,
  "error": null,
  "output": [
    {
      "type": "message",
      "id": "msg_2e7f70db8a114f14abbd52ae9262dc12",
      "role": "assistant",
      "status": "completed",
      "content": [{"type": "output_text", "text": "Rome", "annotations": []}]
    }
  ],
  "usage": {
    "input_tokens": 22,
    "output_tokens": 4,
    "total_tokens": 26,
    "input_tokens_details": {"cached_tokens": 0},
    "output_tokens_details": {"reasoning_tokens": 0}
  }
}

​

Request Fields

​

Message Items

{"role": "user", "content": "What is the capital of Italy?"}

• role is user, assistant, system or developer. system and developer messages become part of the system prompt.
• content is a string, or a list of input_text / output_text parts, e.g. [{"type": "input_text", "text": "..."}]. The parts’ text is joined with spaces.
• An item’s type, if set, must be message.

​

Not Supported Yet

• stream: true
• tools
• previous_response_id
• Any other field not listed above, when set to a non-empty value
• Image or file content parts, and item types other than message (e.g. function call items)
• input with no user message

​

Response Fields

​

Errors

{
  "error": {
    "message": "Not supported yet: stream",
    "type": "invalid_request_error",
    "code": null,
    "param": null
  }
}

​

Billing

​

Related

• OpenAI-Compatible Endpoint — POST /v1/chat/completions, with streaming and tool calling
• Anthropic-Compatible Messages API — POST /v1/messages for the Anthropic SDK
• OpenAI-Compatible Examples