Create chat completion · DeutschlandGPT

Creates a model response for the given chat conversation. OpenAI-compatible — point an OpenAI SDK at the Platform API base URL and swap the API key to migrate most apps.

Supports streaming via SSE (stream: true), function calling, structured output (json_schema), and multi-modal input (images, files).

Supported request fields: messages, model, max_completion_tokens, temperature, tools, parallel_tool_calls, reasoning_effort, response_format, stream, stream_options, prompt_cache_key. Other OpenAI fields — including the legacy max_tokens (use max_completion_tokens), top_p, n, stop, presence_penalty, frequency_penalty, seed, user, logit_bias, and tool_choice — are silently ignored. If you need tool_choice, use /v2/responses.

Prompt caching (Anthropic models). Cache lifetime is five minutes only — ttl: "1h" is NOT supported on this endpoint. Mark the last element of a stable prefix with cache_control and that prefix is cached upstream, so a later request that repeats it byte-for-byte is billed at the cache-read rate. Nothing is cached unless you ask: we never insert breakpoints on your behalf, because whether a cache write pays for itself depends on your access pattern, not on ours. Every cache lives five minutes — ttl: "1h" is accepted but not supported yet, and is reported as marker_ttl_unsupported rather than applied. prompt_cache in the response carries that warning plus any marker we could not place exactly as written. See Billing → Prompt caching.

Prompt caching (Mistral models). Mistral caches prefixes automatically, so cache_control does nothing there — send prompt_cache_key instead: one stable string per conversation or session, repeated on every request that shares a prefix. It is applied unconditionally and costs nothing extra (Mistral has no cache-write premium), your value is namespaced to your workspace, and a hit is a likelihood rather than a guarantee. See Billing → Mistral models.

POSThttps://api.deutschlandgpt.de/v2/chat/completionsTry it

Example request

curl https://api.deutschlandgpt.de/v2/chat/completions \
  -X POST \
  -H "Authorization: Bearer $DGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messages": [
    {
      "role": "system",
      "content": null
    }
  ],
  "model": "gpt-4o",
  "max_completion_tokens": 0,
  "temperature": 0,
  "stream": false,
  "stream_options": {},
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "string"
      }
    }
  ],
  "parallel_tool_calls": true,
  "reasoning_effort": "none",
  "response_format": {
    "type": "text"
  },
  "prompt_cache_key": "conversation-42"
}'

curl https://api.deutschlandgpt.de/v2/chat/completions \
  -X POST \
  -H "Authorization: Bearer $DGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messages": [
    {
      "role": "system",
      "content": null
    }
  ],
  "model": "gpt-4o",
  "max_completion_tokens": 0,
  "temperature": 0,
  "stream": false,
  "stream_options": {},
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "string"
      }
    }
  ],
  "parallel_tool_calls": true,
  "reasoning_effort": "none",
  "response_format": {
    "type": "text"
  },
  "prompt_cache_key": "conversation-42"
}'

import os, requests

response = requests.post(
    "https://api.deutschlandgpt.de/v2/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['DGPT_API_KEY']}"},
    json={
        "messages": [
            {
                "role": "system",
                "content": None
            }
        ],
        "model": "gpt-4o",
        "max_completion_tokens": 0,
        "temperature": 0,
        "stream": False,
        "stream_options": {},
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "string"
                }
            }
        ],
        "parallel_tool_calls": True,
        "reasoning_effort": "none",
        "response_format": {
            "type": "text"
        },
        "prompt_cache_key": "conversation-42"
    },
)

print(response.json())

import os, requests

response = requests.post(
    "https://api.deutschlandgpt.de/v2/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['DGPT_API_KEY']}"},
    json={
        "messages": [
            {
                "role": "system",
                "content": None
            }
        ],
        "model": "gpt-4o",
        "max_completion_tokens": 0,
        "temperature": 0,
        "stream": False,
        "stream_options": {},
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "string"
                }
            }
        ],
        "parallel_tool_calls": True,
        "reasoning_effort": "none",
        "response_format": {
            "type": "text"
        },
        "prompt_cache_key": "conversation-42"
    },
)

print(response.json())

const response = await fetch('https://api.deutschlandgpt.de/v2/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DGPT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "messages": [
      {
        "role": "system",
        "content": null
      }
    ],
    "model": "gpt-4o",
    "max_completion_tokens": 0,
    "temperature": 0,
    "stream": false,
    "stream_options": {},
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "string"
        }
      }
    ],
    "parallel_tool_calls": true,
    "reasoning_effort": "none",
    "response_format": {
      "type": "text"
    },
    "prompt_cache_key": "conversation-42"
  }),
});

console.log(await response.json());

const response = await fetch('https://api.deutschlandgpt.de/v2/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DGPT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "messages": [
      {
        "role": "system",
        "content": null
      }
    ],
    "model": "gpt-4o",
    "max_completion_tokens": 0,
    "temperature": 0,
    "stream": false,
    "stream_options": {},
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "string"
        }
      }
    ],
    "parallel_tool_calls": true,
    "reasoning_effort": "none",
    "response_format": {
      "type": "text"
    },
    "prompt_cache_key": "conversation-42"
  }),
});

console.log(await response.json());

Request body

messagesMessage[]required

Conversation history. Include system, user, assistant, tool, and developer messages.

modelstringrequired

Model ID (e.g. gpt-4o, claude-4.5-sonnet, gemini-2.5-flash). Use /v2/models to list available text models.

max_completion_tokensintegeroptional

