Create | Phonic

Generates one or more alternative assistant responses for a conversation you supply inline to simulate Phonic agent behavior.

This endpoint is stateless, so it does not create a new conversation or store anything. The request carries the system prompt, a conversation so far as input, and the tools the assistant may call as tool_definitions.

Each item in input is a user message, an assistant message (with optional tool_calls), or a tool_call_output. Every assistant tool call must be followed immediately by the tool_call_output item that carries its result.

This is an experimental feature and must be enabled for your workspace; otherwise, it returns 404. Please contact our team if you would like access.

Generates one or more alternative assistant responses for a conversation you supply inline to simulate Phonic agent behavior. This endpoint is stateless, so it does not create a new conversation or store anything. The request carries the system prompt, a conversation so far as `input`, and the tools the assistant may call as `tool_definitions`. Each item in `input` is a user message, an assistant message (with optional `tool_calls`), or a `tool_call_output`. Every assistant tool call must be followed immediately by the `tool_call_output` item that carries its result. This is an experimental feature and must be enabled for your workspace; otherwise, it returns `404`. Please contact our team if you would like access.

Authentication

AuthorizationBearer

Bearer authentication header of the form Bearer <PHONIC_API_KEY>. Manage your API keys here.

Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).

Request

This endpoint expects an object.

system_promptstringRequired>=1 character

The system prompt the assistant should follow.

inputlist of objectsRequired

The conversation so far, in order. Must contain at least one item.

voice_idstringOptionalDefaults to sabrina

ID of the voice the assistant would speak with. It shapes how the responses are worded.

default_languageenumOptional

ISO 639-1 language code that sets the assistant’s default language to recognize and speak.

additional_languageslist of enumsOptionalDefaults to []

Array of additional ISO 639-1 language codes that the assistant should be able to recognize and speak. Should not include default_language.

tool_definitionslist of objectsOptionalDefaults to []

The tools the assistant may call, defined inline. Names must be unique and cannot be one of the names Phonic reserves for its built-in tools.

num_responsesintegerOptional1-200Defaults to 1

Number of alternative responses to generate.

Response

Success response

responseslist of objects

The generated responses - always num_responses of them.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error

502

Bad Gateway Error

503

Service Unavailable Error

Generates one or more alternative assistant responses for a conversation you supply inline to simulate Phonic agent behavior.

This is an experimental feature and must be enabled for your workspace; otherwise, it returns 404. Please contact our team if you would like access.

1	from phonic import Phonic, ResponsesUserMessage, ResponsesToolDefinition, ToolParametersJsonSchema
2
3	client = Phonic(
4	api_key="YOUR_TOKEN_HERE",
5	)
6
7	client.responses.create(
8	system_prompt="You help callers find a pizza shop. Be friendly and concise.",
9	voice_id="sabrina",
10	default_language="en",
11	additional_languages=[
12	"es"
13	],
14	input=[
15	ResponsesUserMessage(
16	role="user",
17	text="Where should I get pizza near Union Square?",
18	)
19	],
20	tool_definitions=[
21	ResponsesToolDefinition(
22	name="search_pizza_shop_recs",
23	description="Search for pizza shop recommendations.",
24	parameters=ToolParametersJsonSchema(
25	type="object",
26	properties={
27	"location": {"type": "string", "description": "The neighborhood to search in."}
28	},
29	required=[
30	"location"
31	],
32	additional_properties=False,
33	),
34	)
35	],
36	num_responses=2,
37	)

1	{
2	"responses": [
3	{
4	"text": "Joe's Pizza is a couple of blocks away - want the address?",
5	"tool_calls": []
6	},
7	{
8	"text": "",
9	"tool_calls": [
10	{
11	"tool_call_id": "call_9f2c4b1a",
12	"tool": {
13	"name": "search_pizza_shop_recs"
14	},
15	"request_body": {
16	"location": "Union Square"
17	}
18	}
19	]
20	}
21	]
22	}