Parcourir la documentation
Référence API
Outils et schémas MCP
Consultez les arguments et valeurs par défaut des outils MCP FlashData, les lectures du compte, les états des tâches et la récupération des résultats.
Sur cette page
Options d’accès : OAuth, Codex, OpenClaw et clé API
Choisissez votre client MCP et connectez-vous
Transport et authentification
Le point d’accès MCP hébergé utilise Streamable HTTP. Les connexions par clé API envoient X-API-Key ; l’accès aux outils dépend des permissions de la clé sur les sources et des crédits disponibles.
URL: https://data.flashdata.dev/mcp
X-API-Key: <votre clé API>Enregistrez votre véritable clé API FlashData dans la configuration des identifiants du client, jamais dans une conversation ni dans les arguments d’un outil. Cette section décrit les connexions par clé API ; le guide d’accès des agents présente la connexion OAuth et les configurations Codex et OpenClaw testées. youtube_download permet les téléchargements de médias asynchrones avec la permission appropriée sur la clé API.
Gérer les clés APIOutils de requête
Votre client découvre les outils autorisés par la clé. Les six outils Google et les huit outils de données YouTube utilisent realtime par défaut et acceptent aussi mode: async. submit_batch prend en charge ces deux groupes. youtube_download utilise l’API Download, exige un stockage client et accepte les tâches async ou submit_batch. Le modèle peut choisir et combiner les outils selon la tâche.
google_search · google_images · google_news · google_shopping · google_videos · google_places
YouTube
youtube_search · youtube_search_extended · youtube_metadata · youtube_transcript · youtube_captions · youtube_trainability · youtube_channel · youtube_suggestions · youtube_download
{
"query": "MCP protocol",
"num": 3,
"gl": "us",
"hl": "en",
"mode": "async"
}Arguments des outils
Placez les champs tels que query, num, language et mode directement dans l’objet arguments de l’outil, sans l’objet params de l’API REST. Le nom de l’outil de requête sélectionne sa source ; seules les entrées de submit_batch nécessitent source. Les clés API et callback_url ne sont pas des arguments d’outil. Les exemples JSON ci-dessous représentent les objets arguments de client.callTool({ name, arguments }).
Utilisez des booléens et des entiers JSON, pas des chaînes de caractères. Les champs inconnus sont rejetés. Les 14 outils de requête de données acceptent mode: realtime ou async ; realtime est la valeur par défaut. Les entrées d’un batch n’acceptent pas mode.
| Outil | Obligatoire | Arguments facultatifs et valeurs par défaut |
|---|---|---|
youtube_download | video_id, storage | mode accepte uniquement async (valeur par défaut). download_type : audio_video (par défaut)/video/audio. video_quality : <=720 par défaut ; best/worst ou <=, ==, >= avec 144/360/480/720/1080/1440/2160/4320. fps : mêmes comparaisons, de 1 à 240. output_format : mp4 (par défaut)/webm/mkv pour la vidéo, m4a (par défaut)/mp3/opus pour l’audio. audio_language : default/original ; audio_quality : best/320/256/192/128, uniquement pour l’audio. yt_dlp_format : jusqu’à 1024 caractères, prend la priorité sur la qualité, fps et le choix de langue. Omettez video_quality/fps pour l’audio et audio_language pour la vidéo seule. storage est obligatoire et correspond à params.storage de l’API Download. start_at/end_at : HH:MM:SS, jusqu’à 12 heures ; end_at doit être postérieur à start_at. upload_metadata : booléen, false par défaut. Chaque téléchargement d’un batch nécessite storage. Ni browser_delivery ni callback_url ne sont acceptés. |
storage | storage_type, storage_url | storage_url est le nom de votre bucket (conteneur pour Azure), pas un répertoire local. storage_type : s3/s3_compatible/oss/gcs/azure/cos/bos/tos ; object_prefix est facultatif. S3, S3-compatible, OSS, COS, BOS et TOS utilisent access_key/secret_key avec les paramètres region/endpoint_url applicables. GCS utilise service_account (project_id, client_email, private_key) ; Azure utilise account_name et un sas_token de conteneur autorisant l’écriture. Le point d’accès doit être joignable depuis le worker. Lisez les identifiants depuis votre configuration de stockage ; ne les collez pas dans le chat et ne les affichez pas. |
google_* | query | query : de 1 à 2 000 caractères. gl : pays sur deux lettres ; hl : code de langue de 1 à 35 caractères ; location/tbs : de 1 à 200 caractères ; num/page : entiers de 1 à 100 ; autocorrect : booléen. Les options omises suivent le comportement du fournisseur de recherche, sans pays, langue ni nombre de résultats fixes garantis. |
youtube_search | query | query : de 1 à 2 000 caractères. max_results : de 1 à 20, 20 par défaut ; filters : objet de filtres, omis ou null pour ne pas filtrer. |
youtube_search_extended | query | query : de 1 à 2 000 caractères. max_results : de 1 à 700, 20 par défaut ; filters : identique à la recherche standard. |
youtube_metadata | video_id | include_formats et include_chapters : booléens, true par défaut pour les deux. |
youtube_transcript | video_id | Omettez language pour privilégier en-orig, puis en, et renvoyer une seule piste. Avec auto=true, chaque code privilégie sa piste -orig, puis le code sans suffixe ; un code -orig explicite ou auto=false impose une correspondance exacte. Un tableau essaie les 1 à 10 langues demandées et renvoie les pistes et erreurs dans cet ordre. auto vaut true par défaut pour les sous-titres automatiques. |
youtube_captions | video_id | Omettez language pour privilégier en-orig, puis en, et renvoyer une seule piste. Avec auto=true, chaque code privilégie sa piste -orig, puis le code sans suffixe ; un code -orig explicite ou auto=false impose une correspondance exacte. Un tableau essaie les 1 à 10 langues demandées et renvoie les pistes et erreurs dans cet ordre. auto vaut false par défaut pour les sous-titres fournis par l’auteur de la vidéo. |
youtube_trainability | video_id | Aucun argument facultatif sauf mode. Indique la classification de licence Creative Commons ; n’accorde pas d’autorisation d’entraînement. |
youtube_channel | handle | handle : de 1 à 100 caractères ; video_limit : de 1 à 100, 20 par défaut. |
youtube_suggestions | query | query : de 1 à 2 000 caractères ; language : en par défaut ; region : code pays sur deux lettres, US par défaut. |
video_id est un identifiant YouTube de 11 caractères composé de lettres, chiffres, tirets bas ou tirets ; fournissez cet identifiant plutôt que l’URL de la vidéo. Chaque code de langue contient de 1 à 35 lettres, chiffres ou tirets. Pour les sous-titres, auto=true sélectionne les sous-titres automatiques et false ceux fournis par l’auteur, sans basculement automatique entre les deux. Avec un tableau de langues, vérifiez errors même si la tâche réussit.
Filtres de recherche YouTube
filters.type : video/channel/playlist/movie ; upload_date : today/last_hour/this_week/this_month/this_year ; duration : <4, 4-20 ou >20 ; sort_by : rating/relevance/view_count/upload_date. Les options de caractéristiques sont des booléens ; true impose la présence de la caractéristique : 360, 3d, 4k, creative_commons, hd, hdr, live, location, purchased, subtitles, vr180.
{
"query": "renewable energy",
"max_results": 5,
"filters": {
"type": "video",
"duration": "<4",
"subtitles": true
}
}Informations du compte (gratuites)
get_balance lit le solde partagé du compte ; get_pricing estime le coût des requêtes ; get_limits lit les limites du forfait et les tâches actuellement en attente ; get_usage résume les 7 derniers jours par défaut, avec une période maximale de 31 jours. La consommation inclut toutes les clés du compte pour les sources autorisées par la clé appelante et peut être mise à jour avec un délai.
get_balance et get_limits prennent {}. get_pricing accepte source en option ; omettez ce champ pour toutes les sources de requête MCP autorisées par votre clé. request_count est un entier de 1 à 100000, avec 1 par défaut ; chaque page ou élément d’un batch compte comme une requête distincte. get_usage accepte source en option ; omettez ce champ pour toutes les sources autorisées. Il inclut la consommation de youtube_download. Le tarif des téléchargements renvoie creditsPerTb (1 TB = 10^12 octets) ; les téléchargements réservent des crédits, puis la facturation est ajustée selon les octets réellement envoyés vers le stockage. request_count ne s’applique pas aux téléchargements et estimatedCredits vaut null.
Les champs from/to de get_usage doivent être des horodatages ISO UTC tels que 2026-09-21T00:00:00Z, avec éventuellement 1 à 3 chiffres après la seconde. from est inclus, to est exclu ; les valeurs sont arrondies à la minute inférieure. La période par défaut est de 7 jours, avec un maximum de 31 jours. Avec seulement from, to se situe sept jours plus tard ; avec seulement to, from se situe sept jours plus tôt. Lisez from/to dans la réponse pour connaître la période effective.
{
"source": "google_search",
"request_count": 3
}{
"source": "youtube_metadata",
"from": "2026-09-21T00:00:00Z",
"to": "2026-09-22T00:00:00Z"
}Tâches et résultats volumineux
Une requête async renvoie un identifiant de tâche ; transmettez-le à get_job dans job_id pour lire job.status. Les tâches terminées contiennent la réponse d’origine dans output. Pour les téléchargements, output est le manifeste d’envoi : output.results[0].file_url pointe vers le stockage client, avec file_size, downloaded_bytes et md5. Les fichiers privés nécessitent votre authentification de stockage. Les résultats JSON sont conservés pendant 24 heures ; la conservation des médias et leur accès dépendent de vos politiques de stockage. submit_batch accepte au moins une requête Google ou YouTube, téléchargements compris, avec source et les arguments directement dans chaque entrée. Chaque entrée est facturée séparément ; les limites de batch et de tâches en attente de votre forfait s’appliquent. Lire les tâches n’entraîne pas de nouvelle facturation. Le traitement Bulk à partir d’un fichier n’est pas un outil MCP.
Un fichier d’identifiants à traiter ? Utilisez l’API HTTP Bulk
{
"video_id": "FUfGcZ092b0",
"language": "en",
"auto": true,
"mode": "async"
}{
"queries": [
{
"source": "google_search",
"query": "renewable energy",
"num": 3
},
{
"source": "youtube_metadata",
"video_id": "FUfGcZ092b0",
"include_formats": false
}
]
}Remplacez les valeurs d’exemple job_id, result_id et offset par celles de votre réponse. Lisez le fragment suivant sans soumettre à nouveau la requête.
{
"job_id": "job_REPLACE_WITH_RETURNED_ID"
}Les réponses volumineuses incluent un fragment de texte JSON, result_id et next_offset. Appelez get_result avec la même clé et le result_id renvoyé. offset est un entier positif ou nul, avec 0 par défaut ; utilisez le next_offset précédent pour poursuivre la lecture. limit est un entier de 1 à 16000, avec 16000 par défaut, mesuré en unités de code UTF-16 plutôt qu’en octets ou en lignes de résultats. Concaténez les fragments dans l’ordre avant d’analyser le JSON ; next_offset=null marque la fin. Les résultats sont mis en cache pendant 10 minutes, avec au plus quatre résultats volumineux par clé, et peuvent être évincés plus tôt. Lire les fragments ne répète pas la requête et ne consomme pas de crédits.
{
"result_id": "result_1800000000000_00000000-0000-0000-0000-000000000000",
"offset": 16000,
"limit": 16000
}Facturation et erreurs
Les requêtes suivent les tarifs en crédits de votre forfait, sans supplément MCP. Les erreurs d’outil définissent isError et conservent le statut HTTP du service en amont ainsi que l’identifiant de requête. En cas de solde insuffisant, ajoutez des crédits ; en cas d’erreur d’accès, vérifiez les permissions de la clé.
Un délai d’attente dépassé ou une connexion perdue ne signifie pas que la requête n’a pas été exécutée. Pour query_outcome_unknown, consultez l’historique des requêtes dans la console avant de décider de soumettre à nouveau. Ne relancez pas automatiquement les soumissions payantes ; les lectures de tâches ou de fragments existants peuvent être réessayées. Les réponses du service en amont sont limitées à 4 MiB : limitez la taille des recherches. Une réponse trop volumineuse peut déjà avoir été facturée.
Vérifier avec un client JavaScript
Ce client utilise la version 1.30.0 vérifiée du SDK officiel pour se connecter via Streamable HTTP et lister les outils sans lancer de requête payante. Enregistrez-le sous le nom mcp-check.mjs, définissez FLASHDATA_API_KEY dans votre environnement, puis exécutez node mcp-check.mjs.
npm install @modelcontextprotocol/[email protected]import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const key = process.env.FLASHDATA_API_KEY;
if (!key) throw new Error('Set FLASHDATA_API_KEY first.');
const client = new Client({ name: 'my-app', version: '1.0.0' });
try {
await client.connect(new StreamableHTTPClientTransport(
new URL('https://data.flashdata.dev/mcp'),
{ requestInit: { headers: { 'X-API-Key': key } } }
));
console.log((await client.listTools()).tools.map(tool => tool.name));
} finally {
await client.close();
}