Create response | Respan Docs

Create a model response using the OpenAI Responses API through the Respan gateway. Supports text and image inputs, text outputs, and stateful interactions.

This endpoint works exclusively with OpenAI models and cannot be used with models from other providers.

How to pass Respan parameters

All Respan parameters are supported. Pass them via the X-Data-Respan-Params header (base64-encoded JSON), since the Responses API body schema does not support extra top-level fields.

1 from openai import OpenAI
2 from base64 import b64encode
3 import json
4 
5 client = OpenAI(
6     base_url="https://api.respan.ai/api/",
7     api_key="YOUR_RESPAN_API_KEY",
8 )
9 
10 respan_params = {
11     "customer_identifier": "user_123",
12     "metadata": {"feature": "responses-api"},
13     "thread_identifier": "thread_abc",
14 }
15 
16 respan_params_header = {
17     "X-Data-Respan-Params": b64encode(json.dumps(respan_params).encode()).decode(),
18 }
19 
20 response = client.responses.create(
21     model="gpt-4o-mini",
22     input="Tell me a joke about programming",
23     extra_headers=respan_params_header,
24 )
25 print(response.output_text)

TypeScript

1 import OpenAI from "openai";
2 
3 const client = new OpenAI({
4   baseURL: "https://api.respan.ai/api",
5   apiKey: "YOUR_RESPAN_API_KEY",
6 });
7 
8 const respanParams = {
9   customer_identifier: "user_123",
10   metadata: { feature: "responses-api" },
11 };
12 
13 const respanParamsHeader = {
14   "X-Data-Respan-Params": Buffer.from(JSON.stringify(respanParams)).toString("base64"),
15 };
16 
17 const response = await client.responses.create(
18   {
19     model: "gpt-4o-mini",
20     input: "Tell me a joke about programming",
21   },
22   { headers: respanParamsHeader }
23 );
24 console.log(response.output_text);

With prompt management

Load a managed prompt and pass runtime variables:

1 respan_params = {
2     "prompt": {
3         "prompt_id": "042f5f",
4         "schema_version": 2,
5         "variables": {"audience": "executive"},
6         "patch": {"temperature": 0.1},
7     },
8 }
9 
10 respan_params_header = {
11     "X-Data-Respan-Params": b64encode(json.dumps(respan_params).encode()).decode(),
12 }
13 
14 response = client.responses.create(
15     model="gpt-4o-mini",
16     input=[{"role": "user", "content": "Summarize this text"}],
17     extra_headers=respan_params_header,
18 )

Streaming

1 respan_params_header = {
2     "X-Data-Respan-Params": b64encode(json.dumps(respan_params).encode()).decode(),
3 }
4 
5 stream = client.responses.create(
6     model="gpt-4o-mini",
7     input="Tell me a joke about programming",
8     stream=True,
9     extra_headers=respan_params_header,
10 )
11 
12 for event in stream:
13     print(event)

Supported features

All standard OpenAI Responses API parameters are passed through to OpenAI. Additionally, Respan provides:

Observability: All requests are logged with full telemetry (latency, tokens, cost)
Customer tracking: Tag requests with customer_identifier and metadata
Prompt management: Load and render managed prompts via the prompt parameter
Thread grouping: Group related requests with thread_identifier

For the full list of Respan parameters, see Chat Completions Respan Parameters.

