crewai-transcriptapi 0.1.0__tar.gz → 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- crewai_transcriptapi-0.2.0/.gitignore +4 -0
- crewai_transcriptapi-0.2.0/PKG-INFO +233 -0
- crewai_transcriptapi-0.2.0/README.md +188 -0
- {crewai_transcriptapi-0.1.0 → crewai_transcriptapi-0.2.0}/pyproject.toml +2 -2
- {crewai_transcriptapi-0.1.0 → crewai_transcriptapi-0.2.0}/src/crewai_transcriptapi/__init__.py +9 -2
- {crewai_transcriptapi-0.1.0 → crewai_transcriptapi-0.2.0}/src/crewai_transcriptapi/transcriptapi_tool.py +92 -11
- {crewai_transcriptapi-0.1.0 → crewai_transcriptapi-0.2.0}/tests/test_transcriptapi_tool.py +111 -1
- crewai_transcriptapi-0.1.0/PKG-INFO +0 -132
- crewai_transcriptapi-0.1.0/README.md +0 -87
- {crewai_transcriptapi-0.1.0 → crewai_transcriptapi-0.2.0}/LICENSE +0 -0
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: crewai-transcriptapi
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: CrewAI tools for TranscriptAPI: fetch YouTube transcripts, search YouTube, and pull video metadata.
|
|
5
|
+
Project-URL: Homepage, https://transcriptapi.com
|
|
6
|
+
Project-URL: Documentation, https://transcriptapi.com/docs
|
|
7
|
+
Project-URL: Repository, https://github.com/ZeroPointRepo/crewai-transcriptapi
|
|
8
|
+
Author-email: Zero Point Studio <hello@transcriptapi.com>
|
|
9
|
+
License: MIT License
|
|
10
|
+
|
|
11
|
+
Copyright (c) 2026 TranscriptAPI (ZeroPointRepo)
|
|
12
|
+
|
|
13
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
14
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
15
|
+
in the Software without restriction, including without limitation the rights
|
|
16
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
17
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
18
|
+
furnished to do so, subject to the following conditions:
|
|
19
|
+
|
|
20
|
+
The above copyright notice and this permission notice shall be included in all
|
|
21
|
+
copies or substantial portions of the Software.
|
|
22
|
+
|
|
23
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
24
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
25
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
26
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
27
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
28
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
29
|
+
SOFTWARE.
|
|
30
|
+
License-File: LICENSE
|
|
31
|
+
Keywords: ai-agent,crewai,crewai-tools,llm,transcript,transcriptapi,youtube,youtube-api,youtube-transcript
|
|
32
|
+
Classifier: Development Status :: 4 - Beta
|
|
33
|
+
Classifier: Intended Audience :: Developers
|
|
34
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
35
|
+
Classifier: Programming Language :: Python :: 3
|
|
36
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
37
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
38
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
39
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
40
|
+
Requires-Python: >=3.10
|
|
41
|
+
Requires-Dist: crewai>=0.80.0
|
|
42
|
+
Requires-Dist: pydantic>=2.0.0
|
|
43
|
+
Requires-Dist: requests>=2.31.0
|
|
44
|
+
Description-Content-Type: text/markdown
|
|
45
|
+
|
|
46
|
+
# crewai-transcriptapi
|
|
47
|
+
|
|
48
|
+
**TranscriptAPI: hosted YouTube transcript + video-discovery API for AI agents.** CrewAI tools edition. Also available as an [n8n community node](https://github.com/ZeroPointRepo/n8n-nodes-transcriptapi), an [MCP server](https://github.com/ZeroPointRepo/youtube-mcp) and [agent skills](https://github.com/ZeroPointRepo/youtube-skills).
|
|
49
|
+
|
|
50
|
+
## Why this package
|
|
51
|
+
|
|
52
|
+
Give a CrewAI agent eyes and ears on YouTube without shelling out to `yt-dlp`, scraping HTML, or juggling the Google YouTube Data API and its quota. [TranscriptAPI](https://transcriptapi.com) is a hosted backend built for this: transcript extraction, video search, and video metadata, wrapped here as three [CrewAI](https://www.crewai.com/) tools that drop straight into an `Agent`'s `tools` list.
|
|
53
|
+
|
|
54
|
+
This package is deliberately **curated**, not a full mirror of the API: three tools cover the core research loop (find a video, learn about it, read what was said in it). See [The full TranscriptAPI surface](#the-full-transcriptapi-surface) below for the rest (channel browsing, playlists, community posts) via the REST API or MCP.
|
|
55
|
+
|
|
56
|
+
## Installation
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
pip install crewai-transcriptapi
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Credentials
|
|
63
|
+
|
|
64
|
+
You need a TranscriptAPI key (starts with `sk_`):
|
|
65
|
+
|
|
66
|
+
1. Create an account at [transcriptapi.com](https://transcriptapi.com): **100 free credits, no card (one-time)**; paid plans from **$5/mo (1,000 credits)**.
|
|
67
|
+
2. Create an API key on the dashboard.
|
|
68
|
+
3. Export it:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
export TRANSCRIPTAPI_API_KEY="sk_..."
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Tools
|
|
75
|
+
|
|
76
|
+
| Tool | What it does | Cost |
|
|
77
|
+
|---|---|---|
|
|
78
|
+
| **TranscriptAPITool** | Fetch the transcript of a YouTube video (full URL, youtu.be, embed, Shorts, or bare ID) as plain text or timestamped JSON, with metadata | 1 credit/call |
|
|
79
|
+
| **TranscriptAPISearchTool** | Search YouTube for videos, channels, playlists, or movies, with sort/upload-date/duration/feature filters (first page only; this tool does not expose a continuation token for further pages) | 1 credit/page |
|
|
80
|
+
| **TranscriptAPIVideoMetadataTool** | Pull a video's view/like counts, publish date, description, links, uploading channel, and optional details (duration, category, tags) or related videos, without pulling the transcript | 1 credit/call |
|
|
81
|
+
|
|
82
|
+
## When to use what
|
|
83
|
+
|
|
84
|
+
| Job | Tool |
|
|
85
|
+
|---|---|
|
|
86
|
+
| Need the spoken content of a video: summarize, quote, translate, fact-check | `TranscriptAPITool` |
|
|
87
|
+
| Need to discover videos, channels, playlists, or movies about a topic before pulling anything else | `TranscriptAPISearchTool` |
|
|
88
|
+
| Need facts about a video without pulling its transcript: view/like counts, publish date, description, duration, tags, related videos | `TranscriptAPIVideoMetadataTool` |
|
|
89
|
+
| Building a research pipeline: find candidates, then decide which ones are worth a full transcript | `TranscriptAPISearchTool` -> `TranscriptAPIVideoMetadataTool` -> `TranscriptAPITool` |
|
|
90
|
+
| Need a channel's profile, uploads, playlists, posts, or sections | Step up to the REST API or MCP server; not exposed by this package |
|
|
91
|
+
|
|
92
|
+
## Usage
|
|
93
|
+
|
|
94
|
+
Basic setup: search, then transcribe.
|
|
95
|
+
|
|
96
|
+
```python
|
|
97
|
+
from crewai import Agent
|
|
98
|
+
from crewai_transcriptapi import TranscriptAPITool, TranscriptAPISearchTool
|
|
99
|
+
|
|
100
|
+
researcher = Agent(
|
|
101
|
+
role="Video researcher",
|
|
102
|
+
goal="Find and summarize YouTube content on a topic",
|
|
103
|
+
backstory="Researches spoken video content via transcripts.",
|
|
104
|
+
tools=[TranscriptAPISearchTool(), TranscriptAPITool()],
|
|
105
|
+
)
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
The agent can then search for videos on a topic and fetch each transcript for summarizing, quoting, translating or analysis.
|
|
109
|
+
|
|
110
|
+
### Research crew example: search, screen, then transcribe
|
|
111
|
+
|
|
112
|
+
Adding `TranscriptAPIVideoMetadataTool` lets the agent screen search results (view count, publish date) before spending a credit on a transcript it doesn't need:
|
|
113
|
+
|
|
114
|
+
```python
|
|
115
|
+
from crewai import Agent, Task, Crew
|
|
116
|
+
from crewai_transcriptapi import (
|
|
117
|
+
TranscriptAPITool,
|
|
118
|
+
TranscriptAPISearchTool,
|
|
119
|
+
TranscriptAPIVideoMetadataTool,
|
|
120
|
+
)
|
|
121
|
+
|
|
122
|
+
researcher = Agent(
|
|
123
|
+
role="Video researcher",
|
|
124
|
+
goal="Find the most relevant, well-established videos on a topic and summarize them",
|
|
125
|
+
backstory=(
|
|
126
|
+
"Searches YouTube for candidates, checks each one's metadata to judge "
|
|
127
|
+
"relevance and credibility before spending a transcript credit, then "
|
|
128
|
+
"reads the transcripts of the ones worth reading."
|
|
129
|
+
),
|
|
130
|
+
tools=[
|
|
131
|
+
TranscriptAPISearchTool(),
|
|
132
|
+
TranscriptAPIVideoMetadataTool(),
|
|
133
|
+
TranscriptAPITool(),
|
|
134
|
+
],
|
|
135
|
+
)
|
|
136
|
+
|
|
137
|
+
task = Task(
|
|
138
|
+
description=(
|
|
139
|
+
"Find 3 well-established videos about {topic}. For each, check the "
|
|
140
|
+
"view count and publish date before deciding it's worth summarizing, "
|
|
141
|
+
"then fetch the transcript and write a 5-bullet summary."
|
|
142
|
+
),
|
|
143
|
+
expected_output="A markdown report with one section per video.",
|
|
144
|
+
agent=researcher,
|
|
145
|
+
)
|
|
146
|
+
|
|
147
|
+
Crew(agents=[researcher], tasks=[task]).kickoff(inputs={"topic": "transformer architectures"})
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### Calling a tool directly
|
|
151
|
+
|
|
152
|
+
Every tool returns a JSON string, so you can call it outside of a `Crew` for scripting or testing:
|
|
153
|
+
|
|
154
|
+
```python
|
|
155
|
+
import json
|
|
156
|
+
from crewai_transcriptapi import TranscriptAPIVideoMetadataTool
|
|
157
|
+
|
|
158
|
+
tool = TranscriptAPIVideoMetadataTool()
|
|
159
|
+
result = json.loads(tool.run(video_url="UF8uR6Z6KLc", include="details,related"))
|
|
160
|
+
if result["success"]:
|
|
161
|
+
print(result["data"]["title"], result["data"]["viewCountText"])
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
## Use cases
|
|
165
|
+
|
|
166
|
+
- **Check a video's facts without pulling its transcript.** `TranscriptAPIVideoMetadataTool` returns view/like counts, publish date, description, and related videos.
|
|
167
|
+
- **Beyond this package.** `TranscriptAPISearchTool` (`search_type="playlist"`) finds a playlist on a topic; listing that playlist's videos or browsing the channel that made it are REST/MCP operations (`playlist/videos`, `channel/videos`), not part of this package's 3 tools.
|
|
168
|
+
|
|
169
|
+
## Tool reference
|
|
170
|
+
|
|
171
|
+
### TranscriptAPITool
|
|
172
|
+
|
|
173
|
+
| Argument | Type | Default | Description |
|
|
174
|
+
|---|---|---|---|
|
|
175
|
+
| `video_url` | str | required | Full YouTube URL (watch, youtu.be, embed, Shorts) or bare 11-character video ID |
|
|
176
|
+
| `output_format` | str | `"text"` | `"text"` for plain transcript, `"json"` for timestamped segments |
|
|
177
|
+
| `language` | str | none | Optional preferred transcript language code, for example `"es"` |
|
|
178
|
+
|
|
179
|
+
### TranscriptAPISearchTool
|
|
180
|
+
|
|
181
|
+
| Argument | Type | Default | Description |
|
|
182
|
+
|---|---|---|---|
|
|
183
|
+
| `query` | str | required | Search query, 1 to 200 characters |
|
|
184
|
+
| `search_type` | str | `"video"` | `"video"`, `"channel"`, `"playlist"`, or `"movie"` |
|
|
185
|
+
| `sort` | str | none | `"relevance"` or `"views"` |
|
|
186
|
+
| `upload_date` | str | none | `"hour"`, `"today"`, `"week"`, `"month"`, or `"year"` (videos only) |
|
|
187
|
+
| `duration` | str | none | `"short"` (<4m), `"medium"` (4-20m), or `"long"` (>20m) (videos only) |
|
|
188
|
+
| `features` | str | none | Comma-separated filters, e.g. `"hd,subtitles,cc,live,4k,hdr,360,creative_commons"` |
|
|
189
|
+
|
|
190
|
+
### TranscriptAPIVideoMetadataTool
|
|
191
|
+
|
|
192
|
+
| Argument | Type | Default | Description |
|
|
193
|
+
|---|---|---|---|
|
|
194
|
+
| `video_url` | str | required | Full YouTube URL (watch, youtu.be, embed, Shorts) or bare 11-character video ID |
|
|
195
|
+
| `include` | str | none | Comma-separated extras: `"details"` and/or `"related"` |
|
|
196
|
+
|
|
197
|
+
## Costs
|
|
198
|
+
|
|
199
|
+
A successful call costs 1 credit: `TranscriptAPITool` per transcript, `TranscriptAPISearchTool` per call (first page only), `TranscriptAPIVideoMetadataTool` per lookup (`include` does not change the price). Failed calls and rate-limited (429) calls cost 0.
|
|
200
|
+
|
|
201
|
+
## Response envelope
|
|
202
|
+
|
|
203
|
+
All three tools return a stable JSON string and never raise:
|
|
204
|
+
|
|
205
|
+
```json
|
|
206
|
+
{"success": true, "data": {"transcript": "...", "metadata": {"title": "..."}}}
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
```json
|
|
210
|
+
{"success": false, "error": {"code": "out_of_credits", "message": "The account is out of credits. See https://transcriptapi.com/billing."}}
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Error codes: `missing_api_key`, `invalid_api_key`, `out_of_credits`, `not_found`, `rate_limited`, `network`, `bad_response`, `http_<status>`. Failed calls are never charged.
|
|
214
|
+
|
|
215
|
+
## The full TranscriptAPI surface
|
|
216
|
+
|
|
217
|
+
This package ships 3 curated tools for the core research loop. TranscriptAPI itself covers more ground: channel profiles, uploads, Shorts, live streams, playlists, community posts, and curated channel sections. That breadth is available today via the [REST API](https://transcriptapi.com/docs/api) or the [MCP server](https://transcriptapi.com/docs/mcp) (12 tools), and via the [n8n community node](https://github.com/ZeroPointRepo/n8n-nodes-transcriptapi) (11 operations). If your CrewAI agents need channel or playlist browsing, call the REST API directly with a custom tool, or open an issue.
|
|
218
|
+
|
|
219
|
+
## Resources
|
|
220
|
+
|
|
221
|
+
- [TranscriptAPI documentation](https://transcriptapi.com/docs)
|
|
222
|
+
- [REST API reference](https://transcriptapi.com/docs/api)
|
|
223
|
+
- [MCP reference](https://transcriptapi.com/docs/mcp)
|
|
224
|
+
- [Pricing](https://transcriptapi.com/#pricing)
|
|
225
|
+
- Family: [n8n node](https://github.com/ZeroPointRepo/n8n-nodes-transcriptapi) · [MCP server](https://github.com/ZeroPointRepo/youtube-mcp) · [agent skills](https://github.com/ZeroPointRepo/youtube-skills)
|
|
226
|
+
|
|
227
|
+
## Disclosure
|
|
228
|
+
|
|
229
|
+
TranscriptAPI is an independent product and is not affiliated with or endorsed by YouTube or Google. Use of these tools is subject to the [TranscriptAPI terms](https://transcriptapi.com/terms).
|
|
230
|
+
|
|
231
|
+
## License
|
|
232
|
+
|
|
233
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
# crewai-transcriptapi
|
|
2
|
+
|
|
3
|
+
**TranscriptAPI: hosted YouTube transcript + video-discovery API for AI agents.** CrewAI tools edition. Also available as an [n8n community node](https://github.com/ZeroPointRepo/n8n-nodes-transcriptapi), an [MCP server](https://github.com/ZeroPointRepo/youtube-mcp) and [agent skills](https://github.com/ZeroPointRepo/youtube-skills).
|
|
4
|
+
|
|
5
|
+
## Why this package
|
|
6
|
+
|
|
7
|
+
Give a CrewAI agent eyes and ears on YouTube without shelling out to `yt-dlp`, scraping HTML, or juggling the Google YouTube Data API and its quota. [TranscriptAPI](https://transcriptapi.com) is a hosted backend built for this: transcript extraction, video search, and video metadata, wrapped here as three [CrewAI](https://www.crewai.com/) tools that drop straight into an `Agent`'s `tools` list.
|
|
8
|
+
|
|
9
|
+
This package is deliberately **curated**, not a full mirror of the API: three tools cover the core research loop (find a video, learn about it, read what was said in it). See [The full TranscriptAPI surface](#the-full-transcriptapi-surface) below for the rest (channel browsing, playlists, community posts) via the REST API or MCP.
|
|
10
|
+
|
|
11
|
+
## Installation
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
pip install crewai-transcriptapi
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Credentials
|
|
18
|
+
|
|
19
|
+
You need a TranscriptAPI key (starts with `sk_`):
|
|
20
|
+
|
|
21
|
+
1. Create an account at [transcriptapi.com](https://transcriptapi.com): **100 free credits, no card (one-time)**; paid plans from **$5/mo (1,000 credits)**.
|
|
22
|
+
2. Create an API key on the dashboard.
|
|
23
|
+
3. Export it:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
export TRANSCRIPTAPI_API_KEY="sk_..."
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Tools
|
|
30
|
+
|
|
31
|
+
| Tool | What it does | Cost |
|
|
32
|
+
|---|---|---|
|
|
33
|
+
| **TranscriptAPITool** | Fetch the transcript of a YouTube video (full URL, youtu.be, embed, Shorts, or bare ID) as plain text or timestamped JSON, with metadata | 1 credit/call |
|
|
34
|
+
| **TranscriptAPISearchTool** | Search YouTube for videos, channels, playlists, or movies, with sort/upload-date/duration/feature filters (first page only; this tool does not expose a continuation token for further pages) | 1 credit/page |
|
|
35
|
+
| **TranscriptAPIVideoMetadataTool** | Pull a video's view/like counts, publish date, description, links, uploading channel, and optional details (duration, category, tags) or related videos, without pulling the transcript | 1 credit/call |
|
|
36
|
+
|
|
37
|
+
## When to use what
|
|
38
|
+
|
|
39
|
+
| Job | Tool |
|
|
40
|
+
|---|---|
|
|
41
|
+
| Need the spoken content of a video: summarize, quote, translate, fact-check | `TranscriptAPITool` |
|
|
42
|
+
| Need to discover videos, channels, playlists, or movies about a topic before pulling anything else | `TranscriptAPISearchTool` |
|
|
43
|
+
| Need facts about a video without pulling its transcript: view/like counts, publish date, description, duration, tags, related videos | `TranscriptAPIVideoMetadataTool` |
|
|
44
|
+
| Building a research pipeline: find candidates, then decide which ones are worth a full transcript | `TranscriptAPISearchTool` -> `TranscriptAPIVideoMetadataTool` -> `TranscriptAPITool` |
|
|
45
|
+
| Need a channel's profile, uploads, playlists, posts, or sections | Step up to the REST API or MCP server; not exposed by this package |
|
|
46
|
+
|
|
47
|
+
## Usage
|
|
48
|
+
|
|
49
|
+
Basic setup: search, then transcribe.
|
|
50
|
+
|
|
51
|
+
```python
|
|
52
|
+
from crewai import Agent
|
|
53
|
+
from crewai_transcriptapi import TranscriptAPITool, TranscriptAPISearchTool
|
|
54
|
+
|
|
55
|
+
researcher = Agent(
|
|
56
|
+
role="Video researcher",
|
|
57
|
+
goal="Find and summarize YouTube content on a topic",
|
|
58
|
+
backstory="Researches spoken video content via transcripts.",
|
|
59
|
+
tools=[TranscriptAPISearchTool(), TranscriptAPITool()],
|
|
60
|
+
)
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The agent can then search for videos on a topic and fetch each transcript for summarizing, quoting, translating or analysis.
|
|
64
|
+
|
|
65
|
+
### Research crew example: search, screen, then transcribe
|
|
66
|
+
|
|
67
|
+
Adding `TranscriptAPIVideoMetadataTool` lets the agent screen search results (view count, publish date) before spending a credit on a transcript it doesn't need:
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
from crewai import Agent, Task, Crew
|
|
71
|
+
from crewai_transcriptapi import (
|
|
72
|
+
TranscriptAPITool,
|
|
73
|
+
TranscriptAPISearchTool,
|
|
74
|
+
TranscriptAPIVideoMetadataTool,
|
|
75
|
+
)
|
|
76
|
+
|
|
77
|
+
researcher = Agent(
|
|
78
|
+
role="Video researcher",
|
|
79
|
+
goal="Find the most relevant, well-established videos on a topic and summarize them",
|
|
80
|
+
backstory=(
|
|
81
|
+
"Searches YouTube for candidates, checks each one's metadata to judge "
|
|
82
|
+
"relevance and credibility before spending a transcript credit, then "
|
|
83
|
+
"reads the transcripts of the ones worth reading."
|
|
84
|
+
),
|
|
85
|
+
tools=[
|
|
86
|
+
TranscriptAPISearchTool(),
|
|
87
|
+
TranscriptAPIVideoMetadataTool(),
|
|
88
|
+
TranscriptAPITool(),
|
|
89
|
+
],
|
|
90
|
+
)
|
|
91
|
+
|
|
92
|
+
task = Task(
|
|
93
|
+
description=(
|
|
94
|
+
"Find 3 well-established videos about {topic}. For each, check the "
|
|
95
|
+
"view count and publish date before deciding it's worth summarizing, "
|
|
96
|
+
"then fetch the transcript and write a 5-bullet summary."
|
|
97
|
+
),
|
|
98
|
+
expected_output="A markdown report with one section per video.",
|
|
99
|
+
agent=researcher,
|
|
100
|
+
)
|
|
101
|
+
|
|
102
|
+
Crew(agents=[researcher], tasks=[task]).kickoff(inputs={"topic": "transformer architectures"})
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### Calling a tool directly
|
|
106
|
+
|
|
107
|
+
Every tool returns a JSON string, so you can call it outside of a `Crew` for scripting or testing:
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
import json
|
|
111
|
+
from crewai_transcriptapi import TranscriptAPIVideoMetadataTool
|
|
112
|
+
|
|
113
|
+
tool = TranscriptAPIVideoMetadataTool()
|
|
114
|
+
result = json.loads(tool.run(video_url="UF8uR6Z6KLc", include="details,related"))
|
|
115
|
+
if result["success"]:
|
|
116
|
+
print(result["data"]["title"], result["data"]["viewCountText"])
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## Use cases
|
|
120
|
+
|
|
121
|
+
- **Check a video's facts without pulling its transcript.** `TranscriptAPIVideoMetadataTool` returns view/like counts, publish date, description, and related videos.
|
|
122
|
+
- **Beyond this package.** `TranscriptAPISearchTool` (`search_type="playlist"`) finds a playlist on a topic; listing that playlist's videos or browsing the channel that made it are REST/MCP operations (`playlist/videos`, `channel/videos`), not part of this package's 3 tools.
|
|
123
|
+
|
|
124
|
+
## Tool reference
|
|
125
|
+
|
|
126
|
+
### TranscriptAPITool
|
|
127
|
+
|
|
128
|
+
| Argument | Type | Default | Description |
|
|
129
|
+
|---|---|---|---|
|
|
130
|
+
| `video_url` | str | required | Full YouTube URL (watch, youtu.be, embed, Shorts) or bare 11-character video ID |
|
|
131
|
+
| `output_format` | str | `"text"` | `"text"` for plain transcript, `"json"` for timestamped segments |
|
|
132
|
+
| `language` | str | none | Optional preferred transcript language code, for example `"es"` |
|
|
133
|
+
|
|
134
|
+
### TranscriptAPISearchTool
|
|
135
|
+
|
|
136
|
+
| Argument | Type | Default | Description |
|
|
137
|
+
|---|---|---|---|
|
|
138
|
+
| `query` | str | required | Search query, 1 to 200 characters |
|
|
139
|
+
| `search_type` | str | `"video"` | `"video"`, `"channel"`, `"playlist"`, or `"movie"` |
|
|
140
|
+
| `sort` | str | none | `"relevance"` or `"views"` |
|
|
141
|
+
| `upload_date` | str | none | `"hour"`, `"today"`, `"week"`, `"month"`, or `"year"` (videos only) |
|
|
142
|
+
| `duration` | str | none | `"short"` (<4m), `"medium"` (4-20m), or `"long"` (>20m) (videos only) |
|
|
143
|
+
| `features` | str | none | Comma-separated filters, e.g. `"hd,subtitles,cc,live,4k,hdr,360,creative_commons"` |
|
|
144
|
+
|
|
145
|
+
### TranscriptAPIVideoMetadataTool
|
|
146
|
+
|
|
147
|
+
| Argument | Type | Default | Description |
|
|
148
|
+
|---|---|---|---|
|
|
149
|
+
| `video_url` | str | required | Full YouTube URL (watch, youtu.be, embed, Shorts) or bare 11-character video ID |
|
|
150
|
+
| `include` | str | none | Comma-separated extras: `"details"` and/or `"related"` |
|
|
151
|
+
|
|
152
|
+
## Costs
|
|
153
|
+
|
|
154
|
+
A successful call costs 1 credit: `TranscriptAPITool` per transcript, `TranscriptAPISearchTool` per call (first page only), `TranscriptAPIVideoMetadataTool` per lookup (`include` does not change the price). Failed calls and rate-limited (429) calls cost 0.
|
|
155
|
+
|
|
156
|
+
## Response envelope
|
|
157
|
+
|
|
158
|
+
All three tools return a stable JSON string and never raise:
|
|
159
|
+
|
|
160
|
+
```json
|
|
161
|
+
{"success": true, "data": {"transcript": "...", "metadata": {"title": "..."}}}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
```json
|
|
165
|
+
{"success": false, "error": {"code": "out_of_credits", "message": "The account is out of credits. See https://transcriptapi.com/billing."}}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Error codes: `missing_api_key`, `invalid_api_key`, `out_of_credits`, `not_found`, `rate_limited`, `network`, `bad_response`, `http_<status>`. Failed calls are never charged.
|
|
169
|
+
|
|
170
|
+
## The full TranscriptAPI surface
|
|
171
|
+
|
|
172
|
+
This package ships 3 curated tools for the core research loop. TranscriptAPI itself covers more ground: channel profiles, uploads, Shorts, live streams, playlists, community posts, and curated channel sections. That breadth is available today via the [REST API](https://transcriptapi.com/docs/api) or the [MCP server](https://transcriptapi.com/docs/mcp) (12 tools), and via the [n8n community node](https://github.com/ZeroPointRepo/n8n-nodes-transcriptapi) (11 operations). If your CrewAI agents need channel or playlist browsing, call the REST API directly with a custom tool, or open an issue.
|
|
173
|
+
|
|
174
|
+
## Resources
|
|
175
|
+
|
|
176
|
+
- [TranscriptAPI documentation](https://transcriptapi.com/docs)
|
|
177
|
+
- [REST API reference](https://transcriptapi.com/docs/api)
|
|
178
|
+
- [MCP reference](https://transcriptapi.com/docs/mcp)
|
|
179
|
+
- [Pricing](https://transcriptapi.com/#pricing)
|
|
180
|
+
- Family: [n8n node](https://github.com/ZeroPointRepo/n8n-nodes-transcriptapi) · [MCP server](https://github.com/ZeroPointRepo/youtube-mcp) · [agent skills](https://github.com/ZeroPointRepo/youtube-skills)
|
|
181
|
+
|
|
182
|
+
## Disclosure
|
|
183
|
+
|
|
184
|
+
TranscriptAPI is an independent product and is not affiliated with or endorsed by YouTube or Google. Use of these tools is subject to the [TranscriptAPI terms](https://transcriptapi.com/terms).
|
|
185
|
+
|
|
186
|
+
## License
|
|
187
|
+
|
|
188
|
+
[MIT](LICENSE)
|
|
@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "crewai-transcriptapi"
|
|
7
|
-
version = "0.
|
|
8
|
-
description = "CrewAI tools for TranscriptAPI: fetch YouTube transcripts
|
|
7
|
+
version = "0.2.0"
|
|
8
|
+
description = "CrewAI tools for TranscriptAPI: fetch YouTube transcripts, search YouTube, and pull video metadata."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
license = { file = "LICENSE" }
|
|
11
11
|
requires-python = ">=3.10"
|
{crewai_transcriptapi-0.1.0 → crewai_transcriptapi-0.2.0}/src/crewai_transcriptapi/__init__.py
RENAMED
|
@@ -3,19 +3,26 @@
|
|
|
3
3
|
from .transcriptapi_tool import (
|
|
4
4
|
TranscriptAPISearchToolSchema,
|
|
5
5
|
TranscriptAPIToolSchema,
|
|
6
|
+
TranscriptAPIVideoMetadataToolSchema,
|
|
6
7
|
)
|
|
7
8
|
|
|
8
9
|
try:
|
|
9
|
-
from .transcriptapi_tool import
|
|
10
|
+
from .transcriptapi_tool import (
|
|
11
|
+
TranscriptAPISearchTool,
|
|
12
|
+
TranscriptAPITool,
|
|
13
|
+
TranscriptAPIVideoMetadataTool,
|
|
14
|
+
)
|
|
10
15
|
except ImportError: # pragma: no cover - crewai not installed
|
|
11
16
|
pass
|
|
12
17
|
|
|
13
|
-
__version__ = "0.
|
|
18
|
+
__version__ = "0.2.0"
|
|
14
19
|
|
|
15
20
|
__all__ = [
|
|
16
21
|
"TranscriptAPITool",
|
|
17
22
|
"TranscriptAPISearchTool",
|
|
23
|
+
"TranscriptAPIVideoMetadataTool",
|
|
18
24
|
"TranscriptAPIToolSchema",
|
|
19
25
|
"TranscriptAPISearchToolSchema",
|
|
26
|
+
"TranscriptAPIVideoMetadataToolSchema",
|
|
20
27
|
"__version__",
|
|
21
28
|
]
|
|
@@ -1,11 +1,15 @@
|
|
|
1
1
|
"""CrewAI tools for TranscriptAPI (transcriptapi.com).
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Three tools following the crewai-tools BaseTool conventions:
|
|
4
4
|
|
|
5
5
|
- TranscriptAPITool: fetch the transcript of a YouTube video (the hero use case)
|
|
6
|
-
- TranscriptAPISearchTool: search YouTube for videos or
|
|
6
|
+
- TranscriptAPISearchTool: search YouTube for videos, channels, playlists, or movies
|
|
7
|
+
- TranscriptAPIVideoMetadataTool: rich video metadata (view/like counts, publish
|
|
8
|
+
date, description, optional player details and related videos) via the
|
|
9
|
+
/youtube/video/metadata endpoint (the paid replacement for the retired
|
|
10
|
+
/youtube/video/info path)
|
|
7
11
|
|
|
8
|
-
|
|
12
|
+
All three return a stable JSON string envelope and never leak exceptions:
|
|
9
13
|
{"success": true, "data": {...}}
|
|
10
14
|
{"success": false, "error": {"code": "...", "message": "..."}}
|
|
11
15
|
|
|
@@ -123,8 +127,50 @@ class TranscriptAPISearchToolSchema(BaseModel):
|
|
|
123
127
|
query: str = Field(..., min_length=1, max_length=200, description="Search query")
|
|
124
128
|
search_type: str = Field(
|
|
125
129
|
default="video",
|
|
126
|
-
pattern="^(video|channel)$",
|
|
127
|
-
description='What to search for: "video" or "
|
|
130
|
+
pattern="^(video|channel|playlist|movie)$",
|
|
131
|
+
description='What to search for: "video", "channel", "playlist", or "movie"',
|
|
132
|
+
)
|
|
133
|
+
sort: Optional[str] = Field(
|
|
134
|
+
default=None,
|
|
135
|
+
pattern="^(relevance|views)$",
|
|
136
|
+
description='Sort order: "relevance" (default) or "views" (YouTube\'s "Popularity")',
|
|
137
|
+
)
|
|
138
|
+
upload_date: Optional[str] = Field(
|
|
139
|
+
default=None,
|
|
140
|
+
pattern="^(hour|today|week|month|year)$",
|
|
141
|
+
description="Upload-date window (videos only): hour, today, week, month, or year",
|
|
142
|
+
)
|
|
143
|
+
duration: Optional[str] = Field(
|
|
144
|
+
default=None,
|
|
145
|
+
pattern="^(short|medium|long)$",
|
|
146
|
+
description="Duration bucket (videos only): short (<4m), medium (4-20m), or long (>20m)",
|
|
147
|
+
)
|
|
148
|
+
features: Optional[str] = Field(
|
|
149
|
+
default=None,
|
|
150
|
+
description=(
|
|
151
|
+
"Comma-separated feature filters, e.g. 'hd,subtitles,cc,live,4k,hdr,360,"
|
|
152
|
+
"creative_commons'"
|
|
153
|
+
),
|
|
154
|
+
)
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
class TranscriptAPIVideoMetadataToolSchema(BaseModel):
|
|
158
|
+
"""Input for TranscriptAPIVideoMetadataTool."""
|
|
159
|
+
|
|
160
|
+
video_url: str = Field(
|
|
161
|
+
...,
|
|
162
|
+
min_length=6,
|
|
163
|
+
description=(
|
|
164
|
+
"Full YouTube URL (watch, youtu.be, embed, or Shorts) or the bare "
|
|
165
|
+
"11-character video ID"
|
|
166
|
+
),
|
|
167
|
+
)
|
|
168
|
+
include: Optional[str] = Field(
|
|
169
|
+
default=None,
|
|
170
|
+
description=(
|
|
171
|
+
"Comma-separated extras: 'details' (duration, category, tags, caption "
|
|
172
|
+
"tracks) and/or 'related' (related videos)"
|
|
173
|
+
),
|
|
128
174
|
)
|
|
129
175
|
|
|
130
176
|
|
|
@@ -164,11 +210,13 @@ if BaseTool is not None:
|
|
|
164
210
|
model_config = ConfigDict(arbitrary_types_allowed=True)
|
|
165
211
|
name: str = "TranscriptAPI YouTube Search"
|
|
166
212
|
description: str = (
|
|
167
|
-
"Searches YouTube for videos or
|
|
168
|
-
"service and returns titles, IDs, thumbnails, view
|
|
169
|
-
"publish dates.
|
|
170
|
-
"
|
|
171
|
-
"
|
|
213
|
+
"Searches YouTube for videos, channels, playlists, or movies via the "
|
|
214
|
+
"TranscriptAPI service and returns titles, IDs, thumbnails, view "
|
|
215
|
+
"counts and publish dates. Supports sorting by relevance or views, "
|
|
216
|
+
"and (for video search) filtering by upload-date window, duration "
|
|
217
|
+
"bucket, or feature (hd, subtitles, live, etc). Use when the task "
|
|
218
|
+
"needs to discover content about a topic before fetching "
|
|
219
|
+
"transcripts. Costs 1 credit per page of results."
|
|
172
220
|
)
|
|
173
221
|
args_schema: Type[BaseModel] = TranscriptAPISearchToolSchema
|
|
174
222
|
package_dependencies: list = Field(default_factory=lambda: ["requests"])
|
|
@@ -178,5 +226,38 @@ if BaseTool is not None:
|
|
|
178
226
|
args = TranscriptAPISearchToolSchema(**kwargs)
|
|
179
227
|
return _request(
|
|
180
228
|
"/youtube/search",
|
|
181
|
-
{
|
|
229
|
+
{
|
|
230
|
+
"q": args.query,
|
|
231
|
+
"type": args.search_type,
|
|
232
|
+
"sort": args.sort,
|
|
233
|
+
"upload_date": args.upload_date,
|
|
234
|
+
"duration": args.duration,
|
|
235
|
+
"features": args.features,
|
|
236
|
+
},
|
|
237
|
+
)
|
|
238
|
+
|
|
239
|
+
class TranscriptAPIVideoMetadataTool(BaseTool):
|
|
240
|
+
"""Fetch rich metadata for a YouTube video via TranscriptAPI."""
|
|
241
|
+
|
|
242
|
+
model_config = ConfigDict(arbitrary_types_allowed=True)
|
|
243
|
+
name: str = "TranscriptAPI YouTube Video Metadata"
|
|
244
|
+
description: str = (
|
|
245
|
+
"Fetches rich metadata for a YouTube video via the TranscriptAPI "
|
|
246
|
+
"service, without needing captions: title, view/like-count text, "
|
|
247
|
+
"publish date, a structured description with extracted links, the "
|
|
248
|
+
"uploading channel's summary, and thumbnails. Optionally include "
|
|
249
|
+
"player-sourced 'details' (duration, category, tags, caption-track "
|
|
250
|
+
"inventory) and/or 'related' videos. Use when the task needs facts "
|
|
251
|
+
"about a video rather than its spoken content. Costs 1 credit per "
|
|
252
|
+
"call regardless of which extras are requested."
|
|
253
|
+
)
|
|
254
|
+
args_schema: Type[BaseModel] = TranscriptAPIVideoMetadataToolSchema
|
|
255
|
+
package_dependencies: list = Field(default_factory=lambda: ["requests"])
|
|
256
|
+
env_vars: list = Field(default_factory=lambda: list(_ENV_VARS))
|
|
257
|
+
|
|
258
|
+
def _run(self, **kwargs: Any) -> str:
|
|
259
|
+
args = TranscriptAPIVideoMetadataToolSchema(**kwargs)
|
|
260
|
+
return _request(
|
|
261
|
+
"/youtube/video/metadata",
|
|
262
|
+
{"video_url": args.video_url, "include": args.include},
|
|
182
263
|
)
|
|
@@ -48,6 +48,8 @@ from crewai_transcriptapi.transcriptapi_tool import ( # noqa: E402
|
|
|
48
48
|
TranscriptAPISearchToolSchema,
|
|
49
49
|
TranscriptAPITool,
|
|
50
50
|
TranscriptAPIToolSchema,
|
|
51
|
+
TranscriptAPIVideoMetadataTool,
|
|
52
|
+
TranscriptAPIVideoMetadataToolSchema,
|
|
51
53
|
)
|
|
52
54
|
|
|
53
55
|
|
|
@@ -80,7 +82,34 @@ class SchemaTests(unittest.TestCase):
|
|
|
80
82
|
with self.assertRaises(Exception):
|
|
81
83
|
TranscriptAPISearchToolSchema(query="")
|
|
82
84
|
with self.assertRaises(Exception):
|
|
83
|
-
TranscriptAPISearchToolSchema(query="x", search_type="
|
|
85
|
+
TranscriptAPISearchToolSchema(query="x", search_type="bogus")
|
|
86
|
+
|
|
87
|
+
def test_search_schema_accepts_new_types_and_filters(self):
|
|
88
|
+
for t in ("video", "channel", "playlist", "movie"):
|
|
89
|
+
TranscriptAPISearchToolSchema(query="x", search_type=t)
|
|
90
|
+
s = TranscriptAPISearchToolSchema(
|
|
91
|
+
query="x", sort="views", upload_date="week", duration="long", features="hd,cc"
|
|
92
|
+
)
|
|
93
|
+
self.assertEqual(s.sort, "views")
|
|
94
|
+
self.assertEqual(s.upload_date, "week")
|
|
95
|
+
self.assertEqual(s.duration, "long")
|
|
96
|
+
self.assertEqual(s.features, "hd,cc")
|
|
97
|
+
|
|
98
|
+
def test_search_schema_rejects_bad_filters(self):
|
|
99
|
+
with self.assertRaises(Exception):
|
|
100
|
+
TranscriptAPISearchToolSchema(query="x", sort="popularity")
|
|
101
|
+
with self.assertRaises(Exception):
|
|
102
|
+
TranscriptAPISearchToolSchema(query="x", upload_date="decade")
|
|
103
|
+
with self.assertRaises(Exception):
|
|
104
|
+
TranscriptAPISearchToolSchema(query="x", duration="epic")
|
|
105
|
+
|
|
106
|
+
def test_video_metadata_schema_requires_video_url(self):
|
|
107
|
+
with self.assertRaises(Exception):
|
|
108
|
+
TranscriptAPIVideoMetadataToolSchema()
|
|
109
|
+
|
|
110
|
+
def test_video_metadata_schema_defaults(self):
|
|
111
|
+
s = TranscriptAPIVideoMetadataToolSchema(video_url="dQw4w9WgXcQ")
|
|
112
|
+
self.assertIsNone(s.include)
|
|
84
113
|
|
|
85
114
|
|
|
86
115
|
class EnvTests(unittest.TestCase):
|
|
@@ -170,6 +199,87 @@ class SearchToolTests(unittest.TestCase):
|
|
|
170
199
|
self.assertEqual(getter.call_args.kwargs["params"]["q"], "machine learning")
|
|
171
200
|
self.assertEqual(getter.call_args.kwargs["params"]["type"], "channel")
|
|
172
201
|
|
|
202
|
+
def test_search_request_with_filters(self):
|
|
203
|
+
resp = _fake_response(payload={"results": []})
|
|
204
|
+
with mock.patch.dict(os.environ, {"TRANSCRIPTAPI_API_KEY": "sk_test"}, clear=True):
|
|
205
|
+
with mock.patch("requests.get", return_value=resp) as getter:
|
|
206
|
+
out = json.loads(
|
|
207
|
+
TranscriptAPISearchTool().run(
|
|
208
|
+
query="innovation",
|
|
209
|
+
search_type="video",
|
|
210
|
+
sort="views",
|
|
211
|
+
upload_date="month",
|
|
212
|
+
duration="long",
|
|
213
|
+
features="hd,cc",
|
|
214
|
+
)
|
|
215
|
+
)
|
|
216
|
+
self.assertTrue(out["success"])
|
|
217
|
+
params = getter.call_args.kwargs["params"]
|
|
218
|
+
self.assertEqual(params["sort"], "views")
|
|
219
|
+
self.assertEqual(params["upload_date"], "month")
|
|
220
|
+
self.assertEqual(params["duration"], "long")
|
|
221
|
+
self.assertEqual(params["features"], "hd,cc")
|
|
222
|
+
|
|
223
|
+
def test_search_optional_filters_omitted_when_unset(self):
|
|
224
|
+
resp = _fake_response(payload={"results": []})
|
|
225
|
+
with mock.patch.dict(os.environ, {"TRANSCRIPTAPI_API_KEY": "sk_test"}, clear=True):
|
|
226
|
+
with mock.patch("requests.get", return_value=resp) as getter:
|
|
227
|
+
TranscriptAPISearchTool().run(query="innovation")
|
|
228
|
+
params = getter.call_args.kwargs["params"]
|
|
229
|
+
for key in ("sort", "upload_date", "duration", "features"):
|
|
230
|
+
self.assertNotIn(key, params)
|
|
231
|
+
|
|
232
|
+
def test_search_accepts_playlist_and_movie_types(self):
|
|
233
|
+
resp = _fake_response(payload={"results": []})
|
|
234
|
+
with mock.patch.dict(os.environ, {"TRANSCRIPTAPI_API_KEY": "sk_test"}, clear=True):
|
|
235
|
+
with mock.patch("requests.get", return_value=resp) as getter:
|
|
236
|
+
TranscriptAPISearchTool().run(query="x", search_type="playlist")
|
|
237
|
+
self.assertEqual(getter.call_args.kwargs["params"]["type"], "playlist")
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
class VideoMetadataToolTests(unittest.TestCase):
|
|
241
|
+
def test_metadata_request_and_envelope(self):
|
|
242
|
+
resp = _fake_response(payload={"videoId": "dQw4w9WgXcQ", "title": "..."})
|
|
243
|
+
with mock.patch.dict(os.environ, {"TRANSCRIPTAPI_API_KEY": "sk_test"}, clear=True):
|
|
244
|
+
with mock.patch("requests.get", return_value=resp) as getter:
|
|
245
|
+
out = json.loads(
|
|
246
|
+
TranscriptAPIVideoMetadataTool().run(video_url="dQw4w9WgXcQ")
|
|
247
|
+
)
|
|
248
|
+
self.assertTrue(out["success"])
|
|
249
|
+
self.assertEqual(
|
|
250
|
+
getter.call_args.args[0],
|
|
251
|
+
"https://transcriptapi.com/api/v2/youtube/video/metadata",
|
|
252
|
+
)
|
|
253
|
+
self.assertEqual(getter.call_args.kwargs["params"]["video_url"], "dQw4w9WgXcQ")
|
|
254
|
+
self.assertNotIn("include", getter.call_args.kwargs["params"])
|
|
255
|
+
|
|
256
|
+
def test_metadata_request_with_include(self):
|
|
257
|
+
resp = _fake_response(payload={"videoId": "dQw4w9WgXcQ", "details": {}})
|
|
258
|
+
with mock.patch.dict(os.environ, {"TRANSCRIPTAPI_API_KEY": "sk_test"}, clear=True):
|
|
259
|
+
with mock.patch("requests.get", return_value=resp) as getter:
|
|
260
|
+
out = json.loads(
|
|
261
|
+
TranscriptAPIVideoMetadataTool().run(
|
|
262
|
+
video_url="dQw4w9WgXcQ", include="details,related"
|
|
263
|
+
)
|
|
264
|
+
)
|
|
265
|
+
self.assertTrue(out["success"])
|
|
266
|
+
self.assertEqual(getter.call_args.kwargs["params"]["include"], "details,related")
|
|
267
|
+
|
|
268
|
+
def test_metadata_missing_key_returns_envelope(self):
|
|
269
|
+
with mock.patch.dict(os.environ, {}, clear=True):
|
|
270
|
+
out = json.loads(TranscriptAPIVideoMetadataTool().run(video_url="dQw4w9WgXcQ"))
|
|
271
|
+
self.assertFalse(out["success"])
|
|
272
|
+
self.assertEqual(out["error"]["code"], "missing_api_key")
|
|
273
|
+
|
|
274
|
+
def test_metadata_402_maps_to_out_of_credits(self):
|
|
275
|
+
with mock.patch.dict(os.environ, {"TRANSCRIPTAPI_API_KEY": "sk_test"}, clear=True):
|
|
276
|
+
with mock.patch("requests.get", return_value=_fake_response(status=402)):
|
|
277
|
+
out = json.loads(
|
|
278
|
+
TranscriptAPIVideoMetadataTool().run(video_url="dQw4w9WgXcQ")
|
|
279
|
+
)
|
|
280
|
+
self.assertFalse(out["success"])
|
|
281
|
+
self.assertEqual(out["error"]["code"], "out_of_credits")
|
|
282
|
+
|
|
173
283
|
|
|
174
284
|
if __name__ == "__main__":
|
|
175
285
|
unittest.main()
|
|
@@ -1,132 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: crewai-transcriptapi
|
|
3
|
-
Version: 0.1.0
|
|
4
|
-
Summary: CrewAI tools for TranscriptAPI: fetch YouTube transcripts and search YouTube videos and channels from CrewAI agents.
|
|
5
|
-
Project-URL: Homepage, https://transcriptapi.com
|
|
6
|
-
Project-URL: Documentation, https://transcriptapi.com/docs
|
|
7
|
-
Project-URL: Repository, https://github.com/ZeroPointRepo/crewai-transcriptapi
|
|
8
|
-
Author-email: Zero Point Studio <hello@transcriptapi.com>
|
|
9
|
-
License: MIT License
|
|
10
|
-
|
|
11
|
-
Copyright (c) 2026 TranscriptAPI (ZeroPointRepo)
|
|
12
|
-
|
|
13
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
14
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
15
|
-
in the Software without restriction, including without limitation the rights
|
|
16
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
17
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
18
|
-
furnished to do so, subject to the following conditions:
|
|
19
|
-
|
|
20
|
-
The above copyright notice and this permission notice shall be included in all
|
|
21
|
-
copies or substantial portions of the Software.
|
|
22
|
-
|
|
23
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
24
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
25
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
26
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
27
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
28
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
29
|
-
SOFTWARE.
|
|
30
|
-
License-File: LICENSE
|
|
31
|
-
Keywords: ai-agent,crewai,crewai-tools,llm,transcript,transcriptapi,youtube,youtube-api,youtube-transcript
|
|
32
|
-
Classifier: Development Status :: 4 - Beta
|
|
33
|
-
Classifier: Intended Audience :: Developers
|
|
34
|
-
Classifier: License :: OSI Approved :: MIT License
|
|
35
|
-
Classifier: Programming Language :: Python :: 3
|
|
36
|
-
Classifier: Programming Language :: Python :: 3.10
|
|
37
|
-
Classifier: Programming Language :: Python :: 3.11
|
|
38
|
-
Classifier: Programming Language :: Python :: 3.12
|
|
39
|
-
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
40
|
-
Requires-Python: >=3.10
|
|
41
|
-
Requires-Dist: crewai>=0.80.0
|
|
42
|
-
Requires-Dist: pydantic>=2.0.0
|
|
43
|
-
Requires-Dist: requests>=2.31.0
|
|
44
|
-
Description-Content-Type: text/markdown
|
|
45
|
-
|
|
46
|
-
# crewai-transcriptapi
|
|
47
|
-
|
|
48
|
-
**TranscriptAPI: hosted YouTube transcript + video-discovery API for AI agents.** CrewAI tools edition. Also available as an [n8n community node](https://github.com/ZeroPointRepo/n8n-nodes-transcriptapi), an [MCP server](https://github.com/ZeroPointRepo/youtube-mcp) and [agent skills](https://github.com/ZeroPointRepo/youtube-skills).
|
|
49
|
-
|
|
50
|
-
This package gives [CrewAI](https://www.crewai.com/) agents two tools over [TranscriptAPI](https://transcriptapi.com):
|
|
51
|
-
|
|
52
|
-
- **TranscriptAPITool**: fetch the transcript of any YouTube video (full URL, youtu.be, Shorts, or bare ID) as plain text or timestamped JSON, with metadata. The hero tool: 1 credit per call.
|
|
53
|
-
- **TranscriptAPISearchTool**: search YouTube for videos or channels to discover content before fetching transcripts. 1 credit per page.
|
|
54
|
-
|
|
55
|
-
## Installation
|
|
56
|
-
|
|
57
|
-
```bash
|
|
58
|
-
pip install crewai-transcriptapi
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
## Credentials
|
|
62
|
-
|
|
63
|
-
You need a TranscriptAPI key (starts with `sk_`):
|
|
64
|
-
|
|
65
|
-
1. Create an account at [transcriptapi.com](https://transcriptapi.com): **100 free credits, no card (one-time)**; paid plans from **$5/mo (1,000 credits)**.
|
|
66
|
-
2. Create an API key on the dashboard.
|
|
67
|
-
3. Export it:
|
|
68
|
-
|
|
69
|
-
```bash
|
|
70
|
-
export TRANSCRIPTAPI_API_KEY="sk_..."
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
## Usage
|
|
74
|
-
|
|
75
|
-
```python
|
|
76
|
-
from crewai import Agent
|
|
77
|
-
from crewai_transcriptapi import TranscriptAPITool, TranscriptAPISearchTool
|
|
78
|
-
|
|
79
|
-
researcher = Agent(
|
|
80
|
-
role="Video researcher",
|
|
81
|
-
goal="Find and summarize YouTube content on a topic",
|
|
82
|
-
backstory="Researches spoken video content via transcripts.",
|
|
83
|
-
tools=[TranscriptAPISearchTool(), TranscriptAPITool()],
|
|
84
|
-
)
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
The agent can then search for videos on a topic and fetch each transcript for summarizing, quoting, translating or analysis.
|
|
88
|
-
|
|
89
|
-
## Tool reference
|
|
90
|
-
|
|
91
|
-
### TranscriptAPITool
|
|
92
|
-
|
|
93
|
-
| Argument | Type | Default | Description |
|
|
94
|
-
|---|---|---|---|
|
|
95
|
-
| `video_url` | str | required | Full YouTube URL (watch, youtu.be, embed, Shorts) or bare 11-character video ID |
|
|
96
|
-
| `output_format` | str | `"text"` | `"text"` for plain transcript, `"json"` for timestamped segments |
|
|
97
|
-
| `language` | str | none | Optional preferred transcript language code, for example `"es"` |
|
|
98
|
-
|
|
99
|
-
### TranscriptAPISearchTool
|
|
100
|
-
|
|
101
|
-
| Argument | Type | Default | Description |
|
|
102
|
-
|---|---|---|---|
|
|
103
|
-
| `query` | str | required | Search query, 1 to 200 characters |
|
|
104
|
-
| `search_type` | str | `"video"` | `"video"` or `"channel"` |
|
|
105
|
-
|
|
106
|
-
## Response envelope
|
|
107
|
-
|
|
108
|
-
Both tools return a stable JSON string and never raise:
|
|
109
|
-
|
|
110
|
-
```json
|
|
111
|
-
{"success": true, "data": {"transcript": "...", "metadata": {"title": "..."}}}
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
```json
|
|
115
|
-
{"success": false, "error": {"code": "out_of_credits", "message": "The account is out of credits. See https://transcriptapi.com/billing."}}
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
Error codes: `missing_api_key`, `invalid_api_key`, `out_of_credits`, `not_found`, `rate_limited`, `network`, `bad_response`, `http_<status>`. Failed calls are never charged.
|
|
119
|
-
|
|
120
|
-
## Resources
|
|
121
|
-
|
|
122
|
-
- [TranscriptAPI documentation](https://transcriptapi.com/docs)
|
|
123
|
-
- [Pricing](https://transcriptapi.com)
|
|
124
|
-
- Family: [n8n node](https://github.com/ZeroPointRepo/n8n-nodes-transcriptapi) · [MCP server](https://github.com/ZeroPointRepo/youtube-mcp) · [agent skills](https://github.com/ZeroPointRepo/youtube-skills)
|
|
125
|
-
|
|
126
|
-
## Disclosure
|
|
127
|
-
|
|
128
|
-
TranscriptAPI is an independent product and is not affiliated with or endorsed by YouTube or Google. Use of these tools is subject to the [TranscriptAPI terms](https://transcriptapi.com/terms).
|
|
129
|
-
|
|
130
|
-
## License
|
|
131
|
-
|
|
132
|
-
[MIT](LICENSE)
|
|
@@ -1,87 +0,0 @@
|
|
|
1
|
-
# crewai-transcriptapi
|
|
2
|
-
|
|
3
|
-
**TranscriptAPI: hosted YouTube transcript + video-discovery API for AI agents.** CrewAI tools edition. Also available as an [n8n community node](https://github.com/ZeroPointRepo/n8n-nodes-transcriptapi), an [MCP server](https://github.com/ZeroPointRepo/youtube-mcp) and [agent skills](https://github.com/ZeroPointRepo/youtube-skills).
|
|
4
|
-
|
|
5
|
-
This package gives [CrewAI](https://www.crewai.com/) agents two tools over [TranscriptAPI](https://transcriptapi.com):
|
|
6
|
-
|
|
7
|
-
- **TranscriptAPITool**: fetch the transcript of any YouTube video (full URL, youtu.be, Shorts, or bare ID) as plain text or timestamped JSON, with metadata. The hero tool: 1 credit per call.
|
|
8
|
-
- **TranscriptAPISearchTool**: search YouTube for videos or channels to discover content before fetching transcripts. 1 credit per page.
|
|
9
|
-
|
|
10
|
-
## Installation
|
|
11
|
-
|
|
12
|
-
```bash
|
|
13
|
-
pip install crewai-transcriptapi
|
|
14
|
-
```
|
|
15
|
-
|
|
16
|
-
## Credentials
|
|
17
|
-
|
|
18
|
-
You need a TranscriptAPI key (starts with `sk_`):
|
|
19
|
-
|
|
20
|
-
1. Create an account at [transcriptapi.com](https://transcriptapi.com): **100 free credits, no card (one-time)**; paid plans from **$5/mo (1,000 credits)**.
|
|
21
|
-
2. Create an API key on the dashboard.
|
|
22
|
-
3. Export it:
|
|
23
|
-
|
|
24
|
-
```bash
|
|
25
|
-
export TRANSCRIPTAPI_API_KEY="sk_..."
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
## Usage
|
|
29
|
-
|
|
30
|
-
```python
|
|
31
|
-
from crewai import Agent
|
|
32
|
-
from crewai_transcriptapi import TranscriptAPITool, TranscriptAPISearchTool
|
|
33
|
-
|
|
34
|
-
researcher = Agent(
|
|
35
|
-
role="Video researcher",
|
|
36
|
-
goal="Find and summarize YouTube content on a topic",
|
|
37
|
-
backstory="Researches spoken video content via transcripts.",
|
|
38
|
-
tools=[TranscriptAPISearchTool(), TranscriptAPITool()],
|
|
39
|
-
)
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
The agent can then search for videos on a topic and fetch each transcript for summarizing, quoting, translating or analysis.
|
|
43
|
-
|
|
44
|
-
## Tool reference
|
|
45
|
-
|
|
46
|
-
### TranscriptAPITool
|
|
47
|
-
|
|
48
|
-
| Argument | Type | Default | Description |
|
|
49
|
-
|---|---|---|---|
|
|
50
|
-
| `video_url` | str | required | Full YouTube URL (watch, youtu.be, embed, Shorts) or bare 11-character video ID |
|
|
51
|
-
| `output_format` | str | `"text"` | `"text"` for plain transcript, `"json"` for timestamped segments |
|
|
52
|
-
| `language` | str | none | Optional preferred transcript language code, for example `"es"` |
|
|
53
|
-
|
|
54
|
-
### TranscriptAPISearchTool
|
|
55
|
-
|
|
56
|
-
| Argument | Type | Default | Description |
|
|
57
|
-
|---|---|---|---|
|
|
58
|
-
| `query` | str | required | Search query, 1 to 200 characters |
|
|
59
|
-
| `search_type` | str | `"video"` | `"video"` or `"channel"` |
|
|
60
|
-
|
|
61
|
-
## Response envelope
|
|
62
|
-
|
|
63
|
-
Both tools return a stable JSON string and never raise:
|
|
64
|
-
|
|
65
|
-
```json
|
|
66
|
-
{"success": true, "data": {"transcript": "...", "metadata": {"title": "..."}}}
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
```json
|
|
70
|
-
{"success": false, "error": {"code": "out_of_credits", "message": "The account is out of credits. See https://transcriptapi.com/billing."}}
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
Error codes: `missing_api_key`, `invalid_api_key`, `out_of_credits`, `not_found`, `rate_limited`, `network`, `bad_response`, `http_<status>`. Failed calls are never charged.
|
|
74
|
-
|
|
75
|
-
## Resources
|
|
76
|
-
|
|
77
|
-
- [TranscriptAPI documentation](https://transcriptapi.com/docs)
|
|
78
|
-
- [Pricing](https://transcriptapi.com)
|
|
79
|
-
- Family: [n8n node](https://github.com/ZeroPointRepo/n8n-nodes-transcriptapi) · [MCP server](https://github.com/ZeroPointRepo/youtube-mcp) · [agent skills](https://github.com/ZeroPointRepo/youtube-skills)
|
|
80
|
-
|
|
81
|
-
## Disclosure
|
|
82
|
-
|
|
83
|
-
TranscriptAPI is an independent product and is not affiliated with or endorsed by YouTube or Google. Use of these tools is subject to the [TranscriptAPI terms](https://transcriptapi.com/terms).
|
|
84
|
-
|
|
85
|
-
## License
|
|
86
|
-
|
|
87
|
-
[MIT](LICENSE)
|
|
File without changes
|