Obtenir une clé API
/login → connexion Google ou GitHub. La première connexion émet automatiquement une clé API virtuelle (sk-...). Les nouveaux comptes démarrent à $0 — recharge en self-service bientôt.
curl (transport streamable-http)
Étape 1 : initialiser et capturer le session id depuis l'en-tête de réponse mcp-session-id
curl -i -X POST https://api.twinkleai.tw/mcp/ \
-H "Authorization: Bearer sk-..." \
-H "Accept: application/json, text/event-stream" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'Étape 2 : tools/call
curl -X POST https://api.twinkleai.tw/mcp/ \
-H "Authorization: Bearer sk-..." \
-H "Accept: application/json, text/event-stream" \
-H "Content-Type: application/json" \
-H "mcp-session-id: <from-step-1>" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"tw_list_domains","arguments":{}}}'La réponse utilise un framing style SSE — trouvez la dernière ligne commençant par data: et parsez le JSON.
Python (fastmcp)
import asyncio
from fastmcp.client import Client
from fastmcp.client.auth import BearerAuth
async def main():
async with Client(
"https://api.twinkleai.tw/mcp/",
auth=BearerAuth("sk-..."),
) as client:
tools = await client.list_tools()
print([t.name for t in tools])
r = await client.call_tool(
"tw_search_datasets",
{"query": "AQI", "domain": "environment", "limit": 5},
)
# response 在 r.content[0].text — JSON string
import json
print(json.loads(r.content[0].text))
asyncio.run(main())Les outils retournent CallToolResult.content[0].text sous forme de chaîne JSON. Licence, citation et autres métadonnées passent dans le champ _meta.
Référence des outils
| Outil | Arguments | Retours (bref) |
|---|---|---|
| tw_list_domains | — | [{key, name_zh, scope, typical_questions}] |
| tw_search_datasets | {query, domain?, limit?} | [{dataset_id, title, score, license}] |
| tw_get_dataset | {dataset_id} | {schema, columns, license, source_url} |
| tw_query_rows | {dataset_id, where?, limit?} | [row, ...] |
| tw_materialize_dataset | {dataset_id, format?} | 全表 CSV / JSON |
Schémas complets via tools/list — auto-générés en JSON Schema.
Authentification
- Bearer token — en-tête
Authorization: Bearer sk-.... Une clé virtuelle émise par Twinkle Hub, une par utilisateur. Récupérez la vôtre depuis /dashboard. - Pas de flux OAuth — pas besoin de PKCE / refresh tokens ; juste un bearer long-terme.
- Rate limit — le forfait Free est encadré par un volume de crédits glissant (50 par tranche glissante de 5 heures, rechargés progressivement, plus un plafond de 200 crédits par semaine), pas par un budget en USD ni un RPM/TPM par clé.
Tarifs
Bientôt
Les outils principaux sont actuellement gratuits — 50 crédits par tranche glissante de 5 heures, rechargés progressivement (plus un plafond de 200 crédits par semaine). Sur le forfait Free, query_rows renvoie au maximum 10 lignes par appel. La recherche sémantique approfondie et la récupération de documents complets sont réservées au prochain forfait Pro ; nous annoncerons les tarifs Pro avant le début de la facturation.
Forfait Free : 50 crédits par tranche glissante de 5 heures, rechargés progressivement (plus un plafond de 200 crédits par semaine) ; query_rows renvoie au maximum 10 lignes par appel ; la recherche sémantique approfondie et la récupération de documents complets sont réservées à Pro. L'application des quotas est active dès maintenant (avec un léger délai asynchrone).