Voices

GET`/v1/voices`

List voices: consented clones of the organization, your own clones and your chosen generic voices

Permission: voices:read

Response `200`

Name	Type	Description
`data` required	`object[]`
`data[].id` required	`string`
`data[].name` required	`string`
`data[].kind` required	`"clone" \| "generic"`
`data[].active` required	`boolean`
`data[].gender` required	`"male" \| "female" \| null`
`data[].status`	`"awaiting_consent" \| "processing" \| "ready" \| "failed" \| "revoked" \| "expired"`	Voices created through the API (consent flow). `ready` = usable in say.
`data[].consent_url`	`string \| null`	Send this link to the person whose voice it is. They sign in with the email of the request, read the consent sentence and record live. Shown while awaiting consent.
`data[].language`	`string`
`data[].person`	`object`
`data[].person.name` required	`string`
`data[].person.email` required	`string`	Masked
`data[].failure_code`	`string \| null`
`data[].expires_at`	`string \| null`
`data[].created_at`	`string`
`data[].livemode`	`boolean`

Example

curl

curl "https://api.kanutus.com/v1/voices" \
  -H "Authorization: Bearer $KANUTUS_API_KEY"

Node.js

const res = await fetch("https://api.kanutus.com/v1/voices", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.KANUTUS_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os, uuid, requests

r = requests.request(
    "GET",
    "https://api.kanutus.com/v1/voices",
    headers={"Authorization": f"Bearer {os.environ['KANUTUS_API_KEY']}"},
)
print(r.status_code, r.json())

Try it

Runs from your browser against the real API. Use a kt_test_ key: nothing is charged. The key stays in this tab only.

API key

GET /v1/voices

Responses by status

200 Voices

200

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "kind": "clone",
      "active": true,
      "gender": "male",
      "status": "awaiting_consent",
      "consent_url": "https://example.com",
      "language": "string",
      "person": {
        "name": "string",
        "email": "string"
      },
      "failure_code": "string",
      "expires_at": "string",
      "created_at": "string",
      "livemode": true
    }
  ]
}

400 Invalid request

400 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 400,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

401 Missing, invalid, expired or revoked credential

401 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 401,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

403 Missing permission, blocked or not allowed

403 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 403,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

429 Rate limit exceeded (see RateLimit-* and Retry-After headers)

429 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 429,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

POST`/v1/voices`

Clone a voice with verifiable consent: returns a link the person opens to read the consent sentence and record live Soon

Permission: voices:clone

Live mode answers 501 coming soon. Try it now with a kt_test_ key (simulator).

Parameters

Name	Type	Description
`idempotency-key` required	`header · string`	Unique key per create request; retries with the same key return the same result.

Request body

Name	Type	Description
`name` required	`string`	length 1–60
`language` required	`string`	Language the person will read in (consent sentence: pt, en or es; others read in English).
`person` required	`object`
`person.name` required	`string`	length 1–80
`person.email` required	`string`	The person signs in with this email to give consent and record. · length 0–254

Response `202`

Name	Type	Description
`id` required	`string`
`name` required	`string`
`kind` required	`"clone" \| "generic"`
`active` required	`boolean`
`gender` required	`"male" \| "female" \| null`
`status`	`"awaiting_consent" \| "processing" \| "ready" \| "failed" \| "revoked" \| "expired"`	Voices created through the API (consent flow). `ready` = usable in say.
`consent_url`	`string \| null`	Send this link to the person whose voice it is. They sign in with the email of the request, read the consent sentence and record live. Shown while awaiting consent.
`language`	`string`
`person`	`object`
`person.name` required	`string`
`person.email` required	`string`	Masked
`failure_code`	`string \| null`
`expires_at`	`string \| null`
`created_at`	`string`
`livemode`	`boolean`

Example

curl

curl -X POST "https://api.kanutus.com/v1/voices" \
  -H "Authorization: Bearer $KANUTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ana (atendimento)","language":"pt","person":{"name":"Ana Ribeiro","email":"ana@vertice.com"}}'

Node.js

const res = await fetch("https://api.kanutus.com/v1/voices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KANUTUS_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"name":"Ana (atendimento)","language":"pt","person":{"name":"Ana Ribeiro","email":"ana@vertice.com"}}),
});
console.log(res.status, await res.json());

Python

import os, uuid, requests

