Clips

Every clip and podcast you make lands in your library, whether it came from the API or from Studio. The clip object is described on Speak.

GET/v1/clips/{clipId}

Retrieve a clip

One clip, with a fresh signed url when it is ready. This is also how you poll a clip that is still processing: call it every second or two (every few seconds for podcasts) until the status changes.

Request

GET
/v1/clips/{clipId}
curl https://api.voixa.vovix.io/v1/clips/$CLIP_ID \
  -H "x-api-key: $VOIXA_API_KEY"
GET/v1/clips

List clips

Your clips, newest first, 20 at a time. Pass the returned cursor to get the next page.

Optional query

  • Name
    project
    Type
    string
    Description

    Only clips in this content group.

  • Name
    source
    Type
    string
    Description

    api or studio.

  • Name
    kind
    Type
    string
    Description

    clip for ordinary clips, podcast for podcasts.

  • Name
    voiceId
    Type
    string
    Description

    Only clips read with this voice.

  • Name
    limit
    Type
    integer
    Description

    1–100, default 20.

  • Name
    cursor
    Type
    string
    Description

    From the previous page.

Request

GET
/v1/clips
# Quote URLs with ? — zsh treats it as a glob
curl "https://api.voixa.vovix.io/v1/clips?project=episode-12&source=api" \
  -H "x-api-key: $VOIXA_API_KEY"

Response

{
  "items": [{ "clipId": "…", "status": "ready", "url": "https://…" }],
  "cursor": "eyJwayI6…"
}
GET/v1/projects

List projects

Every project name you have used, with how many clips and characters it holds. A project exists as soon as one clip or transcript uses it; there is nothing to create.

Request

GET
/v1/projects
curl https://api.voixa.vovix.io/v1/projects -H "x-api-key: $VOIXA_API_KEY"

Response

{ "projects": [{ "project": "episode-12", "clips": 42, "chars": 18930 }] }
POST/v1/clips/{clipId}/share

Share a clip

Publishes a ready clip on a public listening page and returns its shareUrl. Anyone with the link can listen, no account needed; podcasts show their title and transcript. The link lives until you revoke it with DELETE /v1/clips/{clipId}/share, or delete the clip.

Request

POST
/v1/clips/{clipId}/share
curl -X POST https://api.voixa.vovix.io/v1/clips/$CLIP_ID/share \
  -H "x-api-key: $VOIXA_API_KEY"

Response

{ "shareUrl": "https://voixa.vovix.io/s/9f2c41d0a7b3e85c16d2fa", "shared": true }
DELETE/v1/clips

Delete clips

Deletes up to 100 clips at once, with their audio and share pages.

Required attributes

  • Name
    clipIds
    Type
    string[]
    Description

    1–100 clip ids.

Request

DELETE
/v1/clips
curl -X DELETE https://api.voixa.vovix.io/v1/clips \
  -H "x-api-key: $VOIXA_API_KEY" -H "content-type: application/json" \
  -d '{ "clipIds": ["'$CLIP_ID'"] }'

Was this page helpful?