Create a model response using the OpenAI Responses API through the Respan gateway. Supports text and image inputs, text outputs, and stateful interactions. <Warning> This endpoint works exclusively with **OpenAI models** and cannot be used with models from other providers. </Warning> ## How to pass Respan parameters All [Respan parameters](/api-reference/develop/gateway/create-chat-completion#how-to-pass-respan-parameters) are supported. Pass them via the `X-Data-Respan-Params` header (base64-encoded JSON), since the Responses API body schema does not support extra top-level fields. ```python from openai import OpenAI from base64 import b64encode import json client = OpenAI( base_url="https://api.respan.ai/api/", api_key="YOUR_RESPAN_API_KEY", ) respan_params = { "customer_identifier": "user_123", "metadata": {"feature": "responses-api"}, "thread_identifier": "thread_abc", } respan_params_header = { "X-Data-Respan-Params": b64encode(json.dumps(respan_params).encode()).decode(), } response = client.responses.create( model="gpt-4o-mini", input="Tell me a joke about programming", extra_headers=respan_params_header, ) print(response.output_text) ``` ```typescript TypeScript import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.respan.ai/api", apiKey: "YOUR_RESPAN_API_KEY", }); const respanParams = { customer_identifier: "user_123", metadata: { feature: "responses-api" }, }; const respanParamsHeader = { "X-Data-Respan-Params": Buffer.from(JSON.stringify(respanParams)).toString("base64"), }; const response = await client.responses.create( { model: "gpt-4o-mini", input: "Tell me a joke about programming", }, { headers: respanParamsHeader } ); console.log(response.output_text); ``` ## With prompt management Load a managed prompt and pass runtime variables: ```python respan_params = { "prompt": { "prompt_id": "042f5f", "schema_version": 2, "variables": {"audience": "executive"}, "patch": {"temperature": 0.1}, }, } respan_params_header = { "X-Data-Respan-Params": b64encode(json.dumps(respan_params).encode()).decode(), } response = client.responses.create( model="gpt-4o-mini", input=[{"role": "user", "content": "Summarize this text"}], extra_headers=respan_params_header, ) ``` ## Streaming ```python respan_params_header = { "X-Data-Respan-Params": b64encode(json.dumps(respan_params).encode()).decode(), } stream = client.responses.create( model="gpt-4o-mini", input="Tell me a joke about programming", stream=True, extra_headers=respan_params_header, ) for event in stream: print(event) ``` ## Supported features All standard OpenAI Responses API parameters are passed through to OpenAI. Additionally, Respan provides: - **Observability**: All requests are logged with full telemetry (latency, tokens, cost) - **Customer tracking**: Tag requests with `customer_identifier` and `metadata` - **Prompt management**: Load and render managed prompts via the `prompt` parameter - **Thread grouping**: Group related requests with `thread_identifier` For the full list of Respan parameters, see [Chat Completions Respan Parameters](/api-reference/develop/gateway/create-chat-completion#respan-parameters).

Authentication

AuthorizationBearer

API key authentication. Get your API key from https://platform.respan.ai/platform/api-keys

Request

This endpoint expects an object.

modelstringRequired

The model to use for generating the response (e.g., gpt-4o, gpt-4o-mini). Must be an OpenAI model.

inputstring or list of objectsRequired

Text, image, or file inputs to the model. Can be a string or an array of input objects.

instructionsstringOptional

System instructions for the model.

streambooleanOptional

Whether to stream the response.

temperaturedoubleOptional

Sampling temperature (0-2).

max_output_tokensintegerOptional

Maximum number of output tokens.

top_pdoubleOptional

Nucleus sampling parameter.

toolslist of objectsOptional

Tools available to the model (web_search, file_search, function, etc.).

previous_response_idstringOptional

ID of a previous response for multi-turn conversations.

Response

Model response

Errors

400

Bad Request Error

401

Unauthorized Error

Create a model response using the OpenAI Responses API through the Respan gateway. Supports text and image inputs, text outputs, and stateful interactions.

This endpoint works exclusively with OpenAI models and cannot be used with models from other providers.

How to pass Respan parameters

All Respan parameters are supported. Pass them via the X-Data-Respan-Params header (base64-encoded JSON), since the Responses API body schema does not support extra top-level fields.

1 from openai import OpenAI
2 from base64 import b64encode
3 import json
4 
5 client = OpenAI(
6     base_url="https://api.respan.ai/api/",
7     api_key="YOUR_RESPAN_API_KEY",
8 )
9 
10 respan_params = {
11     "customer_identifier": "user_123",
12     "metadata": {"feature": "responses-api"},
13     "thread_identifier": "thread_abc",
14 }
15 
16 respan_params_header = {
17     "X-Data-Respan-Params": b64encode(json.dumps(respan_params).encode()).decode(),
18 }
19 
20 response = client.responses.create(
21     model="gpt-4o-mini",
22     input="Tell me a joke about programming",
23     extra_headers=respan_params_header,
24 )
25 print(response.output_text)

TypeScript

1 import OpenAI from "openai";
2 
3 const client = new OpenAI({
4   baseURL: "https://api.respan.ai/api",
5   apiKey: "YOUR_RESPAN_API_KEY",
6 });
7 
8 const respanParams = {
9   customer_identifier: "user_123",
10   metadata: { feature: "responses-api" },
11 };
12 
13 const respanParamsHeader = {
14   "X-Data-Respan-Params": Buffer.from(JSON.stringify(respanParams)).toString("base64"),
15 };
16 
17 const response = await client.responses.create(
18   {
19     model: "gpt-4o-mini",
20     input: "Tell me a joke about programming",
21   },
22   { headers: respanParamsHeader }
23 );
24 console.log(response.output_text);

With prompt management

Load a managed prompt and pass runtime variables:

