# Table of Contents

- [Introduction - Sudo Developer Platform](#introduction-sudo-developer-platform)
- [Headers & Auth - Sudo Developer Platform](#headers-auth-sudo-developer-platform)
- [Overview - Sudo Developer Platform](#overview-sudo-developer-platform)
- [Streaming - Sudo Developer Platform](#streaming-sudo-developer-platform)
- [Rate Limits & Overload Handling - Sudo Developer Platform](#rate-limits-overload-handling-sudo-developer-platform)
- [Responses API - Sudo Developer Platform](#responses-api-sudo-developer-platform)
- [Quickstart - Sudo Developer Platform](#quickstart-sudo-developer-platform)
- [OpenAI SDK Compatability - Sudo Developer Platform](#openai-sdk-compatability-sudo-developer-platform)
- [Supported AI Models - Sudo Developer Platform](#supported-ai-models-sudo-developer-platform)
- [Introduction - Sudo Developer Platform](#introduction-sudo-developer-platform)
- [Audio Chat Completions - Sudo Developer Platform](#audio-chat-completions-sudo-developer-platform)
- [Get a Chat Completion - Sudo Developer Platform](#get-a-chat-completion-sudo-developer-platform)
- [Generate Image - Sudo Developer Platform](#generate-image-sudo-developer-platform)
- [System Health - Sudo Developer Platform](#system-health-sudo-developer-platform)
- [Image Generation - Sudo Developer Platform](#image-generation-sudo-developer-platform)
- [CRUD Operations - Sudo Developer Platform](#crud-operations-sudo-developer-platform)
- [Reasoning - Sudo Developer Platform](#reasoning-sudo-developer-platform)
- [System Endpoints - Sudo Developer Platform](#system-endpoints-sudo-developer-platform)
- [Chat Completion Messages - Sudo Developer Platform](#chat-completion-messages-sudo-developer-platform)
- [Update Chat Completion - Sudo Developer Platform](#update-chat-completion-sudo-developer-platform)
- [Create Chat Completion - Sudo Developer Platform](#create-chat-completion-sudo-developer-platform)
- [Image Input - Sudo Developer Platform](#image-input-sudo-developer-platform)
- [Delete Chat Completion - Sudo Developer Platform](#delete-chat-completion-sudo-developer-platform)
- [Get supported models list (for devs to use) - Sudo Developer Platform](#get-supported-models-list-for-devs-to-use-sudo-developer-platform)
- [Tool Calling - Sudo Developer Platform](#tool-calling-sudo-developer-platform)
- [Installation & Setup - Sudo Developer Platform](#installation-setup-sudo-developer-platform)
- [Create Response - Sudo Developer Platform](#create-response-sudo-developer-platform)
- [Structured Output - Sudo Developer Platform](#structured-output-sudo-developer-platform)
- [List Chat Completions - Sudo Developer Platform](#list-chat-completions-sudo-developer-platform)
- [Streaming - Sudo Developer Platform](#streaming-sudo-developer-platform)
- [AI Router - Sudo Developer Platform](#ai-router-sudo-developer-platform)
- [Page Not Found](#page-not-found)
- [Page Not Found](#page-not-found)
- [Page Not Found](#page-not-found)

---

# Introduction - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/overview/introduction#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

Overview

Introduction

On this page

*   [Sudo: One API for All Models](https://docs.sudoapp.dev/overview/introduction#sudo:-one-api-for-all-models)
    
*   [What is Sudo?](https://docs.sudoapp.dev/overview/introduction#what-is-sudo)
    
*   [Sudo Developer Platform](https://docs.sudoapp.dev/overview/introduction#sudo-developer-platform)
    
*   [What’s Next: Context & Monetization](https://docs.sudoapp.dev/overview/introduction#what%E2%80%99s-next:-context-&-monetization)
    
*   [Getting Started](https://docs.sudoapp.dev/overview/introduction#getting-started)
    

[​](https://docs.sudoapp.dev/overview/introduction#sudo:-one-api-for-all-models)

Sudo: One API for All Models
================================================================================================================

[​](https://docs.sudoapp.dev/overview/introduction#what-is-sudo)

What is Sudo?
---------------------------------------------------------------------------------

Sudo is a unified API for large language models. We make it simple for developers to route across different LLMs while getting better performance, lower cost, and higher uptime than going direct.

### 

[​](https://docs.sudoapp.dev/overview/introduction#sudo-developer-platform)

Sudo Developer Platform

With Sudo, developers can build AI apps without worrying about vendor lock-in or juggling multiple integrations. **One API gives you seamless access to models from OpenAI, Anthropic, Google, and more** — while our router optimizes every call for speed and price. Sudo’s mission is to be the most reliable and cost-efficient LLM router, so you can focus on building great products instead of managing infrastructure.

### 

[​](https://docs.sudoapp.dev/overview/introduction#what%E2%80%99s-next:-context-&-monetization)

What’s Next: Context & Monetization

We’re extending Sudo beyond routing into context engineering and monetization features. With one single API endpoint, developers will be able to:

*   **Feed context into apps seamlessly** — attach documents, links, or instructions once, and Sudo will automatically **manage and optimize context** across every model call, without manually rewriting system prompts.
*   **Monetize end users directly** — unlock revenue streams through built-in **contextual ad placement and usage-based billing**, so you can focus on growing your product while Sudo handles payments and optimization.

By combining **routing, context, and monetization** in one place, Sudo moves closer to being the all-in-one developer platform for building and scaling AI apps.

[​](https://docs.sudoapp.dev/overview/introduction#getting-started)

Getting Started
--------------------------------------------------------------------------------------

Get onboarded to the Sudo Developer Platform by using our quickstart guide.[Quick Start Guide\
-----------------\
\
Get up and running in minutes](https://docs.sudoapp.dev/overview/quickstart-api)

[Quickstart](https://docs.sudoapp.dev/overview/quickstart-api)

⌘I

---

# Headers & Auth - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/api-ref/auth#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

API Reference

Headers & Auth

On this page

*   [Using an API key](https://docs.sudoapp.dev/api-ref/auth#using-an-api-key)
    
*   [Rotating or revoking keys](https://docs.sudoapp.dev/api-ref/auth#rotating-or-revoking-keys)
    
*   [Minimum headers](https://docs.sudoapp.dev/api-ref/auth#minimum-headers)
    

Sudo uses **Bearer token** authentication. Every request must include your secret API key in the `Authorization` header:

Copy

    Authorization: Bearer <SUDO_API_KEY>
    

You can create and manage keys within apps from the **Developer Portal → My AI Apps** section.

Treat your keys like passwords. Do **not** commit them to version-control or expose them in front-end code.

* * *

[​](https://docs.sudoapp.dev/api-ref/auth#using-an-api-key)

Using an API key
-------------------------------------------------------------------------------

JavaScript / TypeScript

Python

curl

Copy

    fetch('https://sudoapp.dev/api/v1/chat/completions', {
      method: 'POST',
      headers: {
        Authorization: 'Bearer <SUDO_API_KEY>',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'gpt-4o',
        messages: [{ role: 'user', content: 'Hello!' }],
      }),
    });
    

* * *

### 

[​](https://docs.sudoapp.dev/api-ref/auth#rotating-or-revoking-keys)

Rotating or revoking keys

If a key is ever exposed you can disable or delete it from the portal and generate a new one immediately. Requests bearing a revoked key will receive a `401` error.

* * *

### 

[​](https://docs.sudoapp.dev/api-ref/auth#minimum-headers)

Minimum headers

Only two headers are required:

| Header | Example | Notes |
| --- | --- | --- |
| `Authorization` | `Bearer sk-abc123` | Required |
| `Content-Type` | `application/json` | Required |

[Overview](https://docs.sudoapp.dev/api-ref/overview)
[Streaming](https://docs.sudoapp.dev/api-ref/streaming)

⌘I

---

# Overview - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/api-ref/overview#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

API Reference

Overview

On this page

*   [Requests](https://docs.sudoapp.dev/api-ref/overview#requests)
    
*   [Headers](https://docs.sudoapp.dev/api-ref/overview#headers)
    
*   [Example](https://docs.sudoapp.dev/api-ref/overview#example)
    
*   [Responses](https://docs.sudoapp.dev/api-ref/overview#responses)
    
*   [Finish reasons](https://docs.sudoapp.dev/api-ref/overview#finish-reasons)
    
*   [Error handling](https://docs.sudoapp.dev/api-ref/overview#error-handling)
    
*   [Next steps](https://docs.sudoapp.dev/api-ref/overview#next-steps)
    

Sudo’s REST API closely mirrors the [OpenAI Chat Completions](https://platform.openai.com/docs/api-reference/chat)
 specification.  
If you already integrate with OpenAI you can usually **swap the base URL, provide a Sudo API key, and you’re done**. **Base URL**: `https://sudoapp.dev/api`  
**Completions endpoint**: `/v1/chat/completions`

Some third-party model providers do **not** support every OpenAI feature (for example _tools_ or _vision_). Refer to their individual documentation when in doubt.

* * *

[​](https://docs.sudoapp.dev/api-ref/overview#requests)

Requests
-------------------------------------------------------------------

The request body you `POST` to `/v1/chat/completions` accepts the same fields you’re used to. Below is an **example** condensed TypeScript definition (non-exhaustive):

Request Schema

Copy

    export type ChatCompletionRequest = {
      /* Pick **one** */
      messages: Message[];
    
      /** Full model identifier – e.g. `gpt-4o` or `claude-4-sonnet` */
      model: string;
    
      /** Format enforcement – OpenAI-style */
      response_format?: { type: 'json_object' };
    
      /* Common generation params */
      max_completion_tokens?: number;
      parallel_tool_calls?: boolean;
      tools?: Tool[];
      temperature?: number;
      top_p?: number;
      stop_sequences?: string[];
      stream?: boolean;
    };
    
    export type Message = {
      role: 'system' | 'user' | 'assistant' | 'tool';
      content: string | ContentPart[];
      name?: string;
      /** Only for tool role */
      tool_call_id?: string;
    };
    
    export type ContentPart =
      | { type: 'text'; text: string }
      | { type: 'image_url'; image_url: { url: string; detail?: string } };
    

For a more exhaustive spec of supported request parameters, see the endpoints in the next section.

### 

[​](https://docs.sudoapp.dev/api-ref/overview#headers)

Headers

Only two headers are required:

| Header | Value |
| --- | --- |
| `Authorization` | `Bearer <SUDO_API_KEY>` |
| `Content-Type` | `application/json` |

### 

[​](https://docs.sudoapp.dev/api-ref/overview#example)

Example

curl

Copy

    curl https://sudoapp.dev/api/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $SUDO_API_KEY" \
      -d '{
      "model": "gpt-4o",
      "messages": [{"role":"user","content":"Hello!"}]
    }'
    

* * *

[​](https://docs.sudoapp.dev/api-ref/overview#responses)

Responses
---------------------------------------------------------------------

Sudo **normalises** provider responses to match the OpenAI schema. A non-streaming response looks like this:

Example Response

Copy

    {
      "id": "chatcmpl-abc123",
      "object": "chat.completion",
      "created": 1710000000,
      "model": "gpt-4o",
      "choices": [\
        {\
          "index": 0,\
          "message": { "role": "assistant", "content": "Hello there!" },\
          "finish_reason": "stop",\
          "native_finish_reason": "stop"\
        }\
      ],
      "usage": {
        "prompt_tokens": 5,
        "completion_tokens": 4,
        "total_tokens": 9
      }
    }
    

### 

[​](https://docs.sudoapp.dev/api-ref/overview#finish-reasons)

Finish reasons

`finish_reason` is one of `stop`, `length`, `tool_calls`, `content_filter`, or `error` – mirroring OpenAI’s values.

### 

[​](https://docs.sudoapp.dev/api-ref/overview#error-handling)

Error handling

Errors follow the shape:

Error

Copy

    {
      "error": {
        "message": "Invalid API key",
        "type": "api_error"
      }
    }
    

* * *

[​](https://docs.sudoapp.dev/api-ref/overview#next-steps)

Next steps
-----------------------------------------------------------------------

[Headers & Auth\
--------------\
\
Read about authenticating requests](https://docs.sudoapp.dev/api-ref/auth)
[Streaming\
---------\
\
See **Streaming** to deliver tokens to your UI in real-time.](https://docs.sudoapp.dev/api-ref/streaming)

[CRUD Operations](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations)
[Headers & Auth](https://docs.sudoapp.dev/api-ref/auth)

⌘I

---

# Streaming - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/api-ref/streaming#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

API Reference

Streaming

On this page

*   [Example – Python](https://docs.sudoapp.dev/api-ref/streaming#example-%E2%80%93-python)
    
*   [Example – TypeScript / browser fetch](https://docs.sudoapp.dev/api-ref/streaming#example-%E2%80%93-typescript-/-browser-fetch)
    
*   [About the SSE payload](https://docs.sudoapp.dev/api-ref/streaming#about-the-sse-payload)
    
*   [Cancelling streams](https://docs.sudoapp.dev/api-ref/streaming#cancelling-streams)
    

All Sudo models support **server-sent event (SSE) streaming**.  
Add `"stream": true` to your request body and consume the event-stream as it arrives.

* * *

[​](https://docs.sudoapp.dev/api-ref/streaming#example-%E2%80%93-python)

Example – Python
--------------------------------------------------------------------------------------------

Python

Copy

    import requests, json
    
    url = "https://sudoapp.dev/api/v1/chat/completions"
    headers = {
        "Authorization": "Bearer <SUDO_API_KEY>",
        "Content-Type": "application/json",
    }
    
    payload = {
        "model": "gpt-4o",
        "messages": [{"role": "user", "content": "Tell me a joke"}],
        "stream": True,
    }
    
    buffer = ""
    with requests.post(url, headers=headers, json=payload, stream=True) as r:
        for chunk in r.iter_content(chunk_size=1024, decode_unicode=True):
            buffer += chunk
            while "\n" in buffer:
                line, buffer = buffer.split("\n", 1)
                line = line.strip()
                if not line.startswith("data: "):
                    # Comments (begin with :) can be ignored per the SSE spec
                    continue
                data = line[6:]
                if data == "[DONE]":
                    break
                message = json.loads(data)
                content_delta = message["choices"][0]["delta"].get("content")
                if content_delta:
                    print(content_delta, end="", flush=True)
    

* * *

[​](https://docs.sudoapp.dev/api-ref/streaming#example-%E2%80%93-typescript-/-browser-fetch)

Example – TypeScript / browser fetch
------------------------------------------------------------------------------------------------------------------------------------

TypeScript

Copy

    const response = await fetch('https://sudoapp.dev/api/v1/chat/completions', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${SUDO_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'gpt-4o',
        messages: [{ role: 'user', content: 'Tell me a joke' }],
        stream: true,
      }),
    });
    
    const reader = response.body?.getReader();
    if (!reader) throw new Error('Streaming unsupported');
    
    const decoder = new TextDecoder();
    let buffer = '';
    
    while (true) {
      const { value, done } = await reader.read();
      if (done) break;
      buffer += decoder.decode(value, { stream: true });
    
      while (true) {
        const nl = buffer.indexOf('\n');
        if (nl === -1) break;
        const line = buffer.slice(0, nl).trim();
        buffer = buffer.slice(nl + 1);
        if (!line.startsWith('data: ')) continue; // Ignore comments
        const data = line.slice(6);
        if (data === '[DONE]') break;
        const parsed = JSON.parse(data);
        const delta = parsed.choices[0].delta.content;
        if (delta) {
          console.log(delta);
        }
      }
    }
    

* * *

### 

[​](https://docs.sudoapp.dev/api-ref/streaming#about-the-sse-payload)

About the SSE payload

1.  Each line that begins with `data:` contains a JSON chunk.
2.  Lines beginning with `:` are **comments** and can be safely ignored.
3.  A final line `data: [DONE]` signals the end of the stream.

* * *

### 

[​](https://docs.sudoapp.dev/api-ref/streaming#cancelling-streams)

Cancelling streams

Simply abort or close the underlying HTTP connection (e.g. via `AbortController` in the browser). The request will stop; however, you may be billed for the tokens of the full stream.

[Headers & Auth](https://docs.sudoapp.dev/api-ref/auth)
[Responses API](https://docs.sudoapp.dev/api-ref/responses_api)

⌘I

---

# Rate Limits & Overload Handling - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/api-ref/rate_limits#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

API Reference

Rate Limits & Overload Handling

On this page

*   [Rate Limits](https://docs.sudoapp.dev/api-ref/rate_limits#rate-limits)
    
*   [What you’ll see when limited](https://docs.sudoapp.dev/api-ref/rate_limits#what-you%E2%80%99ll-see-when-limited)
    
*   [Provider-level throttling](https://docs.sudoapp.dev/api-ref/rate_limits#provider-level-throttling)
    
*   [Overload: HTTP 503](https://docs.sudoapp.dev/api-ref/rate_limits#overload:-http-503)
    
*   [Best Practices](https://docs.sudoapp.dev/api-ref/rate_limits#best-practices)
    

Sudo enforces request rate limits to ensure fair usage and platform stability. This page describes the limits, response headers, and error codes you may encounter so you can implement appropriate backoff and retry logic.

[​](https://docs.sudoapp.dev/api-ref/rate_limits#rate-limits)

Rate Limits
----------------------------------------------------------------------------

Sudo applies a general request rate of approximately 600 requests per minute (RPM) with short burst capacity. When you exceed the allowed rate, requests may be rejected.

### 

[​](https://docs.sudoapp.dev/api-ref/rate_limits#what-you%E2%80%99ll-see-when-limited)

What you’ll see when limited

*   **HTTP status**: `429 Too Many Requests`
*   **Headers**: Standard rate-limiting headers are returned, including `RateLimit-*` headers when applicable, and a `Retry-After` header in some cases. Use these to determine when to retry.
*   **Body**: A brief message indicating the request was rate limited.

Example handling pattern:

Copy

    # Pseudocode logic for client retries
    if status == 429:
      wait = response.headers.get('Retry-After') or derive_from_rate_limit_headers()
      sleep(wait_seconds)
      retry()
    

### 

[​](https://docs.sudoapp.dev/api-ref/rate_limits#provider-level-throttling)

Provider-level throttling

In addition to general request limits, upstream model providers (OpenAI, Anthropic, Google, xAI, etc.) may enforce their own quotas. When Sudo temporarily exhausts a provider’s budget, you may receive a response instructing you to retry later.

*   **HTTP status**: `503 Service Unavailable`
*   **Header**: `Retry-After: <seconds>` — indicates when it is safe to retry
*   **Body** (JSON):

Copy

    {
      "error": {
        "type": "upstream_rate_limited",
        "scope": "provider:<provider>",
        "detail": "Provider budget temporarily exhausted"
      }
    }
    

Implement exponential backoff and respect `Retry-After` before retrying.

[​](https://docs.sudoapp.dev/api-ref/rate_limits#overload:-http-503)

Overload: HTTP 503
------------------------------------------------------------------------------------------

If the platform is temporarily overloaded (e.g., too many concurrent users or requests), you may receive:

*   **HTTP status**: `503 Service Unavailable`
*   **Header**: `Retry-After: <seconds>` — how long to wait before retrying

Recommended handling:

1.  Read the `Retry-After` header.
2.  Wait the indicated number of seconds.
3.  Retry with exponential backoff if needed.

[​](https://docs.sudoapp.dev/api-ref/rate_limits#best-practices)

Best Practices
----------------------------------------------------------------------------------

*   Prefer exponential backoff with jitter for retries.
*   Always honor `Retry-After` when present.
*   Keep requests within reasonable volumes to avoid throttling.
*   Consider queuing or batching non-urgent work.

Some SDK methods include built-in retry mechanics. If you implement your own, make sure to cap maximum retries and total wait time to provide a responsive user experience.

[Responses API](https://docs.sudoapp.dev/api-ref/responses_api)
[System Health](https://docs.sudoapp.dev/api-reference/system/system-health)

⌘I

---

# Responses API - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/api-ref/responses_api#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

API Reference

Responses API

On this page

*   [Requests](https://docs.sudoapp.dev/api-ref/responses_api#requests)
    
*   [Headers](https://docs.sudoapp.dev/api-ref/responses_api#headers)
    
*   [Minimal JSON example](https://docs.sudoapp.dev/api-ref/responses_api#minimal-json-example)
    
*   [Example: non‑streaming curl](https://docs.sudoapp.dev/api-ref/responses_api#example:-non%E2%80%91streaming-curl)
    
*   [Responses](https://docs.sudoapp.dev/api-ref/responses_api#responses)
    
*   [Example response](https://docs.sudoapp.dev/api-ref/responses_api#example-response)
    
*   [Errors](https://docs.sudoapp.dev/api-ref/responses_api#errors)
    
*   [Streaming](https://docs.sudoapp.dev/api-ref/responses_api#streaming)
    
*   [Example: streaming curl](https://docs.sudoapp.dev/api-ref/responses_api#example:-streaming-curl)
    
*   [Rate limiting & behavior](https://docs.sudoapp.dev/api-ref/responses_api#rate-limiting-&-behavior)
    

Sudo exposes the [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses/create)
 at the `v1/responses` endpoint.  
If you’re already using OpenAI’s Responses API you can usually **swap the base URL, provide a Sudo API key, and you’re done**. **Base URL**: `https://sudoapp.dev/api`  
**Responses endpoint**: `/v1/responses`

This interface **only supports OpenAI models** (for example `gpt-4.1`, `gpt-4.1-mini`, `o3-mini`, etc.).  
Sudo **forwards requests directly to OpenAI’s Responses API** with one-to-one parity, which makes it ideal for **agent-style workflows, tools-heavy orchestration, and modern OpenAI-first features** that go beyond classic chat completions.

As with `/v1/chat/completions`, **rate limiting and error handling are managed by Sudo’s AI router** – behavior is identical to the canonical `/v1/chat/completions` endpoint.

* * *

[​](https://docs.sudoapp.dev/api-ref/responses_api#requests)

Requests
------------------------------------------------------------------------

You `POST` to `/v1/responses` with the same shape OpenAI expects.  
Below is an **example** condensed TypeScript definition (non-exhaustive) that highlights the most commonly used fields:

Request Schema

Copy

    export type ResponsesRequest = {
      /** Required: OpenAI model identifier, e.g. `gpt-4.1-mini` */
      model: string;
    
      /**
       * Core input to the model.
       * Can be a simple string, or an array of structured items (messages, tool calls, etc.).
       */
      input?: ResponsesInput;
    
      /** High-level instructions / system prompt for the model. */
      instructions?: string | ResponseInstructionItem[];
    
      /** Enable or disable automatic tool calling. */
      tool_choice?: 'none' | 'auto' | 'required' | ToolChoiceObject;
    
      /** Tools (functions, file search, code interpreter, etc.) available to the model. */
      tools?: Tool[];
    
      /** Common generation params */
      temperature?: number;
      top_p?: number;
      max_output_tokens?: number;
    
      /** Agent / orchestration features */
      reasoning?: unknown;
      service_tier?: 'auto' | 'default' | string;
      metadata?: Record<string, unknown>;
      store?: boolean;
      conversation?: string | ConversationConfig;
      previous_response_id?: string;
    
      /** Streaming */
      stream?: boolean;
      stream_options?: unknown;
    
      /** Other advanced options from OpenAI are also supported 1:1 */
      truncation?: string;
      max_tool_calls?: number;
      top_logprobs?: number;
      prompt_cache_key?: string;
    };
    
    export type ResponsesInput =
      | string
      | InputItem[];
    
    export type InputItem =
      | {
          role: 'user' | 'assistant' | 'system';
          content: MessageContent;
        }
      | StructuredItem
      | ItemReference;
    
    export type MessageContent =
      | string
      | Array<
          | { type: 'input_text'; text: string }
          | {
              type: 'input_image';
              image_url?: string;
              file_id?: string;
              detail?: 'low' | 'high' | 'auto';
            }
          | {
              type: 'input_file';
              file_id?: string;
              file_url?: string;
              filename?: string;
            }
          | {
              type: 'input_audio';
              input_audio: { data: string; format: string };
            }
        >;
    

For a fully detailed schema (including the richer `Item` types for tools, MCP, computer use, etc.), see the official [OpenAI Responses API reference](https://platform.openai.com/docs/api-reference/responses/create)
.

### 

[​](https://docs.sudoapp.dev/api-ref/responses_api#headers)

Headers

Only two headers are required:

| Header | Value |
| --- | --- |
| `Authorization` | `Bearer <SUDO_API_KEY>` |
| `Content-Type` | `application/json` |

### 

[​](https://docs.sudoapp.dev/api-ref/responses_api#minimal-json-example)

Minimal JSON example

The smallest useful request can be just a model and a string input:

Minimal Request

Copy

    {
      "model": "gpt-4.1-mini",
      "input": "Say hello from the Sudo Responses API."
    }
    

For richer agent-style prompts you typically send an array of input items:

Structured Input Request

Copy

    {
      "model": "gpt-4.1-mini",
      "input": [\
        {\
          "role": "system",\
          "content": [\
            {\
              "type": "input_text",\
              "text": "You are an assistant that answers in JSON."\
            }\
          ]\
        },\
        {\
          "role": "user",\
          "content": [\
            {\
              "type": "input_text",\
              "text": "Return a todo list for moving apartments."\
            }\
          ]\
        }\
      ],
      "tool_choice": "auto",
      "tools": [\
        {\
          "type": "function",\
          "name": "create_task",\
          "description": "Create a task in the user's task manager",\
          "parameters": {\
            "type": "object",\
            "properties": {\
              "title": { "type": "string" },\
              "due_date": { "type": "string", "format": "date-time" }\
            },\
            "required": ["title"]\
          }\
        }\
      ]
    }
    

### 

[​](https://docs.sudoapp.dev/api-ref/responses_api#example:-non%E2%80%91streaming-curl)

Example: non‑streaming `curl`

curl

Copy

    curl https://sudoapp.dev/api/v1/responses \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $SUDO_API_KEY" \
      -d '{
        "model": "gpt-4.1-mini",
        "input": "Say hello from the Sudo Responses API."
      }'
    

* * *

[​](https://docs.sudoapp.dev/api-ref/responses_api#responses)

Responses
--------------------------------------------------------------------------

Sudo **returns the same schema as the OpenAI Responses API**, including the `response` object and `output` items.

Response Schema (simplified)

Copy

    export type Response = {
      id: string;
      object: 'response';
      created_at: number;
      model: string;
    
      /** Overall status of the response */
      status:
        | 'in_progress'
        | 'completed'
        | 'failed'
        | 'cancelled'
        | 'incomplete';
    
      /** Generated output items (messages, tool calls, reasoning, etc.) */
      output?: Item[];
    
      /** Conversation information (if stored) */
      conversation?: { id: string };
    
      /** Token usage */
      usage?: {
        input_tokens: number;
        output_tokens: number;
        total_tokens: number;
      };
    
      /** Optional configuration echoes and metadata */
      metadata?: Record<string, unknown>;
      background?: boolean;
      instructions?: string | unknown[];
      max_output_tokens?: number;
      max_tool_calls?: number;
      parallel_tool_calls?: boolean;
      previous_response_id?: string;
      prompt?: unknown;
      prompt_cache_key?: string;
      reasoning?: unknown;
      safety_identifier?: string;
      service_tier?: string;
      temperature?: number;
      text?: unknown;
      tool_choice?: unknown;
      tools?: unknown[];
      truncation?: string;
      top_p?: number;
      top_logprobs?: number;
    };
    
    export type Item =
      | OutputMessageItem
      | ToolCallItem
      | ToolCallOutputItem
      | ReasoningItem
      | FileSearchItem
      | CodeInterpreterItem
      | MCPItem
      | CustomToolItem;
    
    export type OutputMessageItem = {
      id: string;
      type: 'output_message';
      role: 'assistant';
      status: string;
      content: Array<
        | {
            type: 'output_text';
            text: string;
            annotations: unknown[];
            logprobs?: unknown[];
          }
        | { type: 'refusal'; refusal: string }
      >;
    };
    

### 

[​](https://docs.sudoapp.dev/api-ref/responses_api#example-response)

Example response

Example Response

Copy

    {
      "id": "resp_abc123",
      "object": "response",
      "created_at": 1710000000,
      "model": "gpt-4.1-mini",
      "status": "completed",
      "output": [\
        {\
          "id": "msg_1",\
          "type": "output_message",\
          "role": "assistant",\
          "status": "completed",\
          "content": [\
            {\
              "type": "output_text",\
              "text": "Hello from the Sudo Responses API!",\
              "annotations": [],\
              "logprobs": null\
            }\
          ]\
        }\
      ],
      "usage": {
        "input_tokens": 12,
        "output_tokens": 8,
        "total_tokens": 20
      }
    }
    

### 

[​](https://docs.sudoapp.dev/api-ref/responses_api#errors)

Errors

Error envelopes are **identical** to the rest of the Sudo AI router (including `/v1/chat/completions`), for example:

Error

Copy

    {
      "error": {
        "message": "Invalid API key",
        "type": "api_error"
      }
    }
    

You can expect OpenAI-originated errors (for example invalid model, bad tools schema) to be surfaced through the same structure with appropriate HTTP status codes.

* * *

[​](https://docs.sudoapp.dev/api-ref/responses_api#streaming)

Streaming
--------------------------------------------------------------------------

When you set `"stream": true` in the request body, Sudo will stream **Server‑Sent Events (SSE)** that mirror the [OpenAI Responses streaming format](https://platform.openai.com/docs/api-reference/responses-streaming/response)
. Unlike `/v1/chat/completions` streaming, which sends **delta chunks for `choices[].delta`**, the Responses API streams **typed events** such as:

*   **`response.created`**: the response object has been created.
*   **`response.output_text.delta`**: incremental text tokens being generated.
*   **`response.output_text.done`**: the final text segment for an output item.
*   **`response.completed`**: the entire response has finished.
*   **`error`**: an error occurred while generating the response.

Each SSE event is a JSON object with a top-level `type` field. A typical stream might start like:

SSE events (truncated)

Copy

    data: {"type":"response.created","response":{"id":"resp_abc123","status":"in_progress", ...}}
    
    data: {
      "type": "response.output_text.delta",
      "delta": {
        "content": [\
          {\
            "type": "output_text_delta",\
            "text": { "value": "Hello from the " }\
          }\
        ]
      }
    }
    
    data: {"type":"response.output_text.done", ...}
    
    data: {"type":"response.completed","response":{"id":"resp_abc123","status":"completed", ...}}
    
    data: [DONE]
    

### 

[​](https://docs.sudoapp.dev/api-ref/responses_api#example:-streaming-curl)

Example: streaming `curl`

curl (streaming)

Copy

    curl https://sudoapp.dev/api/v1/responses \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $SUDO_API_KEY" \
      -N \
      -d '{
        "model": "gpt-4.1-mini",
        "input": [\
          {\
            "role": "user",\
            "content": [\
              {\
                "type": "input_text",\
                "text": "Write a short haiku about the Sudo Responses API."\
              }\
            ]\
          }\
        ],
        "stream": true
      }'
    

The SSE stream can be consumed using any EventSource/SSE client or your own HTTP streaming logic.

* * *

[​](https://docs.sudoapp.dev/api-ref/responses_api#rate-limiting-&-behavior)

Rate limiting & behavior
--------------------------------------------------------------------------------------------------------

*   **Rate limits**: The Responses API is subject to the same Sudo-side rate limiting as `/v1/chat/completions` (per‑app, per‑developer, and provider‑level throttling).
*   **Error handling**: Errors are normalized and returned using the same `ErrorResponse` shape as the rest of the AI router.

Because Sudo simply forwards to OpenAI’s Responses API under the hood, you automatically benefit from the **latest OpenAI agent and orchestration features**, while keeping a single Sudo integration (API key, billing, and monitoring) across all your AI usage.

[Streaming](https://docs.sudoapp.dev/api-ref/streaming)
[Rate Limits & Overload Handling](https://docs.sudoapp.dev/api-ref/rate_limits)

⌘I

---

# Quickstart - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/overview/quickstart-api#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

Overview

Quickstart

On this page

*   [Using the Sudo API](https://docs.sudoapp.dev/overview/quickstart-api#using-the-sudo-api)
    
*   [Next Steps](https://docs.sudoapp.dev/overview/quickstart-api#next-steps)
    

The Sudo developer platform gives you access to 100+ AI models with a single API key. To obtain an API key, use the [Sudo developer portal](https://sudoapp.dev/dev/ai-apps/new)
 to create a simple dev app with an API key, then fill your account with credits using your Stripe payment method, which you can connect on the [billing settings page](https://sudoapp.dev/dev/settings/billing)
.

[​](https://docs.sudoapp.dev/overview/quickstart-api#using-the-sudo-api)

Using the Sudo API
==============================================================================================

Python

TypeScript

Shell

Copy

    import requests
    import json
    
    response = requests.post(
      url="https://sudoapp.dev/api/v1/chat/completions",
      headers={
        "Authorization": "Bearer <SUDO_API_KEY>",
      },
      data=json.dumps({
        "model": "gpt-4o",
        "messages": [\
            	{\
            		"role": "developer",\
            		"content": "You are a helpful assistant."\
            	},\
            	{\
            		"role": "user",\
            		"content": "Hello! Give me a study plan to learn Python."\
            	}\
        	],
        	"store": true
    	})
    )
    

The API also supports streaming.

[​](https://docs.sudoapp.dev/overview/quickstart-api#next-steps)

Next Steps
------------------------------------------------------------------------------

Explore the API capabilities and available models:

[API Reference\
-------------](https://docs.sudoapp.dev/api-ref/overview)
[Supported Models\
----------------](https://docs.sudoapp.dev/overview/models)

[Introduction](https://docs.sudoapp.dev/overview/introduction)
[Supported AI Models](https://docs.sudoapp.dev/overview/models)

⌘I

---

# OpenAI SDK Compatability - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/sdk/openai-sdk#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

SDKs

OpenAI SDK Compatability

On this page

*   [Using the OpenAI SDK](https://docs.sudoapp.dev/sdk/openai-sdk#using-the-openai-sdk)
    
*   [Next Steps](https://docs.sudoapp.dev/sdk/openai-sdk#next-steps)
    

The Sudo developer platform maintains parity with the OpenAI _Chat Completions_ API, allowing you to use the **OpenAI SDK** to access Sudo’s AI routing. By changing just two parameters, you can use the OpenAI SDK to build with Sudo today.

This compatability is not suitable for future-proof and production use cases, and is better for testing and validation.

Recall that each model provider has different degrees of support for OpenAI features (e.g. Anthropic models do not support `response_format` parameter). You must refer to their documentation of OpenAI compatability when in doubt

[​](https://docs.sudoapp.dev/sdk/openai-sdk#using-the-openai-sdk)

Using the OpenAI SDK
=========================================================================================

Using an official SDK by OpenAI, do the following:

1.  Change the base URL to Sudo’s chat API URL: [https://sudoapp.dev/api/v1/](https://sudoapp.dev/api/v1/)
    
2.  Change the API key to your **Sudo API key**, which you can get from the [dev dashboard](https://staging.sudoapp.dev/dev/dashboard)
    .

Now, you can call Sudo’s chat API with **any** supported AI model of your choice.

Python

TypeScript

Copy

    import openai
    
    # Replace with your Sudo API key
    openai.api_key = "your-sudo-api-key"
    # Set the custom base URL
    openai.base_url = "https://sudoapp.dev/api/v1/"
    
    # Make a test call to the chat endpoint
    response = openai.chat.completions.create(
        model="claude-sonnet-4-20250514",  # or "gpt-4", "gemini-2.0-flash", etc.
        messages=[\
            {"role": "user", "content": "Hello! What is the capital of France?"}\
        ],
        temperature=0.7,
    )
    
    print("Response:")
    print(response.choices[0].message.content)
    

[​](https://docs.sudoapp.dev/sdk/openai-sdk#next-steps)

Next Steps
---------------------------------------------------------------------

Explore the API capabilities and available models:

[API Reference\
-------------](https://docs.sudoapp.dev/api-ref/overview)
[Supported Models\
----------------](https://docs.sudoapp.dev/sdk/models)

[Supported AI Models](https://docs.sudoapp.dev/overview/models)
[Introduction](https://docs.sudoapp.dev/sdk/sudo-sdk)

⌘I

---

# Supported AI Models - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/overview/models#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

Overview

Supported AI Models

On this page

*   [Fetching the Latest Models via API](https://docs.sudoapp.dev/overview/models#fetching-the-latest-models-via-api)
    
*   [Model Obect Fields](https://docs.sudoapp.dev/overview/models#model-obect-fields)
    
*   [Table of Suppported Models](https://docs.sudoapp.dev/overview/models#table-of-suppported-models)
    

[​](https://docs.sudoapp.dev/overview/models#fetching-the-latest-models-via-api)

Fetching the Latest Models via API
======================================================================================================================

[The models endpoint](https://docs.sudoapp.dev/api-reference/system/get-supported-models)
 is the source of ground truth for supported models in our API. As soon as we confirm support of a model or model provider, it will be added to the API. The models endpoint returns supported models, identified by their canonical model ID that the original provider operates with. There is also an internal Sudo model ID, which is separate of the provider model ID and is used internally:

Copy

    {
    	"data": [\
    		/* Array of model objects */\
    		{\
          		"created_at": "2025-02-19T00:00:00Z",\
          		"sudo_model_id": 52,\
          		"model_name": "claude-3-7-sonnet-20250219",\
          		"model_provider": "Anthropic"\
    		},\
    	],
    	"first_id": "<string>",
      	"has_more": false,
      	"last_id": "<string>"
    }
    

[​](https://docs.sudoapp.dev/overview/models#model-obect-fields)

Model Obect Fields
--------------------------------------------------------------------------------------

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| `created_at` | String | DateTime representation of when the model was added to the Sudo API support . |
| `sudo_model_id` | int | Internal model ID used for identification by the Sudo API, in the form of a serial integer. |
| `model_name` | String | Canonical model ID, as assigned by the original model provider. e.g. “gpt-4.1-mini” |
| `model_provider` | String | The model provider’s name, e.g. “OpenAI” |

[​](https://docs.sudoapp.dev/overview/models#table-of-suppported-models)

Table of Suppported Models
======================================================================================================

| **Model Provider** | **Model ID** | **Display Name** |
| --- | --- | --- |
| OpenAI | gpt-5 | GPT-5 |
|     | gpt-5-nano | GPT-5 nano |
|     | gpt-5-mini | GPT-5 mini |
|     | gpt-5-chat-latest | GPT-5 chat |
|     | o4-mini | o4  |
|     | o3  | o3  |
|     | o3-mini | o3  |
|     | o1  | o1  |
|     | gpt-4.1 | GPT-4.1 |
|     | gpt-4.1-mini | GPT-4.1 mini |
|     | gpt-4.1-nano | GPT-4.1 nano |
|     | gpt-4o | GPT-4o |
|     | gpt-4o-mini | GPT-4o Mini |
|     | gpt-4o-audio-preview | GPT-4o Audio Preview |
|     | gpt-4o-search-preview | GPT-4o Search Preview |
|     | gpt-4o-mini-search-preview | GPT-4o Mini Search Preview |
|     | gpt-4o-mini-audio-preview | GPT-4o Mini Audio Preview |
|     | gpt-4-turbo-preview | GPT-4 Turbo Preview |
|     | gpt-4-turbo | GPT-4 Turbo |
|     | gpt-4-0613 | GPT-4 (0613) |
|     | gpt-4 | GPT-4 |
|     | gpt-3.5-turbo-16k | GPT-3.5 Turbo 16k |
|     | gpt-3.5-turbo-0125 | GPT-3.5 Turbo (0125) |
|     | gpt-3.5-turbo | GPT-3.5 Turbo |
|     | chatgpt-4o-latest | ChatGPT-4o Latest |
|     | gpt-image-1 | GPT Image |
|     | dall-e-3 | DALL-E 3 |
|     | dall-e-2 | DALL-E 2 |
| Anthropic | claude-sonnet-4-5-20250929 | Claude Sonnet 4.5 |
|     | claude-opus-4-1-20250805 | Claude Opus 4.1 (2025-08-05) |
|     | claude-opus-4-20250514 | Claude Opus 4 (2025-05-22) |
|     | claude-sonnet-4-20250514 | Claude Sonnet 4 (2025-05-22) |
|     | claude-3-7-sonnet-20250219 | Claude 3.7 Sonnet (2025-02-19) |
|     | claude-3-7-sonnet-latest | Claude 3.7 Sonnet |
|     | claude-3-5-haiku-20241022 | Claude 3.5 Haiku (2024-10-22) |
|     | claude-3-5-haiku-latest | Claude 3.5 Haiku |
|     | claude-3-haiku-20240307 | Claude 3 Haiku (2024-03-07) |
| DeepSeek | deepseek-chat | DeepSeek Chat (DeepSeek V3) |
|     | deepseek-reasoner | DeepSeek Reasoner (DeepSeek R1) |
| XAI | grok-4-0709 | Grok-4 |
|     | grok-4-fast-reasoning | Grok-4 Fast Reasoning |
|     | grok-4-fast-non-reasoning | Grok-4 Fast Non-Reasoning |
|     | grok-code-fast-1 | Grok Code Fast |
|     | grok-3 | Grok-3 |
|     | grok-3-mini | Grok-3 Mini |
|     | grok-2-image-1212 | Grok-2 Image |
|     | grok-2-vision-1212 | Grok-2 Vision |
| Gemini | gemini-2.5-pro | Gemini 2.5 Pro |
|     | gemini-2.5-flash | Gemini 2.5 Flash |
|     | gemini-2.5-flash-lite | Gemini 2.5 Flash Lite |
|     | gemini-2.5-flash-preview-04-17 | Gemini 2.5 Flash Preview (04-17) |
|     | gemini-2.5-flash-preview-09-2025 | Gemini 2.5 Flash Preview (09-25) |
|     | gemini-2.5-flash-lite-preview-06-17 | Gemini 2.5 Flash-Lite Preview (06-17) |
|     | gemini-2.5-flash-lite-preview-09-2025 | Gemini 2.5 Flash Lite Preview (09-25) |
|     | gemini-2.0-flash | Gemini 2.0 Flash |
|     | gemini-2.0-flash-lite | Gemini 2.0 Flash-Lite |
|     | imagen-4.0-generate-001 | Imagen 4.0 |
|     | imagen-4.0-fast-generate-001 | Imagen 4.0 Fast |
|     | imagen-4.0-ultra-generate-001 | Imagen 4.0 Ultra |
|     | imagen-3.0-generate-002 | Imagen 3.0 |

[Quickstart](https://docs.sudoapp.dev/overview/quickstart-api)
[OpenAI SDK Compatability](https://docs.sudoapp.dev/sdk/openai-sdk)

⌘I

---

# Introduction - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/sdk/sudo-sdk#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

Sudo SDK

Introduction

On this page

*   [Key Features](https://docs.sudoapp.dev/sdk/sudo-sdk#key-features)
    
*   [Quick Start](https://docs.sudoapp.dev/sdk/sudo-sdk#quick-start)
    
*   [Documentation Sections](https://docs.sudoapp.dev/sdk/sudo-sdk#documentation-sections)
    
*   [SDK Benefits](https://docs.sudoapp.dev/sdk/sudo-sdk#sdk-benefits)
    
*   [Type Safety](https://docs.sudoapp.dev/sdk/sudo-sdk#type-safety)
    
*   [Error Handling](https://docs.sudoapp.dev/sdk/sudo-sdk#error-handling)
    
*   [Resource Management](https://docs.sudoapp.dev/sdk/sudo-sdk#resource-management)
    
*   [Performance](https://docs.sudoapp.dev/sdk/sudo-sdk#performance)
    
*   [Next Steps](https://docs.sudoapp.dev/sdk/sudo-sdk#next-steps)
    

The official SDK for Sudo provides a developer-friendly and type-safe way to integrate with the Sudo AI platform. Available in both Python and TypeScript, it offers comprehensive support for all Sudo features including AI responses with streaming, tool calling, structured outputs, and more.

[​](https://docs.sudoapp.dev/sdk/sudo-sdk#key-features)

Key Features
-----------------------------------------------------------------------

🚀 Easy to Use
--------------

Simple installation with pip, npm, or your preferred package manager. Get started in minutes with intuitive APIs.

⚡ High Performance
------------------

Built-in connection pooling, retry logic, and async support for optimal performance.

🔄 Streaming Support
--------------------

Server-sent events for real-time streaming responses with proper context management.

🛠️ Tool Calling
----------------

Native support for function calling and parallel tool execution.

📊 Structured Output
--------------------

JSON schema validation and structured data extraction capabilities.

🖼️ Multimodal
--------------

Support for images, audio, and other modalities beyond text.

[​](https://docs.sudoapp.dev/sdk/sudo-sdk#quick-start)

Quick Start
---------------------------------------------------------------------

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function main() {
      const response = await sudo.router.create({
        model: "claude-sonnet-4-20250514",
        messages: [\
          { role: "user", content: "Hello! How are you?" }\
        ]
      });
      
      console.log(response.choices[0].message.content);
    }
    
    main();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk#documentation-sections)

Documentation Sections
-------------------------------------------------------------------------------------------

[Installation & Setup\
--------------------\
\
Get started with installation, authentication, and basic configuration.](https://docs.sudoapp.dev/sdk/sudo-sdk/installation)
[System Endpoints\
----------------\
\
Health checks and model information endpoints.](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints)
[Chat Completion\
---------------\
\
Basic AI responses with various models and parameters.](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses)
[Streaming\
---------\
\
Real-time streaming responses with server-sent events.](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming)
[Tool Calling\
------------\
\
Function calling and tool execution capabilities.](https://docs.sudoapp.dev/sdk/sudo-sdk/tool-calling)
[Structured Output\
-----------------\
\
JSON schema validation and structured data extraction.](https://docs.sudoapp.dev/sdk/sudo-sdk/structured-output)
[Image Input\
-----------\
\
Working with images and multimodal inputs.](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input)
[Image Generation\
----------------\
\
Generate images with multiple providers and formats.](https://docs.sudoapp.dev/sdk/sudo-sdk/image-generation)
[Audio Chat Completions\
----------------------\
\
Add audio input and output to Chat Completions.](https://docs.sudoapp.dev/sdk/sudo-sdk/audio_chat_completions)
[Reasoning\
---------\
\
Advanced reasoning capabilities with o1 models.](https://docs.sudoapp.dev/sdk/sudo-sdk/reasoning)
[CRUD Operations\
---------------\
\
Managing stored Chat Completions (OpenAI only).](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations)

[​](https://docs.sudoapp.dev/sdk/sudo-sdk#sdk-benefits)

SDK Benefits
-----------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk#type-safety)

Type Safety

Both SDKs are fully typed - Python with Pydantic models and TypeScript with native types, providing excellent IDE support and compile-time error checking.

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk#error-handling)

Error Handling

Comprehensive error handling with specific error types and detailed error information in both languages.

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk#resource-management)

Resource Management

Automatic connection pooling and resource cleanup with context manager support (Python) and proper resource management (TypeScript).

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk#performance)

Performance

Built-in retry logic, connection reuse, and async support for high-performance applications in both languages.

[​](https://docs.sudoapp.dev/sdk/sudo-sdk#next-steps)

Next Steps
-------------------------------------------------------------------

1.  **[Install the SDK](https://docs.sudoapp.dev/sdk/sudo-sdk/installation)
    ** - Get started with installation and setup
2.  **[Try Chat Completion](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses)
    ** - Create your first AI response
3.  **[Explore Streaming](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming)
    ** - Add real-time capabilities
4.  **[Advanced Features](https://docs.sudoapp.dev/sdk/sudo-sdk/tool-calling)
    ** - Tool calling, structured output, and more

The Sudo SDK follows semantic versioning in both languages. For Python, check the [PyPI page](https://pypi.org/project/sudo-sudo-ai/)
 and for TypeScript, check the [npm page](https://www.npmjs.com/package/sudo-ai)
 for the latest release information.**Python**: Compatible with Python 3.9+  
**TypeScript**: Compatible with Node.js 14+ and modern browsers

[OpenAI SDK Compatability](https://docs.sudoapp.dev/sdk/openai-sdk)
[Installation & Setup](https://docs.sudoapp.dev/sdk/sudo-sdk/installation)

⌘I

---

# Audio Chat Completions - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/sdk/sudo-sdk/audio_chat_completions#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

Sudo SDK

Audio Chat Completions

On this page

*   [Audio Output from Text](https://docs.sudoapp.dev/sdk/sudo-sdk/audio_chat_completions#audio-output-from-text)
    
*   [Audio Input + Text](https://docs.sudoapp.dev/sdk/sudo-sdk/audio_chat_completions#audio-input-+-text)
    
*   [Tips](https://docs.sudoapp.dev/sdk/sudo-sdk/audio_chat_completions#tips)
    

Models like GPT-4o can handle audio modalities. With Sudo, you can call OpenAI-compatible audio models to produce audio output and optionally send audio input alongside text.

Only certain providers currently support audio input/output with Chat Completions in this format (notably OpenAI). Before using audio, confirm your chosen model provider’s API accepts `modalities` and `input_audio` as shown here, and adjust parameters accordingly.

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/audio_chat_completions#audio-output-from-text)

Audio Output from Text
------------------------------------------------------------------------------------------------------------------

Generate spoken audio from a text prompt using an audio-capable model.

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function textToSpeech() {
      const response = await sudo.router.create({
        model: "gpt-4o-audio-preview",
        modalities: ["text", "audio"],
        audio: { voice: "alloy", format: "wav" },
        messages: [\
          {\
            role: "user",\
            content: "Is a golden retriever a good family dog?",\
          },\
        ],
      });
    
      // The response may include both text and audio. Inspect the structure as providers evolve.
      console.log("Text:", response.choices[0].message.content);
      // Optionally check for audio fields if present in your provider’s response shape
      // console.log("Audio (base64):", response.choices[0].message.audio?.data);
    }
    
    textToSpeech();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/audio_chat_completions#audio-input-+-text)

Audio Input + Text
----------------------------------------------------------------------------------------------------------

Send user audio together with a text prompt. Encode your audio file as base64 and include it using `type: "input_audio"`.

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    import * as fs from "fs";
    import * as path from "path";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    function encodeAudioToBase64(audioPath: string): { data: string; format: string } {
      const ext = path.extname(audioPath).toLowerCase();
      const format = ext.replace(".", "") || "wav"; // e.g. .wav -> wav
      const audioBuffer = fs.readFileSync(audioPath);
      return { data: audioBuffer.toString("base64"), format };
    }
    
    async function analyzeAudioWithText() {
      const { data, format } = encodeAudioToBase64("path/to/recording.wav");
    
      const response = await sudo.router.create({
        model: "gpt-4o-audio-preview",
        modalities: ["text", "audio"],
        audio: { voice: "alloy", format: "wav" },
        messages: [\
          {\
            role: "user",\
            content: [\
              { type: "text", text: "What is in this recording?" },\
              {\
                type: "input_audio",\
                inputAudio: {\
                  data,\
                  format,\
                },\
              },\
            ],\
          },\
        ],
      });
    
      console.log("Text:", response.choices[0].message.content);
    }
    
    analyzeAudioWithText();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/audio_chat_completions#tips)

Tips
------------------------------------------------------------------------------

*   Prefer lossless or high-quality input formats for best transcription/understanding.
*   Keep requests small; very long audio can increase latency and cost.
*   Verify your chosen model supports audio input/output and the requested `format`.

[Image Input](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input)
[Reasoning](https://docs.sudoapp.dev/sdk/sudo-sdk/reasoning)

⌘I

---

# Get a Chat Completion - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/api-reference/ai-routing/get-a-chat-completion#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

AI Routing

Get a Chat Completion

200

400

401

500

502

Copy

    {
      "choices": [\
        {\
          "finish_reason": "<string>",\
          "index": 1,\
          "logprobs": "<any>",\
          "message": {\
            "annotations": "<any>",\
            "audio": "<any>",\
            "content": "<string>",\
            "refusal": "<string>",\
            "role": "<string>",\
            "tool_calls": [\
              {\
                "function": {\
                  "arguments": "<string>",\
                  "name": "<string>"\
                },\
                "id": "<string>",\
                "type": "<string>"\
              }\
            ]\
          }\
        }\
      ],
      "created": 1,
      "id": "<string>",
      "model": "<string>",
      "object": "<string>",
      "service_tier": "<string>",
      "system_fingerprint": "<string>",
      "usage": {
        "completion_tokens": 1,
        "completion_tokens_details": "<any>",
        "prompt_tokens": 1,
        "prompt_tokens_details": "<any>",
        "total_tokens": 1
      }
    }

GET

/

v1

/

chat

/

completions

/

{completion\_id}

Try it

200

400

401

500

502

Copy

    {
      "choices": [\
        {\
          "finish_reason": "<string>",\
          "index": 1,\
          "logprobs": "<any>",\
          "message": {\
            "annotations": "<any>",\
            "audio": "<any>",\
            "content": "<string>",\
            "refusal": "<string>",\
            "role": "<string>",\
            "tool_calls": [\
              {\
                "function": {\
                  "arguments": "<string>",\
                  "name": "<string>"\
                },\
                "id": "<string>",\
                "type": "<string>"\
              }\
            ]\
          }\
        }\
      ],
      "created": 1,
      "id": "<string>",
      "model": "<string>",
      "object": "<string>",
      "service_tier": "<string>",
      "system_fingerprint": "<string>",
      "usage": {
        "completion_tokens": 1,
        "completion_tokens_details": "<any>",
        "prompt_tokens": 1,
        "prompt_tokens_details": "<any>",
        "total_tokens": 1
      }
    }

#### Path Parameters

[​](https://docs.sudoapp.dev/api-reference/ai-routing/get-a-chat-completion#parameter-completion-id)

completion\_id

string

required

ID of the chat completion

#### Response

200

application/json

Chat completion gotten successfully

[​](https://docs.sudoapp.dev/api-reference/ai-routing/get-a-chat-completion#response-choices)

choices

object\[\]

required

Show child attributes

[​](https://docs.sudoapp.dev/api-reference/ai-routing/get-a-chat-completion#response-created)

created

integer

required

Required range: `x >= 0`

[​](https://docs.sudoapp.dev/api-reference/ai-routing/get-a-chat-completion#response-id)

id

string

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/get-a-chat-completion#response-model)

model

string

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/get-a-chat-completion#response-object)

object

string

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/get-a-chat-completion#response-usage)

usage

object

required

Show child attributes

[​](https://docs.sudoapp.dev/api-reference/ai-routing/get-a-chat-completion#response-service-tier)

service\_tier

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/get-a-chat-completion#response-system-fingerprint)

system\_fingerprint

string | null

[Create Chat Completion](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion)
[Update Chat Completion](https://docs.sudoapp.dev/api-reference/ai-routing/update-chat-completion)

⌘I

---

# Generate Image - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

AI Routing

Generate Image

200

400

401

500

502

Copy

    {
      "background": "<string>",
      "created": 1,
      "data": [\
        {\
          "b64_json": "<string>",\
          "revised_prompt": "<string>",\
          "url": "<string>"\
        }\
      ],
      "output_format": "<string>",
      "quality": "<string>",
      "size": "<string>",
      "usage": null
    }

POST

/

v1

/

images

/

generations

Try it

200

400

401

500

502

Copy

    {
      "background": "<string>",
      "created": 1,
      "data": [\
        {\
          "b64_json": "<string>",\
          "revised_prompt": "<string>",\
          "url": "<string>"\
        }\
      ],
      "output_format": "<string>",
      "quality": "<string>",
      "size": "<string>",
      "usage": null
    }

#### Body

application/json

[​](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#body-model)

model

string

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#body-prompt)

prompt

string

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#body-background)

background

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#body-moderation)

moderation

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#body-n)

n

integer | null

Required range: `x >= 0`

[​](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#body-output-compression)

output\_compression

integer | null

Required range: `x >= 0`

[​](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#body-output-format)

output\_format

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#body-quality)

quality

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#body-response-format)

response\_format

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#body-size)

size

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#body-style)

style

string | null

#### Response

200

application/json

Image generated successfully

[​](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#response-data)

data

object\[\]

required

Show child attributes

[​](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#response-background)

background

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#response-created)

created

integer | null

Required range: `x >= 0`

[​](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#response-output-format)

output\_format

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#response-quality)

quality

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#response-size)

size

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image#response-usage)

usage

object | null

Show child attributes

[Chat Completion Messages](https://docs.sudoapp.dev/api-reference/ai-routing/chat-completion-messages)
[Create Response](https://docs.sudoapp.dev/api-reference/ai-routing/create-response)

⌘I

---

# System Health - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/api-reference/system/system-health#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

System

System Health

200

Copy

    "<any>"

GET

/

system

/

health

Try it

200

Copy

    "<any>"

#### Response

200 - application/json

Health check successful

The response is of type `any`.

[Rate Limits & Overload Handling](https://docs.sudoapp.dev/api-ref/rate_limits)
[Get supported models list (for devs to use)](https://docs.sudoapp.dev/api-reference/system/get-supported-models-list-for-devs-to-use)

⌘I

---

# Image Generation - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/sdk/sudo-sdk/image-generation#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

Sudo SDK

Image Generation

On this page

*   [Basic Image Generation](https://docs.sudoapp.dev/sdk/sudo-sdk/image-generation#basic-image-generation)
    
*   [Response Formats](https://docs.sudoapp.dev/sdk/sudo-sdk/image-generation#response-formats)
    
*   [Parameters](https://docs.sudoapp.dev/sdk/sudo-sdk/image-generation#parameters)
    
*   [Notes](https://docs.sudoapp.dev/sdk/sudo-sdk/image-generation#notes)
    

Use Sudo SDKs to generate images with models like DALL·E, GPT-Image, Imagen, and others. This page shows basic usage and common parameters.

Not all parameters are supported across providers. For example, `quality` may be supported by DALL·E 3 but not by Grok or Imagen. Always consult the respective provider’s model documentation to construct the request body correctly.

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/image-generation#basic-image-generation)

Basic Image Generation
------------------------------------------------------------------------------------------------------------

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function generateBasicImage() {
      const response = await sudo.router.generateImage({
        prompt: "A beautiful sunset over a mountain landscape",
        model: "dall-e-3",
        size: "1024x1024",
        quality: "standard",
      });
    
      // Response can include URLs or base64, depending on provider/params
      const first = response.data?.[0];
      if (first?.url) {
        console.log("Image URL:", first.url);
      } else if (first?.b64Json) {
        console.log("Image base64 length:", first.b64Json.length);
      }
    }
    
    generateBasicImage();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/image-generation#response-formats)

Response Formats
------------------------------------------------------------------------------------------------

Request either a hosted URL or base64 data.

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function generateWithFormats() {
      // URL format
      const urlResp = await sudo.router.generateImage({
        prompt: "A simple geometric pattern",
        model: "dall-e-2",
        n: 1,
        size: "512x512",
        responseFormat: "url",
      });
      console.log("URL:", urlResp.data?.[0]?.url);
    
      // Base64 format
      const b64Resp = await sudo.router.generateImage({
        prompt: "A simple geometric pattern",
        model: "dall-e-2",
        n: 1,
        size: "512x512",
        responseFormat: "b64_json",
      });
      console.log("b64 length:", b64Resp.data?.[0]?.b64Json?.length);
    }
    
    generateWithFormats();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/image-generation#parameters)

Parameters
------------------------------------------------------------------------------------

*   **model**: The image model to use (e.g., `dall-e-3`, `gpt-image-1`, provider-specific models). See `Overview → Models` for availability.
*   **prompt**: Text description of the image to generate.
*   **n**: Number of images to generate.
*   **size**: Output image size, e.g., `256x256`, `512x512`, `1024x1024` (availability varies by model/provider).
*   **responseFormat / response\_format**: `url` or `b64_json`.
*   **quality**: Optional quality preset (e.g., `standard`, `hd`) for providers that support it (often OpenAI/DALL·E only).

If a parameter isn’t supported by your chosen model/provider, remove it or adjust to a supported value per provider documentation.

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/image-generation#notes)

Notes
--------------------------------------------------------------------------

*   Image generation capabilities and parameters vary across providers and model versions.
*   If a request fails due to unsupported options, check the error message and consult the provider’s docs.

[Responses api](https://docs.sudoapp.dev/sdk/sudo-sdk/responses_api)
[Streaming](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming)

⌘I

---

# CRUD Operations - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

Sudo SDK

CRUD Operations

On this page

*   [Storing Completions](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#storing-completions)
    
*   [Basic Storage](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#basic-storage)
    
*   [Retrieving Completions](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#retrieving-completions)
    
*   [List Stored Completions](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#list-stored-completions)
    
*   [Filter by Metadata](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#filter-by-metadata)
    
*   [Get Specific Completion](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#get-specific-completion)
    
*   [Updating Completions](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#updating-completions)
    
*   [Update Metadata](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#update-metadata)
    
*   [Deleting Completions](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#deleting-completions)
    
*   [Delete Single Completion](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#delete-single-completion)
    
*   [Summary](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#summary)
    

CRUD operations allow you to store, retrieve, update, and delete OpenAI Chat Completions for analysis, caching, and model improvement.

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#storing-completions)

Storing Completions
-----------------------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#basic-storage)

Basic Storage

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function basicStorage() {
      try {
        // Create and store a completion
        const response = await sudo.router.create({
          model: "gpt-4o",
          messages: [\
            { role: "user", content: "Explain machine learning" }\
          ],
          store: true,  // Enable storage
          metadata: {
            userId: "user_123",
            topic: "education",
            session: "learning_session_1"
          }
        });
        
        const completionId = response.id;
        console.log(`Stored completion with ID: ${completionId}`);
        console.log(`Response: ${response.choices[0].message.content}`);
      } catch (error) {
        console.error("Storage error:", error);
      }
    }
    
    basicStorage();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#retrieving-completions)

Retrieving Completions
-----------------------------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#list-stored-completions)

List Stored Completions

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function listStoredCompletions() {
      try {
        // List all stored completions
        const completions = await sudo.router.listChatCompletions({
          limit: 10,
          order: "desc"  // Most recent first
        });
        
        console.log(`Found ${completions.data.length} stored completions:`);
        completions.data.forEach(completion => {
          console.log(`- ID: ${completion.id}`);
          console.log(`  Model: ${completion.model}`);
          console.log(`  Created: ${completion.created}`);
          if (completion.metadata) {
            console.log(`  Metadata: ${JSON.stringify(completion.metadata)}`);
          }
        });
      } catch (error) {
        console.error("List completions error:", error);
      }
    }
    
    listStoredCompletions();
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#filter-by-metadata)

Filter by Metadata

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function filterByMetadata() {
      try {
        // Filter completions by metadata
        const completions = await sudo.router.listChatCompletions({
          metadata: {
            userId: "user_123",
            topic: "education"
          },
          limit: 5
        });
        
        console.log("Education-related completions:");
        completions.data.forEach(completion => {
          console.log(`- ${completion.id}: ${completion.model}`);
        });
      } catch (error) {
        console.error("Filter by metadata error:", error);
      }
    }
    
    filterByMetadata();
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#get-specific-completion)

Get Specific Completion

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function getCompletionDetails(completionId: string) {
      try {
        // Get completion metadata
        const completion = await sudo.router.getChatCompletion(completionId);
        
        // Get completion messages
        const messages = await sudo.router.getChatCompletionMessages(completionId);
        
        return {
          completion,
          messages
        };
      } catch (error) {
        console.error("Get completion details error:", error);
        return null;
      }
    }
    
    // Usage
    async function completionDetailsExample() {
      const completionId = "chatcmpl-abc123";  // Replace with actual ID
      const details = await getCompletionDetails(completionId);
      
      if (details) {
        console.log(`Completion ID: ${details.completion.id}`);
        console.log(`Model: ${details.completion.model}`);
        console.log(`Created: ${details.completion.created}`);
        console.log("\nMessages:");
        details.messages.data.forEach(message => {
          console.log(`- ${message.role}: ${message.content}`);
        });
      }
    }
    
    completionDetailsExample();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#updating-completions)

Updating Completions
-------------------------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#update-metadata)

Update Metadata

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function updateCompletionMetadata(completionId: string, newMetadata: Record<string, any>) {
      try {
        const updatedCompletion = await sudo.router.updateChatCompletion({
          completionId: completionId,
          metadata: newMetadata
        });
        
        return updatedCompletion;
      } catch (error) {
        console.error("Update completion metadata error:", error);
        return null;
      }
    }
    
    // Example: Add rating and feedback
    async function updateMetadataExample() {
      const newMetadata = {
        userId: "user_123",
        topic: "education", 
        rating: "5",
        feedback: "very_helpful",
        reviewed: "true"
      };
    
      const updated = await updateCompletionMetadata("chatcmpl-abc123", newMetadata);
      if (updated) {
        console.log(`Updated completion ${updated.id}`);
        console.log(`New metadata: ${JSON.stringify(updated.metadata)}`);
      }
    }
    
    updateMetadataExample();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#deleting-completions)

Deleting Completions
-------------------------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#delete-single-completion)

Delete Single Completion

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function deleteCompletion(completionId: string) {
      try {
        const result = await sudo.router.deleteChatCompletion(completionId);
        return result;
      } catch (error) {
        console.error("Delete completion error:", error);
        return null;
      }
    }
    
    // Delete a completion
    async function deleteCompletionExample() {
      const result = await deleteCompletion("chatcmpl-abc123");
      if (result) {
        console.log(`Deletion result: ${JSON.stringify(result)}`);
      }
    }
    
    deleteCompletionExample();
    

CRUD operations are only available for completions created with `store=True`. This feature is designed for OpenAI API compatibility and works with both Python and TypeScript SDKs.

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#summary)

Summary
-----------------------------------------------------------------------------

The Sudo SDK provides comprehensive functionality for building AI-powered applications in both Python and TypeScript:

*   **System Endpoints**: Monitor API health and discover available models
*   **Chat Completion**: Generate responses from various AI models with extensive customization
*   **Streaming**: Real-time response generation for interactive applications
*   **Tool Calling**: Enable AI models to execute functions and interact with external systems
*   **Structured Output**: Generate validated JSON responses for reliable data extraction
*   **Image Input**: Process images and multimodal content with vision-capable models
*   **Reasoning**: Access advanced reasoning capabilities for complex problem-solving
*   **CRUD Operations**: Manage stored completions for analysis and improvement

Both SDKs are designed for production use with comprehensive error handling, async support, and best practices built-in. Start with basic chat completions and gradually add advanced features as needed. **Resources:**

*   **Python**: [GitHub Repository](https://github.com/sudoappai/sudo-python)
     | [PyPI Package](https://pypi.org/project/sudo-ai/)
    
*   **TypeScript**: [GitHub Repository](https://github.com/sudoappai/sudo-typescript)
     | [npm Package](https://www.npmjs.com/package/sudo-ai)
    

[Reasoning](https://docs.sudoapp.dev/sdk/sudo-sdk/reasoning)
[Overview](https://docs.sudoapp.dev/api-ref/overview)

⌘I

---

# Reasoning - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/sdk/sudo-sdk/reasoning#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

Sudo SDK

Reasoning

On this page

*   [Basic Reasoning](https://docs.sudoapp.dev/sdk/sudo-sdk/reasoning#basic-reasoning)
    
*   [Simple Reasoning Task](https://docs.sudoapp.dev/sdk/sudo-sdk/reasoning#simple-reasoning-task)
    
*   [Reasoning Effort Levels (OpenAI models)](https://docs.sudoapp.dev/sdk/sudo-sdk/reasoning#reasoning-effort-levels-openai-models)
    
*   [Next Steps](https://docs.sudoapp.dev/sdk/sudo-sdk/reasoning#next-steps)
    

The reasoning capabilities in Sudo allow you to access advanced reasoning models like o3 for complex problem-solving tasks.

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/reasoning#basic-reasoning)

Basic Reasoning
---------------------------------------------------------------------------------------

`reasoning_effort` parameter is mainly supported for OpenAI models. While other providers have reasoning models as well, not all providers support `reasoning_effort`

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/reasoning#simple-reasoning-task)

Simple Reasoning Task

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function simpleReasoningTask() {
      try {
        const response = await sudo.router.create({
          model: "o3",  // Reasoning model
          messages: [\
            {\
              role: "user",\
              content: "Solve this step by step: If a train travels 120 km in 2 hours, and then 180 km in 3 hours, what is its average speed for the entire journey?"\
            }\
          ]
        });
        
        console.log("Reasoning Response:");
        console.log(response.choices[0].message.content);
        
      } catch (error) {
        console.error("Reasoning error:", error);
      }
    }
    
    simpleReasoningTask();
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/reasoning#reasoning-effort-levels-openai-models)

Reasoning Effort Levels (OpenAI models)

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function solveWithDifferentEfforts(problem: string): Promise<void> {
      // Effort levels to control reasoning depth
      const efforts: Array<"low" | "medium" | "high"> = ["low", "medium", "high"];
      
      try {
        for (const effort of efforts) {
          console.log(`\n--- Reasoning Effort: ${effort.toUpperCase()} ---`);
          
          const response = await sudo.router.create({
            model: "o3",
            messages: [\
              { role: "user", content: problem }\
            ],
            reasoningEffort: effort
          });
          
          console.log(response.choices[0].message.content);
          
          // Show token usage for different efforts
          if (response.usage) {
            console.log(`Tokens used: ${response.usage.totalTokens}`);
          }
        }
      } catch (error) {
        console.error("Reasoning with efforts error:", error);
      }
    }
    
    // Example complex problem
    const problem = `
    A company has 3 departments. Department A has 15 employees with an average salary of $60,000. 
    Department B has 20 employees with an average salary of $75,000. 
    Department C has 10 employees with an average salary of $90,000.
    If the company wants to give everyone a 8% raise, but needs to keep the total payroll increase under $50,000, 
    what should they do?
    `;
    
    solveWithDifferentEfforts(problem);
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/reasoning#next-steps)

Next Steps
-----------------------------------------------------------------------------

1.  **[CRUD Operations](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations)
    ** - Manage stored completions

Reasoning models like o3 excel at complex problem-solving, mathematical reasoning, and multi-step analysis. Use higher reasoning effort levels for more complex problems, but be aware they consume more tokens. Both TypeScript and Python SDKs provide full support for reasoning capabilities with proper error handling.

[Audio Chat Completions](https://docs.sudoapp.dev/sdk/sudo-sdk/audio_chat_completions)
[CRUD Operations](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations)

⌘I

---

# System Endpoints - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

Sudo SDK

System Endpoints

On this page

*   [Health Check](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints#health-check)
    
*   [Basic Usage](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints#basic-usage)
    
*   [Python Async Usage](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints#python-async-usage)
    
*   [Get Supported Models](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints#get-supported-models)
    
*   [Basic Usage](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints#basic-usage-2)
    
*   [Python Async Usage](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints#python-async-usage-2)
    
*   [Error Handling](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints#error-handling)
    
*   [Next Steps](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints#next-steps)
    

The system endpoints provide information about the Sudo API status and available models. These are typically used for health monitoring and discovering available AI models.

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints#health-check)

Health Check
----------------------------------------------------------------------------------------

Check if the Sudo API and backend infrastructure are healthy and ready to accept connections.

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints#basic-usage)

Basic Usage

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function checkHealth() {
      try {
        // Check API health
        const healthStatus = await sudo.system.healthCheck();
        console.log(`API Status: ${JSON.stringify(healthStatus)}`);
      } catch (error) {
        console.error("Health check failed:", error);
      }
    }
    
    checkHealth();
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints#python-async-usage)

Python Async Usage

Python

Python

Copy

    import asyncio
    import os
    from sudo import Sudo
    
    async def check_health():
        async with Sudo(
            server_url="https://sudoapp.dev/api",
            api_key=os.getenv("SUDO_API_KEY"),
        ) as client:
            health_status = await client.system.health_check_async()
            return health_status
    
    # Run the async function
    health = asyncio.run(check_health())
    print(f"API Status: {health}")
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints#get-supported-models)

Get Supported Models
--------------------------------------------------------------------------------------------------------

Retrieve a list of all AI models supported by the Sudo API, including their capabilities and pricing information.

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints#basic-usage-2)

Basic Usage

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY,
    });
    
    async function getSupportedModels() {
      try {
        const models = await sudo.system.getSupportedModels();
    
        console.log(`Available models: ${models.data.length}`);
        models.data.forEach(m => {
          console.log(`- ${m.modelName} (${m.modelProvider})`);
        });
      } catch (error) {
        console.error("Failed to get models:", error);
      }
    }
    
    getSupportedModels();
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints#python-async-usage-2)

Python Async Usage

Python

Python

Copy

    import asyncio
    import os
    from sudo import Sudo
    
    async def get_models_info():
        async with Sudo(
            server_url="https://sudoapp.dev/api",
            api_key=os.getenv("SUDO_API_KEY"),
        ) as client:
            models = await client.system.get_supported_models_async()
            return models
    
    # Get models asynchronously
    models = asyncio.run(get_models_info())
    print(f"Found {len(models.data)} models")
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints#error-handling)

Error Handling
--------------------------------------------------------------------------------------------

Both system endpoints can encounter various errors. Here’s how to handle them:

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    import * as errors from "sudo-ai/models/errors";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function systemEndpointsWithErrorHandling() {
      try {
        // Try health check
        const health = await sudo.system.healthCheck();
        console.log("✅ Health check passed");
        
        // Try getting models
        const models = await sudo.system.getSupportedModels();
        console.log(`✅ Retrieved ${models.data.length} models`);
        
      } catch (error) {
        if (error instanceof errors.SudoError) {
          if (error.statusCode === 401) {
            console.log("❌ Authentication failed - check your API key");
          } else if (error.statusCode >= 500) {
            console.log("❌ Server error - the API may be experiencing issues");
          } else {
            console.log(`❌ API error: ${error.message}`);
            console.log(`Status: ${error.statusCode}`);
          }
          
          if (error instanceof errors.ErrorResponse) {
            console.log(`Error details: ${error.data$.error}`);
          }
        } else {
          console.log(`❌ Unexpected error: ${error}`);
        }
      }
    }
    
    systemEndpointsWithErrorHandling();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints#next-steps)

Next Steps
------------------------------------------------------------------------------------

Now that you understand the system endpoints:

1.  **[Try AI Responses](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses)
    ** - Start creating AI responses
2.  **[Explore Streaming](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming)
    ** - Add real-time capabilities
3.  **[Advanced Features](https://docs.sudoapp.dev/sdk/sudo-sdk/tool-calling)
    ** - Function calling and more

Use the health check endpoint in your application’s readiness probes and the models endpoint to dynamically discover available AI models. Both TypeScript and Python SDKs provide the same system information with language-appropriate handling.

[Installation & Setup](https://docs.sudoapp.dev/sdk/sudo-sdk/installation)
[AI Router](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses)

⌘I

---

# Chat Completion Messages - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/api-reference/ai-routing/chat-completion-messages#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

AI Routing

Chat Completion Messages

200

400

401

500

502

Copy

    {
      "data": [\
        {\
          "content": "<string>",\
          "content_parts": [\
            {\
              "text": "<string>",\
              "type": "input_text"\
            }\
          ],\
          "id": "<string>",\
          "name": "<string>",\
          "role": "<string>"\
        }\
      ],
      "first_id": "<string>",
      "has_more": true,
      "last_id": "<string>",
      "object": "<string>"
    }

GET

/

v1

/

chat

/

completions

/

{completion\_id}

/

messages

Try it

200

400

401

500

502

Copy

    {
      "data": [\
        {\
          "content": "<string>",\
          "content_parts": [\
            {\
              "text": "<string>",\
              "type": "input_text"\
            }\
          ],\
          "id": "<string>",\
          "name": "<string>",\
          "role": "<string>"\
        }\
      ],
      "first_id": "<string>",
      "has_more": true,
      "last_id": "<string>",
      "object": "<string>"
    }

#### Path Parameters

[​](https://docs.sudoapp.dev/api-reference/ai-routing/chat-completion-messages#parameter-completion-id)

completion\_id

string

required

ID of the chat completion

#### Query Parameters

[​](https://docs.sudoapp.dev/api-reference/ai-routing/chat-completion-messages#parameter-after)

after

string

Identifier for the last message from the previous pagination request.

[​](https://docs.sudoapp.dev/api-reference/ai-routing/chat-completion-messages#parameter-limit)

limit

integer

Number of messages to retrieve.

Required range: `x >= 0`

[​](https://docs.sudoapp.dev/api-reference/ai-routing/chat-completion-messages#parameter-order)

order

string

Sort order for messages by timestamp. Use asc for ascending order or desc for descending order. Defaults to asc.

#### Response

200

application/json

Chat completion messages gotten successfully

[​](https://docs.sudoapp.dev/api-reference/ai-routing/chat-completion-messages#response-data)

data

object\[\]

required

Show child attributes

[​](https://docs.sudoapp.dev/api-reference/ai-routing/chat-completion-messages#response-first-id)

first\_id

string

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/chat-completion-messages#response-has-more)

has\_more

boolean

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/chat-completion-messages#response-last-id)

last\_id

string

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/chat-completion-messages#response-object)

object

string

required

[Delete Chat Completion](https://docs.sudoapp.dev/api-reference/ai-routing/delete-chat-completion)
[Generate Image](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image)

⌘I

---

# Update Chat Completion - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/api-reference/ai-routing/update-chat-completion#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

AI Routing

Update Chat Completion

200

400

401

500

502

Copy

    {
      "choices": [\
        {\
          "finish_reason": "<string>",\
          "index": 1,\
          "logprobs": "<any>",\
          "message": {\
            "annotations": "<any>",\
            "audio": "<any>",\
            "content": "<string>",\
            "refusal": "<string>",\
            "role": "<string>",\
            "tool_calls": [\
              {\
                "function": {\
                  "arguments": "<string>",\
                  "name": "<string>"\
                },\
                "id": "<string>",\
                "type": "<string>"\
              }\
            ]\
          }\
        }\
      ],
      "created": 1,
      "id": "<string>",
      "model": "<string>",
      "object": "<string>",
      "service_tier": "<string>",
      "system_fingerprint": "<string>",
      "usage": {
        "completion_tokens": 1,
        "completion_tokens_details": "<any>",
        "prompt_tokens": 1,
        "prompt_tokens_details": "<any>",
        "total_tokens": 1
      }
    }

POST

/

v1

/

chat

/

completions

/

{completion\_id}

Try it

200

400

401

500

502

Copy

    {
      "choices": [\
        {\
          "finish_reason": "<string>",\
          "index": 1,\
          "logprobs": "<any>",\
          "message": {\
            "annotations": "<any>",\
            "audio": "<any>",\
            "content": "<string>",\
            "refusal": "<string>",\
            "role": "<string>",\
            "tool_calls": [\
              {\
                "function": {\
                  "arguments": "<string>",\
                  "name": "<string>"\
                },\
                "id": "<string>",\
                "type": "<string>"\
              }\
            ]\
          }\
        }\
      ],
      "created": 1,
      "id": "<string>",
      "model": "<string>",
      "object": "<string>",
      "service_tier": "<string>",
      "system_fingerprint": "<string>",
      "usage": {
        "completion_tokens": 1,
        "completion_tokens_details": "<any>",
        "prompt_tokens": 1,
        "prompt_tokens_details": "<any>",
        "total_tokens": 1
      }
    }

#### Path Parameters

[​](https://docs.sudoapp.dev/api-reference/ai-routing/update-chat-completion#parameter-completion-id)

completion\_id

string

required

ID of the chat completion

#### Body

application/json · object

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

[​](https://docs.sudoapp.dev/api-reference/ai-routing/update-chat-completion#body-key)

{key}

string

#### Response

200

application/json

Chat completion updated successfully

[​](https://docs.sudoapp.dev/api-reference/ai-routing/update-chat-completion#response-choices)

choices

object\[\]

required

Show child attributes

[​](https://docs.sudoapp.dev/api-reference/ai-routing/update-chat-completion#response-created)

created

integer

required

Required range: `x >= 0`

[​](https://docs.sudoapp.dev/api-reference/ai-routing/update-chat-completion#response-id)

id

string

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/update-chat-completion#response-model)

model

string

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/update-chat-completion#response-object)

object

string

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/update-chat-completion#response-usage)

usage

object

required

Show child attributes

[​](https://docs.sudoapp.dev/api-reference/ai-routing/update-chat-completion#response-service-tier)

service\_tier

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/update-chat-completion#response-system-fingerprint)

system\_fingerprint

string | null

[Get a Chat Completion](https://docs.sudoapp.dev/api-reference/ai-routing/get-a-chat-completion)
[Delete Chat Completion](https://docs.sudoapp.dev/api-reference/ai-routing/delete-chat-completion)

⌘I

---

# Create Chat Completion - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

AI Routing

Create Chat Completion

200

400

401

500

502

Copy

    {
      "choices": [\
        {\
          "finish_reason": "<string>",\
          "index": 1,\
          "logprobs": "<any>",\
          "message": {\
            "annotations": "<any>",\
            "audio": "<any>",\
            "content": "<string>",\
            "refusal": "<string>",\
            "role": "<string>",\
            "tool_calls": [\
              {\
                "function": {\
                  "arguments": "<string>",\
                  "name": "<string>"\
                },\
                "id": "<string>",\
                "type": "<string>"\
              }\
            ]\
          }\
        }\
      ],
      "created": 1,
      "id": "<string>",
      "model": "<string>",
      "object": "<string>",
      "service_tier": "<string>",
      "system_fingerprint": "<string>",
      "usage": {
        "completion_tokens": 1,
        "completion_tokens_details": "<any>",
        "prompt_tokens": 1,
        "prompt_tokens_details": "<any>",
        "total_tokens": 1
      }
    }

POST

/

v1

/

chat

/

completions

Try it

200

400

401

500

502

Copy

    {
      "choices": [\
        {\
          "finish_reason": "<string>",\
          "index": 1,\
          "logprobs": "<any>",\
          "message": {\
            "annotations": "<any>",\
            "audio": "<any>",\
            "content": "<string>",\
            "refusal": "<string>",\
            "role": "<string>",\
            "tool_calls": [\
              {\
                "function": {\
                  "arguments": "<string>",\
                  "name": "<string>"\
                },\
                "id": "<string>",\
                "type": "<string>"\
              }\
            ]\
          }\
        }\
      ],
      "created": 1,
      "id": "<string>",
      "model": "<string>",
      "object": "<string>",
      "service_tier": "<string>",
      "system_fingerprint": "<string>",
      "usage": {
        "completion_tokens": 1,
        "completion_tokens_details": "<any>",
        "prompt_tokens": 1,
        "prompt_tokens_details": "<any>",
        "total_tokens": 1
      }
    }

#### Body

application/json

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#body-messages)

messages

object\[\]

required

*   Option 1
    
*   Option 2
    
*   Option 3
    
*   Option 4
    
*   Option 5
    

Show child attributes

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#body-model)

model

string

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#body-max-completion-tokens)

max\_completion\_tokens

integer | null

Required range: `x >= 0`

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#body-n)

n

integer | null

Required range: `x >= 0`

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#body-parallel-tool-calls)

parallel\_tool\_calls

boolean | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#body-stop-sequences)

stop\_sequences

string\[\] | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#body-stream)

stream

boolean | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#body-temperature)

temperature

number | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#body-tools)

tools

object\[\] | null

Show child attributes

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#body-top-p)

top\_p

number | null

#### Response

200

application/json

Chat completion created successfully

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#response-choices)

choices

object\[\]

required

Show child attributes

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#response-created)

created

integer

required

Required range: `x >= 0`

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#response-id)

id

string

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#response-model)

model

string

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#response-object)

object

string

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#response-usage)

usage

object

required

Show child attributes

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#response-service-tier)

service\_tier

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion#response-system-fingerprint)

system\_fingerprint

string | null

[List Chat Completions](https://docs.sudoapp.dev/api-reference/ai-routing/list-chat-completions)
[Get a Chat Completion](https://docs.sudoapp.dev/api-reference/ai-routing/get-a-chat-completion)

⌘I

---

# Image Input - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

Sudo SDK

Image Input

On this page

*   [Basic Image Input](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input#basic-image-input)
    
*   [Image from URL](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input#image-from-url)
    
*   [Image from Local File](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input#image-from-local-file)
    
*   [Advanced Image Analysis](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input#advanced-image-analysis)
    
*   [Multiple Images](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input#multiple-images)
    
*   [Next Steps](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input#next-steps)
    

Image input capabilities allow you to send images to vision-enabled AI models for analysis, description, and understanding.

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input#basic-image-input)

Basic Image Input
---------------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input#image-from-url)

Image from URL

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function analyzeImageFromUrl() {
      try {
        const response = await sudo.router.create({
          model: "gpt-4o",  // Vision-capable model
          messages: [\
            {\
              role: "user",\
              content: [\
                {\
                  type: "text",\
                  text: "What do you see in this image?"\
                },\
                {\
                  type: "image_url",\
                  imageUrl: {\
                    url: "https://example.com/image.jpg"\
                  }\
                }\
              ]\
            }\
          ]
        });
        
        console.log(response.choices[0].message.content);
      } catch (error) {
        console.error("Image analysis error:", error);
      }
    }
    
    analyzeImageFromUrl();
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input#image-from-local-file)

Image from Local File

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    import * as fs from 'fs';
    import * as path from 'path';
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    function encodeImageToBase64(imagePath: string): string {
      try {
        const imageBuffer = fs.readFileSync(imagePath);
        return imageBuffer.toString('base64');
      } catch (error) {
        throw new Error(`Failed to read image file: ${error}`);
      }
    }
    
    async function analyzeLocalImage(imagePath: string, prompt: string = "Describe this image"): Promise<string | null> {
      try {
        // Encode image to base64
        const base64Image = encodeImageToBase64(imagePath);
        
        // Determine image type from file extension
        const ext = path.extname(imagePath).toLowerCase();
        const mimeType = ext === '.png' ? 'image/png' : 
                        ext === '.webp' ? 'image/webp' : 
                        'image/jpeg';
        
        const response = await sudo.router.create({
          model: "gpt-4o",
          messages: [\
            {\
              role: "user",\
              content: [\
                {\
                  type: "text",\
                  text: prompt\
                },\
                {\
                  type: "image_url",\
                  imageUrl: {\
                    url: `data:${mimeType};base64,${base64Image}`\
                  }\
                }\
              ]\
            }\
          ]
        });
        
        return response.choices[0].message.content;
      } catch (error) {
        console.error("Local image analysis error:", error);
        return null;
      }
    }
    
    // Usage
    async function example() {
      const description = await analyzeLocalImage("path/to/your/image.jpg", "What objects can you identify in this image?");
      if (description) {
        console.log(description);
      }
    }
    
    example();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input#advanced-image-analysis)

Advanced Image Analysis
---------------------------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input#multiple-images)

Multiple Images

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    import * as fs from 'fs';
    import * as path from 'path';
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    function encodeImage(imagePath: string): string {
      const imageBuffer = fs.readFileSync(imagePath);
      return imageBuffer.toString('base64');
    }
    
    function getMimeType(imagePath: string): string {
      const ext = path.extname(imagePath).toLowerCase();
      switch (ext) {
        case '.png': return 'image/png';
        case '.webp': return 'image/webp';
        case '.gif': return 'image/gif';
        default: return 'image/jpeg';
      }
    }
    
    async function compareImages(imagePaths: string[], prompt: string = "Compare these images"): Promise<string | null> {
      try {
        // Build content with text and multiple images
        const content: any[] = [{ type: "text", text: prompt }];
        
        for (const imagePath of imagePaths) {
          const base64Image = encodeImage(imagePath);
          const mimeType = getMimeType(imagePath);
          
          content.push({
            type: "image_url",
            imageUrl: {
              url: `data:${mimeType};base64,${base64Image}`
            }
          });
        }
        
        const response = await sudo.router.create({
          model: "gpt-4o",
          messages: [{ role: "user", content: content }]
        });
        
        return response.choices[0].message.content;
      } catch (error) {
        console.error("Image comparison error:", error);
        return null;
      }
    }
    
    // Compare two images
    async function imageComparisonExample() {
      const comparison = await compareImages(
        ["image1.jpg", "image2.jpg"],
        "What are the main differences between these two images?"
      );
      
      if (comparison) {
        console.log(comparison);
      }
    }
    
    imageComparisonExample();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input#next-steps)

Next Steps
-------------------------------------------------------------------------------

1.  **[Reasoning](https://docs.sudoapp.dev/sdk/sudo-sdk/reasoning)
    ** - Advanced reasoning capabilities
2.  **[CRUD Operations](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations)
    ** - Manage stored completions

Image input requires vision-capable models like GPT-4o, Claude Sonnet-4, or Gemini Pro Vision. Ensure your images are in supported formats (JPEG, PNG, WebP). Both TypeScript and Python SDKs provide comprehensive support for image analysis with proper error handling and type safety.

[Structured Output](https://docs.sudoapp.dev/sdk/sudo-sdk/structured-output)
[Audio Chat Completions](https://docs.sudoapp.dev/sdk/sudo-sdk/audio_chat_completions)

⌘I

---

# Delete Chat Completion - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/api-reference/ai-routing/delete-chat-completion#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

AI Routing

Delete Chat Completion

200

400

401

500

502

Copy

    {
      "deleted": true,
      "id": "<string>",
      "object": "<string>"
    }

DELETE

/

v1

/

chat

/

completions

/

{completion\_id}

Try it

200

400

401

500

502

Copy

    {
      "deleted": true,
      "id": "<string>",
      "object": "<string>"
    }

#### Path Parameters

[​](https://docs.sudoapp.dev/api-reference/ai-routing/delete-chat-completion#parameter-completion-id)

completion\_id

string

required

ID of the chat completion

#### Response

200

application/json

Chat completion deleted successfully

[​](https://docs.sudoapp.dev/api-reference/ai-routing/delete-chat-completion#response-deleted)

deleted

boolean

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/delete-chat-completion#response-id)

id

string

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/delete-chat-completion#response-object)

object

string

required

[Update Chat Completion](https://docs.sudoapp.dev/api-reference/ai-routing/update-chat-completion)
[Chat Completion Messages](https://docs.sudoapp.dev/api-reference/ai-routing/chat-completion-messages)

⌘I

---

# Get supported models list (for devs to use) - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/api-reference/system/get-supported-models-list-for-devs-to-use#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

System

Get supported models list (for devs to use)

200

401

500

Copy

    {
      "data": [\
        {\
          "created_at": "2023-11-07T05:31:56Z",\
          "model_name": "<string>",\
          "model_provider": "<string>",\
          "sudo_model_id": 123\
        }\
      ],
      "first_id": "<string>",
      "has_more": true,
      "last_id": "<string>"
    }

GET

/

v1

/

models

Try it

200

401

500

Copy

    {
      "data": [\
        {\
          "created_at": "2023-11-07T05:31:56Z",\
          "model_name": "<string>",\
          "model_provider": "<string>",\
          "sudo_model_id": 123\
        }\
      ],
      "first_id": "<string>",
      "has_more": true,
      "last_id": "<string>"
    }

#### Response

200

application/json

Supported models retrieved successfully

[​](https://docs.sudoapp.dev/api-reference/system/get-supported-models-list-for-devs-to-use#response-data)

data

object\[\]

required

Show child attributes

[​](https://docs.sudoapp.dev/api-reference/system/get-supported-models-list-for-devs-to-use#response-first-id)

first\_id

string

required

[​](https://docs.sudoapp.dev/api-reference/system/get-supported-models-list-for-devs-to-use#response-has-more)

has\_more

boolean

required

[​](https://docs.sudoapp.dev/api-reference/system/get-supported-models-list-for-devs-to-use#response-last-id)

last\_id

string

required

[System Health](https://docs.sudoapp.dev/api-reference/system/system-health)
[List Chat Completions](https://docs.sudoapp.dev/api-reference/ai-routing/list-chat-completions)

⌘I

---

# Tool Calling - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/sdk/sudo-sdk/tool-calling#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

Sudo SDK

Tool Calling

On this page

*   [Basic Tool Calling](https://docs.sudoapp.dev/sdk/sudo-sdk/tool-calling#basic-tool-calling)
    
*   [Simple Function Definition](https://docs.sudoapp.dev/sdk/sudo-sdk/tool-calling#simple-function-definition)
    
*   [Streaming with Tools](https://docs.sudoapp.dev/sdk/sudo-sdk/tool-calling#streaming-with-tools)
    
*   [Next Steps](https://docs.sudoapp.dev/sdk/sudo-sdk/tool-calling#next-steps)
    

Tool calling allows AI models to execute functions and interact with external systems, enabling more dynamic and powerful applications.

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/tool-calling#basic-tool-calling)

Basic Tool Calling
------------------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/tool-calling#simple-function-definition)

Simple Function Definition

Define a tool within your application that the AI model can call.

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    function getWeather(location: string): string {
      // This would normally call a real weather API
      return `The weather in ${location} is sunny and 75°F`;
    }
    
    // Define the tool for the AI
    const tools = [\
      {\
        type: "function" as const,\
        function: {\
          name: "get_weather",\
          description: "Get current weather information for a location",\
          parameters: {\
            type: "object",\
            properties: {\
              location: {\
                type: "string",\
                description: "The city and state, e.g. San Francisco, CA"\
              }\
            },\
            required: ["location"]\
          }\
        }\
      }\
    ];
    
    async function basicToolCalling() {
      try {
        const response = await sudo.router.create({
          model: "gpt-4o",
          messages: [\
            { role: "user", content: "What's the weather like in New York?" }\
          ],
          tools: tools,
          toolChoice: "auto"
        });
        
        const message = response.choices[0].message;
        
        // Check if the model wants to call a function
        if (message.toolCalls) {
          for (const toolCall of message.toolCalls) {
            if (toolCall.function.name === "get_weather") {
              const args = JSON.parse(toolCall.function.arguments);
              const weatherResult = getWeather(args.location);
              console.log(`Weather result: ${weatherResult}`);
            }
          }
        } else {
          console.log(`Response: ${message.content}`);
        }
      } catch (error) {
        console.error("Tool calling error:", error);
      }
    }
    
    basicToolCalling();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/tool-calling#streaming-with-tools)

Streaming with Tools
----------------------------------------------------------------------------------------------------

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function streamWithToolCalls() {
      const tools = [\
        {\
          type: "function" as const,\
          function: {\
            name: "search_database",\
            description: "Search for information in the database",\
            parameters: {\
              type: "object",\
              properties: {\
                query: { \
                  type: "string", \
                  description: "Search query" \
                }\
              },\
              required: ["query"]\
            }\
          }\
        }\
      ];
      
      try {
        const stream = await sudo.router.createStreaming({
          model: "gpt-4o",
          messages: [\
            { role: "user", content: "Find information about TypeScript frameworks" }\
          ],
          tools: tools,
          toolChoice: "auto"
        });
        
        const toolCalls: any[] = [];
        const contentParts: string[] = [];
        
        for await (const chunk of stream) {
          if (chunk.data?.choices) {
            for (const choice of chunk.data.choices) {
              if (choice.delta) {
                // Regular content
                if (choice.delta.content) {
                  const content = choice.delta.content;
                  contentParts.push(content);
                  process.stdout.write(content);
                }
                
                // Tool calls
                if (choice.delta.toolCalls) {
                  for (const toolCallDelta of choice.delta.toolCalls) {
                    // Handle streaming tool calls
                    console.log(`\n[Tool Call: ${toolCallDelta.function?.name}]`);
                    if (toolCallDelta.function?.arguments) {
                      console.log(`[Args: ${toolCallDelta.function.arguments}]`);
                    }
                  }
                }
              }
            }
          }
        }
        
        console.log();
      } catch (error) {
        console.error("Streaming tool calling error:", error);
      }
    }
    
    streamWithToolCalls();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/tool-calling#next-steps)

Next Steps
--------------------------------------------------------------------------------

1.  **[Structured Output](https://docs.sudoapp.dev/sdk/sudo-sdk/structured-output)
    ** - Generate JSON and structured data
2.  **[Image Input](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input)
    ** - Work with multimodal inputs
3.  **[Reasoning](https://docs.sudoapp.dev/sdk/sudo-sdk/reasoning)
    ** - Advanced reasoning capabilities

Tool calling works best with models like GPT-4o, Claude Sonnet-4, and other function-calling capable models. Always validate tool inputs and handle errors gracefully. Both TypeScript and Python SDKs provide the same powerful tool calling capabilities with language-appropriate patterns.

[Streaming](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming)
[Structured Output](https://docs.sudoapp.dev/sdk/sudo-sdk/structured-output)

⌘I

---

# Installation & Setup - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

Sudo SDK

Installation & Setup

On this page

*   [Installation](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#installation)
    
*   [Authentication](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#authentication)
    
*   [Environment Variable (Recommended)](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#environment-variable-recommended)
    
*   [Direct Configuration](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#direct-configuration)
    
*   [Basic Configuration](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#basic-configuration)
    
*   [Server URL](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#server-url)
    
*   [Retry Configuration](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#retry-configuration)
    
*   [Custom HTTP Client](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#custom-http-client)
    
*   [Async Support](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#async-support)
    
*   [Async/Await](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#async/await)
    
*   [Synchronous Usage (Python Only)](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#synchronous-usage-python-only)
    
*   [Error Handling](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#error-handling)
    
*   [Debugging](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#debugging)
    
*   [Using Environment Variable](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#using-environment-variable)
    
*   [Language-Specific Debug Configuration](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#language-specific-debug-configuration)
    
*   [IDE Support](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#ide-support)
    
*   [VS Code](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#vs-code)
    
*   [Other IDEs](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#other-ides)
    
*   [Next Steps](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#next-steps)
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#installation)

Installation
------------------------------------------------------------------------------------

The Sudo SDK is available for both Python and TypeScript/JavaScript. Choose your preferred language and package manager below.

npm

pnpm

yarn

bun

pip

poetry

uv

Copy

    npm add sudo-ai
    

**Python**: Requires Python 3.9 or later  
**TypeScript/JavaScript**: Requires Node.js 14+ and supports both CommonJS and ES Modules

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#authentication)

Authentication
----------------------------------------------------------------------------------------

The SDK uses API key authentication. You can obtain your API key from the [Sudo Developer Portal](https://sudoapp.dev/dev/login)
.

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#environment-variable-recommended)

Environment Variable (Recommended)

Set your API key as an environment variable:

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    // Your code here
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#direct-configuration)

Direct Configuration

Alternatively, you can pass the API key directly:

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: "your-api-key-here",
    });
    
    // Your code here
    

Never hardcode your API key in your source code, especially in code that will be committed to version control. Always use environment variables or secure configuration management.

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#basic-configuration)

Basic Configuration
--------------------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#server-url)

Server URL

By default, the SDK points to the production Sudo API. You can customize this:

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    // Production (default)
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: "your-api-key"
    });
    
    // Custom endpoint
    const customSudo = new Sudo({
      serverURL: "https://your-custom-endpoint.com/api",
      apiKey: "your-api-key"
    });
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#retry-configuration)

Retry Configuration

Configure retry behavior for failed requests:

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: "your-api-key",
      retryConfig: {
        strategy: "backoff",
        backoff: {
          initialInterval: 1,
          maxInterval: 50,
          exponent: 1.1,
          maxElapsedTime: 100
        },
        retryConnectionErrors: false
      }
    });
    
    // Client will use custom retry configuration
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#custom-http-client)

Custom HTTP Client

For advanced use cases, you can provide a custom HTTP client:

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    import { HTTPClient } from "sudo-ai/lib/http";
    
    const httpClient = new HTTPClient({
      fetcher: (request) => {
        return fetch(request);
      }
    });
    
    httpClient.addHook("beforeRequest", (request) => {
      const nextRequest = new Request(request, {
        signal: request.signal || AbortSignal.timeout(5000)
      });
    
      nextRequest.headers.set("x-custom-header", "value");
      return nextRequest;
    });
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: "your-api-key",
      httpClient
    });
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#async-support)

Async Support
--------------------------------------------------------------------------------------

Both SDKs support asynchronous operations:

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#async/await)

Async/Await

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function main() {
      try {
        const result = await sudo.system.healthCheck();
        console.log(result);
      } catch (error) {
        console.error("Error:", error);
      }
    }
    
    main();
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#synchronous-usage-python-only)

Synchronous Usage (Python Only)

Copy

    import os
    from sudo import Sudo
    
    with Sudo(
        server_url="https://sudoapp.dev/api",
        api_key=os.getenv("SUDO_API_KEY"),
    ) as client:
        response = client.system.health_check()
        print(response)
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#error-handling)

Error Handling
----------------------------------------------------------------------------------------

Both SDKs provide comprehensive error handling:

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    import * as errors from "sudo-ai/models/errors";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    try {
      const result = await sudo.system.getSupportedModels();
      console.log(result);
    } catch (error) {
      if (error instanceof errors.SudoError) {
        console.log(`SDK Error: ${error.message}`);
        console.log(`Status Code: ${error.statusCode}`);
        
        if (error instanceof errors.ErrorResponse) {
          console.log(`Error Details: ${error.data$.error}`);
        }
      }
    }
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#debugging)

Debugging
------------------------------------------------------------------------------

Enable debug logging to troubleshoot issues:

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#using-environment-variable)

Using Environment Variable

Copy

    export SUDO_DEBUG=true
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#language-specific-debug-configuration)

Language-Specific Debug Configuration

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
      debugLogger: console
    });
    
    // Warning: This will reveal secrets like API tokens in console output
    // Only use during local development
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#ide-support)

IDE Support
----------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#vs-code)

VS Code

Both SDKs work well with VS Code out of the box. For enhanced type checking: **TypeScript:**

Copy

    {
        "typescript.preferences.includePackageJsonAutoImports": "on"
    }
    

**Python:**

Copy

    {
        "python.analysis.typeCheckingMode": "strict"
    }
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#other-ides)

Other IDEs

**PyCharm (Python):**

*   Install the [PyCharm Pydantic Plugin](https://docs.pydantic.dev/latest/integrations/pycharm/)
    
*   Enable Pydantic support in project settings

**WebStorm (TypeScript):**

*   TypeScript support is built-in
*   Enable TypeScript language service

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/installation#next-steps)

Next Steps
--------------------------------------------------------------------------------

Now that you have the SDK installed and configured:

1.  **[Try System Endpoints](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints)
    ** - Test your setup with health checks
2.  **[Create AI Responses](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses)
    ** - Start building AI-powered features
3.  **[Explore Streaming](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming)
    ** - Add real-time capabilities

Both SDKs follow semantic versioning. Pin to a specific version in production to ensure stability:**Python:**

Copy

    pip install sudo-ai==0.1.0
    

**TypeScript:**

Copy

    npm install [email protected]
    

[Introduction](https://docs.sudoapp.dev/sdk/sudo-sdk)
[System Endpoints](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints)

⌘I

---

# Create Response - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

AI Routing

Create Response

200

400

401

500

502

Copy

    {
      "background": true,
      "conversation": null,
      "created_at": 123,
      "error": "<any>",
      "id": "<string>",
      "incomplete_details": null,
      "instructions": null,
      "max_output_tokens": 1,
      "max_tool_calls": 1,
      "metadata": "<any>",
      "model": "<string>",
      "object": "<string>",
      "output": [\
        {\
          "content": "<string>",\
          "role": "<string>",\
          "status": "<string>",\
          "type": "<string>"\
        }\
      ],
      "parallel_tool_calls": true,
      "previous_response_id": "<string>",
      "prompt": "<any>",
      "prompt_cache_key": "<string>",
      "reasoning": "<any>",
      "safety_identifier": "<string>",
      "service_tier": "<string>",
      "status": "<string>",
      "temperature": 123,
      "text": "<any>",
      "tool_choice": null,
      "tools": [\
        "<any>"\
      ],
      "top_logprobs": 1,
      "top_p": 123,
      "truncation": "<string>",
      "usage": null
    }

POST

/

v1

/

responses

Try it

200

400

401

500

502

Copy

    {
      "background": true,
      "conversation": null,
      "created_at": 123,
      "error": "<any>",
      "id": "<string>",
      "incomplete_details": null,
      "instructions": null,
      "max_output_tokens": 1,
      "max_tool_calls": 1,
      "metadata": "<any>",
      "model": "<string>",
      "object": "<string>",
      "output": [\
        {\
          "content": "<string>",\
          "role": "<string>",\
          "status": "<string>",\
          "type": "<string>"\
        }\
      ],
      "parallel_tool_calls": true,
      "previous_response_id": "<string>",
      "prompt": "<any>",
      "prompt_cache_key": "<string>",
      "reasoning": "<any>",
      "safety_identifier": "<string>",
      "service_tier": "<string>",
      "status": "<string>",
      "temperature": 123,
      "text": "<any>",
      "tool_choice": null,
      "tools": [\
        "<any>"\
      ],
      "top_logprobs": 1,
      "top_p": 123,
      "truncation": "<string>",
      "usage": null
    }

#### Body

application/json

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-background)

background

boolean | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-conversation)

conversation

string | nullany

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-include)

include

any\[\] | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-input)

input

string | nullobject\[\] | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-instructions)

instructions

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-max-output-tokens)

max\_output\_tokens

integer | null

Required range: `x >= 0`

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-max-tool-calls)

max\_tool\_calls

integer | null

Required range: `x >= 0`

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-metadata)

metadata

any

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-model)

model

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-parallel-tool-calls)

parallel\_tool\_calls

boolean | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-previous-response-id)

previous\_response\_id

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-prompt)

prompt

any

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-prompt-cache-key)

prompt\_cache\_key

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-reasoning)

reasoning

any

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-safety-identifier)

safety\_identifier

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-service-tier)

service\_tier

string | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-store)

store

boolean | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-stream)

stream

boolean | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-stream-options)

stream\_options

any

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-temperature)

temperature

number | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-text)

text

any

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-tool-choice)

tool\_choice

string | nullany

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-tools)

tools

any\[\] | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-top-logprobs)

top\_logprobs

integer | null

Required range: `x >= 0`

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-top-p)

top\_p

number | null

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#body-truncation)

truncation

string | null

#### Response

200

application/json

Chat completion created successfully

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-created-at)

created\_at

integer

required

Unix timestamp (in seconds) when the response was created

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-id)

id

string

required

Unique identifier for the response

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-model)

model

string

required

The model used to generate the response

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-object)

object

string

required

The object type, always "response"

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-status)

status

string

required

The status of the response (e.g., "in\_progress", "completed", "failed", "cancelled", "incomplete")

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-background)

background

boolean | null

Whether the response was generated in the background

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-conversation)

conversation

object | null

The ID of the conversation this response belongs to

Show child attributes

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-error)

error

any

Error information if the response failed

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-incomplete-details)

incomplete\_details

object | null

Details about why the response is incomplete (if status is "incomplete")

Show child attributes

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-instructions)

instructions

string | nullany\[\] | null

Instructions provided to the model

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-max-output-tokens)

max\_output\_tokens

integer | null

Maximum number of output tokens

Required range: `x >= 0`

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-max-tool-calls)

max\_tool\_calls

integer | null

Maximum number of tool calls

Required range: `x >= 0`

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-metadata)

metadata

any

Set of key-value pairs that can be attached to an object

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-output)

output

object\[\] | null

The output items generated by the model

*   Option 1
    
*   Option 2
    
*   Option 3
    
*   Option 4
    
*   Option 5
    
*   Option 6
    
*   Option 7
    
*   Option 8
    
*   Option 9
    
*   Option 10
    
*   Option 11
    
*   Option 12
    
*   Option 13
    
*   Option 14
    
*   Option 15
    
*   Option 16
    
*   Option 17
    
*   Option 18
    
*   Option 19
    

Show child attributes

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-parallel-tool-calls)

parallel\_tool\_calls

boolean | null

Whether parallel tool calls are enabled

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-previous-response-id)

previous\_response\_id

string | null

ID of the previous response

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-prompt)

prompt

any

Prompt configuration

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-prompt-cache-key)

prompt\_cache\_key

string | null

Prompt cache key

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-reasoning)

reasoning

any

Reasoning configuration

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-safety-identifier)

safety\_identifier

string | null

Safety identifier

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-service-tier)

service\_tier

string | null

Service tier used

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-temperature)

temperature

number | null

Temperature sampling parameter

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-text)

text

any

Text configuration

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-tool-choice)

tool\_choice

string | nullany

Tool choice configuration

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-tools)

tools

any\[\] | null

Tools available to the model

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-top-logprobs)

top\_logprobs

integer | null

Number of top log probabilities to return

Required range: `x >= 0`

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-top-p)

top\_p

number | null

Top-p sampling parameter

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-truncation)

truncation

string | null

Truncation strategy

[​](https://docs.sudoapp.dev/api-reference/ai-routing/create-response#response-usage)

usage

object | null

Usage statistics for the API call

Show child attributes

[Generate Image](https://docs.sudoapp.dev/api-reference/ai-routing/generate-image)

⌘I

---

# Structured Output - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/sdk/sudo-sdk/structured-output#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

Sudo SDK

Structured Output

On this page

*   [Basic Structured Output](https://docs.sudoapp.dev/sdk/sudo-sdk/structured-output#basic-structured-output)
    
*   [Simple JSON Schema](https://docs.sudoapp.dev/sdk/sudo-sdk/structured-output#simple-json-schema)
    
*   [Complex Data Extraction](https://docs.sudoapp.dev/sdk/sudo-sdk/structured-output#complex-data-extraction)
    
*   [Product Information Extraction](https://docs.sudoapp.dev/sdk/sudo-sdk/structured-output#product-information-extraction)
    
*   [Next Steps](https://docs.sudoapp.dev/sdk/sudo-sdk/structured-output#next-steps)
    

Structured output ensures AI responses conform to specific JSON schemas, enabling reliable data extraction and integration with applications.

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/structured-output#basic-structured-output)

Basic Structured Output
---------------------------------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/structured-output#simple-json-schema)

Simple JSON Schema

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    // Define a JSON schema for a person
    const personSchema = {
      type: "object",
      properties: {
        name: { type: "string" },
        age: { type: "integer" },
        email: { type: "string", format: "email" },
        skills: {
          type: "array",
          items: { type: "string" }
        }
      },
      required: ["name", "age", "email"]
    };
    
    // Define TypeScript interface for type safety
    interface Person {
      name: string;
      age: number;
      email: string;
      skills: string[];
    }
    
    async function basicStructuredOutput() {
      try {
        const response = await sudo.router.create({
          model: "gpt-4o",
          messages: [\
            {\
              role: "user",\
              content: "Create a person profile for a software engineer named Alice"\
            }\
          ],
          responseFormat: {
            type: "json_schema",
            jsonSchema: {
              name: "person",
              schema: personSchema,
              strict: true
            }
          }
        });
        
        // Parse the structured response
        const personData: Person = JSON.parse(response.choices[0].message.content);
        console.log(`Name: ${personData.name}`);
        console.log(`Age: ${personData.age}`);
        console.log(`Email: ${personData.email}`);
        console.log(`Skills: ${personData.skills.join(', ')}`);
      } catch (error) {
        console.error("Structured output error:", error);
      }
    }
    
    basicStructuredOutput();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/structured-output#complex-data-extraction)

Complex Data Extraction
---------------------------------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/structured-output#product-information-extraction)

Product Information Extraction

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    // Complex schema for product data
    const productSchema = {
      type: "object",
      properties: {
        products: {
          type: "array",
          items: {
            type: "object",
            properties: {
              name: { type: "string" },
              price: { type: "number" },
              category: { type: "string" },
              features: {
                type: "array",
                items: { type: "string" }
              },
              rating: { type: "number", minimum: 0, maximum: 5 },
              inStock: { type: "boolean" }
            },
            required: ["name", "price", "category", "inStock"]
          }
        },
        totalCount: { type: "integer" },
        averagePrice: { type: "number" }
      },
      required: ["products", "totalCount"]
    };
    
    // Define TypeScript interfaces for type safety
    interface Product {
      name: string;
      price: number;
      category: string;
      features?: string[];
      rating?: number;
      inStock: boolean;
    }
    
    interface ProductExtraction {
      products: Product[];
      totalCount: number;
      averagePrice?: number;
    }
    
    async function extractProductData(text: string): Promise<ProductExtraction | null> {
      try {
        const response = await sudo.router.create({
          model: "gpt-4o",
          messages: [\
            {\
              role: "system",\
              content: "Extract product information from the given text and format it according to the specified schema."\
            },\
            {\
              role: "user",\
              content: `Extract product data from this text: ${text}`\
            }\
          ],
          responseFormat: {
            type: "json_schema",
            jsonSchema: {
              name: "product_extraction",
              schema: productSchema,
              strict: true
            }
          }
        });
        
        return JSON.parse(response.choices[0].message.content) as ProductExtraction;
      } catch (error) {
        console.error("Product extraction error:", error);
        return null;
      }
    }
    
    // Example usage
    async function productExtractionExample() {
      const productText = `
    We have several laptops available:
    1. MacBook Pro 16" - $2499, excellent performance, 16GB RAM, M2 chip, in stock
    2. Dell XPS 13 - $1299, ultraportable, 8GB RAM, Intel i7, limited stock
    3. ThinkPad X1 - $1899, business laptop, 16GB RAM, excellent keyboard, in stock
    `;
    
      const result = await extractProductData(productText);
      if (result) {
        console.log(`Found ${result.totalCount} products:`);
        result.products.forEach(product => {
          console.log(`- ${product.name}: $${product.price} (${product.inStock ? 'In Stock' : 'Limited Stock'})`);
        });
      }
    }
    
    productExtractionExample();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/structured-output#next-steps)

Next Steps
-------------------------------------------------------------------------------------

1.  **[Image Input](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input)
    ** - Work with multimodal inputs
2.  **[Reasoning](https://docs.sudoapp.dev/sdk/sudo-sdk/reasoning)
    ** - Advanced reasoning capabilities
3.  **[CRUD Operations](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations)
    ** - Manage stored completions

Structured output works best with models that support JSON schema validation like GPT-4o, Claude Sonnet-4, and other recent models. Both TypeScript and Python SDKs provide excellent type safety and validation capabilities for structured data extraction.

[Tool Calling](https://docs.sudoapp.dev/sdk/sudo-sdk/tool-calling)
[Image Input](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input)

⌘I

---

# List Chat Completions - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/api-reference/ai-routing/list-chat-completions#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

AI Routing

List Chat Completions

200

401

500

502

Copy

    {
      "data": [\
        {\
          "choices": [\
            {\
              "finish_reason": "<string>",\
              "index": 1,\
              "logprobs": "<any>",\
              "message": {\
                "annotations": "<any>",\
                "audio": "<any>",\
                "content": "<string>",\
                "refusal": "<string>",\
                "role": "<string>",\
                "tool_calls": [\
                  {\
                    "function": {\
                      "arguments": "<string>",\
                      "name": "<string>"\
                    },\
                    "id": "<string>",\
                    "type": "<string>"\
                  }\
                ]\
              }\
            }\
          ],\
          "created": 1,\
          "id": "<string>",\
          "model": "<string>",\
          "object": "<string>",\
          "service_tier": "<string>",\
          "system_fingerprint": "<string>",\
          "usage": {\
            "completion_tokens": 1,\
            "completion_tokens_details": "<any>",\
            "prompt_tokens": 1,\
            "prompt_tokens_details": "<any>",\
            "total_tokens": 1\
          }\
        }\
      ],
      "first_id": "<string>",
      "has_more": true,
      "last_id": "<string>",
      "object": "<string>"
    }

GET

/

v1

/

chat

/

completions

Try it

200

401

500

502

Copy

    {
      "data": [\
        {\
          "choices": [\
            {\
              "finish_reason": "<string>",\
              "index": 1,\
              "logprobs": "<any>",\
              "message": {\
                "annotations": "<any>",\
                "audio": "<any>",\
                "content": "<string>",\
                "refusal": "<string>",\
                "role": "<string>",\
                "tool_calls": [\
                  {\
                    "function": {\
                      "arguments": "<string>",\
                      "name": "<string>"\
                    },\
                    "id": "<string>",\
                    "type": "<string>"\
                  }\
                ]\
              }\
            }\
          ],\
          "created": 1,\
          "id": "<string>",\
          "model": "<string>",\
          "object": "<string>",\
          "service_tier": "<string>",\
          "system_fingerprint": "<string>",\
          "usage": {\
            "completion_tokens": 1,\
            "completion_tokens_details": "<any>",\
            "prompt_tokens": 1,\
            "prompt_tokens_details": "<any>",\
            "total_tokens": 1\
          }\
        }\
      ],
      "first_id": "<string>",
      "has_more": true,
      "last_id": "<string>",
      "object": "<string>"
    }

#### Query Parameters

[​](https://docs.sudoapp.dev/api-reference/ai-routing/list-chat-completions#parameter-after)

after

string

Identifier for the last chat completion from the previous pagination request.

[​](https://docs.sudoapp.dev/api-reference/ai-routing/list-chat-completions#parameter-limit)

limit

integer

Number of Chat Completions to retrieve.

Required range: `x >= 0`

[​](https://docs.sudoapp.dev/api-reference/ai-routing/list-chat-completions#parameter-metadata)

metadata

object

A list of metadata keys to filter the Chat Completions by. Example: metadata\[key1\]=value1&metadata\[key2\]=value2

Show child attributes

[​](https://docs.sudoapp.dev/api-reference/ai-routing/list-chat-completions#parameter-model)

model

string

The model used to generate the Chat Completions.

[​](https://docs.sudoapp.dev/api-reference/ai-routing/list-chat-completions#parameter-order)

order

string

Sort order for Chat Completions by timestamp. Use asc for ascending order or desc for descending order. Defaults to asc.

#### Response

200

application/json

Chat completions listed successfully

[​](https://docs.sudoapp.dev/api-reference/ai-routing/list-chat-completions#response-data)

data

object\[\]

required

Show child attributes

[​](https://docs.sudoapp.dev/api-reference/ai-routing/list-chat-completions#response-first-id)

first\_id

string

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/list-chat-completions#response-has-more)

has\_more

boolean

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/list-chat-completions#response-last-id)

last\_id

string

required

[​](https://docs.sudoapp.dev/api-reference/ai-routing/list-chat-completions#response-object)

object

string

required

[Get supported models list (for devs to use)](https://docs.sudoapp.dev/api-reference/system/get-supported-models-list-for-devs-to-use)
[Create Chat Completion](https://docs.sudoapp.dev/api-reference/ai-routing/create-chat-completion)

⌘I

---

# Streaming - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

Sudo SDK

Streaming

On this page

*   [Basic Streaming](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#basic-streaming)
    
*   [Simple Streaming Example](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#simple-streaming-example)
    
*   [Stream Event Processing](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#stream-event-processing)
    
*   [Detailed Event Handling](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#detailed-event-handling)
    
*   [Handling Different Event Types](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#handling-different-event-types)
    
*   [Async Streaming](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#async-streaming)
    
*   [Basic Python Async Streaming](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#basic-python-async-streaming)
    
*   [Concurrent Streaming](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#concurrent-streaming)
    
*   [Error Handling and Recovery](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#error-handling-and-recovery)
    
*   [Robust Streaming with Retry](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#robust-streaming-with-retry)
    
*   [Best Practices](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#best-practices)
    
*   [Optimized Streaming Setup](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#optimized-streaming-setup)
    
*   [Next Steps](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#next-steps)
    

Streaming allows you to receive AI responses in real-time as they’re generated, providing a better user experience for long-form content generation and interactive applications.

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#basic-streaming)

Basic Streaming
---------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#simple-streaming-example)

Simple Streaming Example

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function simpleStreaming() {
      try {
        // Create a streaming response
        const stream = await sudo.router.createStreaming({
          model: "claude-sonnet-4-20250514",
          messages: [\
            { role: "user", content: "Write a short story about a robot" }\
          ]
        });
        
        // Process the stream
        console.log("AI Response:");
        for await (const chunk of stream) {
          if (chunk.data?.choices) {
            for (const choice of chunk.data.choices) {
              if (choice.delta?.content) {
                process.stdout.write(choice.delta.content);
              }
            }
          }
        }
        console.log(); // New line at the end
      } catch (error) {
        console.error("Streaming error:", error);
      }
    }
    
    simpleStreaming();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#stream-event-processing)

Stream Event Processing
-------------------------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#detailed-event-handling)

Detailed Event Handling

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function detailedStreamProcessing() {
      try {
        const stream = await sudo.router.createStreaming({
          model: "gpt-4o",
          messages: [\
            { role: "user", content: "Explain machine learning algorithms" }\
          ],
          streamOptions: { includeUsage: true }  // Include usage information
        });
        
        let fullResponse = "";
        let totalTokens = 0;
        
        for await (const chunk of stream) {
          // Check for data
          if (chunk.data) {
            // Process choices
            if (chunk.data.choices) {
              for (const choice of chunk.data.choices) {
                // Content delta
                if (choice.delta?.content) {
                  const content = choice.delta.content;
                  process.stdout.write(content);
                  fullResponse += content;
                }
                
                // Finish reason
                if (choice.finishReason) {
                  console.log(`\n[Finished: ${choice.finishReason}]`);
                }
              }
            }
            
            // Usage information (if available)
            if (chunk.data.usage) {
              totalTokens = chunk.data.usage.totalTokens;
              console.log(`\n[Tokens used: ${totalTokens}]`);
            }
          }
        }
        
        return {
          content: fullResponse,
          tokens: totalTokens
        };
      } catch (error) {
        console.error("Streaming error:", error);
        return null;
      }
    }
    
    detailedStreamProcessing().then(result => {
      if (result) {
        console.log(`\nCompleted. Total length: ${result.content.length} chars, ${result.tokens} tokens`);
      }
    });
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#handling-different-event-types)

Handling Different Event Types

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function comprehensiveStreamHandler() {
      try {
        const stream = await sudo.router.createStreaming({
          model: "gpt-4o",
          messages: [{ role: "user", content: "Write a poem about programming" }]
        });
        
        for await (const chunk of stream) {
          if (chunk.data) {
            // Model information
            if (chunk.data.model) {
              console.log(`[Model: ${chunk.data.model}]`);
            }
            
            // Process each choice
            if (chunk.data.choices) {
              chunk.data.choices.forEach((choice, i) => {
                if (choice.delta) {
                  // Role information
                  if (choice.delta.role) {
                    console.log(`\n[Role: ${choice.delta.role}]`);
                  }
                  
                  // Content
                  if (choice.delta.content) {
                    process.stdout.write(choice.delta.content);
                  }
                  
                  // Tool calls (if any)
                  if (choice.delta.toolCalls) {
                    console.log(`\n[Tool calls: ${JSON.stringify(choice.delta.toolCalls)}]`);
                  }
                }
                
                // Finish information
                if (choice.finishReason) {
                  console.log(`\n[Choice ${i} finished: ${choice.finishReason}]`);
                }
              });
            }
          }
        }
      } catch (error) {
        console.error("Streaming error:", error);
      }
    }
    
    comprehensiveStreamHandler();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#async-streaming)

Async Streaming
---------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#basic-python-async-streaming)

Basic Python Async Streaming

Python

Python

Copy

    import asyncio
    import os
    from sudo import Sudo
    
    async def async_stream_chat():
        async with Sudo(
            server_url="https://sudoapp.dev/api",
            api_key=os.getenv("SUDO_API_KEY"),
        ) as client:
            stream = await client.router.create_streaming_async(
                model="claude-sonnet-4-20250514",
                messages=[\
                    {"role": "user", "content": "Explain the benefits of async programming"}\
                ]
            )
            
            print("Async streaming response:")
            full_response = ""
            
            async with stream as event_stream:
                async for chunk in event_stream:
                    if chunk.data and chunk.data.choices:
                        for choice in chunk.data.choices:
                            if choice.delta and choice.delta.content:
                                content = choice.delta.content
                                print(content, end="", flush=True)
                                full_response += content
            
            print()  # New line
            return full_response
    
    # Run async streaming
    response = asyncio.run(async_stream_chat())
    print(f"Response length: {len(response)} characters")
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#concurrent-streaming)

Concurrent Streaming

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function streamSingleQuery(query: string, queryId: number): Promise<string> {
      try {
        console.log(`\n[Query ${queryId}] Starting: ${query}`);
        
        const stream = await sudo.router.createStreaming({
          model: "gpt-4o-mini",
          messages: [{ role: "user", content: query }]
        });
        
        let response = "";
        for await (const chunk of stream) {
          if (chunk.data?.choices) {
            for (const choice of chunk.data.choices) {
              if (choice.delta?.content) {
                const content = choice.delta.content;
                response += content;
                // Print with query ID prefix
                process.stdout.write(`[Q${queryId}] ${content}`);
              }
            }
          }
        }
        
        console.log(`\n[Query ${queryId}] Completed`);
        return response;
      } catch (error) {
        console.error(`[Query ${queryId}] Error:`, error);
        return "";
      }
    }
    
    async function streamMultipleQueries(): Promise<void> {
      try {
        const queries = [\
          "What is TypeScript?",\
          "Explain JavaScript",\
          "What is machine learning?"\
        ];
        
        // Start all streams concurrently
        const promises = queries.map((query, index) => 
          streamSingleQuery(query, index + 1)
        );
        
        const responses = await Promise.all(promises);
        
        console.log("\n\nAll queries completed!");
        responses.forEach((response, index) => {
          console.log(`Query ${index + 1} length: ${response.length} characters`);
        });
      } catch (error) {
        console.error("Concurrent streaming error:", error);
      }
    }
    
    streamMultipleQueries();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#error-handling-and-recovery)

Error Handling and Recovery
---------------------------------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#robust-streaming-with-retry)

Robust Streaming with Retry

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function robustStreamingWithRetry(
      query: string, 
      maxRetries: number = 3,
      backoffMs: number = 1000
    ): Promise<string | null> {
      for (let attempt = 1; attempt <= maxRetries; attempt++) {
        try {
          console.log(`Attempt ${attempt}: Starting stream for "${query}"`);
          
          const stream = await sudo.router.createStreaming({
            model: "gpt-4o",
            messages: [{ role: "user", content: query }],
            maxCompletionTokens: 150
          });
          
          let response = "";
          let lastChunkTime = Date.now();
          const timeoutMs = 30000; // 30 second timeout
          
          for await (const chunk of stream) {
            lastChunkTime = Date.now();
            
            if (chunk.data?.choices) {
              for (const choice of chunk.data.choices) {
                if (choice.delta?.content) {
                  const content = choice.delta.content;
                  response += content;
                  process.stdout.write(content);
                }
                
                if (choice.finishReason) {
                  console.log(`\nStream completed with reason: ${choice.finishReason}`);
                  return response;
                }
              }
            }
            
            // Check for timeout
            if (Date.now() - lastChunkTime > timeoutMs) {
              throw new Error("Stream timeout - no data received");
            }
          }
          
          return response;
          
        } catch (error) {
          console.error(`\nAttempt ${attempt} failed:`, error);
          
          if (attempt === maxRetries) {
            console.error("All retry attempts exhausted");
            return null;
          }
          
          // Exponential backoff
          const delay = backoffMs * Math.pow(2, attempt - 1);
          console.log(`Retrying in ${delay}ms...`);
          await new Promise(resolve => setTimeout(resolve, delay));
        }
      }
      
      return null;
    }
    
    // Usage
    async function robustStreamingExample() {
      const response = await robustStreamingWithRetry(
        "Explain the theory of relativity in simple terms"
      );
    
      if (response) {
        console.log(`\nSuccessfully received response: ${response.length} characters`);
      } else {
        console.log("Failed to get response after all retry attempts");
      }
    }
    
    robustStreamingExample();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#best-practices)

Best Practices
-------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#optimized-streaming-setup)

Optimized Streaming Setup

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    class OptimizedStreaming {
      private sudo: Sudo;
      private currentStream: any = null;
      private isShuttingDown = false;
    
      constructor() {
        this.sudo = new Sudo({
          serverURL: "https://sudoapp.dev/api",
          apiKey: process.env.SUDO_API_KEY ?? "",
        });
        this.setupSignalHandlers();
      }
    
      private setupSignalHandlers(): void {
        // Handle graceful shutdown
        process.on('SIGINT', () => this.signalHandler('SIGINT'));
        process.on('SIGTERM', () => this.signalHandler('SIGTERM'));
      }
    
      private signalHandler(signal: string): void {
        if (this.isShuttingDown) return;
        
        console.log(`\nReceived ${signal}. Shutting down gracefully...`);
        this.isShuttingDown = true;
        
        if (this.currentStream) {
          try {
            // Note: Actual stream cancellation depends on the specific implementation
            this.currentStream = null;
          } catch (error) {
            console.error("Error during stream cleanup:", error);
          }
        }
        
        process.exit(0);
      }
    
      async streamWithContext(message: string, model: string = "gpt-4o"): Promise<string | null> {
        if (this.isShuttingDown) {
          console.log("Cannot start stream: shutting down");
          return null;
        }
    
        try {
          const stream = await this.sudo.router.createStreaming({
            model,
            messages: [{ role: "user", content: message }],
            streamOptions: { includeUsage: true }
          });
    
          this.currentStream = stream;
          const responseParts: string[] = [];
    
          for await (const chunk of stream) {
            if (this.isShuttingDown) {
              console.log("\nStreaming interrupted by shutdown signal");
              break;
            }
    
            if (chunk.data?.choices) {
              for (const choice of chunk.data.choices) {
                if (choice.delta?.content) {
                  const content = choice.delta.content;
                  responseParts.push(content);
                  process.stdout.write(content);
                }
              }
            }
          }
    
          console.log();
          return responseParts.join('');
    
        } catch (error) {
          if (error instanceof Error && error.name === 'AbortError') {
            console.log("\nStreaming interrupted by user");
            return null;
          }
          console.error(`\nStreaming error: ${error}`);
          return null;
        } finally {
          this.currentStream = null;
        }
      }
    
      // Graceful shutdown method
      async shutdown(): Promise<void> {
        this.isShuttingDown = true;
        if (this.currentStream) {
          this.currentStream = null;
        }
      }
    }
    
    // Usage
    async function optimizedStreamingExample() {
      const streamer = new OptimizedStreaming();
      
      try {
        const result = await streamer.streamWithContext(
          "Write a comprehensive guide to TypeScript decorators"
        );
    
        if (result) {
          console.log(`\nStreaming completed. Response length: ${result.length} characters`);
        }
      } catch (error) {
        console.error("Streaming example error:", error);
      }
    }
    
    optimizedStreamingExample();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming#next-steps)

Next Steps
-----------------------------------------------------------------------------

Now that you understand streaming:

1.  **[Try Tool Calling](https://docs.sudoapp.dev/sdk/sudo-sdk/tool-calling)
    ** - Combine streaming with function calls
2.  **[Structured Output](https://docs.sudoapp.dev/sdk/sudo-sdk/structured-output)
    ** - Generate structured data
3.  **[CRUD Operations](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations)
    ** - Manage stored completions

Use streaming for long-form content generation and interactive applications. Remember to implement proper error handling and user interruption capabilities for the best user experience. Both TypeScript and Python SDKs provide excellent streaming support with robust error handling and async capabilities.

[Image Generation](https://docs.sudoapp.dev/sdk/sudo-sdk/image-generation)
[Tool Calling](https://docs.sudoapp.dev/sdk/sudo-sdk/tool-calling)

⌘I

---

# AI Router - Sudo Developer Platform

[Skip to main content](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

Sudo SDK

AI Router

On this page

*   [Basic Usage](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#basic-usage)
    
*   [Simple AI Response](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#simple-ai-response)
    
*   [Conversation with System Message](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#conversation-with-system-message)
    
*   [Multi-turn Conversation](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#multi-turn-conversation)
    
*   [Parameters and Configuration](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#parameters-and-configuration)
    
*   [Temperature and Randomness](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#temperature-and-randomness)
    
*   [Token Limits](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#token-limits)
    
*   [Frequency and Presence Penalties](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#frequency-and-presence-penalties)
    
*   [Stop Sequences](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#stop-sequences)
    
*   [Response Format Options](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#response-format-options)
    
*   [Multiple Choices](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#multiple-choices)
    
*   [Log Probabilities](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#log-probabilities)
    
*   [Metadata and Storage](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#metadata-and-storage)
    
*   [Adding Metadata](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#adding-metadata)
    
*   [Async Usage](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#async-usage)
    
*   [Basic Async](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#basic-async)
    
*   [Concurrent Requests](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#concurrent-requests)
    
*   [Error Handling](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#error-handling)
    
*   [Advanced Examples](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#advanced-examples)
    
*   [Chat Bot with Context Management](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#chat-bot-with-context-management)
    
*   [Next Steps](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#next-steps)
    

AI responses are the core functionality of the Sudo platform, allowing you to generate chat completions from a wide variety of models including GPT, Claude, Gemini, and more.

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#basic-usage)

Basic Usage
----------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#simple-ai-response)

Simple AI Response

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function simpleResponse() {
      const response = await sudo.router.create({
        model: "claude-sonnet-4-20250514",
        messages: [\
          { role: "user", content: "Hello! How are you?" }\
        ]
      });
      
      console.log(response.choices[0].message.content);
    }
    
    simpleResponse();
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#conversation-with-system-message)

Conversation with System Message

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function conversationWithSystem() {
      const response = await sudo.router.create({
        model: "gpt-4o",
        messages: [\
          {\
            role: "system", \
            content: "You are a helpful programming assistant specialized in TypeScript."\
          },\
          {\
            role: "user", \
            content: "How do I create a type-safe object from two arrays?"\
          }\
        ]
      });
      
      console.log(response.choices[0].message.content);
    }
    
    conversationWithSystem();
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#multi-turn-conversation)

Multi-turn Conversation

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    import * as readline from 'readline';
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function chatConversation() {
      // Conversation history
      const messages = [\
        { role: "system", content: "You are a helpful assistant." }\
      ];
      
      const rl = readline.createInterface({
        input: process.stdin,
        output: process.stdout
      });
      
      const askQuestion = (query: string): Promise<string> =>
        new Promise(resolve => rl.question(query, resolve));
      
      console.log("Chat started! Type 'quit' or 'exit' to end.");
      
      while (true) {
        try {
          // Get user input
          const userInput = await askQuestion("You: ");
          if (userInput.toLowerCase() === 'quit' || userInput.toLowerCase() === 'exit') {
            break;
          }
          
          // Add user message
          messages.push({ role: "user", content: userInput });
          
          // Get AI response
          const response = await sudo.router.create({
            model: "claude-sonnet-4-20250514",
            messages: messages
          });
          
          const aiMessage = response.choices[0].message.content;
          console.log(`AI: ${aiMessage}`);
          
          // Add AI response to conversation history
          messages.push({ role: "assistant", content: aiMessage });
          
        } catch (error) {
          console.error("Error:", error);
        }
      }
      
      rl.close();
    }
    
    chatConversation();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#parameters-and-configuration)

Parameters and Configuration
--------------------------------------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#temperature-and-randomness)

Temperature and Randomness

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function temperatureExamples() {
      // Deterministic output (low temperature)
      const deterministic = await sudo.router.create({
        model: "gpt-4o",
        messages: [{ role: "user", content: "Explain quantum computing" }],
        temperature: 0.1  // Very focused, consistent responses
      });
      
      // Creative output (high temperature)
      const creative = await sudo.router.create({
        model: "gpt-4o",
        messages: [{ role: "user", content: "Write a creative story" }],
        temperature: 0.9  // More random and creative
      });
      
      console.log("Deterministic:", deterministic.choices[0].message.content.substring(0, 100));
      console.log("Creative:", creative.choices[0].message.content.substring(0, 100));
    }
    
    temperatureExamples();
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#token-limits)

Token Limits

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function tokenLimitsExample() {
      const response = await sudo.router.create({
        model: "gpt-4o",
        messages: [{ role: "user", content: "Write a summary of machine learning" }],
        maxCompletionTokens: 150  // Limit response length
      });
      
      console.log(`Tokens used: ${response.usage.totalTokens}`);
      console.log(`Response: ${response.choices[0].message.content}`);
    }
    
    tokenLimitsExample();
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#frequency-and-presence-penalties)

Frequency and Presence Penalties

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function penaltiesExample() {
      const response = await sudo.router.create({
        model: "gpt-4o",
        messages: [{ role: "user", content: "List programming languages" }],
        frequencyPenalty: 0.5,  // Reduce repetition of frequent words
        presencePenalty: 0.5    // Encourage diverse vocabulary
      });
      
      console.log(response.choices[0].message.content);
    }
    
    penaltiesExample();
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#stop-sequences)

Stop Sequences

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function stopSequencesExample() {
      const response = await sudo.router.create({
        model: "gpt-4o",
        messages: [{ role: "user", content: "Count from 1 to 10" }],
        stop: ["5", "---"]  // Stop generation at these sequences
      });
      
      console.log(response.choices[0].message.content);
    }
    
    stopSequencesExample();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#response-format-options)

Response Format Options
----------------------------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#multiple-choices)

Multiple Choices

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function multipleChoicesExample() {
      const response = await sudo.router.create({
        model: "gpt-4o",
        messages: [{ role: "user", content: "Give me a creative business idea" }],
        n: 3  // Generate 3 different responses
      });
      
      response.choices.forEach((choice, index) => {
        console.log(`Idea ${index + 1}: ${choice.message.content}`);
        console.log("-".repeat(50));
      });
    }
    
    multipleChoicesExample();
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#log-probabilities)

Log Probabilities

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function logProbsExample() {
      const response = await sudo.router.create({
        model: "gpt-4o",
        messages: [{ role: "user", content: "The capital of France is" }],
        logprobs: true,
        topLogprobs: 3  // Show top 3 token probabilities
      });
      
      const choice = response.choices[0];
      if (choice.logprobs) {
        choice.logprobs.content.forEach(tokenInfo => {
          console.log(`Token: ${tokenInfo.token}`);
          console.log(`Probability: ${tokenInfo.logprob}`);
          console.log("Top alternatives:");
          tokenInfo.topLogprobs.forEach(alt => {
            console.log(`  ${alt.token}: ${alt.logprob}`);
          });
        });
      }
    }
    
    logProbsExample();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#metadata-and-storage)

Metadata and Storage
----------------------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#adding-metadata)

Adding Metadata

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function metadataExample() {
      const response = await sudo.router.create({
        model: "gpt-4o",
        messages: [{ role: "user", content: "Explain TypeScript decorators" }],
        metadata: {
          userId: "user_123",
          sessionId: "session_456",
          feature: "code_explanation",
          version: "1.0"
        },
        store: true  // Store for later retrieval (OpenAI compatible)
      });
      
      console.log(`Completion ID: ${response.id}`);
      console.log(`Response: ${response.choices[0].message.content}`);
    }
    
    metadataExample();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#async-usage)

Async Usage
----------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#basic-async)

Basic Async

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function asyncChat() {
      try {
        const response = await sudo.router.create({
          model: "claude-sonnet-4-20250514",
          messages: [{ role: "user", content: "Hello async world!" }]
        });
        
        return response.choices[0].message.content;
      } catch (error) {
        console.error("Error in async chat:", error);
        throw error;
      }
    }
    
    // Usage
    asyncChat()
      .then(result => console.log(result))
      .catch(error => console.error("Failed:", error));
    

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#concurrent-requests)

Concurrent Requests

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function processMultipleQueries() {
      const queries = [\
        "What is machine learning?",\
        "Explain neural networks",\
        "What is deep learning?",\
        "How do transformers work?"\
      ];
      
      try {
        // Process all queries concurrently
        const promises = queries.map(query =>
          sudo.router.create({
            model: "gpt-4o",
            messages: [{ role: "user", content: query }],
            maxCompletionTokens: 100
          })
        );
        
        const responses = await Promise.all(promises);
        
        // Display results
        responses.forEach((response, index) => {
          console.log(`Q: ${queries[index]}`);
          console.log(`A: ${response.choices[0].message.content}`);
          console.log(`Tokens: ${response.usage.totalTokens}`);
          console.log("---");
        });
        
      } catch (error) {
        console.error("Error processing queries:", error);
      }
    }
    
    processMultipleQueries();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#error-handling)

Error Handling
----------------------------------------------------------------------------------------

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    import * as errors from "sudo-ai/models/errors";
    
    const sudo = new Sudo({
      serverURL: "https://sudoapp.dev/api",
      apiKey: process.env.SUDO_API_KEY ?? "",
    });
    
    async function errorHandlingExample() {
      try {
        const response = await sudo.router.create({
          model: "non-existent-model",  // This will cause an error
          messages: [{ role: "user", content: "Hello" }]
        });
        
        console.log(response.choices[0].message.content);
        
      } catch (error) {
        if (error instanceof errors.SudoError) {
          console.log(`SDK Error: ${error.message}`);
          console.log(`Status Code: ${error.statusCode}`);
          console.log(`Response Body: ${error.body}`);
          
          // Handle specific error types
          if (error instanceof errors.ErrorResponse) {
            console.log(`Error Details: ${error.data$.error}`);
          }
        } else {
          console.log(`Unexpected error: ${error}`);
        }
      }
    }
    
    errorHandlingExample();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#advanced-examples)

Advanced Examples
----------------------------------------------------------------------------------------------

### 

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#chat-bot-with-context-management)

Chat Bot with Context Management

TypeScript

Typescript

Copy

    import { Sudo } from "sudo-ai";
    import * as readline from 'readline';
    
    interface ChatResponse {
      response?: string;
      tokensUsed?: number;
      model?: string;
      error?: string;
    }
    
    class ChatBot {
      private sudo: Sudo;
      private model: string;
      private maxHistory: number;
      private conversationHistory: Array<{role: string; content: string}>;
    
      constructor(model: string = "claude-sonnet-4-20250514", maxHistory: number = 10) {
        this.sudo = new Sudo({
          serverURL: "https://sudoapp.dev/api",
          apiKey: process.env.SUDO_API_KEY ?? "",
        });
        this.model = model;
        this.maxHistory = maxHistory;
        this.conversationHistory = [\
          {\
            role: "system",\
            content: `You are a helpful assistant. Current time: ${new Date().toISOString()}`\
          }\
        ];
      }
    
      async chat(message: string): Promise<ChatResponse> {
        try {
          // Add user message
          this.conversationHistory.push({ role: "user", content: message });
    
          // Trim history if too long
          if (this.conversationHistory.length > this.maxHistory) {
            // Keep system message and recent messages
            this.conversationHistory = [\
              this.conversationHistory[0]  // System message\
            ].concat(this.conversationHistory.slice(-(this.maxHistory - 1)));
          }
    
          const response = await this.sudo.router.create({
            model: this.model,
            messages: this.conversationHistory,
            temperature: 0.7
          });
    
          const aiResponse = response.choices[0].message.content;
    
          // Add AI response to history
          this.conversationHistory.push({ role: "assistant", content: aiResponse });
    
          return {
            response: aiResponse,
            tokensUsed: response.usage.totalTokens,
            model: response.model
          };
    
        } catch (error) {
          return { error: `Failed to get response: ${error}` };
        }
      }
    
      resetConversation(): void {
        // Reset the conversation history, keeping only the system message
        this.conversationHistory = [this.conversationHistory[0]];
      }
    
      getHistorySummary(): { totalMessages: number; userMessages: number; aiMessages: number } {
        const userMessages = this.conversationHistory.filter(m => m.role === "user").length;
        const aiMessages = this.conversationHistory.filter(m => m.role === "assistant").length;
        return {
          totalMessages: this.conversationHistory.length,
          userMessages,
          aiMessages
        };
      }
    }
    
    // Usage
    async function runChatBot() {
      const bot = new ChatBot();
      
      const rl = readline.createInterface({
        input: process.stdin,
        output: process.stdout
      });
    
      const askQuestion = (query: string): Promise<string> =>
        new Promise(resolve => rl.question(query, resolve));
    
      console.log("Chat started! Type 'quit', 'exit', 'reset', or 'summary'");
    
      while (true) {
        try {
          const userInput = await askQuestion("You: ");
          
          if (userInput.toLowerCase() === 'quit' || userInput.toLowerCase() === 'exit') {
            break;
          } else if (userInput.toLowerCase() === 'reset') {
            bot.resetConversation();
            console.log("Conversation reset!");
            continue;
          } else if (userInput.toLowerCase() === 'summary') {
            const summary = bot.getHistorySummary();
            console.log(`Conversation summary: ${JSON.stringify(summary)}`);
            continue;
          }
    
          const result = await bot.chat(userInput);
          if (result.error) {
            console.log(`Error: ${result.error}`);
          } else {
            console.log(`AI: ${result.response}`);
            console.log(`(Tokens: ${result.tokensUsed}, Model: ${result.model})`);
          }
        } catch (error) {
          console.error("Unexpected error:", error);
        }
      }
    
      rl.close();
    }
    
    runChatBot();
    

[​](https://docs.sudoapp.dev/sdk/sudo-sdk/ai-responses#next-steps)

Next Steps
--------------------------------------------------------------------------------

Now that you understand AI responses:

1.  **[Explore Streaming](https://docs.sudoapp.dev/sdk/sudo-sdk/streaming)
    ** - Add real-time streaming responses
2.  **[Try Tool Calling](https://docs.sudoapp.dev/sdk/sudo-sdk/tool-calling)
    ** - Enable function calling capabilities
3.  **[Structured Output](https://docs.sudoapp.dev/sdk/sudo-sdk/structured-output)
    ** - Generate JSON and structured data
4.  **[Image Input](https://docs.sudoapp.dev/sdk/sudo-sdk/image-input)
    ** - Work with multimodal inputs

Start with simple use cases and gradually add complexity. Use appropriate models for your needs - faster models for simple tasks, more capable models for complex reasoning. Both Python and TypeScript SDKs offer the same powerful capabilities with language-specific optimizations.

[System Endpoints](https://docs.sudoapp.dev/sdk/sudo-sdk/system-endpoints)
[Responses api](https://docs.sudoapp.dev/sdk/sudo-sdk/responses_api)

⌘I

---

# Page Not Found

[Skip to main content](https://docs.sudoapp.dev/sdk/sudo-sdk/responses_api#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

Sudo SDK

Page Not Found

404

Page Not Found
==============

We couldn't find the page. Maybe you were looking for one of these pages below?

[Responses API](https://docs.sudoapp.dev/api-ref/responses_api#responses-api)
[CRUD Operations](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#summary)
[OpenAI SDK Compatability](https://docs.sudoapp.dev/sdk/openai-sdk#openai-sdk-compatability)

⌘I

---

# Page Not Found

[Skip to main content](https://docs.sudoapp.dev/sdk/models#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

Page Not Found

404

Page Not Found
==============

We couldn't find the page. Maybe you were looking for one of these pages below?

[OpenAI SDK Compatability](https://docs.sudoapp.dev/sdk/openai-sdk#openai-sdk-compatability)
[Image Generation](https://docs.sudoapp.dev/sdk/sudo-sdk/image-generation#image-generation)
[CRUD Operations](https://docs.sudoapp.dev/sdk/sudo-sdk/crud-operations#summary)

⌘I

---

# Page Not Found

[Skip to main content](https://docs.sudoapp.dev/api-reference/system/get-supported-models#content-area)

[Sudo Developer Platform home page![light logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=73952c0e2019fd50f94b90e4431d8949)![dark logo](https://mintcdn.com/lita/J7nEUwxW1-PGv48x/SUDO_Darkmode.svg?fit=max&auto=format&n=J7nEUwxW1-PGv48x&q=85&s=f4276bf149da1733e72c5d4f2d6bbaa2)](https://docs.sudoapp.dev/)

Search...

⌘K

Search...

Navigation

Page Not Found

404

Page Not Found
==============

We couldn't find the page. Maybe you were looking for one of these pages below?

[Supported AI Models](https://docs.sudoapp.dev/overview/models#fetching-the-latest-models-via-api)
[Get supported models list (for devs to use)](https://docs.sudoapp.dev/api-reference/system/get-supported-models-list-for-devs-to-use#)
[Responses API](https://docs.sudoapp.dev/api-ref/responses_api#responses-api)

⌘I

---