> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.resemble.ai/libraries/python/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.resemble.ai/_mcp/server.

# Python SDK

Install the package:

```bash
pip install resemble
```

Configure the SDK:

```python
from resemble import Resemble

Resemble.api_key("YOUR_API_TOKEN")
```

## Projects

### List All Projects

```python
page = 1
page_size = 10

response = Resemble.v2.projects.all(page, page_size)
projects = response['items']
```

### Get a Project

```python
project_uuid = '<project_uuid>'

response = Resemble.v2.projects.get(project_uuid)
project = response['item']
```

### Create a Project

```python
name = 'My project'
description = 'My description'
is_archived = False
is_collaborative = False

response = Resemble.v2.projects.create(name, description, is_collaborative, is_archived)
project = response['item']
```

### Update a Project

```python
project_uuid = '<project_uuid>'
name = 'My project (archived)'
description = 'My description (this project has been archived)'
is_archived = True
is_collaborative = False

response = Resemble.v2.projects.update(project_uuid, name, description, is_collaborative, is_archived)
project = response['item']
```

### Delete a Project

```python
project_uuid = '<project_uuid>'

response = Resemble.v2.projects.delete(project_uuid)
```

## Voices

### List All Voices

```python
page = 1
page_size = 10

response = Resemble.v2.voices.all(page, page_size)
voices = response['items']
```

### Get a Voice

```python
voice_uuid = '<voice_uuid>'

response = Resemble.v2.voices.get(voice_uuid)
voice = response['item']
```

### Create a Voice

```python
name = 'Test Voice'

response = Resemble.v2.voices.create(
    name,
    dataset_url="https://example.com/dataset.zip",
    callback_uri="http://example.com/cb",
    language="en-US"
)
voice = response['item']
```

### Build a Voice

```python
voice_uuid = '<voice_uuid>'

response = Resemble.v2.voices.build(voice_uuid)
```

### Delete a Voice

```python
voice_uuid = '<voice_uuid>'

response = Resemble.v2.voices.delete(voice_uuid)
```

## Recordings

### List All Recordings

```python
voice_uuid = '<voice_uuid>'
page = 1
page_size = 10

response = Resemble.v2.recordings.all(voice_uuid, page, page_size)
recordings = response['items']
```

### Get a Recording

```python
voice_uuid = '<voice_uuid>'
recording_uuid = '<recording_uuid>'

response = Resemble.v2.recordings.get(voice_uuid, recording_uuid)
recording = response['item']
```

### Create a Recording

```python
voice_uuid = '<voice_uuid>'
name = 'recording'
text = 'This is a test'
is_active = True
emotion = 'neutral'

with open("path/to/audio.wav", 'rb') as file:
    response = Resemble.v2.recordings.create(voice_uuid, file, name, text, is_active, emotion)
    recording = response['item']
```

### Update a Recording

```python
voice_uuid = '<voice_uuid>'
recording_uuid = '<uuid>'
name = 'recording'
text = 'This is a test'
is_active = True
emotion = 'neutral'

response = Resemble.v2.recordings.update(voice_uuid, recording_uuid, name, text, is_active, emotion)
recording = response['item']
```

### Delete a Recording

```python
voice_uuid = '<voice_uuid>'
recording_uuid = '<recording_uuid>'

response = Resemble.v2.recordings.delete(voice_uuid, recording_uuid)
```

## Clips

### List All Clips

```python
project_uuid = '<project_uuid>'
page = 1
page_size = 10

response = Resemble.v2.clips.all(project_uuid, page, page_size)
clips = response['items']
```

### Get a Clip

```python
project_uuid = '<project_uuid>'
clip_uuid = '<clip_uuid>'

response = Resemble.v2.clips.get(project_uuid, clip_uuid)
clip = response['item']
```

### Create a Clip (Synchronous)

```python
response = Resemble.v2.clips.create_sync(
    project_uuid,
    voice_uuid,
    "Welcome to Resemble",
    title="Intro"
)

if response["success"]:
    clip = response["item"]
    print(clip["audio_src"])
else:
    print(response)
```

### Create a Clip (Direct Synthesis)

