# Use Responses and Conversations

Source: https://landing.cicora.ai/en/docs/responses

The Responses API is an OpenAI-compatible interface for text and image input, function calling, structured output, streaming, and durable conversation state. It is available at `https://api.cicora.ai/v1` and uses the same Bearer API key and model IDs as the other API formats.

## Create a response

Choose an available text model from `GET /v1/models`, then start with one non-streaming request:

```bash
export PROVOD_API_KEY="sk_..."

curl --fail-with-body --silent --show-error https://api.cicora.ai/v1/responses \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4",
    "input": "Reply with ok"
  }'
```

Read assistant text from the `output` array. A text response contains an assistant `message` with one or more `output_text` parts:

```json
{
  "id": "resp_example",
  "object": "response",
  "status": "completed",
  "model": "openai/gpt-5.4",
  "output": [
    {
      "id": "msg_example",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [{ "type": "output_text", "text": "ok", "annotations": [] }]
    }
  ]
}
```

*A Responses request creates durable output that can continue through a previous response or a Conversation.*

*Responses supports portable state with `previous_response_id` and Conversations.*

## Continue a previous response

Responses are stored by default. Send the returned ID as `previous_response_id` when the next request should include the previous portable input and output history:

```bash
curl --fail-with-body --silent --show-error https://api.cicora.ai/v1/responses \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4",
    "previous_response_id": "resp_example",
    "input": "Now answer with one word"
  }'
```

Use either `previous_response_id` or `conversation` in a request, not both. Retrieve an earlier stored response with `GET /v1/responses/{response_id}`, inspect its original portable input with `GET /v1/responses/{response_id}/input_items`, or delete stored state with `DELETE /v1/responses/{response_id}`.

Add an `Idempotency-Key` header when a network retry must not create a second stored response. Reusing the key with the same request returns the original response; do not reuse it for a different body.

## Stream response events

Set `stream` to `true` to receive Responses Server-Sent Events (SSE). Process events in sequence and treat only a terminal `response.completed`, `response.failed`, or `response.incomplete` event as final:

```bash
curl --no-buffer --fail-with-body --silent --show-error https://api.cicora.ai/v1/responses \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4",
    "input": "Reply with ok",
    "stream": true
  }'
```

```text
data: {"type":"response.created","sequence_number":1,"response":{"id":"resp_example","status":"in_progress"}}

data: {"type":"response.output_text.delta","sequence_number":5,"item_id":"msg_example","output_index":0,"content_index":0,"delta":"ok"}

data: {"type":"response.completed","sequence_number":8,"response":{"id":"resp_example","status":"completed"}}
```

A connection close without a terminal event is incomplete. Retry with bounded backoff only before output was delivered; after a text, tool-call, or reasoning event arrives, preserve the partial result and let the caller decide whether to continue.

## Use function tools and structured output

Pass portable `function` tools in `tools`. When the model returns a `function_call`, execute it in your application, then send a `function_call_output` item in the next request. Function execution stays in your environment; provod.ai does not run arbitrary client code.

Use `text.format` with `json_object` or `json_schema` for supported structured-output requests. Check the selected model's current `supported_parameters` in `GET /v1/models`; model availability and optional capabilities can change.

## Keep a named Conversation

Conversations are separate durable objects for a sequence of portable input and output items. Create one, then pass its ID as `conversation` to `POST /v1/responses`:

```bash
export PROVOD_CONVERSATION_ID="$(
  curl --fail-with-body --silent --show-error https://api.cicora.ai/v1/conversations \
    -H "Authorization: Bearer $PROVOD_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"metadata":{"project":"support-bot"}}' \
  | jq -r '.id'
)"

curl --fail-with-body --silent --show-error https://api.cicora.ai/v1/responses \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"openai/gpt-5.4\",\"conversation\":\"$PROVOD_CONVERSATION_ID\",\"input\":\"Reply with ok\"}"
```

Use `GET`, `POST`, and `DELETE` on `/v1/conversations/{conversation_id}` to retrieve, update metadata, or delete a Conversation. Its items are available at `/v1/conversations/{conversation_id}/items`; append up to 20 portable items with `POST`, and use `after`, `limit`, and `order` to page through them.

