Apple Shortcuts · 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.

1

Ask for a supported video URL and keep it in a variable. Set your deployed HTTPS API origin; do not use the example host as a live service.

2

Get Contents of URL: POST /api/v1/integrations/quote with Authorization: Bearer <your key>, Content-Type: application/json and the transcription example body.

3

Read the mode, quote.reservedCredits and quote.expiresAt. Show the reservation to the user and ask for confirmation; stop on cancel or an unknown response.

4

Generate a UUID once, keep it with the task payload, and POST /api/v1/integrations/jobs with that UUID as Idempotency-Key and the confirmed quoteId where required. For metered mode include the confirmed quoteId; for free or unmetered mode omit quoteId.

5

Store the returned job.id. Repeat at most 40 times: wait 3 seconds, then GET /api/v1/integrations/jobs/{id}. For 429, honor Retry-After without creating a second job.

6

On succeeded, show job.result.text. On failed or cancelled, show the status and stop. When polling runs out, retain the job ID to check later. To cancel an active job explicitly, DELETE its detail URL.

7

If the create response is lost, retry using exactly the same payload and UUID. Never generate a new UUID to work around a timeout. Reconfirm a new quote only after a definite quote-expired rejection.

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
  }
}