> ## Documentation Index > Fetch the complete documentation index at: https://aisa.one/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > - Base URLs: models `https://api.aisa.one/v1` (Gemini GenerateContent: `https://api.aisa.one/v1beta`); data APIs `https://api.aisa.one/apis/v1`. The `servers` of each operation in https://aisa.one/openapi.yaml is authoritative. > - Auth: `Authorization: Bearer $AISA_API_KEY`. Never print, log, or commit the key. > - MCP (preferred for agents): `https://mcp.aisa.one/mcp`, signed in with OAuth, so there is no key to paste. > - Agent Skill: `npx skills add AIsa-team/agent-skills --skill aisa`. Fallback with the AIsa CLI: `aisa skills install aisa`. > - Spending: docs, https://aisa.one/models, https://aisa.one/api, `/v1/models`, and MCP `search`, `list_categories`, `get_details`, `batch_quote`, and the `account` operation are free. Quote the exact calls before running them (MCP `batch_quote`, CLI `aisa quote --json`). If the quote reports `auto_execute_eligible: true`, run it unless the user set a tighter limit or asked only for a quote. Otherwise, tell the user in one message the planned calls, the quoted price, and a total USD budget for the task, then wait for approval. Direct HTTP calls follow the stricter rule at https://aisa.one/docs/get-started/cli.md#direct-http-fallback. Do not make paid calls to test availability. Full rule: https://aisa.one/llms.txt # Get a YouTube video transcript > Account settings. Read only; needs social:read. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call. Returns the caption track YouTube already holds for one of the connected channel's own videos, as plain text plus timed cues. Use it instead of downloading and transcribing the video yourself. Auto-generated (ASR) tracks are included: YouTube serves them to the channel owner, which is what the connected account is. Uploaded tracks win over auto-generated ones when both exist for a language. ### Caching We store the transcript on first read and serve it from there afterwards, so you do not need to cache it yourself. A cached read costs no YouTube quota and does not call YouTube at all. - `source` tells you which happened: `youtube` on the first read, `cache` after. - Pass `refresh=true` only when the captions actually changed on YouTube, since that re-downloads. ### Notes - Only videos owned by this connected channel. Anything else returns 404. - `contentDetails.caption` in YouTube's own API reads `false` on videos that DO have a serving auto-generated track, so it is not a usable availability signal. Call this endpoint and handle the 404. - YouTube generates auto-captions only for videos with recognisable speech, and can take a few hours after upload to publish them. A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. ## Request contract * **Method and path:** GET /apis/v1/social/accounts/\{accountId}/youtube-captions * **Availability:** enabled * **Request URL template:** `https://api.aisa.one/apis/v1/social/accounts/{accountId}/youtube-captions` * **accountId:** path; required * **videoId:** query; required * **language:** query; optional * **format:** query; optional * **refresh:** query; optional * **Runtime facts:** 99acb5bddbedc8d3352e7c4fef86c3e6d8852c14772bcd18dbcf415237a642bd [Complete OpenAPI definition](https://aisa.one/docs/reference-contracts/aisa-social.json) Effective request and pricing declaration (including authentication and referenced schemas): ```json theme={null} { "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_74e10b", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/youtube-captions", "servers": [ { "url": "https://api.aisa.one" } ], "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "The YouTube video id (the `platformPostId` on a synced external post).", "in": "query", "name": "videoId", "required": true, "schema": { "type": "string" } }, { "description": "BCP-47 language tag as YouTube labels the track. `en` also matches an `en-GB` track. Omit to take the best available track.", "in": "query", "name": "language", "required": false, "schema": { "type": "string" } }, { "description": "`json` returns timed `cues`; `srt` returns the raw SubRip body instead. `text` is present either way.", "in": "query", "name": "format", "required": false, "schema": { "default": "json", "enum": [ "json", "srt" ], "type": "string" } }, { "description": "Re-download from YouTube instead of serving the stored copy. Spends 200 quota units.", "in": "query", "name": "refresh", "required": false, "schema": { "default": false, "type": "boolean" } } ], "security": [ { "bearerAuth": [] } ], "x-aisa-status": "enabled", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "components": { "securitySchemes": { "bearerAuth": { "scheme": "bearer", "type": "http" } } } } ``` ## Cost and request rules A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar. ## OpenAPI ````yaml reference-contracts/aisa-social.json GET /apis/v1/social/accounts/{accountId}/youtube-captions openapi: 3.1.0 info: description: '' title: AIsa Social version: '1' x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote x-aisa-configured-paths: [] x-aisa-document: facts_hash: 99acb5bddbedc8d3352e7c4fef86c3e6d8852c14772bcd18dbcf415237a642bd generator_version: '3' protocol_version: '1' schema_version: '1' composer_version: '27' response_pending: [] document_hash: sha256:7f9742cb1ea233c648dcb290fdfbf24e53a27dcf900ec1386f83a8ef2e6b1bf9 x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-provider: aisa-social x-aisa-catalogs: aisa-social: title: AIsa Social description: '' x-aisa-document: facts_hash: 99acb5bddbedc8d3352e7c4fef86c3e6d8852c14772bcd18dbcf415237a642bd generator_version: '3' protocol_version: '1' schema_version: '1' x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote servers: - url: https://api.aisa.one security: - bearerAuth: [] paths: /apis/v1/social/accounts/{accountId}/youtube-captions: get: summary: Get a YouTube video transcript description: >- Account settings. Read only; needs social:read. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call. Returns the caption track YouTube already holds for one of the connected channel's own videos, as plain text plus timed cues. Use it instead of downloading and transcribing the video yourself. Auto-generated (ASR) tracks are included: YouTube serves them to the channel owner, which is what the connected account is. Uploaded tracks win over auto-generated ones when both exist for a language. ### Caching We store the transcript on first read and serve it from there afterwards, so you do not need to cache it yourself. A cached read costs no YouTube quota and does not call YouTube at all. - `source` tells you which happened: `youtube` on the first read, `cache` after. - Pass `refresh=true` only when the captions actually changed on YouTube, since that re-downloads. ### Notes - Only videos owned by this connected channel. Anything else returns 404. - `contentDetails.caption` in YouTube's own API reads `false` on videos that DO have a serving auto-generated track, so it is not a usable availability signal. Call this endpoint and handle the 404. - YouTube generates auto-captions only for videos with recognisable speech, and can take a few hours after upload to publish them. A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. operationId: get_aisa_social_apis_v1_social_accounts_accountid_74e10b parameters: - description: One of your social accounts (acc_...). in: path name: accountId required: true schema: pattern: ^acc_[0-9A-Za-z]{22}$ type: string - description: >- The YouTube video id (the `platformPostId` on a synced external post). in: query name: videoId required: true schema: type: string - description: >- BCP-47 language tag as YouTube labels the track. `en` also matches an `en-GB` track. Omit to take the best available track. in: query name: language required: false schema: type: string - description: >- `json` returns timed `cues`; `srt` returns the raw SubRip body instead. `text` is present either way. in: query name: format required: false schema: default: json enum: - json - srt type: string - description: >- Re-download from YouTube instead of serving the stored copy. Spends 200 quota units. in: query name: refresh required: false schema: default: false type: boolean responses: '200': content: application/json: schema: properties: accountId: description: One of your social accounts (acc_...). pattern: ^acc_[0-9A-Za-z]{22}$ type: string availableTracks: description: >- Every track on the video, so you can re-request another language. On a cached read this is the listing as it stood when we downloaded, so a language added to the video since then appears only after a `refresh=true` or when you request that language directly. items: properties: language: type: string name: description: >- The track's display name. Empty for auto-generated tracks. type: string trackId: type: string trackKind: enum: - asr - standard type: string type: object type: array cues: description: >- Timed cues. Present when format is json. Auto-generated cues overlap in time by design (captions roll), so `start` can precede the previous cue's `end`. items: properties: end: type: number start: description: Seconds from the start of the video. type: number text: type: string type: object type: array fetchedAt: description: When the stored copy was downloaded from YouTube. format: date-time type: string language: description: The language of the returned track. type: string source: description: >- `cache` when served from our stored copy, `youtube` when this call spent the quota units. enum: - cache - youtube type: string srt: description: Raw SubRip body. Present when format is srt. type: string text: description: The whole transcript as one paragraph, no timings. type: string trackId: description: YouTube's own caption track id. type: string trackKind: description: >- `asr` is YouTube's auto-generated track; `standard` was uploaded by the channel. enum: - asr - standard type: string videoId: type: string type: object description: The transcript. default: content: application/json: schema: properties: error: properties: code: type: - string - 'null' details: additionalProperties: {} type: - object - 'null' message: type: - string - 'null' param: type: - string - 'null' retryHint: enum: - never - after_delay - after_reconnect - reconcile_first - null type: - string - 'null' retryable: type: - boolean - 'null' type: type: - string - 'null' type: - object - 'null' type: object description: Error. The code field is stable; see the error catalog. components: securitySchemes: bearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.