Upper bound for generated tokens, including visible output and reasoning tokens.

temperaturenumberoptional

Sampling temperature (0–2). Higher = more random output. Do not set both temperature and top_p.

streambooleanoptional

If true, stream incremental tokens as server-sent events. Each data: line is a JSON delta. Stream terminates with data: [DONE]. Not compatible with json_schema response format.

stream_optionsobjectoptional

Options for streaming responses. Only valid when stream: true.

include_usagebooleanoptional

If true, send a final chunk with token usage statistics before [DONE].

toolsFunctionTool[]optional

Functions the model may call. When the model calls a function, return the result in a tool message.

typestringrequired

functionobjectrequired

namestringrequired

Function name (a-z, A-Z, 0-9, underscores, dashes)

descriptionstringoptional

What the function does — used by the model to decide when to call it

parametersobjectoptional

JSON Schema describing function parameters

cache_controlCacheControloptional

Cache the tool definitions (and the system prompt with them, since Anthropic orders tools first). Requires a system message in the same request — with none, the marker is dropped rather than moved onto the first user turn, which would change every request and never produce a hit.

typestringrequired

ttlstringoptional

Cache lifetime. On THIS endpoint 1h is NOT SUPPORTED: it is accepted so an existing integration keeps working, but the breakpoint is placed with the default five-minute lifetime, billed at the five-minute cache-write rate (1.25x the input rate, not 2x), and reported as a marker_ttl_unsupported warning in prompt_cache. Because every breakpoint therefore has the same lifetime, mixing the two values is accepted and Anthropic's 1h-before-5m ordering rule is not enforced. 1h IS honoured on /anthropic/v1/messages, where cache_control is Anthropic's own field. Where nothing is cached the markers are ignored entirely.

parallel_tool_callsbooleanoptional

Allow the model to call multiple tools in a single turn.

reasoning_effortstringoptional

Reasoning budget for reasoning models (e.g. o3, o4-mini). Lower = faster and cheaper; none disables extended thinking.

response_formatobject | objectoptional

Constrain the output format. Use json_schema for structured output (streaming not supported).

prompt_cache_keystringoptional

Optional stable identifier for requests that share a prompt prefix — a conversation, session or workflow id. Raises the prompt-cache hit rate on models that cache prefixes automatically (Mistral). Ignored by models that cache on explicit cache_control breakpoints (Anthropic) and by models with no prompt cache. Your value is namespaced to your workspace server-side, so it can never collide with another tenant or aim at their cache. Hits are best-effort and never guaranteed — a miss is billed exactly like an uncached request, so there is nothing to lose by sending it. Do not put secrets or personal data in it.

Response

200application/json

{
  "id": "chatcmpl-xR4qT5Uy",
  "object": "chat.completion",
  "created": 0,
  "model": "string",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "string",
        "tool_calls": [
          null
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 0
    }
  },
  "prompt_cache": {
    "cache_write_tokens": {
      "5m": 0,
      "1h": 0
    },
    "warnings": [
      {
        "code": "breakpoint_limit_exceeded",
        "message": "string"
      }
    ]
  }
}

{
  "id": "chatcmpl-xR4qT5Uy",
  "object": "chat.completion",
  "created": 0,
  "model": "string",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "string",
        "tool_calls": [
          null
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 0
    }
  },
  "prompt_cache": {
    "cache_write_tokens": {
      "5m": 0,
      "1h": 0
    },
    "warnings": [
      {
        "code": "breakpoint_limit_exceeded",
        "message": "string"
      }
    ]
  }
}

Chat completion (JSON) or SSE stream when stream: true

Also available as text/event-stream

idstring

objectstring

createdinteger

Unix timestamp

modelstring

choicesChatCompletionChoice[]

indexinteger

messageobject

rolestring

contentstring | null

tool_callsToolCall[]

finish_reasonstring | null

usageUsage

prompt_tokensinteger

completion_tokensinteger

total_tokensinteger

prompt_tokens_detailsobject

The cache split of prompt_tokens. prompt_tokens is the INCLUSIVE total, so these are subsets of it, not additions to it.

cached_tokensinteger

Input tokens served from the prompt cache, billed at the cache-read rate when prompt caching is enabled for your organisation.

cache_write_tokensinteger

Input tokens written to the prompt cache. Present only when prompt caching is enabled for your organisation.

prompt_cacheobject

DeutschlandGPT extension. What happened to the cache_control breakpoints you sent. Omitted entirely when there is nothing to report, so a request without cache_control is unchanged. See Billing -> Prompt caching.

cache_write_tokensobject

Cache-write tokens by TTL, as the upstream host reported them: 125% of the input rate for 5m, 200% for 1h. On /v2/chat/completions and /v2/responses the 1h bucket is always 0, because those endpoints do not support the one-hour cache and write a ttl: "1h" breakpoint with the five-minute lifetime instead.

5minteger

Tokens written at the default 5-minute TTL.

1hinteger

Tokens written at the extended 1-hour TTL.

warningsobject[]

Breakpoints that could not be honoured exactly as written. Present only when at least one was affected.

codestringrequired

Stable machine-readable reason, so a client can branch without parsing prose.

messagestringrequired

Human-readable explanation naming the affected position.

Response codes

200

Chat completion (JSON) or SSE stream when stream: true

ChatCompletionResponse

400

Validation error or unsupported combination

Error

401

Missing or invalid API key

Error

402

Insufficient credits

Error

403

Feature not enabled for this workspace

Error

404

Model not found

Error