Quick Start

Get started with Dragonfly market routing in 3 steps.

curl https://dragonfly-api.com/v1/chat/completions \
  -H "Authorization: Bearer sk-df-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-chat",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Authentication

All requests require a Bearer token in the Authorization header.

Authorization: Bearer sk-df-xxxxxxxxxxxxxxxxxxxx

Get your access key from the Dashboard.

First request failed?

Chat Completions

Create a chat completion. OpenAI-compatible.

Request Parameters

Request Example

curl https://dragonfly-api.com/v1/chat/completions \
  -H "Authorization: Bearer sk-df-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-chat",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is 2+2?"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1709000000,
  "model": "deepseek/deepseek-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "2 + 2 = 4"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 8,
    "total_tokens": 33
  }
}

Market Routing

Dragonfly operates a market where third-party providers contribute API keys at discounted prices. Routing-Strategy

Routing-Strategy Header

The default strategy is market-only.

If no eligible seller is available, the API returnsmarket_unavailable(503).

Note: market-only requires that you accept the Trading Terms in your Dashboard.

curl https://dragonfly-api.com/v1/chat/completions \
  -H "Authorization: Bearer sk-df-xxx" \
  -H "Content-Type: application/json" \
  -H "Routing-Strategy: market-only" \
  -d '{
    "model": "deepseek/deepseek-chat",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Session Stickiness (Optional)

When using market routing, you can pass an X-Session-Id header to keep consecutive requests routed to the same provider key. This is useful for multi-turn conversations where provider-level context caching may improve latency.

X-Session-Id: my-chat-session-123

Performance Preferences

Latency/throughput constraints are soft by default (affect ranking, not hard rejection). Use hard headers only when strict filtering is required.

Provider Controls

Route Diagnostics Headers

Successful market responses include debug headers for tracing route decisions. These headers are used by the Playground route diagnostics panel.

List Models

List all available models.

curl https://dragonfly-api.com/v1/models

{
  "object": "list",
  "data": [
    {
      "id": "deepseek/deepseek-chat",
      "object": "model",
      "owned_by": "deepseek",
      "pricing": { "input": 0.0005, "output": 0.0015 }
    }
  ]
}

Audio Speech (TTS)

Generate speech from text. Powered by MiniMax.

curl https://dragonfly-api.com/v1/audio/speech \
  -H "Authorization: Bearer sk-df-xxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "minimax/speech-02-hd", "input": "Hello world", "voice": "alloy"}' \
  --output speech.mp3

Models & Pricing

Prices per million tokens.

Rate Limits

Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset.

Error Codes

Error Response Format

{
  "error": {
    "message": "Insufficient balance",
    "type": "forbidden",
    "code": 403
  }
}