1 respan_params = {
2     "prompt": {
3         "prompt_id": "042f5f",
4         "schema_version": 2,
5         "variables": {"audience": "executive"},
6         "patch": {"temperature": 0.1},
7     },
8 }
9 
10 respan_params_header = {
11     "X-Data-Respan-Params": b64encode(json.dumps(respan_params).encode()).decode(),
12 }
13 
14 response = client.responses.create(
15     model="gpt-4o-mini",
16     input=[{"role": "user", "content": "Summarize this text"}],
17     extra_headers=respan_params_header,
18 )

Streaming

1 respan_params_header = {
2     "X-Data-Respan-Params": b64encode(json.dumps(respan_params).encode()).decode(),
3 }
4 
5 stream = client.responses.create(
6     model="gpt-4o-mini",
7     input="Tell me a joke about programming",
8     stream=True,
9     extra_headers=respan_params_header,
10 )
11 
12 for event in stream:
13     print(event)

Supported features

All standard OpenAI Responses API parameters are passed through to OpenAI. Additionally, Respan provides:

Observability: All requests are logged with full telemetry (latency, tokens, cost)
Customer tracking: Tag requests with customer_identifier and metadata
Prompt management: Load and render managed prompts via the prompt parameter
Thread grouping: Group related requests with thread_identifier

For the full list of Respan parameters, see Chat Completions Respan Parameters.

1	import requests
2
3	url = "https://api.respan.ai/api/responses"
4
5	payload = {
6	"model": "string",
7	"input": "string"
8	}
9	headers = {
10	"Authorization": "Bearer <token>",
11	"Content-Type": "application/json"
12	}
13
14	response = requests.post(url, json=payload, headers=headers)
15
16	print(response.json())

1	from openai import OpenAI
2	from base64 import b64encode
3	import json
4
5	client = OpenAI(
6	base_url="https://api.respan.ai/api/",
7	api_key="YOUR_RESPAN_API_KEY",
8	)
9
10	respan_params = {
11	"customer_identifier": "user_123",
12	"metadata": {"feature": "responses-api"},
13	"thread_identifier": "thread_abc",
14	}
15
16	respan_params_header = {
17	"X-Data-Respan-Params": b64encode(json.dumps(respan_params).encode()).decode(),
18	}
19
20	response = client.responses.create(
21	model="gpt-4o-mini",
22	input="Tell me a joke about programming",
23	extra_headers=respan_params_header,
24	)
25	print(response.output_text)

1	import OpenAI from "openai";
2
3	const client = new OpenAI({
4	baseURL: "https://api.respan.ai/api",
5	apiKey: "YOUR_RESPAN_API_KEY",
6	});
7
8	const respanParams = {
9	customer_identifier: "user_123",
10	metadata: { feature: "responses-api" },
11	};
12
13	const respanParamsHeader = {
14	"X-Data-Respan-Params": Buffer.from(JSON.stringify(respanParams)).toString("base64"),
15	};
16
17	const response = await client.responses.create(
18	{
19	model: "gpt-4o-mini",
20	input: "Tell me a joke about programming",
21	},
22	{ headers: respanParamsHeader }
23	);
24	console.log(response.output_text);

1	respan_params = {
2	"prompt": {
3	"prompt_id": "042f5f",
4	"schema_version": 2,
5	"variables": {"audience": "executive"},
6	"patch": {"temperature": 0.1},
7	},
8	}
9
10	respan_params_header = {
11	"X-Data-Respan-Params": b64encode(json.dumps(respan_params).encode()).decode(),
12	}
13
14	response = client.responses.create(
15	model="gpt-4o-mini",
16	input=[{"role": "user", "content": "Summarize this text"}],
17	extra_headers=respan_params_header,
18	)

1	respan_params_header = {
2	"X-Data-Respan-Params": b64encode(json.dumps(respan_params).encode()).decode(),
3	}
4
5	stream = client.responses.create(
6	model="gpt-4o-mini",
7	input="Tell me a joke about programming",
8	stream=True,
9	extra_headers=respan_params_header,
10	)
11
12	for event in stream:
13	print(event)

1	{
2	"id": "resp_abc123",
3	"object": "response",
4	"created_at": 1709155200,
5	"model": "gpt-4o-mini",
6	"output": [
7	{
8	"type": "message",
9	"role": "assistant",
10	"content": [
11	{
12	"type": "output_text",
13	"text": "Why do programmers prefer dark mode? Because light attracts bugs!"
14	}
15	]
16	}
17	],
18	"usage": {
19	"input_tokens": 12,
20	"output_tokens": 18,
21	"total_tokens": 30
22	}
23	}

How to pass Respan parameters

With prompt management

Streaming

Supported features

Authentication

Headers

Request

Response

Errors

How to pass Respan parameters

With prompt management

Streaming

Supported features