deapi-mcp 0.7.0__py3-none-any.whl

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.
deapi_mcp/utils.py ADDED
@@ -0,0 +1,666 @@
1
+ """Utility functions for deAPI MCP server."""
2
+
3
+ import asyncio
4
+ import base64
5
+ import io
6
+ import ipaddress
7
+ import logging
8
+ import re
9
+ import socket
10
+ from typing import Dict, Optional, Tuple, cast
11
+ from urllib.parse import urljoin, urlsplit
12
+
13
+ import httpx
14
+
15
+ from .observability import note_input_error
16
+
17
+ logger = logging.getLogger(__name__)
18
+
19
+
20
+ class InputError(ValueError):
21
+ """The caller's input is unusable. A ValueError, so existing handlers still catch it."""
22
+
23
+ def __init__(self, *args: object) -> None:
24
+ super().__init__(*args)
25
+ note_input_error()
26
+
27
+
28
+ def parse_image_input(image_input: str) -> Tuple[bytes, str]:
29
+ """Parse image input and return file data with filename.
30
+
31
+ Accepts:
32
+ - Data URI: data:image/png;base64,iVBORw0KGg...
33
+ - Base64 string: iVBORw0KGg...
34
+ - URL: https://example.com/image.png (will raise error - not supported yet)
35
+
36
+ Args:
37
+ image_input: Image as data URI, base64 string, or URL
38
+
39
+ Returns:
40
+ Tuple of (image_bytes, filename_with_extension)
41
+
42
+ Raises:
43
+ ValueError: If input format is invalid or URLs are provided
44
+ """
45
+ # Check if it's a data URI
46
+ data_uri_pattern = r"^data:image/(png|jpeg|jpg|gif|bmp|webp);base64,(.+)$"
47
+ match = re.match(data_uri_pattern, image_input, re.IGNORECASE)
48
+
49
+ if match:
50
+ # Extract mime type and base64 data
51
+ mime_subtype = match.group(1).lower()
52
+ base64_data = match.group(2)
53
+
54
+ # Normalize mime type
55
+ if mime_subtype == "jpeg":
56
+ mime_subtype = "jpg"
57
+
58
+ try:
59
+ image_bytes = base64.b64decode(base64_data)
60
+ filename = f"image.{mime_subtype}"
61
+ return image_bytes, filename
62
+ except Exception as e:
63
+ raise InputError(f"Failed to decode base64 data: {str(e)}")
64
+
65
+ # Check if it's a URL
66
+ if image_input.startswith(("http://", "https://")):
67
+ # URLs are fetched by prepare_image_upload_async before this parser is
68
+ # reached; landing here means a caller used the sync path with a URL.
69
+ raise InputError(
70
+ "Expected a data URI (data:image/png;base64,...) or a base64 string, got a URL. "
71
+ "Use prepare_image_upload_async for URL inputs."
72
+ )
73
+
74
+ # Assume it's raw base64 without data URI wrapper
75
+ try:
76
+ image_bytes = base64.b64decode(image_input)
77
+ # Default to PNG if no mime type specified
78
+ filename = "image.png"
79
+ return image_bytes, filename
80
+ except Exception as e:
81
+ raise InputError(
82
+ f"Invalid image input. Expected data URI (data:image/png;base64,...) "
83
+ f"or base64 string, but got: {str(e)}"
84
+ )
85
+
86
+
87
+ def prepare_image_upload(
88
+ image_input: str, field_name: str = "image"
89
+ ) -> Tuple[str, Tuple[str, io.BytesIO, str]]:
90
+ """Prepare image for multipart/form-data upload.
91
+
92
+ Args:
93
+ image_input: Image as data URI or base64 string
94
+ field_name: Form field name (default: "image")
95
+
96
+ Returns:
97
+ Tuple of (field_name, (filename, file_obj, mime_type))
98
+ Ready for httpx files parameter
99
+
100
+ Example:
101
+ >>> field_name, file_tuple = prepare_image_upload(data_uri, "first_frame_image")
102
+ >>> files = {field_name: file_tuple}
103
+ >>> response = await client.post(url, files=files)
104
+ """
105
+ image_bytes, filename = parse_image_input(image_input)
106
+
107
+ # Extract mime type from filename extension
108
+ ext = filename.split(".")[-1].lower()
109
+ mime_mapping = {
110
+ "png": "image/png",
111
+ "jpg": "image/jpeg",
112
+ "jpeg": "image/jpeg",
113
+ "gif": "image/gif",
114
+ "bmp": "image/bmp",
115
+ "webp": "image/webp",
116
+ }
117
+ mime_type = mime_mapping.get(ext, "image/png")
118
+
119
+ # Create BytesIO object for httpx
120
+ file_obj = io.BytesIO(image_bytes)
121
+
122
+ return field_name, (filename, file_obj, mime_type)
123
+
124
+
125
+ def parse_audio_input(audio_input: str) -> Tuple[bytes, str]:
126
+ """Parse audio input and return file data with filename.
127
+
128
+ Accepts:
129
+ - Data URI: data:audio/mp3;base64,SUQzBAA...
130
+ - Base64 string: SUQzBAA...
131
+
132
+ Args:
133
+ audio_input: Audio as data URI or base64 string
134
+
135
+ Returns:
136
+ Tuple of (audio_bytes, filename_with_extension)
137
+
138
+ Raises:
139
+ ValueError: If input format is invalid
140
+ """
141
+ # Check if it's a data URI
142
+ data_uri_pattern = r"^data:audio/(aac|mp3|mpeg|ogg|wav|webm|flac|x-flac);base64,(.+)$"
143
+ match = re.match(data_uri_pattern, audio_input, re.IGNORECASE)
144
+
145
+ if match:
146
+ mime_subtype = match.group(1).lower()
147
+ base64_data = match.group(2)
148
+
149
+ # Normalize mime subtypes
150
+ ext_mapping = {
151
+ "mpeg": "mp3",
152
+ "x-flac": "flac",
153
+ }
154
+ ext = ext_mapping.get(mime_subtype, mime_subtype)
155
+
156
+ try:
157
+ audio_bytes = base64.b64decode(base64_data)
158
+ filename = f"audio.{ext}"
159
+ return audio_bytes, filename
160
+ except Exception as e:
161
+ raise InputError(f"Failed to decode base64 audio data: {str(e)}")
162
+
163
+ # Check if it's a URL (handled separately by fetch_audio_from_url)
164
+ if audio_input.startswith(("http://", "https://")):
165
+ raise InputError(
166
+ "URL inputs should be handled by fetch_audio_from_url. "
167
+ "Use prepare_audio_upload_async for URL support."
168
+ )
169
+
170
+ # Assume it's raw base64 without data URI wrapper
171
+ try:
172
+ audio_bytes = base64.b64decode(audio_input)
173
+ filename = "audio.mp3"
174
+ return audio_bytes, filename
175
+ except Exception as e:
176
+ raise InputError(
177
+ f"Invalid audio input. Expected data URI (data:audio/mp3;base64,...) "
178
+ f"or base64 string, but got: {str(e)}"
179
+ )
180
+
181
+
182
+ def parse_video_input(video_input: str) -> Tuple[bytes, str]:
183
+ """Parse video input and return file data with filename.
184
+
185
+ Accepts:
186
+ - Data URI: data:video/mp4;base64,AAAAIGZ0eXBpc29t...
187
+ - Base64 string: AAAAIGZ0eXBpc29t...
188
+ - URL: https://example.com/video.mp4 (will raise error - not supported yet)
189
+
190
+ Args:
191
+ video_input: Video as data URI, base64 string, or URL
192
+
193
+ Returns:
194
+ Tuple of (video_bytes, filename_with_extension)
195
+
196
+ Raises:
197
+ ValueError: If input format is invalid or URLs are provided
198
+ """
199
+ # Check if it's a data URI
200
+ data_uri_pattern = r"^data:video/(mp4|avi|mov|webm|mkv|mpeg|mpg|flv|wmv);base64,(.+)$"
201
+ match = re.match(data_uri_pattern, video_input, re.IGNORECASE)
202
+
203
+ if match:
204
+ # Extract mime type and base64 data
205
+ mime_subtype = match.group(1).lower()
206
+ base64_data = match.group(2)
207
+
208
+ # Normalize mime type
209
+ if mime_subtype == "mpeg":
210
+ mime_subtype = "mpg"
211
+
212
+ try:
213
+ video_bytes = base64.b64decode(base64_data)
214
+ filename = f"video.{mime_subtype}"
215
+ return video_bytes, filename
216
+ except Exception as e:
217
+ raise InputError(f"Failed to decode base64 video data: {str(e)}")
218
+
219
+ # Check if it's a URL
220
+ if video_input.startswith(("http://", "https://")):
221
+ # URLs are fetched by prepare_video_upload_async before this parser is
222
+ # reached; landing here means a caller used the sync path with a URL.
223
+ raise InputError(
224
+ "Expected a data URI (data:video/mp4;base64,...) or a base64 string, got a URL. "
225
+ "Use prepare_video_upload_async for URL inputs."
226
+ )
227
+
228
+ # Assume it's raw base64 without data URI wrapper
229
+ try:
230
+ video_bytes = base64.b64decode(video_input)
231
+ # Default to MP4 if no mime type specified
232
+ filename = "video.mp4"
233
+ return video_bytes, filename
234
+ except Exception as e:
235
+ raise InputError(
236
+ f"Invalid video input. Expected data URI (data:video/mp4;base64,...) "
237
+ f"or base64 string, but got: {str(e)}"
238
+ )
239
+
240
+
241
+ def prepare_video_upload(
242
+ video_input: str, field_name: str = "video"
243
+ ) -> Tuple[str, Tuple[str, io.BytesIO, str]]:
244
+ """Prepare video for multipart/form-data upload.
245
+
246
+ Args:
247
+ video_input: Video as data URI or base64 string
248
+ field_name: Form field name (default: "video")
249
+
250
+ Returns:
251
+ Tuple of (field_name, (filename, file_obj, mime_type))
252
+ Ready for httpx files parameter
253
+
254
+ Example:
255
+ >>> field_name, file_tuple = prepare_video_upload(data_uri, "video")
256
+ >>> files = {field_name: file_tuple}
257
+ >>> response = await client.post(url, files=files)
258
+ """
259
+ video_bytes, filename = parse_video_input(video_input)
260
+
261
+ # Extract mime type from filename extension
262
+ ext = filename.split(".")[-1].lower()
263
+ mime_mapping = {
264
+ "mp4": "video/mp4",
265
+ "avi": "video/x-msvideo",
266
+ "mov": "video/quicktime",
267
+ "webm": "video/webm",
268
+ "mkv": "video/x-matroska",
269
+ "mpeg": "video/mpeg",
270
+ "mpg": "video/mpeg",
271
+ "flv": "video/x-flv",
272
+ "wmv": "video/x-ms-wmv",
273
+ }
274
+ mime_type = mime_mapping.get(ext, "video/mp4")
275
+
276
+ # Create BytesIO object for httpx
277
+ file_obj = io.BytesIO(video_bytes)
278
+
279
+ return field_name, (filename, file_obj, mime_type)
280
+
281
+
282
+ def prepare_audio_upload(
283
+ audio_input: str, field_name: str = "audio"
284
+ ) -> Tuple[str, Tuple[str, io.BytesIO, str]]:
285
+ """Prepare audio for multipart/form-data upload.
286
+
287
+ Args:
288
+ audio_input: Audio as data URI or base64 string
289
+ field_name: Form field name (default: "audio")
290
+
291
+ Returns:
292
+ Tuple of (field_name, (filename, file_obj, mime_type))
293
+ Ready for httpx files parameter
294
+ """
295
+ audio_bytes, filename = parse_audio_input(audio_input)
296
+
297
+ ext = filename.split(".")[-1].lower()
298
+ mime_mapping = {
299
+ "mp3": "audio/mpeg",
300
+ "wav": "audio/wav",
301
+ "flac": "audio/flac",
302
+ "ogg": "audio/ogg",
303
+ "aac": "audio/aac",
304
+ "webm": "audio/webm",
305
+ }
306
+ mime_type = mime_mapping.get(ext, "audio/mpeg")
307
+
308
+ file_obj = io.BytesIO(audio_bytes)
309
+
310
+ return field_name, (filename, file_obj, mime_type)
311
+
312
+
313
+ def form_bool(value: bool) -> str:
314
+ r"""Render a boolean for a multipart/form-data field.
315
+
316
+ A form field is always a string, and Laravel's built-in ``boolean`` rule
317
+ accepts only ``true/false/0/1`` and the strings ``"0"``/``"1"`` — so
318
+ ``"true"`` fails it with a 422 (``enhance_prompt`` on the image endpoints).
319
+ The API's own ``App\Rules\Boolean`` is laxer but also takes ``"1"``/``"0"``,
320
+ which makes this the one spelling every rule accepts.
321
+ """
322
+ return "1" if value else "0"
323
+
324
+
325
+ def is_url(value: str) -> bool:
326
+ """Check if the given string is a URL."""
327
+ return value.startswith(("http://", "https://"))
328
+
329
+
330
+ # --- SSRF-safe URL fetching -------------------------------------------------
331
+ # A caller-supplied media URL is fetched by the server, so it must never be used
332
+ # to reach internal addresses, to follow a redirect onto one, or to exhaust
333
+ # memory. This mirrors the guard the backend already applies to webhook
334
+ # delivery: resolve the host, require every resolved IP to be public, pin the
335
+ # connection to a validated IP (so DNS rebinding cannot swap it between the
336
+ # check and the connect), refuse auto-redirects and re-validate each hop, cap
337
+ # the body, and return one generic error so nothing becomes a status oracle.
338
+
339
+ _FETCH_GENERIC_ERROR = "Could not retrieve the file from the provided URL."
340
+ _MAX_REDIRECTS = 3
341
+ _CGNAT_RANGE = ipaddress.ip_network("100.64.0.0/10")
342
+ # Never-media content types; refused so the fetchers cannot pull internal pages.
343
+ _REFUSED_CONTENT_TYPES = ("text/", "application/json", "application/xml")
344
+
345
+ # Per-type body caps (bytes): generous but bounded, so one request cannot OOM a pod.
346
+ MAX_IMAGE_BYTES = 25 * 1024 * 1024
347
+ MAX_AUDIO_BYTES = 100 * 1024 * 1024
348
+ MAX_VIDEO_BYTES = 300 * 1024 * 1024
349
+
350
+
351
+ def _ip_is_public(ip_str: str) -> bool:
352
+ """True only for a routable public address (IPv4-mapped IPv6 and CGNAT handled)."""
353
+ try:
354
+ ip = ipaddress.ip_address(ip_str)
355
+ except ValueError:
356
+ return False
357
+ if isinstance(ip, ipaddress.IPv6Address) and ip.ipv4_mapped is not None:
358
+ ip = ip.ipv4_mapped
359
+ if ip.version == 4 and ip in _CGNAT_RANGE:
360
+ return False
361
+ return not (
362
+ ip.is_private
363
+ or ip.is_loopback
364
+ or ip.is_link_local
365
+ or ip.is_multicast
366
+ or ip.is_reserved
367
+ or ip.is_unspecified
368
+ )
369
+
370
+
371
+ async def _resolve_public_ip(host: str, port: int) -> str:
372
+ """Resolve host; require EVERY resolved address to be public; return one to pin."""
373
+ loop = asyncio.get_running_loop()
374
+ try:
375
+ infos = await loop.getaddrinfo(host, port, proto=socket.IPPROTO_TCP)
376
+ except socket.gaierror:
377
+ raise InputError(_FETCH_GENERIC_ERROR)
378
+ ips = {cast(str, info[4][0]) for info in infos}
379
+ if not ips or not all(_ip_is_public(ip) for ip in ips):
380
+ raise InputError(_FETCH_GENERIC_ERROR)
381
+ return sorted(ips)[0]
382
+
383
+
384
+ async def safe_fetch(
385
+ url: str,
386
+ *,
387
+ max_bytes: int,
388
+ timeout: float,
389
+ max_redirects: int = _MAX_REDIRECTS,
390
+ schemes: Tuple[str, ...] = ("http", "https"),
391
+ refused_content_types: Tuple[str, ...] = _REFUSED_CONTENT_TYPES,
392
+ accept: str = "*/*",
393
+ extra_headers: Optional[Dict[str, str]] = None,
394
+ ) -> Tuple[bytes, str]:
395
+ """Fetch an http(s) URL with SSRF protections; return (body, content_type).
396
+
397
+ Blocks non-public hosts, pins the connection to a validated IP, handles
398
+ redirects manually and re-validates each hop, caps the body, and raises a
399
+ single generic ``InputError`` on any failure. The defaults suit media; a
400
+ caller fetching a small JSON document narrows them (no redirects, https only,
401
+ JSON allowed).
402
+ """
403
+ current = url
404
+ async with httpx.AsyncClient(timeout=timeout, follow_redirects=False) as client:
405
+ for _ in range(max_redirects + 1):
406
+ parts = urlsplit(current)
407
+ if parts.scheme not in schemes:
408
+ raise InputError(_FETCH_GENERIC_ERROR)
409
+ host = parts.hostname
410
+ if not host:
411
+ raise InputError(_FETCH_GENERIC_ERROR)
412
+ port = parts.port or (443 if parts.scheme == "https" else 80)
413
+ pin = await _resolve_public_ip(host, port)
414
+
415
+ authority = host if parts.port is None else f"{host}:{parts.port}"
416
+ pin_host = f"[{pin}]" if ":" in pin else pin
417
+ pinned_url = parts._replace(netloc=f"{pin_host}:{port}").geturl()
418
+ request = client.build_request(
419
+ "GET",
420
+ pinned_url,
421
+ headers={"Host": authority, "Accept": accept, **(extra_headers or {})},
422
+ # Keep TLS SNI and certificate verification bound to the real host
423
+ # even though we connect to the pinned IP.
424
+ extensions={"sni_hostname": host},
425
+ )
426
+ try:
427
+ response = await client.send(request, stream=True)
428
+ except httpx.HTTPError:
429
+ raise InputError(_FETCH_GENERIC_ERROR)
430
+ try:
431
+ if response.is_redirect:
432
+ location = response.headers.get("location")
433
+ if not location:
434
+ raise InputError(_FETCH_GENERIC_ERROR)
435
+ current = urljoin(current, location)
436
+ continue
437
+ if response.status_code >= 400:
438
+ raise InputError(_FETCH_GENERIC_ERROR)
439
+ content_type = response.headers.get("content-type", "").lower()
440
+ if refused_content_types and content_type.startswith(refused_content_types):
441
+ raise InputError(_FETCH_GENERIC_ERROR)
442
+ chunks = []
443
+ total = 0
444
+ async for chunk in response.aiter_bytes():
445
+ total += len(chunk)
446
+ if total > max_bytes:
447
+ raise InputError(_FETCH_GENERIC_ERROR)
448
+ chunks.append(chunk)
449
+ return b"".join(chunks), content_type
450
+ except httpx.HTTPError:
451
+ raise InputError(_FETCH_GENERIC_ERROR)
452
+ finally:
453
+ await response.aclose()
454
+ raise InputError(_FETCH_GENERIC_ERROR)
455
+
456
+
457
+ async def fetch_image_from_url(url: str, timeout: float = 30.0) -> Tuple[bytes, str]:
458
+ """Fetch image from URL and return bytes with filename.
459
+
460
+ Fetched through ``safe_fetch``: non-public hosts, redirects onto them,
461
+ oversized bodies and non-media content are refused.
462
+ """
463
+ content, content_type = await safe_fetch(url, max_bytes=MAX_IMAGE_BYTES, timeout=timeout)
464
+ ext = "png" # default
465
+ if "jpeg" in content_type or "jpg" in content_type:
466
+ ext = "jpg"
467
+ elif "png" in content_type:
468
+ ext = "png"
469
+ elif "gif" in content_type:
470
+ ext = "gif"
471
+ elif "webp" in content_type:
472
+ ext = "webp"
473
+ elif "bmp" in content_type:
474
+ ext = "bmp"
475
+ else:
476
+ url_lower = url.lower()
477
+ for img_ext in ["jpg", "jpeg", "png", "gif", "webp", "bmp"]:
478
+ if f".{img_ext}" in url_lower:
479
+ ext = "jpg" if img_ext == "jpeg" else img_ext
480
+ break
481
+ return content, f"image.{ext}"
482
+
483
+
484
+ async def prepare_image_upload_async(
485
+ image_input: str, field_name: str = "image"
486
+ ) -> Tuple[str, Tuple[str, io.BytesIO, str]]:
487
+ """Prepare image for multipart/form-data upload, supporting URLs.
488
+
489
+ This is an async version that can fetch images from URLs.
490
+
491
+ Args:
492
+ image_input: Image as data URI, base64 string, or URL
493
+ field_name: Form field name (default: "image")
494
+
495
+ Returns:
496
+ Tuple of (field_name, (filename, file_obj, mime_type))
497
+ Ready for httpx files parameter
498
+ """
499
+ # Check if it's a URL - if so, fetch it first
500
+ if is_url(image_input):
501
+ image_bytes, filename = await fetch_image_from_url(image_input)
502
+ else:
503
+ # Use existing sync parser for data URI / base64
504
+ image_bytes, filename = parse_image_input(image_input)
505
+
506
+ # Extract mime type from filename extension
507
+ ext = filename.split(".")[-1].lower()
508
+ mime_mapping = {
509
+ "png": "image/png",
510
+ "jpg": "image/jpeg",
511
+ "jpeg": "image/jpeg",
512
+ "gif": "image/gif",
513
+ "bmp": "image/bmp",
514
+ "webp": "image/webp",
515
+ }
516
+ mime_type = mime_mapping.get(ext, "image/png")
517
+
518
+ # Create BytesIO object for httpx
519
+ file_obj = io.BytesIO(image_bytes)
520
+
521
+ return field_name, (filename, file_obj, mime_type)
522
+
523
+
524
+ async def fetch_audio_from_url(url: str, timeout: float = 30.0) -> Tuple[bytes, str]:
525
+ """Fetch audio from URL and return bytes with filename.
526
+
527
+ Args:
528
+ url: URL of the audio to fetch
529
+ timeout: Request timeout in seconds
530
+
531
+ Returns:
532
+ Tuple of (audio_bytes, filename_with_extension)
533
+
534
+ Raises:
535
+ ValueError: If URL cannot be fetched or is not valid audio
536
+ """
537
+ content, content_type = await safe_fetch(url, max_bytes=MAX_AUDIO_BYTES, timeout=timeout)
538
+ ext = "mp3" # default
539
+ if "wav" in content_type:
540
+ ext = "wav"
541
+ elif "flac" in content_type:
542
+ ext = "flac"
543
+ elif "ogg" in content_type:
544
+ ext = "ogg"
545
+ elif "aac" in content_type:
546
+ ext = "aac"
547
+ elif "webm" in content_type:
548
+ ext = "webm"
549
+ elif "mpeg" in content_type or "mp3" in content_type:
550
+ ext = "mp3"
551
+ else:
552
+ url_lower = url.lower()
553
+ for audio_ext in ["mp3", "wav", "flac", "ogg", "aac", "webm"]:
554
+ if f".{audio_ext}" in url_lower:
555
+ ext = audio_ext
556
+ break
557
+ return content, f"audio.{ext}"
558
+
559
+
560
+ async def prepare_audio_upload_async(
561
+ audio_input: str, field_name: str = "audio"
562
+ ) -> Tuple[str, Tuple[str, io.BytesIO, str]]:
563
+ """Prepare audio for multipart/form-data upload, supporting URLs.
564
+
565
+ Args:
566
+ audio_input: Audio as data URI, base64 string, or URL
567
+ field_name: Form field name (default: "audio")
568
+
569
+ Returns:
570
+ Tuple of (field_name, (filename, file_obj, mime_type))
571
+ Ready for httpx files parameter
572
+ """
573
+ if is_url(audio_input):
574
+ audio_bytes, filename = await fetch_audio_from_url(audio_input)
575
+ else:
576
+ audio_bytes, filename = parse_audio_input(audio_input)
577
+
578
+ ext = filename.split(".")[-1].lower()
579
+ mime_mapping = {
580
+ "mp3": "audio/mpeg",
581
+ "wav": "audio/wav",
582
+ "flac": "audio/flac",
583
+ "ogg": "audio/ogg",
584
+ "aac": "audio/aac",
585
+ "webm": "audio/webm",
586
+ }
587
+ mime_type = mime_mapping.get(ext, "audio/mpeg")
588
+
589
+ file_obj = io.BytesIO(audio_bytes)
590
+
591
+ return field_name, (filename, file_obj, mime_type)
592
+
593
+
594
+ async def fetch_video_from_url(url: str, timeout: float = 60.0) -> Tuple[bytes, str]:
595
+ """Fetch video from URL and return bytes with filename.
596
+
597
+ Args:
598
+ url: URL of the video to fetch
599
+ timeout: Request timeout in seconds
600
+
601
+ Returns:
602
+ Tuple of (video_bytes, filename_with_extension)
603
+
604
+ Raises:
605
+ ValueError: If URL cannot be fetched or is not valid video
606
+ """
607
+ content, content_type = await safe_fetch(url, max_bytes=MAX_VIDEO_BYTES, timeout=timeout)
608
+ ext = "mp4" # default
609
+ if "webm" in content_type:
610
+ ext = "webm"
611
+ elif "avi" in content_type or "x-msvideo" in content_type:
612
+ ext = "avi"
613
+ elif "quicktime" in content_type or "mov" in content_type:
614
+ ext = "mov"
615
+ elif "x-matroska" in content_type or "mkv" in content_type:
616
+ ext = "mkv"
617
+ elif "mpeg" in content_type:
618
+ ext = "mpg"
619
+ elif "x-flv" in content_type:
620
+ ext = "flv"
621
+ elif "x-ms-wmv" in content_type:
622
+ ext = "wmv"
623
+ else:
624
+ url_lower = url.lower()
625
+ for vid_ext in ["mp4", "webm", "avi", "mov", "mkv", "mpg", "flv", "wmv"]:
626
+ if f".{vid_ext}" in url_lower:
627
+ ext = vid_ext
628
+ break
629
+ return content, f"video.{ext}"
630
+
631
+
632
+ async def prepare_video_upload_async(
633
+ video_input: str, field_name: str = "video"
634
+ ) -> Tuple[str, Tuple[str, io.BytesIO, str]]:
635
+ """Prepare video for multipart/form-data upload, supporting URLs.
636
+
637
+ Args:
638
+ video_input: Video as data URI, base64 string, or URL
639
+ field_name: Form field name (default: "video")
640
+
641
+ Returns:
642
+ Tuple of (field_name, (filename, file_obj, mime_type))
643
+ Ready for httpx files parameter
644
+ """
645
+ if is_url(video_input):
646
+ video_bytes, filename = await fetch_video_from_url(video_input)
647
+ else:
648
+ video_bytes, filename = parse_video_input(video_input)
649
+
650
+ ext = filename.split(".")[-1].lower()
651
+ mime_mapping = {
652
+ "mp4": "video/mp4",
653
+ "avi": "video/x-msvideo",
654
+ "mov": "video/quicktime",
655
+ "webm": "video/webm",
656
+ "mkv": "video/x-matroska",
657
+ "mpeg": "video/mpeg",
658
+ "mpg": "video/mpeg",
659
+ "flv": "video/x-flv",
660
+ "wmv": "video/x-ms-wmv",
661
+ }
662
+ mime_type = mime_mapping.get(ext, "video/mp4")
663
+
664
+ file_obj = io.BytesIO(video_bytes)
665
+
666
+ return field_name, (filename, file_obj, mime_type)