r = requests.request(
    "POST",
    "https://api.kanutus.com/v1/voices",
    headers={"Authorization": f"Bearer {os.environ['KANUTUS_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={"name":"Ana (atendimento)","language":"pt","person":{"name":"Ana Ribeiro","email":"ana@vertice.com"}},
)
print(r.status_code, r.json())

Try it

Runs from your browser against the real API. Use a kt_test_ key: nothing is charged. The key stays in this tab only.

API key Request body (JSON)

POST /v1/voices

Responses by status

202 Waiting for the person's consent (status awaiting_consent)

202

{
  "id": "string",
  "name": "string",
  "kind": "clone",
  "active": true,
  "gender": "male",
  "status": "awaiting_consent",
  "consent_url": "https://example.com",
  "language": "string",
  "person": {
    "name": "string",
    "email": "string"
  },
  "failure_code": "string",
  "expires_at": "string",
  "created_at": "string",
  "livemode": true
}

400 Invalid request

400 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 400,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

401 Missing, invalid, expired or revoked credential

401 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 401,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

403 Missing permission, blocked or not allowed

403 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 403,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

409 Conflict (idempotency or state)

409 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 409,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

429 Rate limit exceeded (see RateLimit-* and Retry-After headers)

429 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 429,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

501 Not available yet in live mode (use a kt_test_ key)

501 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 501,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

GET`/v1/voices/catalog`

Generic voices you can choose (no consent needed)

Permission: voices:read

Response `200`

Name	Type	Description
`data` required	`object[]`
`data[].id` required	`string`
`data[].name` required	`string`
`data[].gender` required	`"male" \| "female"`
`data[].accent` required	`string \| null`
`data[].description` required	`string \| null`
`data[].preview_url` required	`string \| null`

Example

curl

curl "https://api.kanutus.com/v1/voices/catalog" \
  -H "Authorization: Bearer $KANUTUS_API_KEY"

Node.js

const res = await fetch("https://api.kanutus.com/v1/voices/catalog", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.KANUTUS_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os, uuid, requests

r = requests.request(
    "GET",
    "https://api.kanutus.com/v1/voices/catalog",
    headers={"Authorization": f"Bearer {os.environ['KANUTUS_API_KEY']}"},
)
print(r.status_code, r.json())

Try it

Runs from your browser against the real API. Use a kt_test_ key: nothing is charged. The key stays in this tab only.

API key

GET /v1/voices/catalog

Responses by status

200 Catalog

200

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "gender": "male",
      "accent": "string",
      "description": "string",
      "preview_url": "string"
    }
  ]
}

400 Invalid request

400 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 400,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

401 Missing, invalid, expired or revoked credential

401 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 401,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

403 Missing permission, blocked or not allowed

403 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 403,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

429 Rate limit exceeded (see RateLimit-* and Retry-After headers)

429 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 429,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

POST`/v1/voices/generic`

Choose a generic voice from the catalog (adds it to your voices)

Permission: voices:write

Request body

Name	Type	Description
`voice_id` required	`string`

Response `200`

Name	Type	Description
`id` required	`string`
`name` required	`string`
`kind` required	`"clone" \| "generic"`
`active` required	`boolean`
`gender` required	`"male" \| "female" \| null`
`status`	`"awaiting_consent" \| "processing" \| "ready" \| "failed" \| "revoked" \| "expired"`	Voices created through the API (consent flow). `ready` = usable in say.
`consent_url`	`string \| null`	Send this link to the person whose voice it is. They sign in with the email of the request, read the consent sentence and record live. Shown while awaiting consent.
`language`	`string`
`person`	`object`
`person.name` required	`string`
`person.email` required	`string`	Masked
`failure_code`	`string \| null`
`expires_at`	`string \| null`
`created_at`	`string`
`livemode`	`boolean`

Example

curl

curl -X POST "https://api.kanutus.com/v1/voices/generic" \
  -H "Authorization: Bearer $KANUTUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voice_id":"generic_EXAVITQu4vr4xnSDxMaL"}'

Node.js

const res = await fetch("https://api.kanutus.com/v1/voices/generic", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KANUTUS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"voice_id":"generic_EXAVITQu4vr4xnSDxMaL"}),
});
console.log(res.status, await res.json());

Python

import os, uuid, requests

r = requests.request(
    "POST",
    "https://api.kanutus.com/v1/voices/generic",
    headers={"Authorization": f"Bearer {os.environ['KANUTUS_API_KEY']}"},
    json={"voice_id":"generic_EXAVITQu4vr4xnSDxMaL"},
)
print(r.status_code, r.json())

Try it

Runs from your browser against the real API. Use a kt_test_ key: nothing is charged. The key stays in this tab only.

API key Request body (JSON)

POST /v1/voices/generic

Responses by status

200 Chosen

200

{
  "id": "string",
  "name": "string",
  "kind": "clone",
  "active": true,
  "gender": "male",
  "status": "awaiting_consent",
  "consent_url": "https://example.com",
  "language": "string",
  "person": {
    "name": "string",
    "email": "string"
  },
  "failure_code": "string",
  "expires_at": "string",
  "created_at": "string",
  "livemode": true
}

400 Invalid request

400 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 400,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

401 Missing, invalid, expired or revoked credential

401 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 401,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

403 Missing permission, blocked or not allowed

