Skip to main content
POST
Create custom voice

Authorizations

API-KEY
string
header
required

Headers

Idempotency-Key
string

Client-generated key for safely retrying create requests. Reusing the same key for the same path answers with the original status code and the resource as it is now; reusing it for a different path returns 422. Keys expire after 24 hours.

Path Parameters

workspace_id
integer
required
Required range: x >= 1
Example:

123

Body

application/json

Custom voice params

name
string
required
Maximum string length: 100
Example:

"My Voice"

reference_text
string
required

Reference content (UTF-8). 1–25,000 characters; must contain at least 200 words.

Stored and returned verbatim — no sanitization or normalization. Markdown is the recommended format; predefined Surfer templates use Markdown, and the in-app editor parses this field as Markdown.

The 200-word minimum is counted by a tokenizer over the raw string, so markup characters may or may not contribute to the count.

Maximum string length: 25000
Example:

"Voice reference content..."

default
boolean
default:false

Response

Created custom voice

inserted_at
string<date-time>
required
Example:

"2024-04-12T15:23:45Z"

default
boolean
required
Example:

false

id
integer
required
Required range: x >= 1
Example:

123

name
string
required
Example:

"Professional Blog Voice"

reference_text
string
required

Stored verbatim; Markdown recommended.

Example:

"Voice reference content..."

updated_at
string<date-time>
Example:

"2024-06-01T09:17:33Z"