Hugging Face's logo

Spaces:
apiarium
/
labs
Sleeping

App Files Community
labs
File size: 14,081 Bytes
c1a683f
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <meta name="theme-color" content="#FFD6E8" />
<!-- CRITICAL: paint the dawn sky on the first byte, before any external CSS/JS
       loads. background-attachment:fixed locks it to the viewport AND is the only
       background iOS Safari renders in the overscroll/rubber-band region — so
       scrolling never exposes a bare strip. Literal hex because tokens.css
       hasn't loaded yet. -->
  <style>
    html{background:linear-gradient(180deg,#E8E0FF 0%,#FFD6E8 52%,#FFE5D9 100%) fixed;background-color:#FFD6E8;}
  </style>
  <title>Docs — DreamRouter</title>
  <meta name="description" content="DreamRouter API reference: authenticate, list models, send chat completions, stream responses, and handle errors across one OpenAI-compatible endpoint." />
  <link rel="canonical" href="https://apiarium-labs.hf.space/docs.html" />
  <meta property="og:type" content="website" />
  <meta property="og:title" content="DreamRouter Docs" />
  <meta property="og:description" content="One OpenAI-compatible endpoint. Auth, models, chat, streaming, errors." />

  <link rel="preconnect" href="https://fonts.googleapis.com" />
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
  <link href="https://fonts.googleapis.com/css2?family=Comfortaa:wght@400;500;700&family=Nunito:wght@400;600;700;800&family=JetBrains+Mono:wght@400;600&display=swap" rel="stylesheet" />
  <script src="https://unpkg.com/lenis@1.1.13/dist/lenis.min.js" defer></script>

  <link rel="stylesheet" href="css/tokens.css?v=20260620b" />
  <link rel="stylesheet" href="css/base.css?v=20260620b" />
  <link rel="stylesheet" href="css/scene.css?v=20260620b" />
  <link rel="stylesheet" href="css/nav.css?v=20260620b" />
  <link rel="stylesheet" href="css/sections.css?v=20260620b" />
  <link rel="stylesheet" href="css/docs.css?v=20260620b" />
</head>

<body data-page="docs">

  <!-- dream overlays -->
  <div class="blur-overlay" aria-hidden="true"></div>
  <div class="grain-overlay" aria-hidden="true"></div>

  <!-- a lighter scene for inner pages: far clouds + moon only (no whale) -->
  <div class="scene" aria-hidden="true">
    <div class="layer layer-far-clouds" data-speed="0.06" data-mouse="6">
      <svg class="cloud-far c1" viewBox="0 0 200 100"><use href="#cloud"/></svg>
      <svg class="cloud-far c3" viewBox="0 0 200 100"><use href="#cloud"/></svg>
    </div>
    <div class="layer layer-moon" data-speed="0.10" data-mouse="10">
      <div class="moon"><span class="moon-disc"></span></div>
    </div>
  </div>

  <!-- shared nav + footer -->
  <div data-site-nav></div>

  <main id="main">

    <header class="doc-hero">
      <div class="container">
        <h1 data-split>docs</h1>
        <p data-reveal>One OpenAI-compatible endpoint. Authenticate, send a request, stream the reply.</p>
      </div>
    </header>

    <div class="container">
      <div class="doc-layout">

        <!-- sticky TOC -->
        <aside class="doc-toc" aria-label="On this page">
          <h2>On this page</h2>
          <ul>
            <li><a href="#quickstart">Quickstart</a></li>
            <li><a href="#auth">Authentication</a></li>
            <li><a href="#base-url">Base URL</a></li>
            <li><a href="#models">List models</a></li>
            <li><a href="#chat">Chat completions</a></li>
            <li><a href="#streaming">Streaming</a></li>
            <li><a href="#parameters">Parameters</a></li>
            <li><a href="#errors">Errors</a></li>
            <li><a href="#retries">Retries &amp; limits</a></li>
          </ul>
        </aside>

        <!-- content -->
        <div class="doc-content">

          <section id="quickstart">
            <h2>Quickstart</h2>
            <p data-reveal>Send a standard OpenAI-style chat completion. Swap the base URL and the model name — that's the whole integration.</p>

            <div class="bezel" data-code-tabs>
              <div class="code-tabs" role="tablist">
                <button data-tab="curl" aria-selected="true">cURL</button>
                <button data-tab="py" aria-selected="false">Python</button>
                <button data-tab="js" aria-selected="false">JavaScript</button>
              </div>
              <div class="code-wrap">
                <pre class="code-panel" data-tab="curl" data-active="true"><span class="tok-com"># one endpoint, every model</span>
curl https://apiarium-labs.hf.space/v1/chat/completions \
  -H <span class="tok-str">"Authorization: Bearer $DREAMROUTER_KEY"</span> \
  -H <span class="tok-str">"Content-Type: application/json"</span> \
  -d <span class="tok-str">'{
    "model": "claude-opus-4.8",
    "messages": [{"role":"user","content":"Hello, whale."}]
  }'</span></pre>
                <pre class="code-panel" data-tab="py"><span class="tok-key">from</span> openai <span class="tok-key">import</span> OpenAI

client = OpenAI(
    base_url=<span class="tok-str">"https://apiarium-labs.hf.space/v1"</span>,
    api_key=<span class="tok-str">"dr_u_..."</span>,          <span class="tok-com"># your personal key from the dashboard</span>
)

resp = client.chat.completions.create(
    model=<span class="tok-str">"claude-opus-4.8"</span>,
    messages=[{<span class="tok-str">"role"</span>: <span class="tok-str">"user"</span>, <span class="tok-str">"content"</span>: <span class="tok-str">"Hello, whale."</span>}],
)
<span class="tok-key">print</span>(resp.choices[<span class="tok-num">0</span>].message.content)</pre>
                <pre class="code-panel" data-tab="js"><span class="tok-key">import</span> OpenAI <span class="tok-key">from</span> <span class="tok-str">"openai"</span>;

<span class="tok-key">const</span> client = <span class="tok-key">new</span> OpenAI({
  baseURL: <span class="tok-str">"https://apiarium-labs.hf.space/v1"</span>,
  apiKey:  <span class="tok-str">"dr_u_..."</span>,  <span class="tok-com">// your personal key from the dashboard</span>
});

<span class="tok-key">const</span> resp = <span class="tok-key">await</span> client.chat.completions.create({
  model: <span class="tok-str">"claude-opus-4.8"</span>,
  messages: [{ role: <span class="tok-str">"user"</span>, content: <span class="tok-str">"Hello, whale."</span> }],
});
console.log(resp.choices[<span class="tok-num">0</span>].message.content);</pre>
              </div>
            </div>

            <div class="callout note">
              <span class="ico">i</span>
              <div>The router rewrites your model name to each target's upstream id automatically. You send one name; it resolves to a healthy pool behind the scenes. <a href="models.html">Browse the 374 available models →</a></div>
            </div>
          </section>

          <section id="auth">
            <h2>Authentication</h2>
            <p data-reveal>Proxy endpoints require a Bearer token in the <code>Authorization</code> header.</p>
            <pre class="code-panel" style="background:var(--ink);padding:1rem 1.2rem;border-radius:14px;"><span class="tok-key">Authorization</span>: Bearer sk-your-DreamRouter-key</pre>
            <div class="callout warn">
              <span class="ico">!</span>
              <div>Public endpoints (<code>/</code>, <code>/health</code>, <code>/v1/models</code>) need no auth. Everything else returns <code>403</code> without a valid key. An optional IP allowlist can further lock access.</div>
            </div>
          </section>

          <section id="base-url">
            <h2>Base URL</h2>
            <p data-reveal>All requests are made against:</p>
            <pre class="code-panel" style="background:var(--ink);padding:1rem 1.2rem;border-radius:14px;">https://apiarium-labs.hf.space/v1</pre>
            <p>Point any OpenAI-compatible client at this base URL and you are done.</p>
          </section>

          <section id="models">
            <h2>List models</h2>
            <p data-reveal><code>GET /v1/models</code> returns every model the router can resolve. Public, no auth required.</p>
            <div class="bezel" data-code-tabs>
              <div class="code-tabs" role="tablist">
                <button data-tab="curl" aria-selected="true">cURL</button>
                <button data-tab="resp" aria-selected="false">Response</button>
              </div>
              <div class="code-wrap">
                <pre class="code-panel" data-tab="curl" data-active="true">curl https://apiarium-labs.hf.space/v1/models</pre>
                <pre class="code-panel" data-tab="resp">{
  <span class="tok-key">"object"</span>: <span class="tok-str">"list"</span>,
  <span class="tok-key">"data"</span>: [
    { <span class="tok-key">"id"</span>: <span class="tok-str">"claude-opus-4.8"</span>, <span class="tok-key">"object"</span>: <span class="tok-str">"model"</span>, <span class="tok-key">"owned_by"</span>: <span class="tok-str">"claude-subnet"</span> },
    { <span class="tok-key">"id"</span>: <span class="tok-str">"deepseek-v4-pro"</span>, <span class="tok-key">"object"</span>: <span class="tok-str">"model"</span>, <span class="tok-key">"owned_by"</span>: <span class="tok-str">"deepseek"</span> }
    <span class="tok-com">// ...374 models</span>
  ]
}</pre>
              </div>
            </div>
          </section>

          <section id="chat">
            <h2>Chat completions</h2>
            <p data-reveal><code>POST /v1/chat/completions</code> accepts the standard OpenAI request body. The <code>model</code> field selects the pool; everything else passes through.</p>
            <table class="doc-table">
              <thead><tr><th>Field</th><th>Type</th><th>Notes</th></tr></thead>
              <tbody>
                <tr><td><code>model</code></td><td>string</td><td>Required. Any name from <code>/v1/models</code>.</td></tr>
                <tr><td><code>messages</code></td><td>array</td><td>OpenAI message format.</td></tr>
                <tr><td><code>stream</code></td><td>boolean</td><td>SSE stream when <code>true</code>.</td></tr>
                <tr><td><code>temperature</code></td><td>number</td><td>Forwarded upstream.</td></tr>
                <tr><td><code>max_tokens</code></td><td>number</td><td>Forwarded. GPT-5.x maps to <code>max_completion_tokens</code> automatically.</td></tr>
                <tr><td><code>tools</code></td><td>array</td><td>Tool/function calling supported where the upstream allows it.</td></tr>
              </tbody>
            </table>
          </section>

          <section id="streaming">
            <h2>Streaming</h2>
            <p data-reveal>Set <code>"stream": true</code>. The router forwards the upstream SSE stream and filters non-<code>data:</code> lines so strict parsers stay happy. Each chunk is a standard <code>chat.completion.chunk</code>.</p>
            <div class="bezel">
              <div class="code-wrap">
                <pre class="code-panel" data-active="true" style="display:block;">data: {<span class="tok-key">"choices"</span>:[{<span class="tok-key">"delta"</span>:{<span class="tok-key">"content"</span>:<span class="tok-str">"Hello"</span>}}]}

data: {<span class="tok-key">"choices"</span>:[{<span class="tok-key">"delta"</span>:{<span class="tok-key">"content"</span>:<span class="tok-str">", whale."</span>}}]}

data: [DONE]</pre>
              </div>
            </div>
          </section>

          <section id="parameters">
            <h2>Parameters</h2>
            <p data-reveal>Unsupported parameters are silently dropped before forwarding. The router never invents upstream behavior — it only translates model names and injects keys.</p>
          </section>

          <section id="errors">
            <h2>Errors</h2>
            <table class="doc-table">
              <thead><tr><th>Status</th><th>Meaning</th></tr></thead>
              <tbody>
                <tr><td><code>401</code></td><td>Missing or invalid bearer token.</td></tr>
                <tr><td><code>403</code></td><td>Endpoint blocked, or IP not on the allowlist.</td></tr>
                <tr><td><code>404</code></td><td>Model not found. Returned before any upstream call.</td></tr>
                <tr><td><code>429</code></td><td>All targets rate-limited after retries.</td></tr>
                <tr><td><code>502</code></td><td>Every target in the pool failed its attempts.</td></tr>
                <tr><td><code>503</code></td><td>Pool exhausted — every target cooling down.</td></tr>
              </tbody>
            </table>
          </section>

          <section id="retries">
            <h2>Retries &amp; limits</h2>
            <p data-reveal>Each request gets up to <strong>five attempts</strong>. On <code>401</code>, <code>402</code>, <code>403</code>, <code>429</code>, or <code>5xx</code>, the failing target cools for <strong>sixty seconds</strong> and the router tries the next healthy one. Cooldowns are idempotent — re-failing a target never resets its timer, so flapping endpoints recover cleanly.</p>
            <div class="callout note">
              <span class="ico">↻</span>
              <div>Load is spread by a thread-safe round-robin cursor, so traffic distributes evenly across the whole pool — not hammering the first target.</div>
            </div>
          </section>

        </div><!-- /.doc-content -->
      </div><!-- /.doc-layout -->
    </div><!-- /.container -->

    <div data-site-footer></div>
  </main>

  <!-- SVG sprite (cloud symbol) -->
  <svg width="0" height="0" style="position:absolute" aria-hidden="true">
    <symbol id="cloud" viewBox="0 0 200 100">
      <path fill="currentColor" d="M44,82 C24,82 18,58 38,53 C32,32 62,26 74,42 C80,22 116,22 122,44 C142,32 168,48 158,68 C172,72 172,90 152,90 L54,90 C40,92 35,88 44,82 Z" />
    </symbol>
  </svg>

  <script src="js/layout.js?v=20260620b"></script>
  <script src="js/motion.js?v=20260620b"></script>
  <script src="js/parallax.js?v=20260620b"></script>
  <script src="js/docs.js?v=20260620b"></script>
</body>
</html>