How to Connect Coze to an OpenAI Responses API Provider

If you are building an agent in Coze and want to bring your own model endpoint, the hard part is rarely the model itself. It is usually the wiring: which protocol should the provider use, where should the base URL stop, how should the model ID be entered, and how do you test that normal replies and tool calls are both going through the same route?

This guide walks through a small, practical setup for connecting Coze's custom model form to an OpenAI Responses API-compatible provider using Ace Data Cloud as the endpoint. The goal is not to sell you on another dashboard. It is to give you a repeatable checklist you can use when a Coze bot works in a simple text test but breaks once you enable streaming or tools.

What you can do

Coze's custom model flow lets you add a provider using the OpenAI Responses API protocol. For this specific setup, the documented fields are intentionally minimal:

{
  "protocol": "OpenAI Responses API",
  "base_api_url": "https://api.acedata.cloud/v1",
  "api_key": "YOUR_ACE_DATA_CLOUD_API_TOKEN",
  "model": "EXACT_RESPONSES_API_MODEL_ID"
}

A few details matter more than they first appear:

• The Base API URL is https://api.acedata.cloud/v1.
• The API Key field should contain your Ace Data Cloud API Token.
• The Model field should be the exact model ID from the model directory that supports the Responses API.
• In Coze, do not append /responses to the base URL unless the current UI explicitly asks for a complete API URL.

That last point is the most common source of confusing failures. Some tools ask for a root URL and append the endpoint path themselves. If you paste a full path into a field that expects only a base, the final request can become double-appended and fail in a way that looks like an authentication or model problem.

How it works

Think of the configuration as three separate contracts:

1. Protocol contract: Coze must know it is speaking the OpenAI Responses API, not Chat Completions and not Anthropic Messages.
2. Endpoint contract: Coze needs the base URL only: https://api.acedata.cloud/v1.
3. Model contract: the model string must match a Responses-compatible model ID in the provider catalog.

These contracts are independent. A model that works through a Chat Completions route should not be assumed to work through the Responses route. Likewise, a successful regular text reply does not automatically prove that streaming output or tool invocation is valid for your tenant, region, or package.

Step 1: Add the custom model in Coze

In Coze model management, create a new custom model and select OpenAI Responses API as the protocol. Then fill the form with the values from the JSON above.

Use this checklist while entering the fields:

Protocol:     OpenAI Responses API
Base API URL: https://api.acedata.cloud/v1
API Key:      your Ace Data Cloud API Token
Model:        exact Responses API model ID

The base URL is deliberately short. If you are tempted to paste https://api.acedata.cloud/v1/responses, pause and check the label in the Coze form. The documented setup says to use the base and avoid appending /responses again. Only follow a full-URL variant if your current Coze UI explicitly requests that shape.

Step 2: Run the smallest possible reply test

After saving, complete Coze's connection test. Then put the model into a Bot or Agent and send a deliberately boring prompt:

Reply only OK

This is a useful first test because it removes prompt ambiguity. You are not checking reasoning quality, system instructions, or agent behavior yet. You are checking whether Coze can authenticate, route to the Responses provider, select the configured model, and return a plain text answer.

If this fails, debug in this order:

1. Confirm the protocol is OpenAI Responses API.
2. Confirm the base URL is exactly https://api.acedata.cloud/v1.
3. Confirm the API key is the Ace Data Cloud API Token.
4. Confirm the model ID is exact and Responses-compatible.

Do not switch protocols while debugging the same issue. Chat Completions, Responses, and Anthropic Messages are separate routes and should be validated separately.

Step 3: Test tool invocation separately

Once Reply only OK works, test tool invocation in the same Bot or Agent. This second test is important because different Coze regions, versions, or packages may handle path concatenation, streaming output, and tool invocation differently.

A practical pattern is to keep a tiny test bot whose only job is provider validation. First run the text-only check. Then enable the simplest tool your bot supports and ask for an action that clearly requires that tool. If text succeeds but the tool path fails, you have narrowed the issue to the tool-calling contract rather than authentication or the base URL.

Step 4: Keep route validation isolated

It is tempting to say, "The provider worked once, so all routes are fine." In practice, that assumption creates painful bugs later. Treat each route as its own integration:

• OpenAI Chat Completions
• OpenAI Responses
• Anthropic Messages

For this article, we only validated the OpenAI Responses route. If you later add another custom model entry for a different protocol, repeat the same base URL, key, model, text, and tool checks for that route instead of copying confidence from this one.

A small builder habit that saves time

When an agent integration fails, write down the exact tuple you tested:

{
  "coze_protocol": "OpenAI Responses API",
  "base_api_url": "https://api.acedata.cloud/v1",
  "model": "<exact model id>",
  "first_prompt": "Reply only OK",
  "next_check": "tool invocation"
}

That tiny record makes it much easier to compare behavior across Coze tenants, regions, or plans. It also keeps the team from accidentally debugging a Chat Completions configuration while the failing bot is actually using the Responses route.

If you want the original checklist, the source documentation is here: Coze OpenAI Responses Custom Model.