API Reference

Authentication

Authenticate requests via the Authorization header using your Bearer token.

Standard OpenAI-compatible chat completion endpoint. Supports JSON mode, streaming, and function calling. All standard OpenAI parameters (temperature, max_tokens, top_p, etc.) are passed through to the upstream provider.

Parameters

Streaming

StreamFix supports Server-Sent Events (SSE) with token-by-token repair. The FSM engine buffers only the minimum tokens needed (approximately 10 characters) to apply repairs without delaying the stream.

Example

from openai import OpenAI

client = OpenAI(
    base_url="https://streamfix.dev/v1",
    api_key="sk_YOUR_KEY"
)

stream = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "List 3 items as JSON"}],
    stream=True
)

# Chunks arrive repaired in real-time
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Repair Pipeline

Every response passes through a multi-stage pipeline. Each stage is independent and applies only when needed.

Stage 1: Extraction

Isolates JSON from surrounding prose, markdown fences, and reasoning tags.

Stage 2: Syntax Repair

Fixes common JSON syntax violations produced by LLMs.

Stage 3: Contract

Applied when a schema is provided (Contract Mode).

Schema Validation (Contract Mode)

Enforce strict adherence to a JSON Schema. When a schema is provided, StreamFix runs the full pipeline: repair the syntax, coerce types to match, validate against the schema, and auto-retry with a schema-aware prompt if validation fails.

resp = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Extract the order info"}],
    extra_body={
        "schema": {
            "type": "object",
            "required": ["order_id", "total", "status"],
            "properties": {
                "order_id": {"type": "integer"},
                "total": {"type": "number"},
                "status": {"type": "string", "enum": ["pending", "shipped", "delivered"]}
            }
        }
    }
)

Limitations

• Streaming requests receive repair and coercion but no auto-retry (the response is already sent).
• Maximum 1 retry per request.
• 3 credits are charged regardless of whether a retry occurs.

Strict Mode

Strict Mode guarantees that a response is parseable JSON or returns a structured error. Enable it by setting the X-StreamFix-Strict header.

Behavior

• Returns 200 when the response is valid JSON after repair.
• Returns 422 when the JSON could not be parsed even after all repair stages.
• The 422 response body includes a typed error object with details about the parse failure.
• Not compatible with streaming -- returns 400 if stream: true is set alongside Strict Mode.
• Can be combined with Contract Mode for maximum guarantees (schema validation + parse-or-fail).

Example

from openai import OpenAI

client = OpenAI(
    base_url="https://streamfix.dev/v1",
    api_key="sk_YOUR_KEY",
    default_headers={"X-StreamFix-Strict": "true"}
)

# 200 = valid JSON, 422 = parse failure
resp = client.with_raw_response.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Return a JSON object"}]
)

print(resp.status_code)  # 200 or 422

422 Response Body

{
  "error": {
    "type": "parse_failure",
    "message": "Failed to extract or repair valid JSON from response",
    "request_id": "req_abc123def456",
    "extraction_status": "FAILED",
    "raw_content_preview": "Sure! Here is some info..."
  }
}

Type Coercion

When a schema is provided, StreamFix automatically coerces values to match the declared types before validation. This fixes the most common schema violations from LLMs without requiring a retry.

Retrieve the repaired JSON and validation metadata for any request (streaming or non-streaming).

{
  "request_id": "req_abc123",
  "status": "REPAIRED",
  "repairs_applied": ["remove_trailing_comma"],
  "repaired_content": "{\"status\": \"ok\"}",
  "schema_valid": true,
  "response_time_ms": 450
}

Tool Calls Support

StreamFix automatically repairs broken JSON in tool_calls[].function.arguments for non-streaming requests.

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Call test_function"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "test_function",
            "parameters": {
                "type": "object",
                "properties": {"arg": {"type": "string"}}
            }
        }
    }]
)

# Tool call arguments are automatically repaired if broken
tool_calls = response.choices[0].message.tool_calls
if tool_calls:
    args = tool_calls[0].function.arguments  # Already repaired JSON

Supported Models

We support all models via OpenRouter. Here are our recommended defaults for reliability.

Response Headers

StreamFix returns all repair and validation metadata in HTTP headers to maintain 100% OpenAI API compatibility in the response body.

Always Present

x-streamfix-request-id: req_abc123def456
x-streamfix-status: repaired
x-streamfix-applied: fence_strip,remove_trailing_comma
x-streamfix-credits-used: 1
x-streamfix-credits-remaining: 999
x-streamfix-mode: shared

Contract Mode (When Schema Provided)

x-streamfix-contract-mode: active
x-streamfix-schema-valid: true
x-streamfix-schema-errors: 0
x-streamfix-retry-count: 1  # If retry was triggered

Tool Calls (When Arguments Repaired)

x-streamfix-tool-args-repaired: 1  # Non-streaming only

Header Reference

Repair Taxonomy

The x-streamfix-applied header contains a comma-separated list of repair names. Use this to monitor which models produce which errors.

Error Codes

Create a new account and receive an API key with 1000 free credits.

Request

POST /account/create?email=user@example.com

Response

{
  "api_key": "sk_abc123...",
  "email": "user@example.com",
  "credits": 1000,
  "message": "Account created! Save your API key - it won't be shown again."
}

Check your remaining credits. Requires authentication.

Request

GET /account/balance
Authorization: Bearer sk_YOUR_API_KEY

Response

{
  "credits_remaining": 997,
  "is_active": true
}

Create a Stripe checkout session for purchasing credits. User-friendly: uses email instead of API key.

Request

POST /account/purchase-by-email
Content-Type: application/json

{
  "email": "user@example.com"
}

Response

{
  "checkout_url": "https://checkout.stripe.com/...",
  "credits": 10000,
  "price_usd": 10.0
}

BYOK (Bring Your Own Key)

Use your own provider API keys to avoid using the shared pool.

from openai import OpenAI

client = OpenAI(
    base_url="https://streamfix.dev/v1",
    api_key="sk_YOUR_STREAMFIX_KEY",
    default_headers={
        "X-Provider-Authorization": "Bearer YOUR_OPENROUTER_KEY"
    }
)

Pricing

Best Practices

• Use Contract Mode for agent pipelines: Agents that parse JSON tool outputs or structured data benefit from schema validation and auto-retry -- not just streaming UIs.
• Combine Strict Mode + Contract Mode: For maximum guarantees, enable both. You get schema validation with retry and a hard 422 if the output still cannot be parsed.
• Monitor X-StreamFix-Applied: This header tells you exactly which repairs were needed. Use it to understand which models produce bad output and to track repair rates over time.
• Use BYOK to control upstream costs: Pass your own OpenRouter key via X-Provider-Authorization to separate upstream LLM costs from StreamFix credits.
• Non-streaming for tool calls, streaming for UIs: Tool call argument repair only works in non-streaming mode. Use streaming for user-facing chat interfaces where latency matters.
• Always use JSON Mode: Set response_format: {"type": "json_object"} when possible. StreamFix repairs what breaks, but starting with valid intent helps.
• Handle 429s: Implement exponential backoff for rate limits (60 requests/minute).
• Use Correlation IDs: Send X-Request-Id or X-Client-Request-Id header to track requests across your system logs.