Modern API Interface

Responses API

DEVUP AI provides an OpenAI-compatible Responses API endpoint for any text model in the catalog. This endpoint exposes a structured request/response interface with Responses output payloads, built-in reasoning configuration, and transparent billing in Algerian Dinar (DZD).

POST

https://api.devupai.com/v1/responses

Authentication & Billing

The Responses API uses standard Bearer token authentication with your existing DEVUP AI API key. It connects directly to our canonical billing engine, applying exact balance reservation and settlement in Algerian Dinar (DZD) without separate subscription tiers or secondary ledgers.

Authorization: Bearer <YOUR_API_KEY>

Quick Start

You can interact with /v1/responses using official OpenAI SDKs or standard HTTP clients by setting the base URL to https://api.devupai.com/v1.

import os
from openai import OpenAI

# Initialize the client with the DEVUP AI base URL
client = OpenAI(
    api_key=os.environ.get("DEVUP_API_KEY"),
    base_url="https://api.devupai.com/v1",
)

# Call the Responses endpoint with any text model from the catalog
response = client.responses.create(
    model="openai/gpt-5.3-codex",
    input="Explain how quantum entanglement enables quantum key distribution.",
    max_output_tokens=1024,
)

# Output items follow the Responses format
for item in response.output:
    if item.type == "message":
        for content in item.content:
            if content.type == "output_text":
                print(content.text)

# Token usage metrics
print(f"Input: {response.usage.input_tokens}, Output: {response.usage.output_tokens}")

Note: Examples use openai/gpt-5.3-codex. Any text model in the catalog works the same way: pass its model id, for example deepseek-ai/DeepSeek-V4-Pro.

Streaming

Set stream: true to receive the response as Server-Sent Events, with any text model in the catalog. A client reads response.created first, then response.output_text.delta events carrying the text, response.output_item.done as each output item finishes, and response.completed with the final response and its usage; on failure, the stream ends with response.failed followed by an error event.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("DEVUP_API_KEY"),
    base_url="https://api.devupai.com/v1",
)

