Conversions

The unified API for all audio generation. Submit a changelog or any text document and get back polished audio.

Create a conversion

POST/conversions

Create a conversion

Parameters

Parameter	Type	Required	Description
`Idempotency-Key`	string	Optional	Unique key for idempotent requests. Keys must be 1-256 printable ASCII characters. If the same key is sent within 24 hours, the cached response is returned.
`X-Organization-ID`	string	Optional	Specify organization context for multi-org users. If omitted, uses default org for API key.

Request Body

Parameter	Type	Required	Description
`source_type`	string changelogdocument	Required	Type of content being converted
`title`	string	Required	Title for this conversion
`content`	string	Required	Content to convert (max 50KB)
`additional_context`	string	Optional	Additional context for the AI script generator (max 10KB)
`product_id`	string	Optional	Associate with a specific product
`ignore_org`	boolean	Optional	Skip organization-level context for this conversion
`public_url`	boolean	Optional(default: `false`)	If true, creates publicly shareable listen and embed URLs
`webhook_url`	string	Optional	HTTPS URL to receive completion webhook notification
`wait`	boolean	Optional(default: `false`)	Block until completion (returns 200 instead of 202). Maximum wait is 90 seconds.
`voice`	object	Optional	TTS voice configuration. Applies to ElevenLabs when provider is "elevenlabs".
`settings`	object	Optional	Script generation and audio settings for conversions

voice

Parameter	Type	Required	Description
`provider`	string geminielevenlabs	Optional(default: `gemini`)	Text-to-speech provider
`delivery_preset`	string measureddynamictheatrical	Optional	Controls the pacing and energy of the narration
`expression_settings.emotional_range`	string subtlemoderatefull	Optional
`expression_settings.allow_whispering`	boolean	Optional
`expression_settings.allow_laughter`	boolean	Optional
`expression_settings.emphasis_style`	string pausesboth	Optional
`expression_settings.emotional_arc`	boolean	Optional
`pronunciation_notes`	string	Optional	Pronunciation guidance for product names, acronyms, etc.
`voice_id`	string	Optional	ElevenLabs voice ID for single-speaker mode
`model`	string v3flash_v2	Optional	ElevenLabs model to use
`host_voice_ids.host1`	string	Optional	ElevenLabs voice ID for host 1
`host_voice_ids.host2`	string	Optional	ElevenLabs voice ID for host 2

settings

Parameter	Type	Required	Description
`product_name`	string	Optional	Product or company name to use in the script
`version`	string	Optional	Version number to emphasize
`tone`	string casualprofessionalenthusiastictechnical	Optional(default: `casual`)	Voice tone for the script
`audience`	string	Optional	Target audience description
`verbosity`	string briefnormaldetailed	Optional(default: `normal`)	Script length preference
`cta`	string	Optional	Optional call-to-action to include at the end
`severity_aware_tone`	boolean	Optional	Adjust tone based on severity of changes (e.g. more serious for breaking changes)
`summary_threshold`	integer	Optional	Minimum number of changes before switching to summary mode
`use_history`	boolean	Optional(default: `true`)	Whether to include previous changelogs as context
`history_limit`	integer	Optional(default: `10`)	Number of previous changelogs to include as context
`speakers`	integer 12	Optional(default: `1`)	Number of speakers (1 = single narrator, 2 = dialogue)

Body

{
  "source_type": "changelog",
  "title": "MyApp v2.0.0 Release",
  "content": "## v2.0.0 - New Features\n- Added dark mode support\n- Improved performance by 40%",
  "additional_context": "This release focuses on performance improvements after customer feedback.",
  "settings": {
    "product_name": "MyApp",
    "version": "2.0.0",
    "tone": "casual"
  },
  "use_history": true,
  "history_limit": 5,
  "public_url": true
}

List conversions

GET/conversions

List conversions

Parameters

Parameter	Type	Required	Description
`X-Organization-ID`	string	Optional	Specify organization context for multi-org users. If omitted, uses default org for API key.
`source_type`	string changelogdocument	Optional	Filter by source type
`status`	string pendingprocessinggeneratingcompletedfailed	Optional	Filter by conversion status
`limit`	integer	Optional(default: `20`)	Maximum number of results to return
`cursor`	string	Optional	Pagination cursor from previous response

curl -X GET https://logtalk.io/api/v1/conversions \
  -H "Authorization: Bearer lt_live_your_api_key_here" \
  -H "Content-Type: application/json"

Get conversion details

GET/conversions/{id}

Get conversion details

Parameters

Parameter	Type	Required	Description
`id`	string	Required	Conversion UUID
`X-Organization-ID`	string	Optional	Specify organization context for multi-org users. If omitted, uses default org for API key.

curl -X GET https://logtalk.io/api/v1/conversions/{id} \
  -H "Authorization: Bearer lt_live_your_api_key_here" \
  -H "Content-Type: application/json"

Update a conversion

PATCH/conversions/{id}

Update a conversion

Parameters

Parameter	Type	Required	Description
`id`	string	Required	Conversion UUID
`X-Organization-ID`	string	Optional	Specify organization context for multi-org users. If omitted, uses default org for API key.

Request Body

Parameter	Type	Required	Description
`public_url`	boolean	Optional	Enable or disable public listen/embed URLs
`title`	string	Optional	Update the conversion title
`additional_context`	string	Optional	Update the additional context

Body

{
  "public_url": true
}

Retry a failed conversion

POST/conversions/{id}/retry

Retry a failed conversion

Parameters

