Media

Media

toothfairyai@latest…

Manager for media operations: voices, audio, image and video generation.

Example:

>>> client = ToothFairyClient(api_key="...", workspace_id="...")
>>> voices = client.media.list_voices()
>>> result = client.media.generate_audio("Hello world")
>>> print(result.contents[0])

Accessed via client.media.

Methods

Method	HTTP	Endpoint
list_voices	GET	GET /media/voices
get_voice	GET	GET /media/voices/{voice_id}
clone_voice	POST	POST /media/voices/clone
delete_voice	DELETE	DELETE /media/voices/{voice_id}
generate_audio	POST	POST /media/audio_generation
get_audio_task	GET	GET /media/audio_generation/{task_id}
generate_image	POST	POST /media/image_generation
get_image_task	GET	GET /media/image/{task_id}
generate_video	POST	POST /media/video_generation
get_video_task	GET	GET /media/video_generation/{task_id}

list_voices

List available TTS voices.

def list_voices() -> List[Voice]

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

client.media.list_voices()

get_voice

Get details of a specific voice.

def get_voice(voice_id: str) -> Voice

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

Response fields

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

Example

client.media.get_voice(voice_id="agent-id")

clone_voice

Clone a custom voice from a reference clip.

def clone_voice(
    name: str,
    clip: Union[str, bytes],
    language: str = 'en',
    description: Optional[str] = None
) -> ClonedVoice

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

client.media.clone_voice(name="…", clip="…")

delete_voice

Delete a custom voice.

def delete_voice(voice_id: str) -> Dict[str, bool]

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

Example

client.media.delete_voice(voice_id="agent-id")

generate_audio

Generate speech audio from text.

def generate_audio(
    text: str,
    speech_mode: Optional[MediaSpeechMode] = None,
    tts_model: Optional[MediaTtsModel] = None,
    tts_voice: Optional[str] = None,
    voice_type: Optional[MediaVoiceType] = None,
    language: Optional[str] = None,
    chat_id: Optional[str] = None,
    agent_id: Optional[str] = None,
    last_message_id: Optional[str] = None,
    async_: bool = False
) -> Union[MediaGenerationResult, MediaTask]

Endpoint: POST /media/audio_generation · API service

Request fields

No fields.

Always pass snake_case keyword arguments — the Python kwarg column shows the exact name to use for each wire field (as a named parameter where it appears in the method signature, otherwise via **kwargs). The SDK converts it deterministically to the camelCase wire key the API expects. Passing camelCase directly is deprecated: it emits a warning and converts to the same wire key.

Response fields

No fields.

Example

client.media.generate_audio(text="…")

get_audio_task

Get the status of an asynchronous audio generation task.

def get_audio_task(task_id: str) -> MediaTask

Endpoint: GET /media/audio_generation/{task_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

client.media.get_audio_task(task_id="agent-id")

generate_image

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

def generate_image(
    prompt: str,
    model: MediaImageModel = 'mystica_sd',
    num_outputs: int = 4,
    base_image: Optional[str] = None,
    aspect: Optional[MediaAspect] = None,
    prompt_influence: Optional[float] = None,
    chat_id: Optional[str] = None,
    last_message_id: Optional[str] = None,
    async_: bool = False
) -> Union[MediaGenerationResult, MediaTask]

Endpoint: POST /media/image_generation · Media service

Request fields

Python kwarg	Wire field	Type	Required	Description
workspace_id	workspaceid	string	yes	Workspace identifier used for authentication and consumption tracking.
prompt	prompt	string	yes	What to generate. With base_image set, describes the edit/evolution to apply.
model	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 | num_outputs | integer | no | Number of image variations to generate. | | base_image | base_image | string | no | Optional source image (workspace S3 key or import key) for image-to-image editing and restyling. | | aspect | 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 | 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 | chatid | string | no | Optional chat context for attribution. | | last_message_id | lastMessageId | string | no | Optional message id to attribute the generation to. | | async | async | boolean | no | When true, the request returns 202 with a taskId; poll GET /media/image/{taskId}. |

Always pass snake_case keyword arguments — the Python kwarg column shows the exact name to use for each wire field (as a named parameter where it appears in the method signature, otherwise via **kwargs). The SDK converts it deterministically to the camelCase wire key the API expects. Passing camelCase directly is deprecated: it emits a warning and converts to the same wire key.

Response

Returns the AudioGenerationResponse object — fields documented in the generate-audio section above.

Example

client.media.generate_image(prompt="…")

get_image_task

Get the status of an asynchronous image generation task.

def get_image_task(task_id: str) -> MediaTask

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

Response

Returns the TaskStatusResponse object — fields documented in the get-audio-task section above.

Example

client.media.get_image_task(task_id="agent-id")

generate_video

Generate video from text or animate a still frame.

def generate_video(
    prompt: str,
    model: MediaVideoModel = 'sorcerer_motion',
    num_outputs: int = 1,
    base_image: Optional[str] = None,
    aspect: Optional[MediaAspect] = None,
    length: Optional[int] = None,
    prompt_influence: Optional[float] = None,
    loop: bool = False,
    chat_id: Optional[str] = None,
    last_message_id: Optional[str] = None,
    async_: bool = False
) -> Union[MediaGenerationResult, MediaTask]

Endpoint: POST /media/video_generation · Media service

Request fields

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

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

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

Always pass snake_case keyword arguments — the Python kwarg column shows the exact name to use for each wire field (as a named parameter where it appears in the method signature, otherwise via **kwargs). The SDK converts it deterministically to the camelCase wire key the API expects. Passing camelCase directly is deprecated: it emits a warning and converts to the same wire key.

Response

Returns the AudioGenerationResponse object — fields documented in the generate-audio section above.

Example

client.media.generate_video(prompt="…")

get_video_task

Get the status of an asynchronous video generation task.

def get_video_task(task_id: str) -> MediaTask

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

Response

Returns the TaskStatusResponse object — fields documented in the get-audio-task section above.

Example

client.media.get_video_task(task_id="agent-id")