stream = client.responses.create(
    model="deepseek-ai/DeepSeek-V4-Pro",
    input="Write a haiku about the Sahara desert.",
    max_output_tokens=1024,
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        usage = event.response.usage
        print(f"\nInput: {usage.input_tokens}, Output: {usage.output_tokens}")

Request Parameters

DEVUP AI accepts Responses parameters and validates them before processing the request.

Parameter	Type	Requirement	Description
model	string	Required	Model id of any text model in the catalog.
input	string \| array	Optional	The text prompt or array of input content items to process. For multi-turn conversations, send the full conversation in `input` on every turn. When the last message in the conversation is from the assistant, the model answers with a new assistant message.
instructions	string	Optional	System-level instructions directing the model's behavior.
max_output_tokens	integer	Optional	The most output tokens the reply may have: a whole number from 1 to the model's `max_output_tokens` in `GET /v1/models`. A larger value, or one that is not a whole number, returns HTTP 400 `invalid_max_tokens`. When omitted, the reply is limited to the model's default output length, which is at most its `max_output_tokens`.
reasoning	object	Optional	Nested reasoning object. Supports `effort` (accepted values vary by model; see Reasoning Configuration below).
temperature	number	Optional	Sampling temperature. Higher values make the output more random.
top_p	number	Optional	Nucleus sampling threshold.
user	string	Optional	End-user identifier for abuse monitoring and logging.
metadata	object	Optional	Developer metadata key-value pairs attached to the request.
tools	array	Optional	Tools the model may call. Supported tool types: `function` and `namespace`. See Tool Calls below.
tool_choice	string \| object	Optional	`auto`, `none`, `required`, or `{ "type": "function", "name": "..." }` to require one function.
parallel_tool_calls	boolean	Optional	Whether the model may call several tools in one turn.
store	boolean	Forced False	`store` is always treated as `false`, so responses are not saved for later retrieval. Any value you send is overridden.
stream	boolean	Optional	Set to `true` to receive the response as Server-Sent Events. See Streaming above.

Reasoning Configuration

In the Responses API, reasoning parameters must be nested under the reasoning object. Top-level parameters such as Chat's reasoning_effort are explicitly rejected with an HTTP 400 error. Accepted effort levels depend on the model:

Model	Accepted Values
openai/gpt-5.3-codex	none, low, medium, high, xhigh
openai/gpt-5.5-pro	medium, high (none and low not accepted)
openai/gpt-5.4-pro	medium, high (none and low not accepted)

json

{
  "model": "openai/gpt-5.3-codex",
  "input": "Prove whether P equals NP or explain why the problem remains unresolved.",
  "reasoning": {
    "effort": "high"
  },
  "max_output_tokens": 2048
}

Tool Calls

Supported tool types: function and namespace.

A namespace tool groups related functions under one name. Its name uses letters, digits, _ and - (up to 64 characters), and its tools array holds at least one function tool whose name follows the same rule.

json

{
  "model": "deepseek-ai/DeepSeek-V4-Pro",
  "input": "Find the customer whose email is amina@example.com.",
  "tools": [
    {
      "type": "namespace",
      "name": "crm",
      "description": "Customer records.",
      "tools": [
        {
          "type": "function",
          "name": "lookup_customer",
          "description": "Find a customer by email.",
          "parameters": {
            "type": "object",
            "properties": { "email": { "type": "string" } },
            "required": ["email"]
          }
        }
      ]
    }
  ]
}

When the model calls a function declared inside a namespace, the function_call item carries the function's own name and a separate namespace field. On the next turn, send that item back unchanged in input, followed by a function_call_output with the same call_id.

json

{
  "id": "fc_01j8k9m0n1p2q3r4s5t6u7v8wb",
  "type": "function_call",
  "status": "completed",
  "call_id": "call_01j8k9m0n1p2q3r4s5t6u7v8wc",
  "name": "lookup_customer",
  "namespace": "crm",
  "arguments": "{\"email\":\"amina@example.com\"}"
}

The input of the next turn:

json

[
  { "role": "user", "content": "Find the customer whose email is amina@example.com." },
  {
    "type": "function_call",
    "call_id": "call_01j8k9m0n1p2q3r4s5t6u7v8wc",
    "name": "lookup_customer",
    "namespace": "crm",
    "arguments": "{\"email\":\"amina@example.com\"}"
  },
  {
    "type": "function_call_output",
    "call_id": "call_01j8k9m0n1p2q3r4s5t6u7v8wc",
    "output": "{\"id\":\"cus_42\",\"name\":\"Amina\"}"
  }
]

Responses Output

A non-streaming request returns a Responses object whose output[] array holds the generated items (messages, function calls and reasoning), with billing details attached under _devup. A call to a function declared in a namespace tool also carries a namespace field (see Tool Calls). A model's reasoning arrives in its own reasoning item, separate from the message text.

json

{
  "id": "resp_01j8k9m0n1p2q3r4s5t6u7v8w9",
  "object": "response",
  "created_at": 1700000000,
  "model": "openai/gpt-5.3-codex",
  "status": "completed",
  "output": [
    {
      "id": "msg_01j8k9m0n1p2q3r4s5t6u7v8wa",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Quantum key distribution (QKD) leverages the fundamental quantum principle...",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 24,
    "output_tokens": 182,
    "total_tokens": 206,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens_details": {
      "reasoning_tokens": 0
    }
  },
  "_devup": {
    "request_id": "req_9fd8ddec5b2149539860a86dccba58cf"
  }
}

Usage Metrics & Token Accounting

The usage object reports detailed token metrics normalized by DEVUP AI:

input_tokens

Total prompt tokens counted for the input request.

output_tokens

Total tokens generated by the model (including reasoning tokens).

input_tokens_details.cached_tokens

Prompt tokens served from cache with discounted billing rates.

output_tokens_details.reasoning_tokens

Internal reasoning tokens generated prior to final answer output.

Model Compatibility

Any text model in the catalog works with this endpoint: pass its model id as model.

If the model is not served on this endpoint, for example an image, speech, video or embedding model, the request fails with an HTTP 400 wrong_endpoint error that names the endpoint serving it, before any charge is made. Find model ids in the Model Catalog.

Error Reference

The Responses API adheres to the standard DEVUP AI error envelope. For the complete reference of error codes, visit the API Error Reference.

Status	Error Code	Description & Resolution
400	missing_model	The `model` parameter is missing or empty. Provide a valid model string.
400	unsupported_parameter	A parameter in the request is not accepted. The error message names it; remove it and retry. Set reasoning effort with `reasoning.effort`.
400	unsupported_parameter	A tool type in the request is not accepted, or a `namespace` tool is invalid. The error message names the problem; fix it and retry.
400	wrong_endpoint	The model is not served on `/v1/responses`. The message names the endpoint that serves it; send the request there, or choose a text model. Not billed.
400	unsupported_destination	The model does not support the Responses API or its input token counting. Use `/v1/chat/completions` or another model.
400	invalid_max_tokens	`max_output_tokens` is not a whole number from 1 to the model's `max_output_tokens` in `GET /v1/models`. The message names the parameter and the model's limit. Send a value in that range, or leave it out.
400	invalid_request_error	The model rejected the request, and no more specific code applies. Check the input and parameters against this page.
401	missing_api_key / invalid_api_key	Provide a valid active API key in the `Authorization: Bearer` header.
402	insufficient_balance	Your DZD balance does not cover this request. Top up via the dashboard, or send a smaller max_output_tokens.
404	model_not_found	The requested model identifier was not found in the DEVUP AI catalog.
429	rate_limit_exceeded	Your account's rate limit (600 req/min) reached. Wait for `Retry-After`, then retry.
429	model_at_capacity	The model is momentarily at capacity. Retry after `Retry-After` (5 seconds); the OpenAI SDK retries it automatically.
500	model_configuration_error	The request has no output limit, and this model needs one. The request is not billed. Send `max_tokens` (`max_output_tokens` on `POST /v1/responses`), or contact support with the request ID.
503	model_unavailable	The model is temporarily unavailable. Honor `Retry-After` and/or `retry-after-ms` when present before retrying.

Related Guides

Chat Completions

OpenAI-compatible chat completion endpoint.

OpenAI Compatibility

Parameter mapping and model rules.

Model Catalog

Browse all supported foundation models.

Error Reference

Status codes and troubleshooting.