Docs - Twinkle Hub

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

text

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

text

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":"opendata-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)

python

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(
            "opendata-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)
opendata-list_domains	—	[{key, name_zh, scope, typical_questions}]
opendata-search_datasets	{query, domain?, limit?}	[{dataset_id, title, score, license}]
opendata-get_dataset	{dataset_id}	{schema, columns, license, source_url}
opendata-query_rows	{dataset_id, where?, limit?}	[row, ...]
opendata-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 — pas de limites RPM/TPM par clé aujourd'hui ; seul max_budget s'applique (la gateway rejette quand spend > max_budget).

Tarifs

Bientôt

Tous les outils sont gratuits en alpha. Nous annoncerons les tarifs par outil avant le début de la facturation, et les utilisateurs existants auront une période de remise de transition.

Gratuit en alpha. Le pipeline de tracking de dépenses tourne (lag asynchrone 5-15s, la gateway batch les écritures DB) ; quand la facturation démarre, l'application des quotas est temps réel à la requête suivante.