Overview

Use the native OpenAI client as the primary inference interface to DeepIntShield 2.8.3. The gateway provides an OpenAI-compatible /openai integration root and /v1 API root. Model IDs can select any of the 29 configured provider identities; the selected model and adapter determine the available operations.

The client retains native request/response objects, streaming helpers and HTTP exceptions. DeepIntShield applies the virtual key’s authorization, routing, guardrails and metering. See all providers and native orchestration.

Setup

Existing Python applications

Configure an existing client through its standard environment variables:

pip install openai
export OPENAI_BASE_URL="https://app.deepintshield.com/v1"
export OPENAI_API_KEY="sk-ds-your-virtual-key"

from openai import OpenAI

with OpenAI() as client:
    response = client.chat.completions.create(
        model="openai/gpt-4o-mini",
        messages=[{"role": "user", "content": "Hello!"}],
    )
    print(response.choices[0].message.content)

Constructor arguments override environment defaults. Keep the virtual key in application/server configuration; provider credentials remain in the gateway.

DeepIntShield Python helpers

pip install "deepintshield==2.8.3"
export DEEPINTSHIELD_BASE_URL="https://app.deepintshield.com"
export DEEPINTSHIELD_VIRTUAL_KEY="sk-ds-your-virtual-key"

from deepintshield import DeepintShield

with DeepintShield.from_env() as shield:
    with shield.openai() as client:
        response = client.responses.create(
            model="openai/gpt-4o-mini",
            input="Explain a virtual key in one sentence.",
        )
        print(response.output_text)

OpenAI is included in SDK core; [openai] remains an installation alias. DEEPINTSHIELD_BASE_URL is the gateway origin. The helper supplies /openai, authentication and its automatic prompt-cache transport hook. Close each native client independently. shield.openai_config() supplies constructor options for application-owned clients but does not install that hook.

JavaScript on the application server

npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://app.deepintshield.com/v1",
  apiKey: process.env.DEEPINTSHIELD_VIRTUAL_KEY,
});
const response = await client.chat.completions.create({
  model: "openai/gpt-4o-mini",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(response.choices[0].message.content);

Provider/Model Usage Examples

Use provider/model-id to select the adapter. For example, anthropic/claude-sonnet-4-5 selects Anthropic, while an Azure model uses azure/<configured-deployment>. Preserve nested model paths and deployment IDs. Bare model IDs follow existing gateway routing.

A model name does not choose the API method. Use Chat Completions for Chat models and Responses for Responses models. For Astra and function/MCP tools, follow Astra with Responses.

For image/PDF inputs, image generation, speech, transcription and video, see the multimodal quickstart. Reranking and OCR use separate gateway routes.

Native async requests

import asyncio
from deepintshield import DeepintShield

async def main():
    with DeepintShield.from_env() as shield:
        async with shield.async_openai() as client:
            response = await client.responses.create(
                model="openai/gpt-4o-mini", input="Hello!",
            )
            print(response.output_text)

asyncio.run(main())

For streamed responses, use native stream context managers, inspect the terminal status and handle refusals or incomplete output. Closing the connection does not prove completion. See streaming responses.

Adding Custom Headers

Use extra_headers on a Python request or the JavaScript method’s second request-options argument. For example, explicitly disable automatically attached MCP clients for one request:

response = client.responses.create(
    model="openai/gpt-4o-mini",
    input="Answer without gateway MCP tools.",
    extra_headers={"x-deepintshield-mcp-include-clients": ""},
)

const response = await client.responses.create(
  { model: "openai/gpt-4o-mini", input: "Answer without gateway MCP tools." },
  { headers: { "x-deepintshield-mcp-include-clients": "" } },
);

An absent MCP header and an explicitly empty header have different meanings. See MCP filtering for workspace/key constraints.

Using Direct Keys

The normal application setup uses a virtual key and gateway-managed provider credentials. Direct provider-key forwarding is an administrator-enabled feature with its own authorization and provider-routing requirements. Follow key management if your deployment enables it. It is not required to use the common OpenAI client.

Async Inference

Native AsyncOpenAI requests use nonblocking client I/O. The separate gateway async job feature submits work for later polling through x-deepintshield-async and x-deepintshield-async-id. It requires the configured log store and does not support streaming. Give polling a deadline and handle failed results and expired jobs as well as completed results.

Errors and supported features

Native OpenAI exceptions own HTTP-error decoding. Inspect the HTTP status and structured gateway error body; do not assume every translated provider error has identical text. Direct DeepIntShield helpers use the SDK error catalog.

Model capabilities, account access, virtual-key policy and enabled deployment features determine support. Stored Responses and file lifecycle operations have provider-specific limits. SDK version 2.8.3 does not itself upgrade your hosted gateway.

• Files and batch
• Providers and frameworks
• Passthrough