Responses (بتا)

POST /v1/responses نسخهٔ سازگار با Responses API OpenAI است: با client.responses.create(...) در SDK‌های رسمی کار می‌کند. این اندپوینت در وضعیت بتاست. نسخهٔ SDK خود را پین کنید. ورودی صدا در این اندپوینت پشتیبانی نمی‌شود و باید از چت استفاده کنید.

POST/v1/responsesاحراز هویت Bearer

[BETA] Create a response (OpenAI Responses API compatible)

⚠ Beta. This endpoint is in public beta. The request/response shape may change without notice. Pin your SDK version and add a contract test before shipping production traffic.

Generate a model response in the OpenAI Responses API shape. Drop-in compatible with openai-python (>= 1.50) and openai-node (>= 4.50) via client.responses.create(...).

Two modes:

Non-streaming (default): returns the full Response object as JSON.
Streaming ("stream": true): returns Server-Sent Events. Named events: response.created, response.output_item.added, response.content_part.added, response.content_part.delta (text chunk delta), response.output_item.done, and the terminal frame response.done or response.completed carrying the final usage block. Stream terminates with data: [DONE].

Function tools (type: "function") are supported and forwarded verbatim. Built-in tools (web_search, file_search, code_interpreter, computer_use, mcp, image_generation) return 400 UNSUPPORTED_TOOL in beta.

Images: pass {"type":"input_image","image_url":"https://..."} inside an input message item. The image_url may be a fully qualified URL or a data: URI. Iran-hosted images are auto-proxied through the gateway so foreign-IP upstreams can read them.

Multi-turn: previous_response_id works only on models whose apis list in GET /v1/models includes responses, and only with the id of an earlier response from your own account on such a model. Otherwise the request is refused before anything is charged: 400 MULTI_TURN_NOT_SUPPORTED (model keeps no state) or 400 PREVIOUS_RESPONSE_NOT_FOUND (not one of your stored responses). conversation is not supported (400 CONVERSATION_NOT_SUPPORTED). Resend the earlier turns in input, or use POST /v1/chat/completions.

Billing: a hold is placed based on estimated tokens, then settled inline from usage on the response. No client action needed. Same hold/settle pipeline as /v1/chat/completions.

پارامترها

فیلد	in	نوع	توضیح
`Idempotency-Key`	header	string	Optional deduplication token (any string up to 200 characters). How it works: Same key + same request body → cached response replayed (safe retry) Same key + different body → `409 CONFLICT` error Keys expire after 24 hours When to use: Add this header when you want to safely retry a request after a network timeout without risking a duplicate operation.

بدنه درخواستالزامی

فیلد	نوع	توضیح
`model`الزامی	string	نمونه: `openai/gpt-4o`
`input`الزامی	string \| array of object	Plain string OR array of input items.
`instructions`	string
`max_output_tokens`	integer
`temperature`	number
`top_p`	number
`stream`	boolean	پیش‌فرض: `false`
`store`	boolean	Forwarded upstream; no server-side persistence on Hormouz.
`previous_response_id`	string
`tools`	array of object	Same tool flavours as `/v1/chat/completions`: user-defined function tools (`type:"function"`) plus the built-in server tools (`web_search`, `web_search_preview`, `web_fetch`, `datetime`, `image_generation`). Tools whose pricing is not yet wired into the gateway hold estimator are still rejected at admission with `400 UNSUPPORTED_TOOL` (`file_search`, `code_interpreter`, `computer_use`, `computer_use_preview`, `mcp`).
`tool_choice`	string \| object
`metadata`	object
`parallel_tool_calls`	boolean
`reasoning`	object
`text`	object

نمونه

curlPythonJavaScriptGo

curl https://api.hormouz.net/v1/responses \
  -H "Authorization: Bearer ng-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "input": "Write a haiku about the sea."
  }'

from openai import OpenAI

client = OpenAI(api_key="ng-YOUR_API_KEY", base_url="https://api.hormouz.net/v1")

resp = client.responses.create(
    model="openai/gpt-4o",
    input="Write a haiku about the sea.",
)
print(resp.output_text)

import OpenAI from "openai";

const client = new OpenAI({ apiKey: "ng-YOUR_API_KEY", baseURL: "https://api.hormouz.net/v1" });

const resp = await client.responses.create({
  model: "openai/gpt-4o",
  input: "Write a haiku about the sea.",
});
console.log(resp.output_text);

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"model": "openai/gpt-4o",
		"input": "Write a haiku about the sea.",
	})
	req, _ := http.NewRequest("POST", "https://api.hormouz.net/v1/responses", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer ng-YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	raw, _ := io.ReadAll(resp.Body)
	fmt.Println(string(raw))
}

پاسخ‌ها

200هدرها: X-Hormouz-Admission-Latency-Ms, X-Hormouz-Upstream-Latency-Ms, X-Hormouz-Proxy-Latency-Ms

Success. JSON object, or SSE stream when stream:true.

400

Bad request. Codes:

BAD_REQUEST: malformed JSON or missing required fields.
INVALID_TOOLS: :online model suffix, plugins:[{id:"web"}], or an internal <internal>:* tool-type prefix in the request body.
UNSUPPORTED_TOOL: built-in tool whose pricing is not yet wired (file_search, code_interpreter, computer_use, mcp).

401

Authentication failed. Either the Authorization header is missing, the key format is invalid, or the key doesn't match any active account.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "status": 401
  }
}

402

Insufficient credits.

409

Idempotency key conflict: you sent the same Idempotency-Key with a different request body.

413

Request body too large after image inlining (> 25 MiB).

429

Too many requests. Back off and retry after a short delay. Check the Retry-After header for guidance.

499

Your HTTP client cancelled the request before the gateway finished. No charge: the hold has been released. The most common cause is a 30 s default client timeout against a model whose p95 latency is 45-60 s; bump your client timeout to 120 s.

Retries with the same Idempotency-Key will replay this 499 forever (the prior outcome is "you cancelled"). For an actual re-attempt, mint a fresh Idempotency-Key. See docs/CUSTOMER_ERROR_HANDLING.md §3 for the full contract.

{
  "error": {
    "code": "CLIENT_CLOSED",
    "message": "Client disconnected before response",
    "status": 499
  }
}

500

Unexpected server error. Please retry with exponential backoff. If the issue persists, contact your admin.

502

Bad Gateway. Upstream returned a 5xx after all retries were exhausted, OR upstream sent an unexpected redirect on the streaming path (Hormouz synthesises a 502 rather than forward an HTML/Location body as SSE).

503

Service Unavailable. The proxy could not reach the upstream provider (network failure, classifier unavailable). Retry with a fresh Idempotency-Key.

504

The gateway's 120 s upstream deadline elapsed before the upstream provider produced a response. Retry with the same Idempotency-Key so a delayed-but-eventually-successful upstream call can be replayed instead of re-charged. Consider switching to a faster model or capping max_tokens if this recurs.

{
  "error": {
    "code": "UPSTREAM_TIMEOUT",
    "message": "Upstream did not respond before timeout",
    "status": 504
  }
}