# Model API (/docs/developers/model-api)





**Point your OpenAI client at Buda.** `POST /api/v1/responses` speaks the OpenAI [Responses API](https://platform.openai.com/docs/api-reference/responses) wire format — the same one OpenAI Codex CLI and other newer OpenAI-ecosystem tools use by default. Set your tool's base URL to Buda and your API key to a Buda `sk_` key, and it works without writing any Buda-specific integration code.

<Callout type="info">
  This is the raw model API — one call in, one model reply out, billed per call. If you want a hosted agent with its own Drive-based knowledge, session history, and multi-step runtime instead, see [API Claws](/en/docs/developers/api-claws).
</Callout>

## Base URL [#base-url]

```
https://buda.im/api/v1
```

Configure your client's base URL to the value above and its API key to a Buda `sk_` key — see [Authentication](/en/docs/developers/authentication) to create one.

## Supported models [#supported-models]

Buda gives you one endpoint in front of many model families — pick whichever fits the task, or let Buda pick for you.

| Model                 | Family                                     |
| --------------------- | ------------------------------------------ |
| `claude-haiku-4-5`    | Claude                                     |
| `claude-sonnet-5`     | Claude                                     |
| `claude-opus-5-5`\*   | Claude                                     |
| `claude-fable-5-1`\*  | Claude                                     |
| `gemini-3.1-pro`      | Gemini                                     |
| `gemini-3.1-flash`    | Gemini                                     |
| `gemini-3.7-flash`    | Gemini                                     |
| `gemini-3.8-flash`    | Gemini                                     |
| `gpt-6.1-sol`\*       | GPT                                        |
| `gpt-6-luna`          | GPT                                        |
| `deepseek-v4-flash`\* | DeepSeek                                   |
| `deepseek-v4-pro`\*   | DeepSeek                                   |
| `auto`                | Buda picks a current default model for you |

\* Gated to specific subscription plans; an ungated request for one of these falls back to a default model.

<Callout type="warn">
  Use Buda's model IDs above in the `model` field, not OpenAI's own model names (`gpt-4o`, etc.) — Buda doesn't proxy to OpenAI's model catalog, it routes to its own.
</Callout>

## Example: a single reply [#example-a-single-reply]

```bash
curl -X POST https://buda.im/api/v1/responses \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "input": "Say hello in exactly three words."
  }'
```

```json
{
  "id": "resp_...",
  "object": "response",
  "status": "completed",
  "model": "claude-sonnet-5",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Hello there, friend!" }]
    }
  ],
  "usage": { "input_tokens": 12, "output_tokens": 5, "total_tokens": 17 }
}
```

## Example: streaming [#example-streaming]

Set `"stream": true` to get the reply as it's generated, as standard OpenAI Responses API server-sent events (`response.created`, `response.output_text.delta`, `response.completed`, ...):

```bash
curl -N -X POST https://buda.im/api/v1/responses \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "input": "Say hello in exactly three words.",
    "stream": true
  }'
```

## Example: system instructions and multi-turn context [#example-system-instructions-and-multi-turn-context]

`instructions` sets the system prompt for the call; `input` also accepts a full message array instead of a single string when you need to pass prior turns yourself:

```bash
curl -X POST https://buda.im/api/v1/responses \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "instructions": "Reply in Simplified Chinese.",
    "input": [
      { "role": "user", "content": "What is Buda?" },
      { "role": "assistant", "content": "Buda is an AI agent platform." },
      { "role": "user", "content": "Summarize that in one sentence." }
    ]
  }'
```

<Callout type="info">
  Each call is stateless — Buda doesn't keep server-side conversation state between calls (no `previous_response_id`). If you need multi-turn history, send it back yourself as shown above.
</Callout>

## Using it with OpenAI Codex CLI [#using-it-with-openai-codex-cli]

Codex CLI now requires `wire_api = "responses"` for custom providers, which is exactly what this endpoint speaks. Add a provider to `~/.codex/config.toml`:

```toml
[model_providers.buda]
name = "buda"
base_url = "https://buda.im/api/v1"
wire_api = "responses"
env_key = "BUDA_API_KEY"
```

```bash
BUDA_API_KEY=sk_your_api_key codex --model claude-sonnet-5 -c model_provider=\"buda\"
```

## What's not supported yet [#whats-not-supported-yet]

This first version covers plain text in, text out. Not yet available: function/tool calling, image or file inputs, and the `GET /v1/models` listing endpoint. If your use case needs one of these, use the model IDs from the table above directly and check back — this surface is actively growing.

## Billing [#billing]

Every call is billed in AI credits against your own account, the same pool used by [API Claws](/en/docs/developers/api-claws) — not a shared quota. See [What are credits](/en/docs/billing/credits) for how the credit pools work, and top up if a call returns `429 insufficient_quota`.

## Related [#related]

<Cards>
  <Card title="Authentication" href="/en/docs/developers/authentication" description="Create the sk_ key these calls use." />

  <Card title="API Claws" href="/en/docs/developers/api-claws" description="A hosted agent instead of a raw model call." />

  <Card title="REST API" href="/en/docs/developers/rest-api" description="The rest of Buda's /api/v1 surface." />
</Cards>