Skip to content

Latest commit

 

History

History
76 lines (53 loc) · 4.44 KB

README.md

File metadata and controls

76 lines (53 loc) · 4.44 KB

Instagram API reference (compact)

The Instagram parts of the Transcript Dock /v1 API on one page. Full reference: transcriptdock.com/docs/api-reference. Contract: OpenAPI 3.1. Every source and endpoint: transcriptdock-api.

Instagram in one paragraph

Instagram support is in beta. It uses AI transcription only: auto and transcribe are supported, captions_only is not (422 CAPABILITY_UNAVAILABLE). It costs 2 credits per started minute with a 60 second minimum and needs a paid plan (402 PLAN_REQUIRED on the free plan). Accepted links: public Reels instagram.com/reel/... and public video posts instagram.com/p/.... Up to 2 hours and 250 MB.

Basics

  • Base URL https://www.transcriptdock.com (always www).
  • Authorization: Bearer td_live_... from the dashboard.
  • Idempotency-Key (8 to 128 printable ASCII characters) is required on POST /v1/jobs and POST /v1/batches. Same key and body replays the original at no cost. A different body is 409 IDEMPOTENCY_CONFLICT.
  • Every response has X-Request-Id.

Check first: GET /v1/capabilities

With your key, the instagram object shows what your plan can do:

{ "enabled": true, "captions_only": false, "auto": true, "transcribe": true, "social_acquisition_fee": true, "native_captions": "unverified_disabled" }

native_captions: "unverified_disabled" is why there is no captions mode. GET /v1/usage returns plan, credits_remaining and credits_reserved.

Create a job: POST /v1/jobs

Field Notes
source.url A public Reel or video post
mode auto or transcribe. Both run AI transcription for Instagram.
language Optional spoken language hint (BCP 47). Default: detect.
recognition_profile standard
max_credits Spend cap. The media is measured first; above the cap the job fails with BUDGET_EXCEEDED and nothing is charged. Default covers 2 hours (240).
webhook_endpoint_id Receives job.succeeded or job.failed
metadata Up to 10 string values, echoed in webhooks

Returns 202 (queued) or 200 (already in your workspace, billing.kind: "cached", free).

Wait: GET /v1/jobs/{id}?wait=25

Holds up to 25 seconds and returns when status is succeeded, failed or cancelled. While AI transcription runs, status can be awaiting_provider and stage moves through acquire_audio, submit_asr, wait_asr, finalize. billing.credits_reserved is held while it runs; billing.credits_charged is the final cost.

POST /v1/jobs/{id}/cancel works before AI transcription starts. After that it returns 409 CANCELLATION_NOT_ALLOWED.

Transcript: GET /v1/transcripts/{id}

Field Instagram value
source_origin speech_recognition
timing_granularity word
words { start, end, text, confidence } per word, seconds
segments Caption sized { start, end, text }, used by SRT and VTT
recognition profile, model, quality_status (validated_language, provider_supported, experimental_language)
duration_seconds Measured media length

Export: GET /v1/transcripts/{id}/export?format=txt|json|srt|vtt. Free and repeatable.

Batches: POST /v1/batches

items: an array of job bodies, each with its own max_credits. Items per batch: 10 Starter, 25 Pro, 50 Scale. The maximum cost of every item is reserved at submit; the batch is accepted or rejected as a whole. GET /v1/batches/{id} returns status, counters and items with each job_id.

Errors you will meet on Instagram

Code HTTP Meaning
CAPABILITY_UNAVAILABLE 422 captions_only was sent for Instagram.
PLAN_REQUIRED 402 Instagram on the free plan.
BUDGET_EXCEEDED 402 Measured cost above max_credits. Nothing charged.
INSUFFICIENT_BALANCE 402 Not enough credits.
SOURCE_PRIVATE / SOURCE_NOT_FOUND / SOURCE_AUTH_REQUIRED 422 The media is not publicly reachable.
SOURCE_RATE_LIMITED / SOURCE_BLOCKED / SOURCE_TIMEOUT 503 Instagram is limiting access. The job retries automatically.
NO_SPEECH / NO_AUDIO 422 Nothing to transcribe.
DURATION_LIMIT_EXCEEDED 413 Longer than 2 hours.

Every code: error list.