deapi-sdk 0.6.1__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.
Files changed (47) hide show
  1. deapi_sdk/__init__.py +409 -0
  2. deapi_sdk/_cards.py +313 -0
  3. deapi_sdk/_client.py +411 -0
  4. deapi_sdk/_config.py +77 -0
  5. deapi_sdk/_constants.py +61 -0
  6. deapi_sdk/_download.py +37 -0
  7. deapi_sdk/_exceptions.py +184 -0
  8. deapi_sdk/_files.py +59 -0
  9. deapi_sdk/_payload.py +50 -0
  10. deapi_sdk/_polling.py +157 -0
  11. deapi_sdk/_realtime/__init__.py +7 -0
  12. deapi_sdk/_realtime/_discovery.py +43 -0
  13. deapi_sdk/_realtime/_engine.py +419 -0
  14. deapi_sdk/_realtime/_protocol.py +152 -0
  15. deapi_sdk/_realtime/_session.py +529 -0
  16. deapi_sdk/_types.py +31 -0
  17. deapi_sdk/_version.py +3 -0
  18. deapi_sdk/py.typed +0 -0
  19. deapi_sdk/resources/__init__.py +35 -0
  20. deapi_sdk/resources/account.py +149 -0
  21. deapi_sdk/resources/audio.py +386 -0
  22. deapi_sdk/resources/embeddings.py +116 -0
  23. deapi_sdk/resources/images.py +616 -0
  24. deapi_sdk/resources/keys.py +277 -0
  25. deapi_sdk/resources/models.py +161 -0
  26. deapi_sdk/resources/ocr.py +152 -0
  27. deapi_sdk/resources/prompts.py +137 -0
  28. deapi_sdk/resources/transcription.py +308 -0
  29. deapi_sdk/resources/video.py +985 -0
  30. deapi_sdk/transcript.py +142 -0
  31. deapi_sdk/types/__init__.py +68 -0
  32. deapi_sdk/types/account.py +115 -0
  33. deapi_sdk/types/audio.py +35 -0
  34. deapi_sdk/types/common.py +174 -0
  35. deapi_sdk/types/embeddings.py +11 -0
  36. deapi_sdk/types/images.py +40 -0
  37. deapi_sdk/types/keys.py +53 -0
  38. deapi_sdk/types/ocr.py +14 -0
  39. deapi_sdk/types/prompts.py +26 -0
  40. deapi_sdk/types/transcription.py +14 -0
  41. deapi_sdk/types/video.py +84 -0
  42. deapi_sdk/types/websocket.py +36 -0
  43. deapi_sdk/webhook.py +159 -0
  44. deapi_sdk-0.6.1.dist-info/METADATA +644 -0
  45. deapi_sdk-0.6.1.dist-info/RECORD +47 -0
  46. deapi_sdk-0.6.1.dist-info/WHEEL +4 -0
  47. deapi_sdk-0.6.1.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,985 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ from typing import Any
