bytedance

ByteDance (ModelArk) video generation provider for the Robota SDK. BytedanceProvider implements the IVideoGenerationProvider contract from @robota-sdk/agent-core: it creates a video generation task, reads its status, and cancels it, over a small built-in HTTP client (fetch, no vendor SDK). It is a media provider, not a chat provider, so it is used directly rather than passed to a ConversationAgent agent's aiProviders.

Installation

npm install @robota-sdk/agent-provider @robota-sdk/agent-core

Usage

import { BytedanceProvider } from '@robota-sdk/agent-provider/bytedance';
 
const provider = new BytedanceProvider({
  apiKey: process.env.SEEDANCE_API_KEY ?? '',
  baseUrl: process.env.SEEDANCE_BASE_URL ?? '', // your ModelArk API base URL
});
 
const created = await provider.createVideo({
  model: 'seedance-2.0',
  prompt: 'A paper boat drifting down a rainy street',
});
if (!created.ok) throw new Error(created.error.message);
 
const snapshot = await provider.getVideoJob(created.value.jobId);
if (snapshot.ok && snapshot.value.status === 'succeeded') {
  console.log(snapshot.value.output?.uri);
}
 
// Stop a job that is still running.
await provider.cancelVideoJob(created.value.jobId);

The provider has three methods: createVideo(request) starts a task, getVideoJob(jobId) reads its current state, and cancelVideoJob(jobId) cancels it. getVideoJob and cancelVideoJob both return a job snapshot whose status is normalized to queued, running, succeeded, failed or cancelled. A failed snapshot carries the vendor's error message in error when the API sends one.

durationSeconds and aspectRatio are forwarded as the task's duration and ratio. A request may include inputImages (inline base64 or URI); they are sent to the task as image content alongside the prompt. A request with seed is rejected as invalid.

Options

new BytedanceProvider(options: IBytedanceProviderOptions).

Option	Type	Description
`apiKey`	`string`	Sent as `Authorization: Bearer <apiKey>` (required).
`baseUrl`	`string`	API base URL that task paths are appended to (required).
`createVideoPath`	`string`	Task creation path (default `/contents/generations/tasks`).
`getVideoTaskPathTemplate`	`string`	Task lookup path; `{taskId}` is replaced (default `/contents/generations/tasks/{taskId}`).
`cancelVideoTaskPathTemplate`	`string`	Task cancellation path; `{taskId}` is replaced (default `/contents/generations/tasks/{taskId}`).
`cancelVideoTaskMethod`	`'POST' \| 'DELETE'`	HTTP method for cancellation (default `'DELETE'`).
`timeoutMs`	`number`	Per-request timeout in milliseconds (default `60000`).
`defaultHeaders`	`Record<string, string>`	Extra headers added to every request.

Errors

Every method returns a result object ({ ok: true, value } or { ok: false, error }) instead of throwing. error.code is normalized, and error.status holds the HTTP status when the failure was an HTTP response:

`code`	When
`PROVIDER_INVALID_REQUEST`	The request fails a local check (empty prompt, model, job id or input image; `seed` set), or the API answers with another 4xx status.
`PROVIDER_AUTH_ERROR`	HTTP 401 or 403.
`PROVIDER_JOB_NOT_FOUND`	HTTP 404.
`PROVIDER_JOB_NOT_CANCELLABLE`	HTTP 409: the job's current state does not allow cancellation.
`PROVIDER_RATE_LIMITED`	HTTP 429.
`PROVIDER_TIMEOUT`	No response within `timeoutMs`.
`PROVIDER_UPSTREAM_ERROR`	HTTP 5xx, a network failure, or a response the provider cannot read (not JSON, no task id, an unknown status).

@robota-sdk/agent-core: the IVideoGenerationProvider contract and the media result types.
@robota-sdk/agent-provider/builtin: the default media provider definitions, including a Seedance video definition built on this provider.
@robota-sdk/agent-provider/gemini: image generation through Gemini.

See docs/SPEC.md for the package contract.

License

This package is dual-licensed under the GNU AGPL-3.0 or a commercial license. See LICENSING.md.