Parameter	Type	Required	Description
`id`	string	Required	Conversion UUID
`X-Organization-ID`	string	Optional	Specify organization context for multi-org users. If omitted, uses default org for API key.

curl -X POST https://logtalk.io/api/v1/conversions/{id}/retry \
  -H "Authorization: Bearer lt_live_your_api_key_here" \
  -H "Content-Type: application/json"

Get signed audio URL

GET/conversions/{id}/audio

Get signed audio URL

Parameters

Parameter	Type	Required	Description
`id`	string	Required	Conversion UUID
`X-Organization-ID`	string	Optional	Specify organization context for multi-org users. If omitted, uses default org for API key.

curl -X GET https://logtalk.io/api/v1/conversions/{id}/audio \
  -H "Authorization: Bearer lt_live_your_api_key_here" \
  -H "Content-Type: application/json"

Delete a conversion

DELETE/conversions/{id}

Delete a conversion

Parameters

Parameter	Type	Required	Description
`id`	string	Required	Conversion UUID
`X-Organization-ID`	string	Optional	Specify organization context for multi-org users. If omitted, uses default org for API key.

curl -X DELETE https://logtalk.io/api/v1/conversions/{id} \
  -H "Authorization: Bearer lt_live_your_api_key_here" \
  -H "Content-Type: application/json"

Embed Tokens

Embed tokens allow you to embed an audio player on external sites without making the conversion fully public. Each token is scoped to a single conversion and does not expire.

Rate limit: 100 tokens per organization per day. Requires paid tier.

Create an embed token

POST/conversions/{id}/embed-token

Create an embed token

Parameters

Parameter	Type	Required	Description
`id`	string	Required	Conversion UUID
`X-Organization-ID`	string	Optional	Specify organization context for multi-org users. If omitted, uses default org for API key.

curl -X POST https://logtalk.io/api/v1/conversions/{id}/embed-token \
  -H "Authorization: Bearer lt_live_your_api_key_here" \
  -H "Content-Type: application/json"

List embed tokens

GET/conversions/{id}/embed-token

List embed tokens

Parameters

Parameter	Type	Required	Description
`id`	string	Required	Conversion UUID
`X-Organization-ID`	string	Optional	Specify organization context for multi-org users. If omitted, uses default org for API key.

curl -X GET https://logtalk.io/api/v1/conversions/{id}/embed-token \
  -H "Authorization: Bearer lt_live_your_api_key_here" \
  -H "Content-Type: application/json"

Revoke an embed token

DELETE/conversions/{id}/embed-token/{token}

Revoke an embed token

Parameters

Parameter	Type	Required	Description
`id`	string	Required	Conversion UUID
`token`	string	Required	The embed token to revoke
`X-Organization-ID`	string	Optional	Specify organization context for multi-org users. If omitted, uses default org for API key.

curl -X DELETE https://logtalk.io/api/v1/conversions/{id}/embed-token/{token} \
  -H "Authorization: Bearer lt_live_your_api_key_here" \
  -H "Content-Type: application/json"

Polling for Completion

After creating a conversion, poll GET /v1/conversions/{id} until status is completed or failed:

const API_KEY = process.env.LOGTALK_API_KEY;
const BASE = 'https://logtalk.io/api/v1';

// 1. Create conversion
const { data } = await fetch(`${BASE}/conversions`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    source_type: 'changelog',
    title: 'MyApp v2.0.0',
    content: changelogMarkdown,
    settings: { product_name: 'MyApp' }
  })
}).then(r => r.json());

// 2. Poll until complete (max 2 minutes)
let conversion;
const maxAttempts = 40;
for (let i = 0; i < maxAttempts; i++) {
  await new Promise(r => setTimeout(r, 3000));
  const res = await fetch(`${BASE}/conversions/${data.id}`, {
    headers: { Authorization: `Bearer ${API_KEY}` }
  }).then(r => r.json());

  conversion = res.data;
  if (conversion.status === 'completed') break;
  if (conversion.status === 'failed') throw new Error('Conversion failed');
}
if (conversion.status !== 'completed') throw new Error('Polling timed out');

console.log('Audio URL:', conversion.audio_url);

Tip: Use "wait": true on the create request to skip polling entirely — the API blocks until completion and returns the full result.

Set public_url: true when creating a conversion (or via PATCH) to generate public share and embed URLs:

Field	Description
`listen_url`	Full public page with audio player, show notes, and share buttons.
`embed_url`	Compact player for iframe embedding on external sites.

<iframe
  src="https://logtalk.io/embed/550e8400-e29b-41d4-a716-446655440000"
  width="100%"
  height="180"
  frameborder="0"
  allow="autoplay"
></iframe>

Idempotency

Include the Idempotency-Key header on POST requests to prevent duplicate conversions on retries:

curl -X POST https://logtalk.io/api/v1/conversions \
  -H "Authorization: Bearer lt_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: release-v2.0.0-20260118" \
  -d '{"source_type": "changelog", "title": "...", "content": "..."}'

Keys must be 1-256 printable ASCII characters
Keys are valid for 24 hours
Same key + same body returns the cached response
Same key + different body returns 409 Conflict

PreviousAuthentication NextEpisodes (Deprecated)

Create a conversion

Parameters

Request Body

voice

settings

Body

List conversions

Parameters

Get conversion details

Parameters

Update a conversion

Parameters

Request Body

Body

Retry a failed conversion

Parameters

Get signed audio URL

Parameters

Delete a conversion

Parameters

Embed Tokens

Create an embed token

Parameters

List embed tokens

Parameters

Revoke an embed token

Parameters

Polling for Completion

Public Sharing & Embedding

Idempotency