GenAI Proxy

Ultimo aggiornamento il 4 nov 2026

In questa sezione

1

Overview

Vai alla sezione→

2

Headers

Vai alla sezione→

3

Supported providers and engines

Vai alla sezione→

4

Request body

Vai alla sezione→

5

Request examples

Vai alla sezione→

6

Responses

Vai alla sezione→

7

Notes

Vai alla sezione→

---

Overview

The GenAI Proxy lets you use the GenAI credits of your Algho license to send requests directly to a GenAI provider, outside of assistants, forms and conversations.

• Method: POST
• Path: /gen_ai/proxy
• Content-Type: application/json
• Authentication: algho-api-key header

The endpoint forwards the GenAI request to the default provider or to the one specified in the headers.

Headers

Header	Required	Description
algho-api-key	Yes	Algho API key used to authenticate the request.
provider	No	Provider to use. Supported values: openai, azure, google.
engine	No	Model to use for the selected provider.
apikey	No	Custom provider API key. When set, no credits are deducted from the Algho license.
endpoint	No, but required with a custom Azure key	Endpoint associated with the custom Azure apikey. Send it when using provider: azure with a custom key.

Supported providers and engines

OpenAI / Azure

• gpt-4.1
• gpt-4.1-mini
• gpt-5.1
• gpt-5-mini
• gpt-5-nano

Google Gemini

• gemini-2.5-flash-lite
• gemini-2.5-flash

Request body

The body must be valid JSON. Its structure may depend on the selected engine.

Example payload:

{
  "system_prompt": "You are a test assistant. Answer yes or no when users ask whether you are a test. Answer yes, since you are a test.",
  "user_prompt": "Are you a test?",
  "reasoning_effort": "medium"
}

informazioni

reasoning_effort applies only to engines that support reasoning.

Request examples

Standard request:

curl --request POST 'https://<host>/gen_ai/proxy' \
  --header 'Content-Type: application/json' \
  --header 'algho-api-key: <ALGHO_API_KEY>' \
  --header 'provider: azure' \
  --header 'engine: gpt-5.1' \
  --data-raw '{
    "system_prompt": "You are a test assistant. Answer yes or no when users ask whether you are a test. Answer yes, since you are a test.",
    "user_prompt": "Are you a test?",
    "reasoning_effort": "medium"
  }'

Request with a custom provider API key:

curl --request POST 'https://<host>/gen_ai/proxy' \
  --header 'Content-Type: application/json' \
  --header 'algho-api-key: <ALGHO_API_KEY>' \
  --header 'provider: azure' \
  --header 'engine: gpt-5.1' \
  --header 'apikey: <CUSTOM_PROVIDER_API_KEY>' \
  --header 'endpoint: https://<azure-resource>.openai.azure.com/' \
  --data-raw '{
    "system_prompt": "You are a test assistant. Answer yes or no when users ask whether you are a test. Answer yes, since you are a test.",
    "user_prompt": "Are you a test?",
    "reasoning_effort": "medium"
  }'

When the apikey header is sent, the GenAI credits of the Algho license are not deducted.

Responses

Missing algho-api-key header

Response code: 401

{
  "responseType": "UNAUTHORIZED",
  "messageCode": "UNAUTHORIZED",
  "serverTime": "2026-05-04 12:02:04"
}

Missing body

Response code: 403

{
  "responseType": "KO",
  "messageCode": "INVALID_PARAMS",
  "serverTime": "2026-05-04 12:02:19"
}

License without GenAI access

Response code: 403

{
  "message": "License has no access to GenAI",
  "responseType": "KO",
  "messageCode": "UNAUTHORIZED",
  "serverTime": "2026-05-04 12:04:56"
}

License without GenAI credits

Response code: 403

{
  "message": "No available GenAI credits",
  "responseType": "KO",
  "messageCode": "UNAUTHORIZED",
  "serverTime": "2026-05-04 12:05:57"
}

Successful response

Response code: 200

The response depends on the selected engine. Example of an OpenAI response:

{
  "top_logprobs": 0,
  "metadata": {},
  "max_tool_calls": 1,
  "presence_penalty": 0,
  "reasoning": {
    "effort": "medium"
  },
  "usage": {
    "total_tokens": 147,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 93,
    "input_tokens": 54,
    "output_tokens_details": {
      "reasoning_tokens": 84
    }
  },
  "created_at": 1.777889596E9,
  "tools": [],
  "content_filters": [
    {
      "content_filter_results": {
        "self_harm": {
          "filtered": false,
          "severity": "safe"
        },
        "jailbreak": {
          "filtered": false,
          "detected": false
        },
        "hate": {
          "filtered": false,
          "severity": "safe"
        },
        "sexual": {
          "filtered": false,
          "severity": "safe"
        },
        "violence": {
          "filtered": false,
          "severity": "safe"
        }
      },
      "content_filter_offsets": {
        "end_offset": 1445,
        "start_offset": 0,
        "check_offset": 0
      },
      "source_type": "prompt",
      "blocked": false,
      "content_filter_raw": []
    },
    {
      "content_filter_results": {
        "self_harm": {
          "filtered": false,
          "severity": "safe"
        },
        "protected_material_text": {
          "filtered": false,
          "detected": false
        },
        "protected_material_code": {
          "filtered": false,
          "detected": false
        },
        "hate": {
          "filtered": false,
          "severity": "safe"
        },
        "sexual": {
          "filtered": false,
          "severity": "safe"
        },
        "violence": {
          "filtered": false,
          "severity": "safe"
        }
      },
      "content_filter_offsets": {
        "end_offset": 312,
        "start_offset": 0,
        "check_offset": 0
      },
      "source_type": "completion",
      "blocked": false,
      "content_filter_raw": []
    }
  ],
  "output": [
    {
      "summary": [],
      "type": "reasoning",
      "id": "rs_073259b95261e2800169f8713d0c5c819581520e48313c34c8"
    },
    {
      "id": "msg_073259b95261e2800169f8713e77988195b6edfbca82a4610e",
      "role": "assistant",
      "type": "message",
      "content": [
        {
          "annotations": [],
          "text": "Yes.",
          "type": "output_text",
          "logprobs": []
        }
      ],
      "status": "completed"
    }
  ],
  "top_p": 1,
  "frequency_penalty": 0,
  "temperature": 1,
  "tool_choice": "auto",
  "model": "azure-5.1",
  "service_tier": "default",
  "id": "resp_073259b95261e2800169f8713c6d888195bf5c77663d05d88e",
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "medium"
  },
  "truncation": "disabled",
  "store": false,
  "completed_at": 1777889598,
  "parallel_tool_calls": true,
  "background": false,
  "object": "response",
  "max_output_tokens": 4096,
  "status": "completed"
}

Notes

• If provider and engine are not sent, GPT 5.1 on Azure is used.
• When using a custom apikey with Azure, also send endpoint.
• The structure of the 200 response may change depending on the selected provider or model.