Intake Production API

Full control over audio structure. This is the canonical format that all other schemas transform into.

Endpoint

POST /api/intake/production/{accessToken}

Quick Test

curl -X POST https://huebsch.schoenreden.com/api/intake/production/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"type":"doc","content":[{"type":"article","attrs":{"title":"Test","slug":"/test","voiceName":"Hannah","proofreadPromptName":"Default"},"content":[{"type":"paragraph","attrs":{"voiceName":"Hannah","proofreadPromptName":"Default"},"content":[{"type":"text","text":"Hello world."}]}]}]}'

Request Body

{
  "type": "doc",
  "content": [
    {
      "type": "article",
      "attrs": {
        "title": "Article Title",
        "slug": "/unique-slug",
        "voiceName": "Voice Name",
        "proofreadPromptName": "Prompt Name",
        "locale": "de-CH",
        "cover": "https://example.com/image.jpg",
        "description": "Short description",
        "webhook": "https://callback.url",
        "source": "https://original.article.url"
      },
      "content": [
        // Content nodes...
      ]
    }
  ]
}

Article Attributes

Article-level attributes apply to the article as a whole (e.g., title, slug, cover). Voice and proofreading settings must be specified on each content node individually.

Field	Type	Required	Description
`title`	string	Yes	Article title
`slug`	string	Yes	Identifier (2-256 chars), must start with `/`, alphanumeric + hyphens + slashes. Reusing a slug creates a new production that replaces the existing track.
`voiceName`	string	No	Voice name (max 128 chars). Not used by the production pipeline directly — set voice on each paragraph instead. Get available voices from Voices API.
`proofreadPromptName`	string	No	Proofreading prompt name (max 128 chars). Not used by the production pipeline directly — set on each paragraph instead. Configured by Huebsch during onboarding.
`locale`	string	No	Language locale (e.g., `de-CH`, `en-UK`)
`cover`	url	No	Cover image URL
`description`	string	No	Short description (max 256 chars)
`webhook`	url	No	Callback URL for completion notification
`source`	url	No	Original article URL
`shownotes`	string	No	Podcast show notes / extended description

Shownotes support basic HTML (<p>, <a>, <br>). Apple Podcasts truncates descriptions beyond 4000 characters.

Content Node Types

Paragraph

Text content to be synthesized as speech.

{
  "type": "paragraph",
  "attrs": {
    "voiceName": "Voice Name",
    "proofreadPromptName": "Prompt Name",
    "locale": "de-CH"
  },
  "content": [
    { "type": "text", "text": "The text to speak..." }
  ]
}

Field	Type	Required	Description
`voiceName`	string	Yes	Voice for this paragraph
`proofreadPromptName`	string	Yes	Proofreading prompt
`locale`	string	No	Override article locale

Pause

Insert a pause in the audio.

{
  "type": "pause",
  "attrs": {
    "pause": 1.5
  }
}

Field	Type	Required	Description
`pause`	number	Yes	Duration in seconds (0-10, up to 3 decimal places)

Sound

Insert a pre-configured sound by name. Contact your Huebsch contact for available sounds.

{
  "type": "sound",
  "attrs": {
    "soundName": "Jingle Intro"
  }
}

Field	Type	Required	Description
`soundName`	string	Yes	Sound identifier (max 128 chars)

Sound External

Insert audio from an external URL.

{
  "type": "soundExternal",
  "attrs": {
    "asset": "https://example.com/audio.mp3",
    "name": "Optional name",
    "crossfade.leadin": 0.5,
    "crossfade.leadout": 0.5
  }
}

Field	Type	Required	Description
`asset`	url	Yes	Audio file URL
`name`	string	No	Display name (max 128 chars)
`crossfade.leadin`	number	No	Crossfade in seconds
`crossfade.leadout`	number	No	Crossfade in seconds

Marker

Insert a chapter marker. Markers become chapters in the finished track — visible in the Track API response and the web player.

{
  "type": "marker",
  "attrs": {
    "label": "Chapter Title"
  }
}

Field	Type	Required	Description
`label`	string	Yes	Chapter title (1-256 chars)

Supported Locales

de-DE, de-CH

Reach out to your Huebsch contact for other locales.

Minimal Example

{
  "type": "doc",
  "content": [{
    "type": "article",
    "attrs": {
      "title": "Hello World",
      "slug": "/hello",
      "voiceName": "Hannah",
      "proofreadPromptName": "Default"
    },
    "content": [{
      "type": "paragraph",
      "attrs": {
        "voiceName": "Hannah",
        "proofreadPromptName": "Default"
      },
      "content": [{ "type": "text", "text": "Hello, world." }]
    }]
  }]
}

Full Example

{
  "type": "doc",
  "content": [
    {
      "type": "article",
      "attrs": {
        "title": "My First Production",
        "slug": "/2024/01/my-first-production",
        "voiceName": "Hannah",
        "proofreadPromptName": "Default",
        "locale": "de-CH"
      },
      "content": [
        {
          "type": "sound",
          "attrs": { "soundName": "Intro Jingle" }
        },
        {
          "type": "marker",
          "attrs": { "label": "Introduction" }
        },
        {
          "type": "paragraph",
          "attrs": {
            "voiceName": "Hannah",
            "proofreadPromptName": "Default",
            "locale": "de-CH"
          },
          "content": [
            { "type": "text", "text": "Welcome to my first audio production." }
          ]
        },
        {
          "type": "pause",
          "attrs": { "pause": 1.0 }
        },
        {
          "type": "paragraph",
          "attrs": {
            "voiceName": "Hannah",
            "proofreadPromptName": "Default",
            "locale": "de-CH"
          },
          "content": [
            { "type": "text", "text": "This demonstrates the production schema." }
          ]
        },
        {
          "type": "sound",
          "attrs": { "soundName": "Outro Jingle" }
        }
      ]
    }
  ]
}

Validation

Article content must contain at least one paragraph, sound, or soundExternal node
Maximum 512 content nodes per article
Text content maximum 5,000 characters per paragraph
Slug must match pattern: /[a-zA-Z0-9-/]+

Processing

After validation, processing occurs in two phases:

Content transformation - Your request is transformed into the internal production format
Audio generation - Text is synthesized, sounds are fetched, and the final audio is assembled

For the production schema, both phases happen immediately after your request. Errors in your content that only show during audio generation (like an unknown voice) arrive via webhook. See Webhook Callback.