```python
voice_uuid = '<voice_uuid>'
project_uuid = '<project_uuid>'
output_format = 'wav'
data = 'Hello, how are you?'
title = 'Greeting'
precision = 'PCM_32'
sample_rate = 48000

response = Resemble.v2.clips.create_direct(
    project_uuid,
    voice_uuid,
    data,
    title,
    precision,
    output_format,
    sample_rate
)

clip = response['audio_content']
```

### Stream a Clip

```python
# Configure synthesis URL for streaming
Resemble.api_key('YOUR_API_TOKEN')
Resemble.syn_server_url('<syn_server_url>')  # Obtain from https://app.resemble.ai/account/api

project_uuid = '<project_uuid>'
voice_uuid = '<voice_uuid>'
body = 'This is a streaming test'

try:
    for chunk in Resemble.v2.clips.stream(project_uuid, voice_uuid, body):
        # chunk is a byte array of shorts (int 16) representing WAV audio
        # Process the audio chunk here
        pass
except Exception as e:
    # Handle exceptions
    print(f"Error: {e}")
```

### Update a Clip (Async)

```python
project_uuid = '<project_uuid>'
clip_uuid = '<clip_uuid>'
voice_uuid = '<voice_uuid>'
callback_uri = 'https://example.com/callback/resemble-clip'
body = 'This is an updated async test'

response = Resemble.v2.clips.update_async(
    project_uuid,
    clip_uuid,
    voice_uuid,
    callback_uri,
    body,
    title=None,
    sample_rate=None,
    output_format=None,
    precision=None,
    include_timestamps=None,
    is_archived=None
)
clip = response['item']
```

### Delete a Clip

```python
project_uuid = '<project_uuid>'
clip_uuid = '<clip_uuid>'

response = Resemble.v2.clips.delete(project_uuid, clip_uuid)
```

## Term Substitutions

### List All Term Substitutions

```python
page = 1
page_size = 10

response = Resemble.v2.term_substitutions.all(page, page_size)
substitutions = response['items']
```

### Create a Term Substitution

```python
response = Resemble.v2.term_substitutions.create('Original', 'Replacement')
substitutions = response['items']
```

### Delete a Term Substitution

```python
substitution_uuid = '...'

response = Resemble.v2.term_substitutions.delete(substitution_uuid)
```

## Deepfake Detection

### Create a Detection

```python
media_url = "https://example.com/sample-video.mp4"

response = Resemble.v2.deepfake_detection.detect(url=media_url)

if response["success"]:
    detection_uuid = response["item"]["uuid"]
    status = response["item"]["status"]
```

### Get a Detection Result

```python
import time

detection_uuid = "<detection_uuid>"
max_attempts = 10
wait_time_seconds = 3

for _ in range(max_attempts):
    response = Resemble.v2.deepfake_detection.get(detection_uuid)
    status = response.get("item", {}).get("status")

    if status in ("completed", "failed"):
        break

    time.sleep(wait_time_seconds)
```

### Create and Get a Detection (URL)

```python
import json

media_url = "https://example.com/sample-audio.wav"

response = Resemble.v2.deepfake_detection.detect_and_get(
    url=media_url,
    audio_source_tracing=True,
    intelligence=True,
    use_ood_detector=True,
)

# Full API response
print(json.dumps(response, indent=2))

# Parsed values
result = response.get("item", {})
status = response.get("item", {}).get("status")
```

### Create and Get a Detection (File Upload)

```python
import json

file_path = "path/to/local-audio.wav"

with open(file_path, "rb") as file:
    response = Resemble.v2.deepfake_detection.detect_and_get(
        file=file,
        audio_source_tracing=True,
        intelligence=True,
        use_ood_detector=True,
    )

# Full API response
print(json.dumps(response, indent=2))

# Parsed values
result = response.get("item", {})
status = response.get("item", {}).get("status")
```

## Additional Resources

* [Creating Clips Guide](/guides/creating-clips/getting-started) - Step-by-step tutorial
* [WebSocket Streaming Guide](/guides/creating-clips/websocket-streaming/getting-started) - Real-time audio streaming
* [GitHub Examples](https://github.com/resemble-ai/resemble-examples) - Sample code and projects