API reference · ClipScribe

Permissions and authentication

Read permission can read existing tasks and their content in this account, including tasks created outside this key. Write permission can create tasks that consume credits and cancel supported tasks in this account. Always confirm the quote before creating a task. Never put a key in a URL, shared shortcut, screenshot or source repository. Revoke it if disclosed. Jobs and their content belong to the account, not exclusively to the key.

Quote, confirm, create, then poll

POST the task to quote. Show reservedCredits and expiresAt for a metered quote and obtain confirmation. Submit the same task with quoteId and one stable Idempotency-Key. If creation times out, retry that same payload and key; never create a new key just because the response was lost. Include quoteId only for metered mode. For free or unmetered mode, omit quoteId entirely. A reservation is an allowance, not a promise of final usage. A free or unmetered response is not a metered zero-price quote. Do not silently authorize unknown charges. An expired quote must be obtained and confirmed again.

Status, failures and retries

Poll the job detail at a bounded interval, for example every 3 seconds for at most 40 attempts. Stop on succeeded, failed or cancelled. On timeout retain the job ID so you can resume later. A succeeded detail contains result; lists are metadata only. A terminal failed task must not be silently resubmitted. The list returns the most recent 100 jobs and accepts an optional kind filter; this is not a complete paginated archive. Fetch a known older job by its ID. Each key is limited to 60 requests per fixed minute. 429: honor Retry-After. 401: replace an expired or revoked key. 403: check scope. 402: insufficient credits. Other 4xx responses require correcting the request. Network or 5xx creation failures have an unknown outcome: retain the original idempotency key.

Endpoints

Task request examples

Replace https://YOUR_DEPLOYMENT with your own HTTPS deployment. All credentials and IDs below are placeholders.

curl --request POST 'https://YOUR_DEPLOYMENT/api/v1/integrations/quote' \
  --header 'Authorization: Bearer csk_YOUR_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{"kind":"transcription","input":{"sourceUrl":"https://www.youtube.com/watch?v=abcdefghijk","language":"en"}}'

{
  "Authorization": "Bearer csk_YOUR_SECRET",
  "Content-Type": "application/json",
  "Idempotency-Key": "UUID_GENERATED_ONCE_FOR_THIS_TASK"
}

The create body below is for metered mode: replace quoteId with the confirmed quote ID. Remove quoteId entirely for free or unmetered mode.

{
  "kind": "transcription",
  "input": {
    "sourceUrl": "https://www.youtube.com/watch?v=abcdefghijk",
    "language": "en"
  },
  "quoteId": "QUOTE_ID_FROM_CONFIRMED_METERED_QUOTE"
}

{
  "kind": "transcription",
  "input": {
    "sourceUrl": "https://www.youtube.com/watch?v=abcdefghijk",
    "language": "en"
  }
}

{
  "kind": "text",
  "input": {
    "task": "summary",
    "segments": [
      {
        "startMs": 0,
        "endMs": 3000,
        "text": "The team tested three prototypes before choosing the final design."
      }
    ],
    "targetLanguage": "en"
  }
}

{
  "kind": "writing",
  "input": {
    "task": "article",
    "segments": [
      {
        "startMs": 0,
        "endMs": 3000,
        "text": "The team tested three prototypes before choosing the final design."
      }
    ],
    "targetLanguage": "en"
  }
}

{
  "kind": "youtubeData",
  "input": {
    "url": "https://www.youtube.com/watch?v=abcdefghijk",
    "tool": "video",
    "limit": 1
  }
}