5
+
6
+ from deapi_sdk._cards import VIDEO_KEYS, afill_payload, fill_payload
7
+ from deapi_sdk._client import AsyncHTTPClient, SyncHTTPClient
8
+ from deapi_sdk._download import adownload_text, download_text
9
+ from deapi_sdk._exceptions import DeapiError
10
+ from deapi_sdk._files import FileInput, normalize_file
11
+ from deapi_sdk._payload import drop_none, form_bool, webhook_fields
12
+ from deapi_sdk._polling import AsyncJob, Job
13
+ from deapi_sdk.types.common import JobResult, PriceResult
14
+ from deapi_sdk.types.video import VideoDescription, parse_video_description
15
+
16
+
17
+ class Video:
18
+ """Sync video resource — generation, animation, audio-to-video, description, upscale.
19
+ """
20
+
21
+ def __init__(self, client: SyncHTTPClient) -> None:
22
+ self._client = client
23
+
24
+ def generate(
25
+ self,
26
+ *,
27
+ prompt: str,
28
+ model: str,
29
+ width: int | None = None,
30
+ height: int | None = None,
31
+ steps: int | None = None,
32
+ seed: int | None = None,
33
+ frames: int | None = None,
34
+ fps: int | None = None,
35
+ negative_prompt: str | None = None,
36
+ guidance: float | None = None,
37
+ enhance_prompt: bool | None = None,
38
+ webhook_url: str | None = None,
39
+ webhook_secret: str | None = None,
40
+ ) -> Job:
41
+ """Submit a text-to-video generation job.
42
+
43
+ Unset ``width``, ``height``, ``frames`` and ``fps`` are taken from the model's ``info.defaults`` (one
44
+ catalogue request per client, cached; disable with ``fill_model_defaults=False``); ``seed`` defaults to -1
45
+ (random). Other parameters left as ``None`` are not sent.
46
+ ``enhance_prompt`` rewrites the prompt server-side (needs a prompt-booster guide for the model).
47
+ """
48
+ url = self._client._resolve_endpoint("txt2video")
49
+ payload = _build_txt2video_payload(
50
+ prompt=prompt, model=model, width=width, height=height,
51
+ steps=steps, seed=seed, frames=frames, fps=fps,
52
+ negative_prompt=negative_prompt, guidance=guidance,
53
+ enhance_prompt=enhance_prompt,
54
+ **webhook_fields(webhook_url, webhook_secret),
55
+ )
56
+ payload = fill_payload(self._client, payload, VIDEO_KEYS, seed=True)
57
+ resp = self._client.post(url, json=payload)
58
+ request_id = resp["data"]["request_id"]
59
+ status_url = self._client._resolve_endpoint("request_status")
60
+ return Job(request_id, self._client, status_url)
61
+
62
+ def generate_price(
63
+ self,
64
+ *,
65
+ prompt: str,
66
+ model: str,
67
+ width: int | None = None,
68
+ height: int | None = None,
69
+ steps: int | None = None,
70
+ seed: int | None = None,
71
+ frames: int | None = None,
72
+ fps: int | None = None,
73
+ negative_prompt: str | None = None,
74
+ guidance: float | None = None,
75
+ ) -> PriceResult:
76
+ """Calculate price for text-to-video generation.
77
+
78
+ Unset ``width``, ``height``, ``frames`` and ``fps`` are taken from the model's
79
+ ``info.defaults`` (one catalogue request per
80
+ client, cached; disable with ``fill_model_defaults=False``).
81
+ """
82
+ url = self._client._resolve_endpoint("txt2video_price")
83
+ payload = _build_txt2video_payload(
84
+ prompt=prompt, model=model, width=width, height=height,
85
+ steps=steps, seed=seed, frames=frames, fps=fps,
86
+ negative_prompt=negative_prompt, guidance=guidance,
87
+ )
88
+ payload = fill_payload(self._client, payload, VIDEO_KEYS)
89
+ resp = self._client.post(url, json=payload)
90
+ return PriceResult.model_validate(resp.get("data", resp))
91
+
92
+ def animate(
93
+ self,
94
+ *,
95
+ prompt: str,
96
+ model: str,
97
+ first_frame_image: FileInput | None = None,
98
+ seed: int | None = None,
99
+ width: int | None = None,
100
+ height: int | None = None,
101
+ frames: int | None = None,
102
+ fps: int | None = None,
103
+ negative_prompt: str | None = None,
104
+ last_frame_image: FileInput | None = None,
105
+ guidance: float | None = None,
106
+ steps: int | None = None,
107
+ ref_images: list[FileInput] | None = None,
108
+ ref_videos: list[FileInput] | None = None,
109
+ ref_audios: list[FileInput] | None = None,
110
+ enhance_prompt: bool | None = None,
111
+ webhook_url: str | None = None,
112
+ webhook_secret: str | None = None,
113
+ ) -> Job:
114
+ """Submit an image-to-video animation job.
115
+
116
+ Two input modes (pick one):
117
+
118
+ * **Keyframes** — ``first_frame_image`` and, on models that support it, ``last_frame_image``.
119
+ * **Full-reference** — ``ref_images`` and/or ``ref_videos``, optionally with ``ref_audios``
120
+ (models whose card reports ``supports_image_refs`` / ``supports_video_refs`` /
121
+ ``supports_audio_refs``). Cannot be combined with keyframes; audio alone is not enough.
122
+
123
+ The order of each reference list binds the files to prompt tags: ``ref_images[0]`` is
124
+ ``<Picture 1>``, ``ref_images[1]`` is ``<Picture 2>``, ``ref_videos[0]`` is ``<Video 1>`` and
125
+ ``ref_audios[0]`` is ``<Audio 1>`` (``<Audio 2>`` if the reference video has its own audio track).
126
+ Numbering is independent per type. Reference limits come from the model card
127
+ (``max_ref_images``, ``max_ref_videos``, ``max_ref_audios``, ``max_ref_files``); the API never
128
+ accepts more than 9 images, 1 video or 3 audios. Parts are sent as ``ref_images[0]``, ``ref_images[1]``, ...
129
+
130
+ Unset ``width``, ``height``, ``frames`` and ``fps`` are taken from the model's
131
+ ``info.defaults`` (one catalogue request per
132
+ client, cached; disable with ``fill_model_defaults=False``); ``seed`` defaults to -1 (random).
133
+
134
+ Raises:
135
+ ValueError: mixed modes, audio-only references, or no image source at all.
136
+ """
137
+ url = self._client._resolve_endpoint("img2video")
138
+ data, files = _build_img2video_multipart(
139
+ prompt=prompt, model=model, first_frame_image=first_frame_image,
140
+ seed=seed, width=width, height=height, frames=frames, fps=fps,
141
+ negative_prompt=negative_prompt, last_frame_image=last_frame_image,
142
+ guidance=guidance, steps=steps,
143
+ ref_images=ref_images, ref_videos=ref_videos, ref_audios=ref_audios,
144
+ enhance_prompt=enhance_prompt,
145
+ webhook=webhook_fields(webhook_url, webhook_secret),
146
+ )
147
+ data = fill_payload(self._client, data, VIDEO_KEYS, seed=True, form=True)
148
+ resp = self._client.post(url, data=data, files=files)
149
+ request_id = resp["data"]["request_id"]
150
+ status_url = self._client._resolve_endpoint("request_status")
151
+ return Job(request_id, self._client, status_url)
152
+
153
+ def animate_price(
154
+ self,
155
+ *,
156
+ model: str,
157
+ width: int | None = None,
158
+ height: int | None = None,
159
+ frames: int | None = None,
160
+ fps: int | None = None,
161
+ steps: int | None = None,
162
+ guidance: float | None = None,
163
+ ref_images_count: int | None = None,
164
+ ref_videos_count: int | None = None,
165
+ ref_audios_count: int | None = None,
166
+ ) -> PriceResult:
167
+ """Calculate price for image-to-video animation.
168
+
169
+ For reference mode pass the *number* of reference files the job will carry, not the files
170
+ (``ref_images_count`` 0-9, ``ref_videos_count`` 0-1, ``ref_audios_count`` 0-3).
171
+ More than 2 reference images applies a x2 multiplier, any reference video x3 (the highest wins,
172
+ they do not stack). Reference audio adds no surcharge. The quote does not check model limits.
173
+
174
+ Unset ``width``, ``height``, ``frames`` and ``fps`` are taken from the model's
175
+ ``info.defaults`` (one catalogue request per
176
+ client, cached; disable with ``fill_model_defaults=False``).
177
+ """
178
+ url = self._client._resolve_endpoint("img2video_price")
179
+ payload = drop_none({
180
+ "model": model, "width": width, "height": height,
181
+ "frames": frames, "fps": fps, "steps": steps, "guidance": guidance,
182
+ "ref_images_count": ref_images_count, "ref_videos_count": ref_videos_count,
183
+ "ref_audios_count": ref_audios_count,
184
+ })
185
+ payload = fill_payload(self._client, payload, VIDEO_KEYS)
186
+ resp = self._client.post(url, json=payload)
187
+ return PriceResult.model_validate(resp.get("data", resp))
188
+
189
+ def generate_from_audio(
190
+ self,
191
+ *,
192
+ prompt: str,
193
+ audio: FileInput,
194
+ model: str,
195
+ width: int | None = None,
196
+ height: int | None = None,
197
+ seed: int | None = None,
198
+ frames: int | None = None,
199
+ fps: int | None = None,
200
+ negative_prompt: str | None = None,
201
+ first_frame_image: FileInput | None = None,
202
+ last_frame_image: FileInput | None = None,
203
+ guidance: float | None = None,
204
+ steps: int | None = None,
205
+ webhook_url: str | None = None,
206
+ webhook_secret: str | None = None,
207
+ ) -> Job:
208
+ """Submit an audio-to-video generation job (``videos/audio-syncs`` on v2).
209
+
210
+ Unset ``width``, ``height``, ``frames`` and ``fps`` are taken from the model's ``info.defaults`` (one
211
+ catalogue request per client, cached; disable with ``fill_model_defaults=False``); ``seed`` defaults to -1
212
+ (random). Other parameters left as ``None`` are not sent.
213
+ """
214
+ url = self._client._resolve_endpoint("aud2video")
215
+ data, files = _build_aud2video_multipart(
216
+ prompt=prompt, audio=audio, model=model, width=width, height=height,
217
+ seed=seed, frames=frames, fps=fps, negative_prompt=negative_prompt,
218
+ first_frame_image=first_frame_image, last_frame_image=last_frame_image,
219
+ guidance=guidance, steps=steps,
220
+ webhook=webhook_fields(webhook_url, webhook_secret),
221
+ )
222
+ data = fill_payload(self._client, data, VIDEO_KEYS, seed=True, form=True)
223
+ resp = self._client.post(url, data=data, files=files)
224
+ request_id = resp["data"]["request_id"]
225
+ status_url = self._client._resolve_endpoint("request_status")
226
+ return Job(request_id, self._client, status_url)
227
+
228
+ def generate_from_audio_price(
229
+ self,
230
+ *,
231
+ model: str,
232
+ width: int | None = None,
233
+ height: int | None = None,
234
+ frames: int | None = None,
235
+ fps: int | None = None,
236
+ guidance: float | None = None,
237
+ steps: int | None = None,
238
+ ) -> PriceResult:
239
+ """Calculate price for audio-to-video generation.
240
+
241
+ Unset ``width``, ``height``, ``frames`` and ``fps`` are taken from the model's
242
+ ``info.defaults`` (one catalogue request per
243
+ client, cached; disable with ``fill_model_defaults=False``).
244
+ """
245
+ url = self._client._resolve_endpoint("aud2video_price")
246
+ payload = drop_none({
247
+ "model": model, "width": width, "height": height,
248
+ "frames": frames, "fps": fps, "guidance": guidance, "steps": steps,
249
+ })
250
+ payload = fill_payload(self._client, payload, VIDEO_KEYS)
251
+ resp = self._client.post(url, json=payload)
252
+ return PriceResult.model_validate(resp.get("data", resp))
253
+
254
+ def describe(
255
+ self,
256
+ *,
257
+ model: str,
258
+ video_url: str | None = None,
259
+ video_file: FileInput | None = None,
260
+ preset: str | None = None,
261
+ include_metadata: bool | None = None,
262
+ return_result_in_response: bool | None = None,
263
+ webhook_url: str | None = None,
264
+ webhook_secret: str | None = None,
265
+ ) -> Job:
266
+ """Submit a video description job (``videos/descriptions``).
267
+
268
+ Produces a timestamped index of what happens on screen (events, scenes, metadata); it reads the
269
+ picture, not the audio (use ``transcription.create`` for speech). Pass exactly one source: ``video_url``
270
+ (YouTube, Twitter/X, Twitch, Kick, TikTok) or ``video_file`` (file upload).
271
+
272
+ ``preset`` is honoured only by models whose card has ``supports_presets`` (``available_presets``
273
+ lists the choices: ``fast``, ``balanced``, ``detail``). ``include_metadata`` adds source metadata
274
+ to the job status; only URL sources have any (a file returns null, uncharged).
275
+ With ``return_result_in_response=True`` the JSON is also returned
276
+ inline in ``JobResult.result``; otherwise download ``JobResult.result_url``. Use
277
+ :meth:`get_description` to get a typed :class:`~deapi_sdk.types.video.VideoDescription`.
278
+
279
+ Raises:
280
+ ValueError: not exactly one source.
281
+ """
282
+ url = self._client._resolve_endpoint("vid_description")
283
+ data, files = _build_describe_form(
284
+ model=model, video_url=video_url, video_file=video_file, preset=preset,
285
+ include_metadata=include_metadata, return_result_in_response=return_result_in_response,
286
+ webhook=webhook_fields(webhook_url, webhook_secret),
287
+ )
288
+ resp = self._client.post(url, data=data, files=files)
289
+ request_id = resp["data"]["request_id"]
290
+ status_url = self._client._resolve_endpoint("request_status")
291
+ return Job(request_id, self._client, status_url)
292
+
293
+ def describe_price(
294
+ self,
295
+ *,
296
+ model: str,
297
+ video_url: str | None = None,
298
+ video_file: FileInput | None = None,
299
+ duration_seconds: float | None = None,
300
+ platform: str | None = None,
301
+ preset: str | None = None,
302
+ include_metadata: bool | None = None,
303
+ ) -> PriceResult:
304
+ """Calculate price for a video description.
305
+
306
+ Pass exactly one source: ``video_url``, ``video_file`` or ``duration_seconds``. ``platform``
307
+ (``youtube``, ``twitter``, ``twitch``, ``kick``, ``tiktok``) is only accepted with
308
+ ``duration_seconds``; TikTok is priced on a fixed card by length (max 10 minutes) and a TikTok URL
309
+ cannot be quoted, so quote it by duration. Use the same ``preset`` / ``include_metadata`` as the job.
310
+ """
311
+ url = self._client._resolve_endpoint("vid_description_price")
312
+ data, files = _build_describe_price_form(
313
+ model=model, video_url=video_url, video_file=video_file, duration_seconds=duration_seconds,
314
+ platform=platform, preset=preset, include_metadata=include_metadata,
315
+ )
316
+ resp = self._client.post(url, data=data, files=files)
317
+ return PriceResult.model_validate(resp.get("data", resp))
318
+
319
+ def upscale(
320
+ self,
321
+ *,
322
+ video: FileInput,
323
+ model: str,
324
+ scale: int | None = None,
325
+ webhook_url: str | None = None,
326
+ webhook_secret: str | None = None,
327
+ ) -> Job:
328
+ """Submit a video upscale job.
329
+
330
+ ``scale`` is the upscale factor; only models whose card has a ``scale`` range accept it
331
+ (e.g. FlashVSR: 2-4). Left unset, such models use their smallest factor.
332
+ """
333
+ url = self._client._resolve_endpoint("vid_upscale")
334
+ data: dict[str, Any] = {"model": model}
335
+ if scale is not None:
336
+ data["scale"] = scale
337
+ data.update(webhook_fields(webhook_url, webhook_secret))
338
+ files = [("video", normalize_file(video, "video"))]
339
+ resp = self._client.post(url, data=data, files=files)
340
+ request_id = resp["data"]["request_id"]
341
+ status_url = self._client._resolve_endpoint("request_status")
342
+ return Job(request_id, self._client, status_url)
343
+
344
+ def upscale_price(
345
+ self,
346
+ *,
347
+ model: str,
348
+ video: FileInput | None = None,
349
+ width: int | None = None,
350
+ height: int | None = None,
351
+ scale: int | None = None,
352
+ duration: float | None = None,
353
+ ) -> PriceResult:
354
+ """Calculate price for video upscale.
355
+
356
+ Pass the ``video`` itself, or its ``width``, ``height`` and ``duration`` (seconds).
357
+ """
358
+ url = self._client._resolve_endpoint("vid_upscale_price")
359
+ if video is not None:
360
+ data: dict[str, Any] = {"model": model}
361
+ if scale is not None:
362
+ data["scale"] = scale
363
+ if duration is not None:
364
+ data["duration"] = duration
365
+ files = [("video", normalize_file(video, "video"))]
366
+ resp = self._client.post(url, data=data, files=files)
367
+ else:
368
+ payload = drop_none({
369
+ "model": model, "width": width, "height": height, "scale": scale, "duration": duration,
370
+ })
371
+ resp = self._client.post(url, json=payload)
372
+ return PriceResult.model_validate(resp.get("data", resp))
373
+
374
+ def get_description(self, result: JobResult | str) -> VideoDescription:
375
+ """Return the typed result of a finished :meth:`describe` job.
376
+
377
+ ``result`` is the ``JobResult`` from ``job.wait()`` / ``job.status()``, a raw JSON string, or a
378
+ ``result_url``. Inline ``result`` JSON is used when present; otherwise ``result_url`` is downloaded
379
+ **without** the Authorization header (it is a storage URL; the API key is never sent to it).
380
+ """
381
+ inline, result_url = _description_source(result)
382
+ if inline is not None:
383
+ return parse_video_description(inline)
384
+ return parse_video_description(_load_json(download_text(result_url, self._client._config.timeout)))
385
+
386
+
387
+ class AsyncVideo:
388
+ """Async video resource — generation, animation, audio-to-video, description, upscale.
389
+ """
390
+
391
+ def __init__(self, client: AsyncHTTPClient) -> None:
392
+ self._client = client
393
+
394
+ async def generate(
395
+ self,
396
+ *,
397
+ prompt: str,
398
+ model: str,
399
+ width: int | None = None,
400
+ height: int | None = None,
401
+ steps: int | None = None,
402
+ seed: int | None = None,
403
+ frames: int | None = None,
404
+ fps: int | None = None,
405
+ negative_prompt: str | None = None,
406
+ guidance: float | None = None,
407
+ enhance_prompt: bool | None = None,
408
+ webhook_url: str | None = None,
409
+ webhook_secret: str | None = None,
410
+ ) -> AsyncJob:
411
+ """Submit a text-to-video generation job.
412
+
413
+ Unset ``width``, ``height``, ``frames`` and ``fps`` are taken from the model's ``info.defaults`` (one
414
+ catalogue request per client, cached; disable with ``fill_model_defaults=False``); ``seed`` defaults to -1
415
+ (random). Other parameters left as ``None`` are not sent.
416
+ ``enhance_prompt`` rewrites the prompt server-side (needs a prompt-booster guide for the model).
417
+ """
418
+ url = self._client._resolve_endpoint("txt2video")
419
+ payload = _build_txt2video_payload(
420
+ prompt=prompt, model=model, width=width, height=height,
421
+ steps=steps, seed=seed, frames=frames, fps=fps,
422
+ negative_prompt=negative_prompt, guidance=guidance,
423
+ enhance_prompt=enhance_prompt,
424
+ **webhook_fields(webhook_url, webhook_secret),
425
+ )
426
+ payload = await afill_payload(self._client, payload, VIDEO_KEYS, seed=True)
427
+ resp = await self._client.post(url, json=payload)
428
+ request_id = resp["data"]["request_id"]
429
+ status_url = self._client._resolve_endpoint("request_status")
430
+ return AsyncJob(request_id, self._client, status_url)
431
+
432
+ async def generate_price(
433
+ self,
434
+ *,
435
+ prompt: str,
436
+ model: str,
437
+ width: int | None = None,
438
+ height: int | None = None,
439
+ steps: int | None = None,
440
+ seed: int | None = None,
441
+ frames: int | None = None,
442
+ fps: int | None = None,
443
+ negative_prompt: str | None = None,
444
+ guidance: float | None = None,
445
+ ) -> PriceResult:
446
+ """Calculate price for text-to-video generation.
447
+
448
+ Unset ``width``, ``height``, ``frames`` and ``fps`` are taken from the model's
449
+ ``info.defaults`` (one catalogue request per
450
+ client, cached; disable with ``fill_model_defaults=False``).
451
+ """
452
+ url = self._client._resolve_endpoint("txt2video_price")
453
+ payload = _build_txt2video_payload(
454
+ prompt=prompt, model=model, width=width, height=height,
455
+ steps=steps, seed=seed, frames=frames, fps=fps,
456
+ negative_prompt=negative_prompt, guidance=guidance,
457
+ )
458
+ payload = await afill_payload(self._client, payload, VIDEO_KEYS)
459
+ resp = await self._client.post(url, json=payload)
460
+ return PriceResult.model_validate(resp.get("data", resp))
461
+
462
+ async def animate(
463
+ self,
464
+ *,
465
+ prompt: str,
466
+ model: str,
467
+ first_frame_image: FileInput | None = None,
468
+ seed: int | None = None,
469
+ width: int | None = None,
470
+ height: int | None = None,
471
+ frames: int | None = None,
472
+ fps: int | None = None,
473
+ negative_prompt: str | None = None,
474
+ last_frame_image: FileInput | None = None,
475
+ guidance: float | None = None,
476
+ steps: int | None = None,
477
+ ref_images: list[FileInput] | None = None,
478
+ ref_videos: list[FileInput] | None = None,
479
+ ref_audios: list[FileInput] | None = None,
480
+ enhance_prompt: bool | None = None,
481
+ webhook_url: str | None = None,
482
+ webhook_secret: str | None = None,
483
+ ) -> AsyncJob:
484
+ """Submit an image-to-video animation job.
485
+
486
+ Two input modes (pick one):
487
+
488
+ * **Keyframes** — ``first_frame_image`` and, on models that support it, ``last_frame_image``.
489
+ * **Full-reference** — ``ref_images`` and/or ``ref_videos``, optionally with ``ref_audios``
490
+ (models whose card reports ``supports_image_refs`` / ``supports_video_refs`` /
491
+ ``supports_audio_refs``). Cannot be combined with keyframes; audio alone is not enough.
492
+
493
+ The order of each reference list binds the files to prompt tags: ``ref_images[0]`` is
494
+ ``<Picture 1>``, ``ref_images[1]`` is ``<Picture 2>``, ``ref_videos[0]`` is ``<Video 1>`` and
495
+ ``ref_audios[0]`` is ``<Audio 1>`` (``<Audio 2>`` if the reference video has its own audio track).
496
+ Numbering is independent per type. Reference limits come from the model card
497
+ (``max_ref_images``, ``max_ref_videos``, ``max_ref_audios``, ``max_ref_files``); the API never
498
+ accepts more than 9 images, 1 video or 3 audios. Parts are sent as ``ref_images[0]``, ``ref_images[1]``, ...
499
+
500
+ Unset ``width``, ``height``, ``frames`` and ``fps`` are taken from the model's
501
+ ``info.defaults`` (one catalogue request per
502
+ client, cached; disable with ``fill_model_defaults=False``); ``seed`` defaults to -1 (random).
503
+
504
+ Raises:
505
+ ValueError: mixed modes, audio-only references, or no image source at all.
506
+ """
507
+ url = self._client._resolve_endpoint("img2video")
508
+ data, files = _build_img2video_multipart(
509
+ prompt=prompt, model=model, first_frame_image=first_frame_image,
510
+ seed=seed, width=width, height=height, frames=frames, fps=fps,
511
+ negative_prompt=negative_prompt, last_frame_image=last_frame_image,
512
+ guidance=guidance, steps=steps,
513
+ ref_images=ref_images, ref_videos=ref_videos, ref_audios=ref_audios,
514
+ enhance_prompt=enhance_prompt,
515
+ webhook=webhook_fields(webhook_url, webhook_secret),
516
+ )
517
+ data = await afill_payload(self._client, data, VIDEO_KEYS, seed=True, form=True)
518
+ resp = await self._client.post(url, data=data, files=files)
519
+ request_id = resp["data"]["request_id"]
520
+ status_url = self._client._resolve_endpoint("request_status")
521
+ return AsyncJob(request_id, self._client, status_url)
522
+
523
+ async def animate_price(
524
+ self,
525
+ *,
526
+ model: str,
527
+ width: int | None = None,
528
+ height: int | None = None,
529
+ frames: int | None = None,
530
+ fps: int | None = None,
531
+ steps: int | None = None,
532
+ guidance: float | None = None,
533
+ ref_images_count: int | None = None,
534
+ ref_videos_count: int | None = None,
535
+ ref_audios_count: int | None = None,
536
+ ) -> PriceResult:
537
+ """Calculate price for image-to-video animation.
538
+
539
+ For reference mode pass the *number* of reference files the job will carry, not the files
540
+ (``ref_images_count`` 0-9, ``ref_videos_count`` 0-1, ``ref_audios_count`` 0-3).
541
+ More than 2 reference images applies a x2 multiplier, any reference video x3 (the highest wins,
542
+ they do not stack). Reference audio adds no surcharge. The quote does not check model limits.
543
+
544
+ Unset ``width``, ``height``, ``frames`` and ``fps`` are taken from the model's
545
+ ``info.defaults`` (one catalogue request per
546
+ client, cached; disable with ``fill_model_defaults=False``).
547
+ """
548
+ url = self._client._resolve_endpoint("img2video_price")
549
+ payload = drop_none({
550
+ "model": model, "width": width, "height": height,
551
+ "frames": frames, "fps": fps, "steps": steps, "guidance": guidance,
552
+ "ref_images_count": ref_images_count, "ref_videos_count": ref_videos_count,
553
+ "ref_audios_count": ref_audios_count,
554
+ })
555
+ payload = await afill_payload(self._client, payload, VIDEO_KEYS)
556
+ resp = await self._client.post(url, json=payload)
557
+ return PriceResult.model_validate(resp.get("data", resp))
558
+
559
+ async def generate_from_audio(
560
+ self,
561
+ *,
562
+ prompt: str,
563
+ audio: FileInput,
564
+ model: str,
565
+ width: int | None = None,
566
+ height: int | None = None,
567
+ seed: int | None = None,
568
+ frames: int | None = None,
569
+ fps: int | None = None,
570
+ negative_prompt: str | None = None,
571
+ first_frame_image: FileInput | None = None,
572
+ last_frame_image: FileInput | None = None,
573
+ guidance: float | None = None,
574
+ steps: int | None = None,
575
+ webhook_url: str | None = None,
576
+ webhook_secret: str | None = None,
577
+ ) -> AsyncJob:
578
+ """Submit an audio-to-video generation job (``videos/audio-syncs`` on v2).
579
+
580
+ Unset ``width``, ``height``, ``frames`` and ``fps`` are taken from the model's ``info.defaults`` (one
581
+ catalogue request per client, cached; disable with ``fill_model_defaults=False``); ``seed`` defaults to -1
582
+ (random). Other parameters left as ``None`` are not sent.
583
+ """
584
+ url = self._client._resolve_endpoint("aud2video")
585
+ data, files = _build_aud2video_multipart(
586
+ prompt=prompt, audio=audio, model=model, width=width, height=height,
587
+ seed=seed, frames=frames, fps=fps, negative_prompt=negative_prompt,
588
+ first_frame_image=first_frame_image, last_frame_image=last_frame_image,
589
+ guidance=guidance, steps=steps,
590
+ webhook=webhook_fields(webhook_url, webhook_secret),
591
+ )
592
+ data = await afill_payload(self._client, data, VIDEO_KEYS, seed=True, form=True)
593
+ resp = await self._client.post(url, data=data, files=files)
594
+ request_id = resp["data"]["request_id"]
595
+ status_url = self._client._resolve_endpoint("request_status")
596
+ return AsyncJob(request_id, self._client, status_url)
597
+
598
+ async def generate_from_audio_price(
599
+ self,
600
+ *,
601
+ model: str,
602
+ width: int | None = None,
603
+ height: int | None = None,
604
+ frames: int | None = None,
605
+ fps: int | None = None,
606
+ guidance: float | None = None,
607
+ steps: int | None = None,
608
+ ) -> PriceResult:
609
+ """Calculate price for audio-to-video generation.
610
+
611
+ Unset ``width``, ``height``, ``frames`` and ``fps`` are taken from the model's
612
+ ``info.defaults`` (one catalogue request per
613
+ client, cached; disable with ``fill_model_defaults=False``).
614
+ """
615
+ url = self._client._resolve_endpoint("aud2video_price")
616
+ payload = drop_none({
617
+ "model": model, "width": width, "height": height,
618
+ "frames": frames, "fps": fps, "guidance": guidance, "steps": steps,
619
+ })
620
+ payload = await afill_payload(self._client, payload, VIDEO_KEYS)
621
+ resp = await self._client.post(url, json=payload)
622
+ return PriceResult.model_validate(resp.get("data", resp))
623
+
624
+ async def describe(
625
+ self,
626
+ *,
627
+ model: str,
628
+ video_url: str | None = None,
629
+ video_file: FileInput | None = None,
630
+ preset: str | None = None,
631
+ include_metadata: bool | None = None,
632
+ return_result_in_response: bool | None = None,
633
+ webhook_url: str | None = None,
634
+ webhook_secret: str | None = None,
635
+ ) -> AsyncJob:
636
+ """Submit a video description job (``videos/descriptions``).
637
+
638
+ Produces a timestamped index of what happens on screen (events, scenes, metadata); it reads the
639
+ picture, not the audio (use ``transcription.create`` for speech). Pass exactly one source: ``video_url``
640
+ (YouTube, Twitter/X, Twitch, Kick, TikTok) or ``video_file`` (file upload).
641
+
642
+ ``preset`` is honoured only by models whose card has ``supports_presets`` (``available_presets``
643
+ lists the choices: ``fast``, ``balanced``, ``detail``). ``include_metadata`` adds source metadata
644
+ to the job status; only URL sources have any (a file returns null, uncharged).
645
+ With ``return_result_in_response=True`` the JSON is also returned
646
+ inline in ``JobResult.result``; otherwise download ``JobResult.result_url``. Use
647
+ :meth:`get_description` to get a typed :class:`~deapi_sdk.types.video.VideoDescription`.
648
+
649
+ Raises:
650
+ ValueError: not exactly one source.
651
+ """
652
+ url = self._client._resolve_endpoint("vid_description")
653
+ data, files = _build_describe_form(
654
+ model=model, video_url=video_url, video_file=video_file, preset=preset,
655
+ include_metadata=include_metadata, return_result_in_response=return_result_in_response,
656
+ webhook=webhook_fields(webhook_url, webhook_secret),
657
+ )
658
+ resp = await self._client.post(url, data=data, files=files)
659
+ request_id = resp["data"]["request_id"]
660
+ status_url = self._client._resolve_endpoint("request_status")
661
+ return AsyncJob(request_id, self._client, status_url)
662
+
663
+ async def describe_price(
664
+ self,
665
+ *,
666
+ model: str,
667
+ video_url: str | None = None,
668
+ video_file: FileInput | None = None,
669
+ duration_seconds: float | None = None,
670
+ platform: str | None = None,
671
+ preset: str | None = None,
672
+ include_metadata: bool | None = None,
673
+ ) -> PriceResult:
674
+ """Calculate price for a video description.
675
+
676
+ Pass exactly one source: ``video_url``, ``video_file`` or ``duration_seconds``. ``platform``
677
+ (``youtube``, ``twitter``, ``twitch``, ``kick``, ``tiktok``) is only accepted with
678
+ ``duration_seconds``; TikTok is priced on a fixed card by length (max 10 minutes) and a TikTok URL
679
+ cannot be quoted, so quote it by duration. Use the same ``preset`` / ``include_metadata`` as the job.
680
+ """
681
+ url = self._client._resolve_endpoint("vid_description_price")
682
+ data, files = _build_describe_price_form(
683
+ model=model, video_url=video_url, video_file=video_file, duration_seconds=duration_seconds,
684
+ platform=platform, preset=preset, include_metadata=include_metadata,
685
+ )
686
+ resp = await self._client.post(url, data=data, files=files)
687
+ return PriceResult.model_validate(resp.get("data", resp))
688
+
689
+ async def upscale(
690
+ self,
691
+ *,
692
+ video: FileInput,
693
+ model: str,
694
+ scale: int | None = None,
695
+ webhook_url: str | None = None,
696
+ webhook_secret: str | None = None,
697
+ ) -> AsyncJob:
698
+ """Submit a video upscale job.
699
+
700
+ ``scale`` is the upscale factor; only models whose card has a ``scale`` range accept it
701
+ (e.g. FlashVSR: 2-4). Left unset, such models use their smallest factor.
702
+ """
703
+ url = self._client._resolve_endpoint("vid_upscale")
704
+ data: dict[str, Any] = {"model": model}
705
+ if scale is not None:
706
+ data["scale"] = scale
707
+ data.update(webhook_fields(webhook_url, webhook_secret))
708
+ files = [("video", normalize_file(video, "video"))]
709
+ resp = await self._client.post(url, data=data, files=files)
710
+ request_id = resp["data"]["request_id"]
711
+ status_url = self._client._resolve_endpoint("request_status")
712
+ return AsyncJob(request_id, self._client, status_url)
713
+
714
+ async def upscale_price(
715
+ self,
716
+ *,
717
+ model: str,
718
+ video: FileInput | None = None,
719
+ width: int | None = None,
720
+ height: int | None = None,
721
+ scale: int | None = None,
722
+ duration: float | None = None,
723
+ ) -> PriceResult:
724
+ """Calculate price for video upscale.
725
+
726
+ Pass the ``video`` itself, or its ``width``, ``height`` and ``duration`` (seconds).
727
+ """
728
+ url = self._client._resolve_endpoint("vid_upscale_price")
729
+ if video is not None:
730
+ data: dict[str, Any] = {"model": model}
731
+ if scale is not None:
732
+ data["scale"] = scale
733
+ if duration is not None:
734
+ data["duration"] = duration
735
+ files = [("video", normalize_file(video, "video"))]
736
+ resp = await self._client.post(url, data=data, files=files)
737
+ else:
738
+ payload = drop_none({
739
+ "model": model, "width": width, "height": height, "scale": scale, "duration": duration,
740
+ })
741
+ resp = await self._client.post(url, json=payload)
742
+ return PriceResult.model_validate(resp.get("data", resp))
743
+
744
+ async def get_description(self, result: JobResult | str) -> VideoDescription:
745
+ """Return the typed result of a finished :meth:`describe` job (see :meth:`Video.get_description`).
746
+
747
+ The ``result_url`` download carries no Authorization header.
748
+ """
749
+ inline, result_url = _description_source(result)
750
+ if inline is not None:
751
+ return parse_video_description(inline)
752
+ text = await adownload_text(result_url, self._client._config.timeout)
753
+ return parse_video_description(_load_json(text))
754
+
755
+
756
+ def _as_list(items: Any) -> list[Any]:
757
+ if items is None:
758
+ return []
759
+ if isinstance(items, (list, tuple)):
760
+ return list(items)
761
+ return [items]
762
+
763
+
764
+ def _build_txt2video_payload(
765
+ *,
766
+ prompt: str,
767
+ model: str,
768
+ width: int | None = None,
769
+ height: int | None = None,
770
+ steps: int | None = None,
771
+ seed: int | None = None,
772
+ frames: int | None = None,
773
+ fps: int | None = None,
774
+ negative_prompt: str | None = None,
775
+ guidance: float | None = None,
776
+ enhance_prompt: bool | None = None,
777
+ **extra: str,
778
+ ) -> dict[str, Any]:
779
+ payload = drop_none({
780
+ "prompt": prompt,
781
+ "model": model,
782
+ "width": width,
783
+ "height": height,
784
+ "steps": steps,
785
+ "seed": seed,
786
+ "frames": frames,
787
+ "fps": fps,
788
+ "negative_prompt": negative_prompt,
789
+ "guidance": guidance,
790
+ "enhance_prompt": enhance_prompt,
791
+ })
792
+ payload.update(extra)
793
+ return payload
794
+
795
+
796
+ def _build_img2video_multipart(
797
+ *,
798
+ prompt: str,
799
+ model: str,
800
+ first_frame_image: FileInput | None = None,
801
+ seed: int | None = None,
802
+ width: int | None = None,
803
+ height: int | None = None,
804
+ frames: int | None = None,
805
+ fps: int | None = None,
806
+ negative_prompt: str | None = None,
807
+ last_frame_image: FileInput | None = None,
808
+ guidance: float | None = None,
809
+ steps: int | None = None,
810
+ ref_images: list[FileInput] | None = None,
811
+ ref_videos: list[FileInput] | None = None,
812
+ ref_audios: list[FileInput] | None = None,
813
+ enhance_prompt: bool | None = None,
814
+ webhook: dict[str, str] | None = None,
815
+ ) -> tuple[dict[str, Any], list[tuple[str, tuple[str, bytes, str]]]]:
816
+ """Build multipart form data and files list for img2video (keyframe or reference mode)."""
817
+ images = _as_list(ref_images)
818
+ videos = _as_list(ref_videos)
819
+ audios = _as_list(ref_audios)
820
+ has_refs = bool(images or videos or audios)
821
+
822
+ if has_refs and (first_frame_image is not None or last_frame_image is not None):
823
+ raise ValueError(
824
+ "ref_images/ref_videos/ref_audios cannot be combined with first_frame_image/last_frame_image"
825
+ )
826
+ for label, items, cap in (("ref_images", images, 9), ("ref_videos", videos, 1), ("ref_audios", audios, 3)):
827
+ if len(items) > cap:
828
+ raise ValueError(f"{label} accepts at most {cap} files (got {len(items)})")
829
+ if audios and not (images or videos):
830
+ raise ValueError("ref_audios requires at least one ref_images or ref_videos entry")
831
+ if first_frame_image is None and last_frame_image is None and not (images or videos):
832
+ raise ValueError("Provide first_frame_image, or ref_images/ref_videos (reference mode)")
833
+
834
+ data = drop_none({
835
+ "prompt": prompt,
836
+ "model": model,
837
+ "seed": seed,
838
+ "width": width,
839
+ "height": height,
840
+ "frames": frames,
841
+ "fps": fps,
842
+ "negative_prompt": negative_prompt,
843
+ "guidance": guidance,
844
+ "steps": steps,
845
+ })
846
+ if enhance_prompt is not None:
847
+ data["enhance_prompt"] = form_bool(enhance_prompt)
848
+ data.update(webhook or {})
849
+
850
+ file_tuples: list[tuple[str, tuple[str, bytes, str]]] = []
851
+ if first_frame_image is not None:
852
+ file_tuples.append(("first_frame_image", normalize_file(first_frame_image, "first_frame_image")))
853
+ if last_frame_image is not None:
854
+ file_tuples.append(("last_frame_image", normalize_file(last_frame_image, "last_frame_image")))
855
+ # Explicit indices (`ref_images[0]`, `ref_images[1]`, ...) bind files to <Picture N>/<Video N>/<Audio N>.
856
+ for i, item in enumerate(images):
857
+ file_tuples.append((f"ref_images[{i}]", normalize_file(item, "ref_image")))
858
+ for i, item in enumerate(videos):
859
+ file_tuples.append((f"ref_videos[{i}]", normalize_file(item, "ref_video")))
860
+ for i, item in enumerate(audios):
861
+ file_tuples.append((f"ref_audios[{i}]", normalize_file(item, "ref_audio")))
862
+
863
+ return data, file_tuples
864
+
865
+
866
+ def _build_aud2video_multipart(
867
+ *,
868
+ prompt: str,
869
+ audio: FileInput,
870
+ model: str,
871
+ width: int | None = None,
872
+ height: int | None = None,
873
+ seed: int | None = None,
874
+ frames: int | None = None,
875
+ fps: int | None = None,
876
+ negative_prompt: str | None = None,
877
+ first_frame_image: FileInput | None = None,
878
+ last_frame_image: FileInput | None = None,
879
+ guidance: float | None = None,
880
+ steps: int | None = None,
881
+ webhook: dict[str, str] | None = None,
882
+ ) -> tuple[dict[str, Any], list[tuple[str, tuple[str, bytes, str]]]]:
883
+ """Build multipart form data and files list for aud2video."""
884
+ data = drop_none({
885
+ "prompt": prompt,
886
+ "model": model,
887
+ "width": width,
888
+ "height": height,
889
+ "seed": seed,
890
+ "frames": frames,
891
+ "fps": fps,
892
+ "negative_prompt": negative_prompt,
893
+ "guidance": guidance,
894
+ "steps": steps,
895
+ })
896
+ data.update(webhook or {})
897
+
898
+ file_tuples: list[tuple[str, tuple[str, bytes, str]]] = []
899
+ file_tuples.append(("audio", normalize_file(audio, "audio")))
900
+ if first_frame_image is not None:
901
+ file_tuples.append(("first_frame_image", normalize_file(first_frame_image, "first_frame_image")))
902
+ if last_frame_image is not None:
903
+ file_tuples.append(("last_frame_image", normalize_file(last_frame_image, "last_frame_image")))
904
+
905
+ return data, file_tuples
906
+
907
+
908
+ def _build_describe_form(
909
+ *,
910
+ model: str,
911
+ video_url: str | None,
912
+ video_file: FileInput | None,
913
+ preset: str | None,
914
+ include_metadata: bool | None,
915
+ return_result_in_response: bool | None,
916
+ webhook: dict[str, str],
917
+ ) -> tuple[dict[str, Any], list[tuple[str, tuple[str, bytes, str]]] | None]:
918
+ if (video_url is None) == (video_file is None):
919
+ raise ValueError("Provide exactly one of 'video_url' or 'video_file'")
920
+ data: dict[str, Any] = {"model": model}
921
+ if preset is not None:
922
+ data["preset"] = preset
923
+ if include_metadata is not None:
924
+ data["include_metadata"] = form_bool(include_metadata)
925
+ if return_result_in_response is not None:
926
+ data["return_result_in_response"] = form_bool(return_result_in_response)
927
+ data.update(webhook)
928
+ if video_url is not None:
929
+ data["video_url"] = video_url
930
+ return data, None
931
+ return data, [("video_file", normalize_file(video_file, "video_file"))] # type: ignore[arg-type]
932
+
933
+
934
+ def _build_describe_price_form(
935
+ *,
936
+ model: str,
937
+ video_url: str | None,
938
+ video_file: FileInput | None,
939
+ duration_seconds: float | None,
940
+ platform: str | None,
941
+ preset: str | None,
942
+ include_metadata: bool | None,
943
+ ) -> tuple[dict[str, Any], list[tuple[str, tuple[str, bytes, str]]] | None]:
944
+ sources = [s for s in (video_url, video_file, duration_seconds) if s is not None]
945
+ if len(sources) != 1:
946
+ raise ValueError("Provide exactly one of 'video_url', 'video_file' or 'duration_seconds'")
947
+ if platform is not None and duration_seconds is None:
948
+ raise ValueError("platform is only accepted together with duration_seconds")
949
+ data: dict[str, Any] = {"model": model}
950
+ if preset is not None:
951
+ data["preset"] = preset
952
+ if include_metadata is not None:
953
+ data["include_metadata"] = form_bool(include_metadata)
954
+ if video_url is not None:
955
+ data["video_url"] = video_url
956
+ return data, None
957
+ if duration_seconds is not None:
958
+ data["duration_seconds"] = str(duration_seconds)
959
+ if platform is not None:
960
+ data["platform"] = platform
961
+ return data, None
962
+ return data, [("video_file", normalize_file(video_file, "video_file"))] # type: ignore[arg-type]
963
+
964
+
965
+ def _description_source(result: JobResult | str) -> tuple[Any, str]:
966
+ """Split a JobResult/str into (inline JSON or None, result_url)."""
967
+ if isinstance(result, JobResult):
968
+ if result.result:
969
+ return result.result, ""
970
+ if not result.result_url:
971
+ raise ValueError("Job result has neither inline 'result' nor 'result_url' (is the job done?)")
972
+ return None, result.result_url
973
+ text = result.strip()
974
+ if text.startswith("{"):
975
+ return text, ""
976
+ if not text.lower().startswith("https://"):
977
+ raise ValueError("Expected a JobResult, a JSON string, or an https result_url")
978
+ return None, text
979
+
980
+
981
+ def _load_json(text: str) -> Any:
982
+ try:
983
+ return json.loads(text)
984
+ except ValueError as exc:
985
+ raise DeapiError("Could not parse the video description result (invalid JSON)") from exc