feat(api): Add Video APIs

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 39
+configured_endpoints: 41
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/togetherai%2Ftogetherai-dc94b2b06f27f9d2031307115c3aa9db86a430741037ffd6baaf12304c747f02.yml
 openapi_spec_hash: 4ad476ccff245fe0460d730bc6e44d60
-config_hash: e2d1be538fd1fb65bfc566a2a168cc16
+config_hash: 5c3a2f90c5f665091f9de844810eb099

MIGRATION.md

@@ -133,16 +133,16 @@ If you were relying on anything that was only exported from `together-ai/core` a
 
 #### Resource classes
 
-Previously under certain circumstances it was possible to import resource classes like `Chat` directly from the root of the package. This was never valid at the type level and only worked in CommonJS files.
+Previously under certain circumstances it was possible to import resource classes like `Videos` directly from the root of the package. This was never valid at the type level and only worked in CommonJS files.
 Now you must always either reference them as static class properties or import them directly from the files in which they are defined.
 
 ```typescript
 // Before
-const { Chat } = require('together-ai');
+const { Videos } = require('together-ai');
 
 // After
 const { Together } = require('together-ai');
-Together.Chat; // or import directly from together-ai/resources/chat/chat
+Together.Videos; // or import directly from together-ai/resources/videos
 ```
 
 #### Cleaned up `uploads` exports

api.md

@@ -8,6 +8,18 @@ Methods:
 
 - <code title="post /rerank">client.<a href="./src/index.ts">rerank</a>({ ...params }) -> RerankResponse</code>
 
+# Videos
+
+Types:
+
+- <code><a href="./src/resources/videos.ts">VideoCreateResponse</a></code>
+- <code><a href="./src/resources/videos.ts">VideoRetrieveResponse</a></code>
+
+Methods:
+
+- <code title="post /videos">client.videos.<a href="./src/resources/videos.ts">create</a>({ ...params }) -> VideoCreateResponse</code>
+- <code title="get /videos/{id}">client.videos.<a href="./src/resources/videos.ts">retrieve</a>(id) -> VideoRetrieveResponse</code>
+
 # Chat
 
 ## Completions

src/client.ts

@@ -96,6 +96,7 @@ import { Hardware, HardwareListParams, HardwareListResponse } from './resources/
 import { ImageCreateParams, ImageDataB64, ImageDataURL, ImageFile, Images } from './resources/images';
 import { JobListResponse, JobRetrieveResponse, Jobs } from './resources/jobs';
 import { ModelListResponse, ModelUploadParams, ModelUploadResponse, Models } from './resources/models';