403 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 403,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

409 Conflict (idempotency or state)

409 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 409,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

429 Rate limit exceeded (see RateLimit-* and Retry-After headers)

429 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 429,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

GET`/v1/voices/{id}`

Get a voice (and its consent status)

Permission: voices:read

Parameters

Name	Type	Description
`id` required	`path · string`

Response `200`

Name	Type	Description
`id` required	`string`
`name` required	`string`
`kind` required	`"clone" \| "generic"`
`active` required	`boolean`
`gender` required	`"male" \| "female" \| null`
`status`	`"awaiting_consent" \| "processing" \| "ready" \| "failed" \| "revoked" \| "expired"`	Voices created through the API (consent flow). `ready` = usable in say.
`consent_url`	`string \| null`	Send this link to the person whose voice it is. They sign in with the email of the request, read the consent sentence and record live. Shown while awaiting consent.
`language`	`string`
`person`	`object`
`person.name` required	`string`
`person.email` required	`string`	Masked
`failure_code`	`string \| null`
`expires_at`	`string \| null`
`created_at`	`string`
`livemode`	`boolean`

Example

curl

curl "https://api.kanutus.com/v1/voices/kqz-mbdt-wpa" \
  -H "Authorization: Bearer $KANUTUS_API_KEY"

Node.js

const res = await fetch("https://api.kanutus.com/v1/voices/kqz-mbdt-wpa", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.KANUTUS_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os, uuid, requests

r = requests.request(
    "GET",
    "https://api.kanutus.com/v1/voices/kqz-mbdt-wpa",
    headers={"Authorization": f"Bearer {os.environ['KANUTUS_API_KEY']}"},
)
print(r.status_code, r.json())

Try it

Runs from your browser against the real API. Use a kt_test_ key: nothing is charged. The key stays in this tab only.

API key id path required

GET /v1/voices/{id}

Responses by status

200 Voice

200

{
  "id": "string",
  "name": "string",
  "kind": "clone",
  "active": true,
  "gender": "male",
  "status": "awaiting_consent",
  "consent_url": "https://example.com",
  "language": "string",
  "person": {
    "name": "string",
    "email": "string"
  },
  "failure_code": "string",
  "expires_at": "string",
  "created_at": "string",
  "livemode": true
}

400 Invalid request

400 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 400,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

401 Missing, invalid, expired or revoked credential

401 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 401,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

403 Missing permission, blocked or not allowed

403 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 403,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

404 Not found

404 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 404,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

429 Rate limit exceeded (see RateLimit-* and Retry-After headers)

429 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 429,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

DELETE`/v1/voices/{id}`

Delete a voice: revokes a consented clone or removes a chosen generic voice

Permission: voices:write

Parameters

Name	Type	Description
`id` required	`path · string`

Response `200`

Name	Type	Description
`id` required	`string`
`deleted` required	`true`

Example

curl

curl -X DELETE "https://api.kanutus.com/v1/voices/kqz-mbdt-wpa" \
  -H "Authorization: Bearer $KANUTUS_API_KEY"

Node.js

const res = await fetch("https://api.kanutus.com/v1/voices/kqz-mbdt-wpa", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.KANUTUS_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os, uuid, requests

r = requests.request(
    "DELETE",
    "https://api.kanutus.com/v1/voices/kqz-mbdt-wpa",
    headers={"Authorization": f"Bearer {os.environ['KANUTUS_API_KEY']}"},
)
print(r.status_code, r.json())

Try it

Runs from your browser against the real API. Use a kt_test_ key: nothing is charged. The key stays in this tab only.

API key id path required

DELETE /v1/voices/{id}

Responses by status

200 Deleted

200

{
  "id": "string",
  "deleted": true
}

400 Invalid request

400 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 400,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

401 Missing, invalid, expired or revoked credential

401 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 401,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

403 Missing permission, blocked or not allowed

403 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 403,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

404 Not found

404 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 404,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

429 Rate limit exceeded (see RateLimit-* and Retry-After headers)

429 application/problem+json

{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 429,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

See all error codes

Voices

GET/v1/voices#

Response 200

Example

Responses by status

POST/v1/voices#

Parameters

Request body

Response 202

Example

Responses by status

GET/v1/voices/catalog#

Response 200

Example

Responses by status

POST/v1/voices/generic#

Request body

Response 200

Example

Responses by status

GET/v1/voices/{id}#

Parameters

Response 200

Example

Responses by status

DELETE/v1/voices/{id}#

Parameters

Response 200

Example

Responses by status

GET`/v1/voices`

Response `200`

POST`/v1/voices`

Response `202`

GET`/v1/voices/catalog`

Response `200`

POST`/v1/voices/generic`

Response `200`

GET`/v1/voices/{id}`

Response `200`

DELETE`/v1/voices/{id}`

Response `200`