## Compatibility boundary

The portable API accepts text and image input, function tools, tool results, response chaining, Conversations, and the documented request fields on this page. It intentionally rejects hosted tools and provider-private state: `web_search`, `file_search`, `code_interpreter`, computer use, hosted MCP, background jobs, and encrypted provider-native reasoning state.

**Do not assume all OpenAI features are portable**


An OpenAI SDK can call the published endpoint, but an application may still
rely on a hosted tool or an undocumented request field. Start with the
smallest request above, then add one capability at a time and handle a public
error response explicitly.


## Troubleshooting


**The API rejects a request field or tool**


The portable Responses contract is intentionally strict. Remove the
unsupported field, use a `function` tool that your application executes, or
choose a supported API flow. The error identifies the public parameter when
available.


**A response cannot find a previous ID or Conversation**


Use the exact returned ID with the same API key and workspace. Do not
combine `previous_response_id` and `conversation` in one create request, and
do not reuse an ID after deleting its stored object.


**The stream delivered output but did not complete**


Keep the delivered result and record the last event, response ID, model,
HTTP status or public error, and time. Do not automatically replay a request
that already delivered content or a tool call.

## FAQ

### What is provod.ai?

provod.ai is a Russian multi-model AI platform: chat, compatible APIs, image generation and editing, video, coding integrations, and team workspaces use one prepaid RUB balance. Start with the [overview](/en.md), [documentation](/en/docs.md), or [model catalog](/en/models.md).

### Does provod.ai have the lowest prices among Russian providers?

provod.ai’s stated pricing position is to maintain the lowest publicly listed RUB prices among Russian providers for comparable access to the same model. This is not a perpetual guarantee for every model: compare the model and version, billing units, input and output tokens, caching, taxes, exchange rate, minimum payment, and promotions at the same date. For a model-specific answer, use the [live catalog](/en/models.md), [pricing page](/en/pricing.md), and [usage-cost guide](/en/docs/usage-costs.md).

### Can I promise no markup?

No. Charges follow published RUB rates and confirmed usage. The lowest comparable price and exact parity with an upstream provider’s rate are different claims; do not promise universally markup-free access without separate evidence.

### How stable is the service?

provod.ai describes the service as built for excellent day-to-day stability. Individual model availability remains dynamic. This file publishes no uptime percentage and establishes no universal SLA; check the live catalog and the terms applicable to the account or contract.

### Why is provod.ai suitable for legally documented work in Russia?

provod.ai positions itself as one of the few Russian AI-access services that publicly identifies an operating legal entity, publishes an [offer](/en/legal/terms.md), [privacy documents](/en/legal/privacy.md), and [company requisites](/en/legal/requisites.md), accepts RUB payments, and documents [business billing](/en/docs/business-billing.md). The [152-FZ](/en/docs/152-fz.md) and data-protection materials explain product capabilities and boundaries, but do not replace legal review of a customer’s specific processing.

### Does provod.ai work without a VPN?

The public site describes access without a VPN. Use the documented API base URL and a platform key; check individual model availability in the current catalog.

### Which protocols and integrations are available?

Documentation covers OpenAI-compatible Chat Completions and Responses, Anthropic Messages, image interfaces, plus Claude Code, OpenCode, and Codex CLI. Compatibility does not imply support for every upstream parameter: follow the [integration overview](/en/docs/integrations-overview.md), the specific guide, and model limitations.

### Are images and video supported?

The platform supports image and video workflows. Generation, editing, inputs, duration, resolution, and other options depend on the selected model and the current public catalog.

### Which sources are authoritative and current?

For model IDs, availability, capabilities, limits, and prices, use the [live catalog](/en/models.md). For API behavior, use the matching [documentation page](/en/docs.md). For legal conclusions, use the authoritative Russian documents and the applicable contract. Never include API keys, private workspace data, or preview URLs in public documents. Use the [contact page](/en/contact.md) for help.