+import { VideoCreateParams, VideoCreateResponse, VideoRetrieveResponse, Videos } from './resources/videos';
 import {
   Audio,
   AudioCreateParams,
@@ -828,6 +829,7 @@ export class Together {
 
   static toFile = Uploads.toFile;
 
+  videos: API.Videos = new API.Videos(this);
   chat: API.Chat = new API.Chat(this);
   completions: API.Completions = new API.Completions(this);
   embeddings: API.Embeddings = new API.Embeddings(this);
@@ -845,6 +847,7 @@ export class Together {
   evaluations: API.Evaluations = new API.Evaluations(this);
 }
 
+Together.Videos = Videos;
 Together.Chat = Chat;
 Together.Completions = Completions;
 Together.Embeddings = Embeddings;
@@ -866,6 +869,13 @@ export declare namespace Together {
 
   export { type RerankResponse as RerankResponse, type RerankParams as RerankParams };
 
+  export {
+    Videos as Videos,
+    type VideoCreateResponse as VideoCreateResponse,
+    type VideoRetrieveResponse as VideoRetrieveResponse,
+    type VideoCreateParams as VideoCreateParams,
+  };
+
   export { Chat as Chat };
 
   export {

src/resources/index.ts

@@ -98,4 +98,10 @@ export {
 } from './images';
 export { Jobs, type JobRetrieveResponse, type JobListResponse } from './jobs';
 export { Models, type ModelListResponse, type ModelUploadResponse, type ModelUploadParams } from './models';
+export {
+  Videos,
+  type VideoCreateResponse,
+  type VideoRetrieveResponse,
+  type VideoCreateParams,
+} from './videos';
 export { type RerankResponse, type RerankParams } from './top-level';

src/resources/videos.ts

@@ -0,0 +1,222 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Videos extends APIResource {
+  /**
+   * Create a video
+   *
+   * @example
+   * ```ts
+   * const video = await client.videos.create({
+   *   model: 'model',
+   * });
+   * ```
+   */
+  create(body: VideoCreateParams, options?: RequestOptions): APIPromise<VideoCreateResponse> {
+    return this._client.post('/videos', { body, defaultBaseURL: 'https://api.together.xyz/v2', ...options });
+  }
+
+  /**
+   * Fetch video metadata
+   *
+   * @example
+   * ```ts
+   * const video = await client.videos.retrieve('id');
+   * ```
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<VideoRetrieveResponse> {
+    return this._client.get(path`/videos/${id}`, {
+      defaultBaseURL: 'https://api.together.xyz/v2',
+      ...options,
+    });
+  }
+}
+
+export interface VideoCreateResponse {
+  /**
+   * Unique identifier for the video job.
+   */
+  id?: string;
+}
+
+/**
+ * Structured information describing a generated video job.
+ */
+export interface VideoRetrieveResponse {
+  /**
+   * Unique identifier for the video job.
+   */
+  id: string;
+
+  /**
+   * Unix timestamp (seconds) for when the job was created.
+   */
+  created_at: number;
+
+  /**
+   * The video generation model that produced the job.
+   */
+  model: string;
+
+  /**
+   * Duration of the generated clip in seconds.
+   */
+  seconds: string;
+
+  /**
+   * The resolution of the generated video.
+   */
+  size: string;
+
+  /**
+   * Current lifecycle status of the video job.
+   */
+  status: 'in_progress' | 'completed' | 'failed';
+
+  /**
+   * Unix timestamp (seconds) for when the job completed, if finished.
+   */
+  completed_at?: number;
+
+  /**
+   * Error payload that explains why generation failed, if applicable.
+   */
+  error?: VideoRetrieveResponse.Error;
+
+  /**
+   * The object type, which is always video.
+   */
+  object?: 'video';
+
+  /**
+   * Available upon completion, the outputs provides the cost charged and the hosted
+   * url to access the video
+   */
+  outputs?: VideoRetrieveResponse.Outputs;
+}
+
+export namespace VideoRetrieveResponse {
+  /**
+   * Error payload that explains why generation failed, if applicable.
+   */
+  export interface Error {
+    message: string;
+
+    code?: string;
+  }
+
+  /**
+   * Available upon completion, the outputs provides the cost charged and the hosted
+   * url to access the video
+   */
+  export interface Outputs {
+    /**
+     * The cost of generated video charged to the owners account.
+     */
+    cost: number;
+
+    /**
+     * URL hosting the generated video
+     */
+    video_url: string;
+  }
+}
+
+export interface VideoCreateParams {
+  /**
+   * The model to be used for the video creation request.
+   */
+  model: string;
+
+  /**
+   * Frames per second. Defaults to 24.
+   */
+  fps?: number;
+
+  /**
+   * 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
+   */
+  frame_images?: Array<VideoCreateParams.FrameImage>;
+
+  /**
+   * 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. guidence_scale affects both visual content and
+   * temporal consistency.Recommended range is 6.0-10.0 for most video models. Values
+   * above 12 may cause over-guidance artifacts or unnatural motion patterns.
+   */
+  guidance_scale?: number;
+
+  height?: number;
+
+  /**
+   * Similar to prompt, but specifies what to avoid instead of what to include
+   */
+  negative_prompt?: string;
+
+  /**
+   * Specifies the format of the output video. Defaults to MP4.
+   */
+  output_format?: 'MP4' | 'WEBM';
+
+  /**
+   * Compression quality. Defaults to 20.
+   */
+  output_quality?: number;
+
+  /**
+   * Text prompt that describes the video to generate.
+   */
+  prompt?: string;
+
+  /**
+   * TODO need to figure this out
+   */
+  reference_images?: Array<unknown>;
+
+  /**
+   * Clip duration in seconds.
+   */
+  seconds?: string;
+
+  /**
+   * 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.
+   */
+  seed?: number;
+
+  /**
+   * The number of denoising steps the model performs during video generation. More
+   * steps typically result in higher quality output but require longer processing
+   * time.
+   */
+  steps?: number;
+
+  width?: number;
+}
+
+export namespace VideoCreateParams {
+  export interface FrameImage {
+    frame: number | 'first' | 'last';
+
+    /**
+     * idk
+     */
+    input_image: string;
+  }
+}
+
+export declare namespace Videos {
+  export {
+    type VideoCreateResponse as VideoCreateResponse,
+    type VideoRetrieveResponse as VideoRetrieveResponse,
+    type VideoCreateParams as VideoCreateParams,
+  };
+}

tests/api-resources/videos.test.ts

@@ -0,0 +1,51 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import Together from 'together-ai';
+
+const client = new Together({
+  apiKey: 'My API Key',
+  baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010',
+});
+
+describe('resource videos', () => {
+  test('create: only required params', async () => {
+    const responsePromise = client.videos.create({ model: 'model' });
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
+  test('create: required and optional params', async () => {
+    const response = await client.videos.create({
+      model: 'model',
+      fps: 0,
+      frame_images: [{ frame: 0, input_image: 'input_image' }],
+      guidance_scale: 0,
+      height: 0,
+      negative_prompt: 'negative_prompt',
+      output_format: 'MP4',
+      output_quality: 0,
+      prompt: 'x',
+      reference_images: [{}],
+      seconds: 'seconds',
+      seed: 0,
+      steps: 10,
+      width: 0,
+    });
+  });
+
+  test('retrieve', async () => {
+    const responsePromise = client.videos.retrieve('id');
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+});