DocTalk API

Deprecated

These endpoints are deprecated thin wrappers around the Conversions API. They continue to work but will be removed in a future version.

Deprecated. Use POST /conversions with source_type: "document" instead. The DocTalk endpoints are maintained for backward compatibility and will be removed in a future version. New integrations should use the Conversions API.

Quick Start

Submit text, poll for completion, download the audio:

# 1. Submit content for conversion
RESPONSE=$(curl -s -X POST https://logtalk.io/api/v1/doctalk/convert \
  -H "Authorization: Bearer $LOGTALK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Your text content here...",
    "content_description": "Article",
    "settings": {
      "tone": "casual",
      "verbosity": "normal",
      "speakers": 1
    }
  }')

# Extract the conversion ID
ID=$(echo $RESPONSE | jq -r '.data.id')
echo "Conversion ID: $ID"

# 2. Poll until complete
while true; do
  STATUS=$(curl -s https://logtalk.io/api/v1/doctalk/convert/$ID \
    -H "Authorization: Bearer $LOGTALK_API_KEY" \
    | jq -r '.data.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && echo "Failed!" && exit 1
  sleep 3
done

# 3. Download the audio
curl -L -o output.mp3 \
  -H "Authorization: Bearer $LOGTALK_API_KEY" \
  https://logtalk.io/api/v1/doctalk/convert/$ID/audio

Create Conversion

POST/doctalk/convert

Submit text content for audio conversion. Returns immediately with a conversion ID.

Audio generation runs asynchronously — poll the status endpoint or provide a webhook URL to be notified when complete.

Request Body

Parameter	Type	Required	Description
`content`	string	Required	The text content to convert. Maximum 50KB.
`context`	string	Optional	Additional context to guide the conversion (e.g., a job description when converting a resume). Maximum 10KB.
`content_description`	string	Optional	A short label describing what the content is (e.g., "Blog Post", "Resume", "Release Notes"). Maximum 200 characters.
`settings`	object	Optional	Audio generation settings. See below.
`webhook_url`	string	Optional	HTTPS URL to receive a webhook when conversion completes or fails.
`public_url`	boolean	Optional	If true, generates public listen and embed URLs for the audio.

Settings Object

Parameter	Type	Required	Description
`tone`	string casualformalexcited	Optional(default: `casual`)	Audio delivery tone. One of: "casual", "formal", "excited".
`verbosity`	string normalsuccinct	Optional(default: `normal`)	"normal" (~900 words / ~6 min) or "succinct" (~600 words / ~4 min).
`speakers`	number	Optional(default: `1`)	1 (single narrator) or 2 (dialogue with two hosts).
`product_name`	string	Optional	Optional product name for additional context.

Response (202)

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-...",
    "status": "processing",
    "poll_url": "https://logtalk.io/api/v1/doctalk/convert/a1b2c3d4-...",
    "estimated_completion_seconds": 60,
    "created_at": "2026-02-27T00:00:00.000Z"
  },
  "request_id": "req_abc123"
}

Get Conversion Status

GET/doctalk/convert/{id}

Poll this endpoint to check conversion progress and retrieve the result.

Once status is "completed", the response includes the generated script and audio URL.

Responses

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-...",
    "status": "processing",
    "poll_url": "https://logtalk.io/api/v1/doctalk/convert/a1b2c3d4-...",
    "estimated_completion_seconds": 30,
    "created_at": "2026-02-27T00:00:00.000Z"
  }
}

Download Audio

GET/doctalk/convert/{id}/audio

Returns the audio file for a completed conversion via redirect to a signed URL.

The endpoint redirects (302) to a signed URL that expires after 1 hour. The signed URL does not require authentication — it can be passed directly to audio players or downloaded.

# Download to file (follow redirect)
curl -L -o output.mp3 \
  -H "Authorization: Bearer $LOGTALK_API_KEY" \
  https://logtalk.io/api/v1/doctalk/convert/{id}/audio

Notes

Returns 404 if audio has not been generated yet. Poll the status endpoint until status is "completed" before requesting audio.
The signed URL expires after 1 hour. Request a new one by calling this endpoint again.
No quota is consumed — credits are used when the conversion is created, not when audio is downloaded.

Content Types

DocTalk adapts its script style based on the content_description field. While any value is accepted, these patterns trigger specialized prompt behavior:

Description	Behavior
`"Resume"`, `"CV"`	First-person pitch format. Matches experience against `context` (job description).
`"Article"`, `"Blog Post"`	Conversational summary highlighting key points and arguments.
Any other value	General-purpose narration adapted to the content.

Webhooks

Provide a webhook_url in your POST request to receive a notification when the conversion completes or fails. See the Webhooks documentation for payload format and signature verification.

DocTalk webhook events use the types doctalk.completed and doctalk.failed.

PreviousEpisodes (Deprecated)NextScripts