Chat Completions

The model

Quick start

Use the official OpenAI SDK. Only two lines change compared to a normal OpenAI setup.

curl https://api.staffifyai.com/api/v1/chat/completions \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "staffify-ki-1.0",
    "messages": [
      { "role": "user", "content": "Say hi in one word." }
    ]
  }'

Creates a model response for the given chat conversation. The full OpenAI request body shape is supported — any parameter not listed below is forwarded to the upstream model untouched.

Example response (non-stream)

{
  "id": "chatcmpl-9a1B2c3D4e...",
  "object": "chat.completion",
  "created": 1751812345,
  "model": "staffify-ki-1.0",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hi!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 2,
    "total_tokens": 14
  }
}

Streaming

Set stream: true to receive chunks as they are generated. Frames follow the OpenAI SSE format — data: {...} lines separated by blank lines, ending with data: [DONE]. Token usage is included in the final chunk before [DONE].

curl -N https://api.staffifyai.com/api/v1/chat/completions \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "staffify-ki-1.0",
    "messages": [{ "role": "user", "content": "Count from 1 to 5." }],
    "stream": true
  }'

Vision

Send images as content parts alongside text. Either an HTTPS URL or a base64 data URL.

curl https://api.staffifyai.com/api/v1/chat/completions \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "staffify-ki-1.0",
    "messages": [{
      "role": "user",
      "content": [
        { "type": "text", "text": "What is in this image?" },
        { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
      ]
    }]
  }'

Function calling (tools)

Define tools in OpenAI format. The assistant may reply with tool_calls instead of content. Send the tool result back as a role: "tool" message and call the endpoint again to continue.

curl https://api.staffifyai.com/api/v1/chat/completions \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "staffify-ki-1.0",
    "messages": [{ "role": "user", "content": "What is the weather in Amsterdam?" }],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }]
  }'

JSON mode & structured output

Force the model to return valid JSON, optionally matching a JSON Schema.

curl https://api.staffifyai.com/api/v1/chat/completions \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "staffify-ki-1.0",
    "messages": [{ "role": "user", "content": "Return the JSON object { \"ok\": true }" }],
    "response_format": { "type": "json_object" }
  }'

Returns the list of models available on this API. Currently a single entry.

{
  "object": "list",
  "data": [{
    "id": "staffify-ki-1.0",
    "object": "model",
    "owned_by": "staffify",
    "display_name": "Staffify KI 1.0",
    "context_window": 128000,
    "max_output_tokens": 16384,
    "supports_vision": true,
    "supports_tools": true,
    "supports_json_mode": true,
    "input_cost_per_million_tokens_eur": 0.552,
    "output_cost_per_million_tokens_eur": 2.208
  }]
}

Billing

Every request is deducted from your Staffify credits wallet based on the actual token usage reported by the model.

• A pre-check runs before the request: if worst-case cost (input + max_tokens output) exceeds your balance, you get 402 INSUFFICIENT_CREDITS.
• The actual deduct happens post-response, on usage.prompt_tokens and usage.completion_tokens returned by the model.
• For streaming requests, usage arrives in the final chunk; billing is applied when the stream closes.
• Transactions appear in /api/v1/credits history with type: "ai_completion".

Rate limits

Chat completions have their own limits, separate from the standard v1 REST limits. Every response includes X-AI-RateLimit-* headers.

Errors

Good to know

• The response model field always echoes back "staffify-ki-1.0". Internal provider names are never exposed.
• High-availability failover is built-in. If the primary upstream fails, requests are transparently routed to a fallback provider. Some advanced parameters (response_format, seed, logprobs) are best-effort during a failover event and may be ignored.
• The base URL is https://api.staffifyai.com/api/v1. When configuring an OpenAI SDK, that value goes into the base_url / baseURL field.