API reference

Chat completions

Generates a model response for a conversation. Request and response follow the OpenAI Chat Completions format.

On this page

Create a chat completion
Request body
Response
Response headers
Streaming

Create a chat completion

POSThttps://gateway.ditfa.com/v1/chat/completionsRequires an sk-dp- key

Request body

modelstringrequired: Model slug in author/name form, e.g. openai/gpt-4o-mini. See List models.
messagesarrayrequired: At least one message. Roles: system, developer, user, assistant, tool. content may be a string or an array of content parts (text and, for vision models, images).
streamboolean: Default false. When true, the response is a stream of server-sent events. See Streaming.
max_completion_tokensinteger: Output cap. max_tokens is accepted too (if both are sent, max_completion_tokens wins). Without either, the gateway applies a cap of 16,384 tokens or the model's maximum output, whichever is lower.
temperaturenumber: Sampling temperature, usually 0 to 2.
top_pnumber: Nucleus sampling probability mass.
stopstring | string[]: Sequences where generation stops.
presence_penalty / frequency_penaltynumber: Penalties for repeated topics and tokens, where the model supports them.
seedinteger: Best-effort deterministic sampling, where supported.
tools / tool_choice / parallel_tool_callsarray / string | object / boolean: Function calling in the OpenAI format. Only for models whose supported_parameters include tools.
response_formatobject: { "type": "json_object" } or a json_schema for structured output, where supported.
logprobs / top_logprobsboolean / integer: Token log probabilities, where supported.
ditfa.allow_paidboolean: Ditfa only, sent as "ditfa": { "allow_paid": true } and not forwarded to the provider. Pay the normal price if a free or sponsored request is refused. See Paying the normal price.

Unsupported fields are dropped

Only the OpenAI fields above are forwarded to the provider. Others (for example user, n or vendor extensions) are ignored without an error. Support for optional parameters varies by model and provider.

Response

A chat.completion object. id is the Ditfa generation id and model is the public slug you requested, whichever provider served it.

200 OK

{
  "id": "gen-3f1c2a7e-8b4d-4c1e-9a0f-5d6e7b8c9d0e",
  "object": "chat.completion",
  "created": 1793318400,
  "model": "openai/gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Waves fold into foam…"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 17,
    "total_tokens": 31
  }
}

Response headers

x-ditfa-generation-idstring: gen-… id of a successful request. Use it with /generation to read its final token counts and cost.
x-ditfa-charge-modestring: paid, free or sponsored: how this request was paid. See Who pays.
x-ratelimit-limit-requestsinteger: Requests allowed per minute for this key.
x-ratelimit-remaining-requestsinteger: Requests left in the current one-minute window.
retry-afterinteger: Seconds to wait. Sent with 429 rate_limit_exceeded.
x-ditfa-free-resetstring: ISO 8601 time. Sent when a free or sponsored limit refuses a request and that limit has a reset time.

Streaming

Set stream: true to receive server-sent events (text/event-stream) in the OpenAI chunk format, ending with data: [DONE].

curl https://gateway.ditfa.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DITFA_API_KEY" \
  -N \
  -d '{
  "model": "openai/gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "Write a haiku about the ocean."
    }
  ],
  "stream": true
}'

Event stream

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"openai/gpt-4o-mini","choices":[{"index":0,"delta":{"role":"assistant","content":"Waves"}}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"openai/gpt-4o-mini","choices":[{"index":0,"delta":{"content":" fold"}}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"openai/gpt-4o-mini","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"openai/gpt-4o-mini","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":17,"total_tokens":31}}

data: [DONE]

The last chunk before [DONE] carries usage with an empty choices array. The gateway always requests it, so you do not need stream_options. Guard against empty choices when reading deltas.
Chunk ids come from the provider. Use the x-ditfa-generation-id response header to look the request up later.
If you disconnect mid-stream, you pay for the prompt and the output already delivered. A stream cut before the model sent anything is not charged.

{ "id": "gen-3f1c2a7e-8b4d-4c1e-9a0f-5d6e7b8c9d0e", "object": "chat.completion", "created": 1793318400, "model": "openai/gpt-4o-mini", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Waves fold into foam…" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 14, "completion_tokens": 17, "total_tokens": 31 } }

curl https://gateway.ditfa.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DITFA_API_KEY" \ -N \ -d '{ "model": "openai/gpt-4o-mini", "messages": [ { "role": "user", "content": "Write a haiku about the ocean." } ], "stream": true }'

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"openai/gpt-4o-mini","choices":[{"index":0,"delta":{"role":"assistant","content":"Waves"}}]} data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"openai/gpt-4o-mini","choices":[{"index":0,"delta":{"content":" fold"}}]} data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"openai/gpt-4o-mini","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]} data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"openai/gpt-4o-mini","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":17,"total_tokens":31}} data: [DONE]

Request body

Response

Response headers

Request body

Response

Response headers

Your analytics choice