Media

Media

@toothfairyai/sdk@latest…

Media Management Module Voice management (list, get, clone, delete), audio generation (text-to-speech), image generation and video generation.

Accessed via client.media.

Methods

Method	HTTP	Endpoint
listVoices	GET	GET /media/voices
getVoice	GET	GET /media/voices/{id}
cloneVoice	POST	POST /media/voices/clone
deleteVoice	DELETE	DELETE /media/voices/{id}
generateAudio	POST	POST /media/audio_generation
getAudioTask	GET	GET /media/audio_generation/{id}
generateImage	POST	POST /media/image_generation
getImageTask	GET	GET /media/image/{id}
generateVideo	POST	POST /media/video_generation
getVideoTask	GET	GET /media/video_generation/{id}

listVoices

List available TTS voices Includes built-in voices and custom voices cloned by the workspace (is_custom=true).

async listVoices()

Endpoint: GET /media/voices · Media service

Response fields

Field	Type	Description
contents	array<object>	Available voices. Custom voices cloned by the workspace carry is_custom: true.
workspaceid	string	Workspace the voices belong to.

Example

const result = await client.media.listVoices();

getVoice

Get details of a specific voice

async getVoice(voiceId: string)

Endpoint: GET /media/voices/{id} · Media service

Response fields

Field	Type	Description
contents	object	The requested voice details.
workspaceid	string	Workspace the voice belongs to.

Example

const result = await client.media.getVoice('agent-id');

cloneVoice

Clone a custom voice from a reference clip The returned voice_id is a workspace-level custom voice: store it in an agent's voiceName (with ttsModel='cartesia') to use it as the agent's live voice, or in audiosGenerationVoiceName for voice-overs.

async cloneVoice(
    name: string,
    clip: string | Buffer,
    options: { language?: string; description?: string } = {}
)

Endpoint: POST /media/voices/clone · Media service

Response fields

Field	Type	Description
contents	object	The newly cloned voice. Attach voice_id to an agent's voice setting (with tts_model: "cartesia") or pass it as tts_voice on /media/audio_generation.
workspaceid	string	Workspace the cloned voice belongs to.

Example

const result = await client.media.cloneVoice('…', '…');

deleteVoice

Delete a custom voice

async deleteVoice(voiceId: string): Promise<

Endpoint: DELETE /media/voices/{id} · Media service

Example

const result = await client.media.deleteVoice('agent-id');

generateAudio

Generate speech audio from text Markdown is accepted — internal sections, code fences, tables and image syntax are stripped automatically.

async generateAudio(data: AudioGenerationData)

Endpoint: POST /media/audio_generation · API service

Request fields

No fields.

Response fields

No fields.

Example

const result = await client.media.generateAudio(…);

getAudioTask

Get the status of an asynchronous audio generation task

async getAudioTask(taskId: string)

Endpoint: GET /media/audio_generation/{id} · Media service

Response fields

Field	Type	Description
taskId	string	The asynchronous task identifier (echoed back).
status	string	completed populates keys/contents; failed populates error.

Allowed: pending, running, completed, failed | | keys | array<string> | Present when status is completed. | | contents | array<string> | Presigned download URLs, present when status is completed. | | error | string | Present when status is failed. | | workspaceid | string | Workspace the task belongs to. |

Example

const result = await client.media.getAudioTask('agent-id');

generateImage

Generate images from text (or image-to-image with base_image)

async generateImage(data: ImageGenerationData)

Endpoint: POST /media/image_generation · Media service

Request fields

Field	Type	Required	Description
workspaceid	string	yes	Workspace identifier used for authentication and consumption tracking.
prompt	string	yes	What to generate. With base_image set, describes the edit/evolution to apply.
model	string	no	Image model. mystica_sd (Google Nano Banana 2) is the balanced default; mystica_realism_sd (GPT Image 2) for photorealism; sorcerer_canvas (Nano Banana Pro) for large canvas editing; sorcerer_vision/mystica_vision (Seedream 4/4.5) for high-fidelity renders.

Allowed: mystica_sd, mystica_realism_sd, sorcerer_canvas, sorcerer_vision, mystica_vision | | num_outputs | integer | no | Number of image variations to generate. | | base_image | string | no | Optional source image (workspace S3 key or import key) for image-to-image editing and restyling. | | aspect | string | no | Output aspect ratio. When omitted, the model default is used.

Allowed: 1:1, 16:9, 9:16, 4:3, 3:4 | | prompt_influence | number | no | How strictly the model follows the prompt vs the base image (image-to-image); higher values follow the prompt more closely. | | chatid | string | no | Optional chat context for attribution. | | lastMessageId | string | no | Optional message id to attribute the generation to. | | async | boolean | no | When true, the request returns 202 with a taskId; poll GET /media/image/{taskId}. |

Response

Returns the AudioGenerationResponse object — fields documented in the generateAudio section above.

Example

const result = await client.media.generateImage(…);

getImageTask

Get the status of an asynchronous image generation task

async getImageTask(taskId: string)

Endpoint: GET /media/image/{id} · Media service

Response

Returns the TaskStatusResponse object — fields documented in the getAudioTask section above.

Example

const result = await client.media.getImageTask('agent-id');

generateVideo

Generate video from text or animate a still frame (base_image)

async generateVideo(data: VideoGenerationData)

Endpoint: POST /media/video_generation · Media service

Request fields

Field	Type	Required	Description
workspaceid	string	yes	Workspace identifier used for authentication and consumption tracking.
prompt	string	yes	Motion/scene description. With base_image set, describes the camera move and animation to apply to the still.
model	string	no	Video model — sorcerer_motion (Kling v3).

Allowed: sorcerer_motion | | num_outputs | integer | no | Number of video variations to generate. | | base_image | string | no | Optional still frame (workspace S3 key or import key) to animate into a video. | | aspect | string | no | Output aspect ratio.

Allowed: 1:1, 16:9, 9:16, 4:3, 3:4 | | length | integer | no | Clip duration in seconds, capped by the model's maximum (up to 10s). | | prompt_influence | number | no | How strictly the model follows the prompt vs the base image. | | loop | boolean | no | When true, the clip loops seamlessly. | | chatid | string | no | Optional chat context for attribution. | | lastMessageId | string | no | Optional message id to attribute the generation to. | | async | boolean | no | When true, the request returns 202 with a taskId; poll GET /media/video_generation/{taskId}. |

Response

Returns the AudioGenerationResponse object — fields documented in the generateAudio section above.

Example

const result = await client.media.generateVideo(…);

getVideoTask

Get the status of an asynchronous video generation task

async getVideoTask(taskId: string)

Endpoint: GET /media/video_generation/{id} · Media service

Response

Returns the TaskStatusResponse object — fields documented in the getAudioTask section above.

Example

const result = await client.media.getVideoTask('agent-id');