Update openai-sdk README.md and index.html

README.md

@@ -4,13 +4,15 @@ emoji: 🔌
 colorFrom: blue
 colorTo: purple
 sdk: static
-pinned: false
+pinned: true
 license: mit
-short_description: Switch base_url to Modelflare — one-line OpenAI SDK setup
+short_description: One-line OpenAI SDK switch — bilingual guide
 ---
 
 # OpenAI SDK → Modelflare (one-line switch)
 
-Point any OpenAI-compatible client at Modelflare. Create a key at [modelflare.dev](https://modelflare.dev/), then set `base_url` to `https://modelflare.dev/v1`.
+Point any OpenAI-compatible client at Modelflare. Create a key at [modelflare.dev](https://modelflare.dev/?utm_source=huggingface&utm_medium=space&utm_campaign=sdk_guide), then set `base_url` to `https://modelflare.dev/v1`.
 
-Full docs: [docs.modelflare.dev](https://docs.modelflare.dev/) · Hub landing: [Modelflare/start](https://huggingface.co/spaces/Modelflare/start)
+- Full docs: [docs.modelflare.dev](https://docs.modelflare.dev/?utm_source=huggingface&utm_medium=space&utm_campaign=sdk_guide)
+- Hub landing: [Modelflare/start](https://huggingface.co/spaces/Modelflare/start)
+- Collection: [Getting Started](https://huggingface.co/collections/Modelflare/modelflare-getting-started)

index.html

@@ -4,10 +4,11 @@
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>OpenAI SDK → Modelflare</title>
+  <meta name="description" content="One-line OpenAI SDK switch to Modelflare. Bilingual Python, Node, curl, streaming examples." />
   <style>
     :root {
       --bg:#0b1020; --card:#121a2f; --text:#e8ecf7; --muted:#9aa6c2;
-      --accent:#8b5cf6; --accent2:#ec4899; --border:rgba(255,255,255,.08); --ok:#34d399;
+      --accent:#8b5cf6; --accent2:#ec4899; --border:rgba(255,255,255,.08); --ok:#34d399; --warn:#fbbf24;
     }
     *{box-sizing:border-box}
     body{margin:0;font-family:ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,Helvetica,Arial,sans-serif;background:radial-gradient(1000px 500px at 0% 0%,#2a1850 0%,transparent 50%),var(--bg);color:var(--text);line-height:1.55}
@@ -22,14 +23,16 @@
     a.primary{background:linear-gradient(135deg,var(--accent),var(--accent2));color:#fff}
     a.ghost{border:1px solid var(--border);color:var(--text)}
     h2{font-size:18px;margin:28px 0 10px}
-    ol{color:var(--muted);padding-left:1.2em}
-    ol li{margin:6px 0}
+    ol,ul{color:var(--muted);padding-left:1.2em}
+    ol li,ul li{margin:6px 0}
     pre{background:#070b16;border:1px solid var(--border);border-radius:14px;padding:14px 16px;overflow:auto;font-size:12.5px;color:#d7def0;position:relative}
     .copy{position:absolute;top:8px;right:8px;font-size:11px;border:1px solid var(--border);background:#121a2f;color:var(--muted);border-radius:8px;padding:4px 8px;cursor:pointer}
     .note{background:var(--card);border:1px solid var(--border);border-radius:14px;padding:14px 16px;color:var(--muted);font-size:14px;margin-top:16px}
     .note strong{color:var(--ok)}
+    .tip{border-left:3px solid var(--warn);padding-left:12px;margin:12px 0;color:var(--muted);font-size:14px}
     code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
     .hidden{display:none}
+    a{color:#c4b5fd}
   </style>
 </head>
 <body>
@@ -44,8 +47,9 @@
       <p class="lead">从 Hugging Face 过来？先拿 key，再改 <code>base_url</code>。文本 / 图片 / 视频同一把钥匙，带分组故障转移与用量成本记录。</p>
       <div class="cta">
         <a class="btn primary" href="https://modelflare.dev/?utm_source=huggingface&utm_medium=space&utm_campaign=sdk_guide" target="_blank" rel="noopener">打开控制台领取 API Key</a>
-        <a class="btn ghost" href="https://docs.modelflare.dev/" target="_blank" rel="noopener">完整文档</a>
+        <a class="btn ghost" href="https://docs.modelflare.dev/?utm_source=huggingface&utm_medium=space&utm_campaign=sdk_guide" target="_blank" rel="noopener">完整文档</a>
         <a class="btn ghost" href="https://huggingface.co/collections/Modelflare/modelflare-getting-started" target="_blank" rel="noopener">Getting Started 合集</a>
+        <a class="btn ghost" href="https://huggingface.co/spaces/Modelflare/start" target="_blank" rel="noopener">落地页</a>
       </div>
       <h2>三步接入</h2>
       <ol>
@@ -53,11 +57,16 @@
         <li>把 OpenAI 客户端的 <code>base_url</code> 改成 <code>https://modelflare.dev/v1</code>。</li>
         <li>模型名用你分组里实际开通的 id（例如 Grok 分组用 <code>grok-4.7</code>）。</li>
       </ol>
+      <div class="tip">模型 id 必须在当前 key 所属分组里已开通；否则会 404 / 无权限。价目与可用性以控制台为准。</div>
+      <h2>环境变量（推荐）</h2>
+      <pre><button class="copy" type="button">复制</button><code>export MODELFLARE_API_KEY="mf-..."
+# base_url 固定为 https://modelflare.dev/v1</code></pre>
       <h2>Python</h2>
-      <pre><button class="copy" type="button">复制</button><code>from openai import OpenAI
+      <pre><button class="copy" type="button">复制</button><code>import os
+from openai import OpenAI
 
 client = OpenAI(
-    api_key="YOUR_MODELFLARE_KEY",
+    api_key=os.environ["MODELFLARE_API_KEY"],
     base_url="https://modelflare.dev/v1",
 )
 
@@ -66,6 +75,15 @@ r = client.chat.completions.create(
     messages=[{"role": "user", "content": "Hello from Hugging Face"}],
 )
 print(r.choices[0].message.content)</code></pre>
+      <h2>流式输出（Python）</h2>
+      <pre><button class="copy" type="button">复制</button><code>stream = client.chat.completions.create(
+    model="grok-4.7",
+    messages=[{"role": "user", "content": "Say hi in one line"}],
+    stream=True,
+)
+for chunk in stream:
+    delta = chunk.choices[0].delta.content or ""
+    print(delta, end="", flush=True)</code></pre>
       <h2>Node.js / TypeScript</h2>
       <pre><button class="copy" type="button">复制</button><code>import OpenAI from "openai";
 
@@ -84,9 +102,15 @@ console.log(r.choices[0].message.content);</code></pre>
   -H "Authorization: Bearer $MODELFLARE_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{"model":"grok-4.7","messages":[{"role":"user","content":"ping"}]}'</code></pre>
+      <h2>常见问题</h2>
+      <ul>
+        <li><strong>401</strong>：检查 key 是否完整、是否多了空格；环境变量是否生效。</li>
+        <li><strong>模型不可用</strong>：换到该分组已开通的模型 id，或在控制台换分组。</li>
+        <li><strong>图片 / 视频</strong>：同一把 key，但请求字段走原生合约，见文档站 Image / Video 章节。</li>
+        <li><strong>Coding agents</strong>：Codex / Claude Code / Gemini CLI 配置见文档站。</li>
+      </ul>
       <div class="note">
         <strong>从 Hub 来的访客：</strong>注册后即可在控制台看价、开 key、看用量。
-        Coding agents（Codex / Claude Code 等）配置见文档站。
         可互动 Chat Demo 需 Hugging Face PRO 后上线；现在请用控制台与 API 试用。
       </div>
     </section>
@@ -96,8 +120,9 @@ console.log(r.choices[0].message.content);</code></pre>
       <p class="lead">Coming from Hugging Face? Get a key, then set <code>base_url</code>. One key for text, image, and video — with group failover and per-request cost tracking.</p>
       <div class="cta">
         <a class="btn primary" href="https://modelflare.dev/?utm_source=huggingface&utm_medium=space&utm_campaign=sdk_guide" target="_blank" rel="noopener">Open Console → Get API Key</a>
-        <a class="btn ghost" href="https://docs.modelflare.dev/" target="_blank" rel="noopener">Docs</a>
+        <a class="btn ghost" href="https://docs.modelflare.dev/?utm_source=huggingface&utm_medium=space&utm_campaign=sdk_guide" target="_blank" rel="noopener">Docs</a>
         <a class="btn ghost" href="https://huggingface.co/collections/Modelflare/modelflare-getting-started" target="_blank" rel="noopener">Getting Started collection</a>
+        <a class="btn ghost" href="https://huggingface.co/spaces/Modelflare/start" target="_blank" rel="noopener">Landing</a>
       </div>
       <h2>Three steps</h2>
       <ol>
@@ -105,11 +130,16 @@ console.log(r.choices[0].message.content);</code></pre>
         <li>Point your OpenAI client at <code>https://modelflare.dev/v1</code>.</li>
         <li>Use a model id enabled on your group (e.g. <code>grok-4.7</code> on a Grok group).</li>
       </ol>
+      <div class="tip">Model ids must be enabled on the key’s group — otherwise you get 404 / unauthorized. Live prices and availability live in the console.</div>
+      <h2>Environment variable (recommended)</h2>
+      <pre><button class="copy" type="button">Copy</button><code>export MODELFLARE_API_KEY="mf-..."
+# base_url is always https://modelflare.dev/v1</code></pre>
       <h2>Python</h2>
-      <pre><button class="copy" type="button">Copy</button><code>from openai import OpenAI
+      <pre><button class="copy" type="button">Copy</button><code>import os
+from openai import OpenAI
 
 client = OpenAI(
-    api_key="YOUR_MODELFLARE_KEY",
+    api_key=os.environ["MODELFLARE_API_KEY"],
     base_url="https://modelflare.dev/v1",
 )
 
@@ -118,6 +148,15 @@ r = client.chat.completions.create(
     messages=[{"role": "user", "content": "Hello from Hugging Face"}],
 )
 print(r.choices[0].message.content)</code></pre>
+      <h2>Streaming (Python)</h2>
+      <pre><button class="copy" type="button">Copy</button><code>stream = client.chat.completions.create(
+    model="grok-4.7",
+    messages=[{"role": "user", "content": "Say hi in one line"}],
+    stream=True,
+)
+for chunk in stream:
+    delta = chunk.choices[0].delta.content or ""
+    print(delta, end="", flush=True)</code></pre>
       <h2>Node.js / TypeScript</h2>
       <pre><button class="copy" type="button">Copy</button><code>import OpenAI from "openai";
 
@@ -136,33 +175,34 @@ console.log(r.choices[0].message.content);</code></pre>
   -H "Authorization: Bearer $MODELFLARE_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{"model":"grok-4.7","messages":[{"role":"user","content":"ping"}]}'</code></pre>
+      <h2>Troubleshooting</h2>
+      <ul>
+        <li><strong>401</strong>: key truncated / whitespace / env not loaded.</li>
+        <li><strong>Model unavailable</strong>: switch to an id enabled on that group, or change groups in the console.</li>
+        <li><strong>Image / video</strong>: same key, native request fields — see Image / Video docs.</li>
+        <li><strong>Coding agents</strong>: Codex / Claude Code / Gemini CLI setups are in the docs.</li>
+      </ul>
       <div class="note">
         <strong>HF visitors:</strong> sign up on the console for pricing, keys, and usage.
-        Coding-agent setups live in the docs. Interactive Chat Spaces need HF PRO; use the console + API for now.
+        Interactive Chat Spaces need HF PRO; use the console + API for now.
       </div>
     </section>
   </div>
   <script>
-    const zh = document.getElementById('zh');
-    const en = document.getElementById('en');
-    document.querySelectorAll('.lang button').forEach(btn => {
-      btn.addEventListener('click', () => {
-        document.querySelectorAll('.lang button').forEach(b => b.classList.remove('on'));
+    const zh=document.getElementById('zh'), en=document.getElementById('en');
+    document.querySelectorAll('.lang button').forEach(btn=>{
+      btn.addEventListener('click',()=>{
+        document.querySelectorAll('.lang button').forEach(b=>b.classList.remove('on'));
         btn.classList.add('on');
-        const l = btn.dataset.lang;
-        zh.classList.toggle('hidden', l !== 'zh');
-        en.classList.toggle('hidden', l !== 'en');
+        const l=btn.dataset.lang;
+        zh.classList.toggle('hidden',l!=='zh');
+        en.classList.toggle('hidden',l!=='en');
       });
     });
-    document.querySelectorAll('pre .copy').forEach(btn => {
-      btn.addEventListener('click', async () => {
-        const code = btn.parentElement.querySelector('code').innerText;
-        try {
-          await navigator.clipboard.writeText(code);
-          const t = btn.textContent;
-          btn.textContent = btn.textContent.includes('Copy') ? 'Copied' : '已复制';
-          setTimeout(() => btn.textContent = t, 1200);
-        } catch (_) {}
+    document.querySelectorAll('pre .copy').forEach(btn=>{
+      btn.addEventListener('click',async()=>{
+        const code=btn.parentElement.querySelector('code').innerText;
+        try{await navigator.clipboard.writeText(code);const t=btn.textContent;btn.textContent=t.includes('Copy')?'Copied':'已复制';setTimeout(()=>btn.textContent=t,1200)}catch(_){}
       });
     });
   </script>