OpenAI Responses API
Codex, SDK'ler ve diğer OpenAI uyumlu istemciler için durum bilgisi tutmayan model yanıtları oluşturun.
POST /openai/{region}/v1/responses ile bir model yanıtı oluşturun. ajan, aşağıda listelenen alanlar için OpenAI Responses istek ve yanıt şeklini uygular; böylece OpenAI SDK responses.create yöntemini ve diğer Responses uyumlu istemcileri bir ajan API anahtarıyla kullanabilirsiniz.
Bu endpoint'i, Responses input öğeleri gönderen ve Responses output öğelerini okuyan Codex ve diğer istemciler için kullanın. messages gönderen ve choices okuyan entegrasyonlar için OpenAI Chat Completions kullanın.
Başlamadan önce
- API key: API'yi kullanmak için bir personal API key oluşturun veya workspace admin'inizden Completion API kapsamına sahip bir workspace API anahtarı isteyin. Personal anahtarlar yalnızca Completion API kapsamını içerir.
Base URL
https://api.ajan.io/openai/{region}/v1/responsesDedicated deployments Tüm isteklerde
api.ajan.com'u/api/publicile değiştirin.
Parameters
input içinde bir string, message öğeleri veya tool sonuçları geçirin. ajan; instructions, max_output_tokens, temperature, top_p, reasoning, text, metadata, include, truncation, service_tier, tools, tool_choice ve parallel_tool_calls için desteklenen değerleri iletir. Endpoint, paralel function call'lar dahil native server-sent event streaming ve function tool'ları destekler. Hangi ayarların geçerli olduğu seçilen modele bağlıdır.
{region} path değeri eu, us veya global olmalı ve modelinizin kullanılabilir olduğu bölgeyle eşleşmelidir. Workspace'inizde kullanılabilir modelleri listelemek için aynı bölgeyle GET /openai/{region}/v1/models çağırın. Liste, workspace'iniz Bring your own key (BYOK) kullanıyorsa farklılık gösterebilir.
OpenAI API'den farklar
ajan, Responses API durumunu kalıcı olarak saklamaz. Her istekte tam konuşma durumunu gönderin.
storealanını atlayın veyafalseolarak ayarlayın.store=truereddedilir.previous_response_iddesteklenmez ve reddedilir. Önceki mesajları ve tool sonuçlarınıinputiçinde geçirin.- Background response'lar desteklenmez.
backgroundalanını atlayın veyafalseolarak ayarlayın. - Web search, file search, code interpreter, image generation, computer use ve MCP gibi hosted tool'lar desteklenmez.
- Paralel function call'lar dahil function tool'lar desteklenir.
OpenAI Python kütüphanesini kullanma
ajan'ı base URL olarak ayarlayın ve responses.create kullanın:
python
from openai import OpenAI
client = OpenAI(
base_url="https://api.ajan.io/openai/eu/v1",
api_key="<YOUR_AJAN_API_KEY>",
)
response = client.responses.create(
model="gpt-5-mini",
input="Write a short poem about cats.",
store=False,
)
print(response.output_text)Bir yanıtı stream edin
Native Responses API event'lerini almak için stream=True ayarlayın:
python
stream = client.responses.create(
model="gpt-5-mini",
input="Write a short poem about cats.",
store=False,
stream=True,
)
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="")Durum bilgisi tutmayan bir tool konuşmasını sürdürün
Döndürülen output öğelerini ve eşleşen function_call_output değerini sonraki isteğe ekleyin:
python
import json
conversation = [
{"role": "user", "content": "What is the weather in Berlin?"}
]
tools = [{
"type": "function",
"name": "lookup_weather",
"description": "Get the current weather for a city.",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
"additionalProperties": False,
},
}]
response = client.responses.create(
model="gpt-5-mini",
input=conversation,
tools=tools,
store=False,
)
conversation.extend(response.output)
tool_call = next(item for item in response.output if item.type == "function_call")
conversation.append({
"type": "function_call_output",
"call_id": tool_call.call_id,
"output": json.dumps({"temperature_c": 18, "condition": "sunny"}),
})
final_response = client.responses.create(
model="gpt-5-mini",
input=conversation,
tools=tools,
store=False,
)
print(final_response.output_text)Codex'i bağlama
Bir personal API key oluşturun, ardından Settings > Account > API keys sayfasında Connect your tools > Codex'i açın. Kullanılabilir bir OpenAI uyumlu model seçin ve işletim sisteminiz için oluşturulan kurulum adımlarını izleyin. Kurulum, Codex'i ajan'ın Responses endpoint'ine (wire_api = "responses") ve seçtiğiniz modele yönlendirir.
Rate limits
Varsayılan limitler 500 RPM (dakikada istek) ve 150.000 TPM (dakikada token)'dır.
- RPM, workspace, model ve API anahtarı başına uygulanır.
- TPM, bir workspace'te aynı modeli kullanan tüm API anahtarları arasında paylaşılır.
- Dedicated deployment'larda admin'ler Settings > Workspace > Products > API üzerinden model başına özel limitler yapılandırabilir.
Rate limit'e takılan bir istek 429 Too Many Requests döndürür. Başarılı ve rate limit'li yanıtlar x-ratelimit-limit-requests, x-ratelimit-limit-tokens, x-ratelimit-remaining-requests ve x-ratelimit-remaining-tokens içerir.
Personal API anahtarı kullanımı, sohbet ve agent kullanımıyla birlikte üyenin etkili personal bütçesine ve workspace harcama limitine sayılır. Workspace API anahtarı kullanımı workspace API harcama limitine sayılır. Bkz. Personal API keys ve Pricing.
Tarayıcı ve CORS entegrasyonları desteklenmez. API anahtarlarını sunucu tarafında tutun ve endpoint'i bir sunucu, CLI veya yerel geliştirme aracından çağırın. Bkz. API Key Best Practices.
OpenAPI
openapi: 3.0.0
info:
title: ajan API
version: 3.0.0
servers:
- url: https://api.ajan.io
description: Production
security:
- bearerAuth: []
paths:
/openai/{region}/v1/responses:
post:
tags:
- Responses
summary: Creates a stateless model response.
description: >-
Creates a stateless OpenAI-compatible response. Supports text
generation, streaming, and function tools. Do not send store=true,
previous_response_id, background=true, or hosted tools.
operationId: createResponse
parameters:
- name: region
in: path
required: true
description: The region of the API to use.
schema:
type: string
enum:
- eu
- us
- global
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- model
- input
properties:
model:
type: string
description: >-
The model ID. Use the models endpoint to list models
available in your workspace.
input:
description: The input text or full conversation state to process.
oneOf:
- type: string
- type: array
items: {}
- type: object
additionalProperties: true
instructions:
type: string
nullable: true
description: Instructions added to the model context.
max_output_tokens:
type: integer
minimum: 1
nullable: true
description: The maximum number of output tokens.
temperature:
type: number
nullable: true
description: Controls response randomness.
top_p:
type: number
nullable: true
description: Controls nucleus sampling.
stream:
type: boolean
nullable: true
default: false
description: Whether to return native Responses API server sent events.
tools:
type: array
description: Function tool definitions. Hosted tools are not supported.
items:
type: object
required:
- type
- name
properties:
type:
type: string
enum:
- function
name:
type: string
minLength: 1
description:
type: string
nullable: true
parameters:
type: object
nullable: true
additionalProperties: true
strict:
type: boolean
nullable: true
tool_choice:
description: Controls whether the model can call a function.
oneOf:
- type: string
enum:
- none
- auto
- required
- type: object
required:
- type
- name
properties:
type:
type: string
enum:
- function
name:
type: string
minLength: 1
parallel_tool_calls:
type: boolean
nullable: true
description: Whether the model can return multiple function calls.
reasoning:
type: object
description: OpenAI Responses reasoning configuration.
additionalProperties: true
text:
type: object
description: OpenAI Responses text output configuration.
additionalProperties: true
metadata:
type: object
nullable: true
description: String metadata attached to the request.
additionalProperties:
type: string
store:
type: boolean
nullable: true
enum:
- false
description: >-
Responses are not persisted. Omit this field or set it to
false.
background:
type: boolean
nullable: true
enum:
- false
description: Background responses are not supported.
include:
type: array
nullable: true
items:
type: string
description: Additional response fields to include.
truncation:
type: string
nullable: true
enum:
- auto
- disabled
service_tier:
type: string
nullable: true
description: The OpenAI service tier forwarded to the model provider.
example:
model: gpt-5-mini
input: Write a short poem about cats.
store: false
responses:
'200':
description: Successful response or event stream.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateResponseResponse'
example:
id: resp_09e99d1f7f163d10016a678387353481
object: response
created_at: 1785168775
status: completed
model: gpt-5-mini-2025-08-07
output:
- id: rs_09e99d1f7f163d10016a678387f47881
type: reasoning
content: []
summary: []
- id: msg_09e99d1f7f163d10016a67838935a881
type: message
status: completed
role: assistant
content:
- type: output_text
annotations: []
logprobs: []
text: |-
Whiskers sketch moonlight on the sill,
paws treading silence, soft and still.
Eyes like lanterns, sly and bright,
turning midnight into light.
A velvet sigh, a sudden purr—
the world made small, the heart made her.
usage:
input_tokens: 13
input_tokens_details:
cached_tokens: 0
output_tokens: 154
output_tokens_details:
reasoning_tokens: 64
total_tokens: 167
text/event-stream:
schema:
type: string
description: Native OpenAI Responses API server sent events.
'400':
description: Invalid fields, unsupported features, or an unavailable model.
'401':
description: Missing, invalid, or expired API key.
'403':
description: API key without the Completion API scope.
'413':
description: Request body exceeds 20 MB.
'429':
description: Usage or rate limit exceeded.
'500':
description: Internal server or upstream provider error.
default:
description: Error returned by the upstream model provider.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- message
- type
properties:
message:
type: string
type:
type: string
code:
type: string
nullable: true
param:
type: string
nullable: true
security:
- bearerAuth: []
components:
schemas:
CreateResponseResponse:
type: object
description: A response returned by the OpenAI-compatible Responses endpoint.
required:
- id
- object
- created_at
- status
- model
- output
properties:
id:
type: string
description: Unique identifier for the response.
example: resp_09e99d1f7f163d10016a678387353481
object:
type: string
enum:
- response
description: The object type, which is always `response`.
created_at:
type: integer
description: Unix timestamp in seconds when the response was created.
example: 1785168775
completed_at:
type: integer
nullable: true
description: Unix timestamp in seconds when the response completed.
example: 1785168778
background:
type: boolean
enum:
- false
description: ajan does not support background responses.
status:
type: string
enum:
- completed
- failed
- in_progress
- cancelled
- queued
- incomplete
description: Current response status.
example: completed
model:
type: string
description: Model used to generate the response.
example: gpt-5-mini-2025-08-07
output:
type: array
description: Output items generated by the model.
items:
oneOf:
- $ref: '#/components/schemas/ResponseReasoningItem'
- $ref: '#/components/schemas/ResponseOutputMessage'
- $ref: '#/components/schemas/ResponseFunctionToolCall'
output_text:
type: string
description: Aggregated text from all `output_text` items.
error:
type: object
nullable: true
description: Error information when the response failed.
properties:
code:
type: string
nullable: true
message:
type: string
incomplete_details:
type: object
nullable: true
description: Details explaining why the response is incomplete.
properties:
reason:
type: string
enum:
- max_output_tokens
- content_filter
instructions:
type: string
nullable: true
description: Instructions used for the response.
max_output_tokens:
type: integer
nullable: true
description: Maximum number of output tokens configured for the response.
parallel_tool_calls:
type: boolean
description: Whether the model can return multiple function calls.
reasoning:
type: object
nullable: true
description: Reasoning configuration used for the response.
additionalProperties: true
store:
type: boolean
enum:
- false
description: ajan Responses are never persisted.
temperature:
type: number
nullable: true
description: Sampling temperature used for the response.
text:
type: object
nullable: true
description: Text output configuration used for the response.
additionalProperties: true
service_tier:
type: string
nullable: true
description: Service tier used to process the response.
tool_choice:
description: Tool choice used for the response.
oneOf:
- type: string
- type: object
additionalProperties: true
tools:
type: array
description: Function tools available to the model.
items:
type: object
additionalProperties: true
top_p:
type: number
nullable: true
description: Nucleus sampling value used for the response.
truncation:
type: string
enum:
- auto
- disabled
description: Truncation strategy used for the response.
usage:
$ref: '#/components/schemas/ResponseUsage'
metadata:
type: object
nullable: true
description: Metadata attached to the request.
additionalProperties:
type: string
additionalProperties: true
ResponseReasoningItem:
type: object
description: Reasoning information generated by a reasoning model.
required:
- id
- type
- summary
properties:
id:
type: string
example: rs_123
type:
type: string
enum:
- reasoning
summary:
type: array
items:
type: object
additionalProperties: true
content:
type: array
items:
type: object
additionalProperties: true
encrypted_content:
type: string
nullable: true
description: Encrypted reasoning content when requested.
status:
type: string
nullable: true
enum:
- in_progress
- completed
- incomplete
additionalProperties: true
ResponseOutputMessage:
type: object
description: A message generated by the model.
required:
- id
- type
- status
- role
- content
properties:
id:
type: string
example: msg_09e99d1f7f163d10016a67838935a881
type:
type: string
enum:
- message
status:
type: string
enum:
- in_progress
- completed
- incomplete
role:
type: string
enum:
- assistant
content:
type: array
items:
oneOf:
- $ref: '#/components/schemas/ResponseOutputText'
- $ref: '#/components/schemas/ResponseOutputRefusal'
additionalProperties: true
ResponseFunctionToolCall:
type: object
description: A function call requested by the model.
required:
- id
- type
- call_id
- name
- arguments
properties:
id:
type: string
example: fc_123
type:
type: string
enum:
- function_call
status:
type: string
enum:
- in_progress
- completed
- incomplete
call_id:
type: string
example: call_123
name:
type: string
example: lookup_weather
arguments:
type: string
description: JSON-encoded arguments for the function.
example: '{"city":"Berlin"}'
additionalProperties: true
ResponseUsage:
type: object
description: Token usage for the response.
required:
- input_tokens
- output_tokens
- total_tokens
properties:
input_tokens:
type: integer
example: 13
input_tokens_details:
type: object
properties:
cached_tokens:
type: integer
example: 0
additionalProperties: true
output_tokens:
type: integer
example: 154
output_tokens_details:
type: object
properties:
reasoning_tokens:
type: integer
example: 64
additionalProperties: true
total_tokens:
type: integer
example: 167
additionalProperties: true
ResponseOutputText:
type: object
description: Text generated by the model.
required:
- type
- text
- annotations
properties:
type:
type: string
enum:
- output_text
text:
type: string
example: |-
Whiskers sketch moonlight on the sill,
paws treading silence, soft and still.
annotations:
type: array
items:
type: object
additionalProperties: true
logprobs:
type: array
items:
type: object
additionalProperties: true
additionalProperties: true
ResponseOutputRefusal:
type: object
description: A refusal returned by the model.
required:
- type
- refusal
properties:
type:
type: string
enum:
- refusal
refusal:
type: string
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: API key as Bearer token. Format "Bearer YOUR_API_KEY"