Video API support

rishabh-bhargava · rishabh-bhargava · commit 9e17597fdfb3 · 2025-10-16T03:51:19.000+05:30
diff --git a/src/together/client.py b/src/together/client.py
@@ -26,6 +26,7 @@ class Together:
     batches: resources.Batches
     code_interpreter: CodeInterpreter
     evaluation: resources.Evaluation
+    videos: resources.Videos
 
     # client options
     client: TogetherClient
@@ -94,6 +95,7 @@ def __init__(
         self.code_interpreter = CodeInterpreter(self.client)
         self.batches = resources.Batches(self.client)
         self.evaluation = resources.Evaluation(self.client)
+        self.videos = resources.Videos(self.client)
 
 
 class AsyncTogether:
@@ -109,6 +111,7 @@ class AsyncTogether:
     code_interpreter: CodeInterpreter
     batches: resources.AsyncBatches
     evaluation: resources.AsyncEvaluation
+    videos: resources.AsyncVideos
     # client options
     client: TogetherClient
 
@@ -175,6 +178,7 @@ def __init__(
         self.code_interpreter = CodeInterpreter(self.client)
         self.batches = resources.AsyncBatches(self.client)
         self.evaluation = resources.AsyncEvaluation(self.client)
+        self.videos = resources.AsyncVideos(self.client)
 
 
 Client = Together
diff --git a/src/together/resources/__init__.py b/src/together/resources/__init__.py
@@ -10,6 +10,7 @@
 from together.resources.rerank import AsyncRerank, Rerank
 from together.resources.batch import Batches, AsyncBatches
 from together.resources.evaluation import Evaluation, AsyncEvaluation
+from together.resources.videos import AsyncVideos, Videos
 
 
 __all__ = [
@@ -37,4 +38,6 @@
     "AsyncBatches",
     "Evaluation",
     "AsyncEvaluation",
+    "AsyncVideos",
+    "Videos",
 ]
diff --git a/src/together/resources/videos.py b/src/together/resources/videos.py
@@ -0,0 +1,307 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from together.abstract import api_requestor
+from together.together_response import TogetherResponse
+from together.types import (
+    TogetherClient,
+    TogetherRequest,
+)
+from together.types.videos import (
+    VideoGenerateResponse,
+    VideoRequest,
+    VideoStatusResponse,
+)
+
+
+class Videos:
+    def __init__(self, client: TogetherClient) -> None:
+        self._client = client
+
+    def generate(
+        self,
+        *,
+        prompt: str,
+        model: str,
+        height: int | None = None,
+        width: int | None = None,
+        seconds: float | None = None,
+        fps: int | None = None,
+        steps: int | None = None,
+        seed: int | None = None,
+        guidance_scale: float | None = None,
+        output_format: str | None = None,
+        output_quality: int | None = None,
+        negative_prompt: str | None = None,
+        frame_images: List[Dict[str, Any]] | None = None,
+        reference_images: List[Dict[str, Any]] | None = None,
+        metadata: Dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> VideoGenerateResponse:
+        """
+        Method to generate videos based on a given prompt using a specified model.
+
+        Args:
+            prompt (str): A description of the desired video. Positive prompt for the generation.
+
+            model (str): The model to use for video generation (e.g., "google/veo-3.0-fast").
+
+            height (int, optional): Height of the video to generate in pixels.
+
+            width (int, optional): Width of the video to generate in pixels.
+
+            seconds (float, optional): Length of generated video in seconds. Min 1 max 10.
+
+            fps (int, optional): Frames per second, min 15 max 60. Defaults to 24.
+
+            steps (int, optional): The number of denoising steps the model performs during video
+                generation. More steps typically result in higher quality output but require longer
+                processing time. Min 10 max 50. Defaults to 20.
+
+            seed (int, optional): Seed to use in initializing the video generation. Using the same
+                seed allows deterministic video generation. If not provided, a random seed is
+                generated for each request. Note: When requesting multiple videos with the same
+                seed, the seed will be incremented by 1 (+1) for each video generated.
+
+            guidance_scale (float, optional): Controls how closely the video generation follows your
+                prompt. Higher values make the model adhere more strictly to your text description,
+                while lower values allow more creative freedom. Recommended range is 6.0-10.0 for
+                most video models. Values above 12 may cause over-guidance artifacts or unnatural
+                motion patterns. Defaults to 8.
+
+            output_format (str, optional): Specifies the format of the output video. Either "MP4"
+                or "WEBM". Defaults to "MP4".
+
+            output_quality (int, optional): Compression quality. Defaults to 20.
+
+            negative_prompt (str, optional): Similar to prompt, but specifies what to avoid instead
+                of what to include. Defaults to None.
+
+            frame_images (List[Dict[str, Any]], optional): Array of images to guide video generation,
+                like keyframes. If size 1, starting frame; if size 2, starting and ending frame;
+                if more than 2 then frame must be specified. Defaults to None.
+
+            reference_images (List[Dict[str, Any]], optional): An array containing reference images
+                used to condition the generation process. These images provide visual guidance to
+                help the model generate content that aligns with the style, composition, or
+                characteristics of the reference materials. Defaults to None.
+
+            metadata (Dict[str, Any], optional): Additional metadata for the request. Defaults to None.
+
+        Returns:
+            VideoGenerateResponse: Object containing video generation job id
+        """
+
+        requestor = api_requestor.APIRequestor(
+            client=self._client,
+        )
+
+        parameter_payload = VideoRequest(
+            prompt=prompt,
+            model=model,
+            height=height,
+            width=width,
+            seconds=seconds,
+            fps=fps,
+            steps=steps,
+            seed=seed,
+            guidance_scale=guidance_scale,
+            output_format=output_format,
+            output_quality=output_quality,
+            negative_prompt=negative_prompt,
+            frame_images=frame_images,
+            reference_images=reference_images,
+            metadata=metadata,
+            **kwargs,
+        ).model_dump(exclude_none=True)
+
+        response, _, _ = requestor.request(
+            options=TogetherRequest(
+                method="POST",
+                url="../v2/videos",
+                params=parameter_payload,
+            ),
+            stream=False,
+        )
+
+        assert isinstance(response, TogetherResponse)
+
+        return VideoGenerateResponse(**response.data)
+
+    def status(
+        self,
+        *,
+        id: str,
+    ) -> VideoStatusResponse:
+        """
+        Method to check the status of a video generation job.
+
+        Args:
+            id (str): The ID of the video generation job to check.
+
+        Returns:
+            VideoStatusResponse: Object containing the current status and details of the video generation job
+        """
+
+        requestor = api_requestor.APIRequestor(
+            client=self._client,
+        )
+
+        response, _, _ = requestor.request(
+            options=TogetherRequest(
+                method="GET",
+                url=f"../v2/videos/status?id={id}",
+            ),
+            stream=False,
+        )
+
+        assert isinstance(response, TogetherResponse)
+
+        return VideoStatusResponse(**response.data)
+
+
+class AsyncVideos:
+    def __init__(self, client: TogetherClient) -> None:
+        self._client = client
+
+    async def generate(
+        self,
+        *,
+        prompt: str,
+        model: str,
+        height: int | None = None,
+        width: int | None = None,
+        seconds: float | None = None,
+        fps: int | None = None,
+        steps: int | None = None,
+        seed: int | None = None,
+        guidance_scale: float | None = None,
+        output_format: str | None = None,
+        output_quality: int | None = None,
+        negative_prompt: str | None = None,
+        frame_images: List[Dict[str, Any]] | None = None,
+        reference_images: List[Dict[str, Any]] | None = None,
+        metadata: Dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> VideoGenerateResponse:
+        """
+        Async method to generate videos based on a given prompt using a specified model.
+
+        Args:
+            prompt (str): A description of the desired video. Positive prompt for the generation.
+
+            model (str): The model to use for video generation (e.g., "google/veo-3.0-fast").
+
+            height (int, optional): Height of the video to generate in pixels.
+
+            width (int, optional): Width of the video to generate in pixels.
+
+            seconds (float, optional): Length of generated video in seconds. Min 1 max 10.
+
+            fps (int, optional): Frames per second, min 15 max 60. Defaults to 24.
+
+            steps (int, optional): The number of denoising steps the model performs during video
+                generation. More steps typically result in higher quality output but require longer
+                processing time. Min 10 max 50. Defaults to 20.
+
+            seed (int, optional): Seed to use in initializing the video generation. Using the same
+                seed allows deterministic video generation. If not provided, a random seed is
+                generated for each request. Note: When requesting multiple videos with the same
+                seed, the seed will be incremented by 1 (+1) for each video generated.
+
+            guidance_scale (float, optional): Controls how closely the video generation follows your
+                prompt. Higher values make the model adhere more strictly to your text description,
+                while lower values allow more creative freedom. Recommended range is 6.0-10.0 for
+                most video models. Values above 12 may cause over-guidance artifacts or unnatural
+                motion patterns. Defaults to 8.
+
+            output_format (str, optional): Specifies the format of the output video. Either "MP4"
+                or "WEBM". Defaults to "MP4".
+
+            output_quality (int, optional): Compression quality. Defaults to 20.
+
+            negative_prompt (str, optional): Similar to prompt, but specifies what to avoid instead
+                of what to include. Defaults to None.
+
+            frame_images (List[Dict[str, Any]], optional): Array of images to guide video generation,
+                like keyframes. If size 1, starting frame; if size 2, starting and ending frame;
+                if more than 2 then frame must be specified. Defaults to None.
+
+            reference_images (List[Dict[str, Any]], optional): An array containing reference images
+                used to condition the generation process. These images provide visual guidance to
+                help the model generate content that aligns with the style, composition, or
+                characteristics of the reference materials. Defaults to None.
+
+            metadata (Dict[str, Any], optional): Additional metadata for the request. Defaults to None.
+
+        Returns:
+            VideoGenerateResponse: Object containing video generation job id
+        """
+
+        requestor = api_requestor.APIRequestor(
+            client=self._client,
+        )
+
+        parameter_payload = VideoRequest(
+            prompt=prompt,
+            model=model,
+            height=height,
+            width=width,
+            seconds=seconds,
+            fps=fps,
+            steps=steps,
+            seed=seed,
+            guidance_scale=guidance_scale,
+            output_format=output_format,
+            output_quality=output_quality,
+            negative_prompt=negative_prompt,
+            frame_images=frame_images,
+            reference_images=reference_images,
+            metadata=metadata,
+            **kwargs,
+        ).model_dump(exclude_none=True)
+
+        response, _, _ = await requestor.arequest(
+            options=TogetherRequest(
+                method="POST",
+                url="../v2/videos",
+                params=parameter_payload,
+            ),
+            stream=False,
+        )
+
+        assert isinstance(response, TogetherResponse)
+
+        return VideoGenerateResponse(**response.data)
+
+    async def status(
+        self,
+        *,
+        id: str,
+    ) -> VideoStatusResponse:
+        """
+        Async method to check the status of a video generation job.
+
+        Args:
+            id (str): The ID of the video generation job to check.
+
+        Returns:
+            VideoStatusResponse: Object containing the current status and details of the video generation job
+        """
+
+        requestor = api_requestor.APIRequestor(
+            client=self._client,
+        )
+
+        response, _, _ = await requestor.arequest(
+            options=TogetherRequest(
+                method="GET",
+                url=f"../v2/videos/status?id={id}",
+            ),
+            stream=False,
+        )
+
+        assert isinstance(response, TogetherResponse)
+
+        return VideoStatusResponse(**response.data)
diff --git a/src/together/types/__init__.py b/src/together/types/__init__.py
@@ -75,6 +75,13 @@
     EvaluationJob,
     EvaluationStatusResponse,
 )
+from together.types.videos import (
+    VideoRequest,
+    VideoInputs,
+    VideoOutputs,
+    VideoGenerateResponse,
+    VideoStatusResponse,
+)
 
 
 __all__ = [
@@ -152,4 +159,9 @@
     "EvaluationCreateResponse",
     "EvaluationJob",
     "EvaluationStatusResponse",
+    "VideoRequest",
+    "VideoInputs",
+    "VideoOutputs",
+    "VideoGenerateResponse",
+    "VideoStatusResponse",
 ]
diff --git a/src/together/types/videos.py b/src/together/types/videos.py
