Skip to main content
This page is for an integration that runs on API v2 today. It says what to rewrite, what behaves differently, and what happens to the projects you already have. API v2 keeps working while you move: the two run side by side, and you can move one call at a time.

​
1. Get a key

API v2 signs in with client credentials and trades them for a token. API v3 takes an API key on every request, and there is no token to fetch or refresh:
Neither works in place of the other. API v2 credentials answer 401 invalid_token on v3. Create the key in the web app, as Authentication describes. Three choices matter when you come from v2:
  • The workspace. A key works in one workspace. Projects made through v2 are in the default workspace of the account that owns the v2 credentials, so create the key there to keep working with them.
  • The access. An integration that creates and dubs projects needs a key that can spend: the preset “Full access”, or your own set of scopes with credits:spend.
  • The limits. A key that can spend gets monthly caps unless you choose “no limit”, and it must expire, after a year at most. API v2 credentials have neither, so size the caps for your volume and plan to replace the key before it expires.

​
2. Replace each method

API v3 has 82 operations against the 23 methods above. What v2 could not do at all is in Capabilities: voice clones, on-screen text, exports, copies into more languages, transcript versions, usage, and more.

​
3. What behaves differently

  • Long work is a job. Creating a project, dubbing and lip-sync answer at once with a job, and you wait for the job instead of reading the project until its status changes. See Jobs.
  • You name the price before you pay it. Every operation that spends has an estimate, and the spending request carries expected_cost_minutes. A price above it answers 409 cost_changed and charges nothing. See Pricing.
  • The text of a new project is closed until its dub is charged. A project created through v3 dubs by itself after translation, and its transcript, segments and subtitles open with that charge. See Paid text.
  • A retry is safe. A request that creates, edits or starts something takes an Idempotency-Key, and repeating it with the same key does the work once. See Idempotency.
  • Errors have a code to branch on. Every error is application/problem+json with a stable code, listed in Errors.
  • Lists page by cursor, and no request takes a workspace id. See Conventions.

​
4. Projects made through v2

A v3 key sees them when it belongs to their workspace, which is the default workspace of the account that owns the v2 credentials. A key of any other workspace gets 404 project_not_found. On such a project:
  • The text is open. Paid text closes only projects created through v3. A copy you make of it through v3 is a v3 project, so Paid text applies to the copy.
  • Everything else works as on any project: reading and editing segments, dubbing again, lip-sync, exports, downloads and copies into more languages. Work ordered through v3 is priced by its estimate.
  • Work started in v2 has no job. While it runs, getProject shows it in processing_state, and active_jobs lists only jobs started through v3.
  • Its media cannot be reused. source_media_id of such a project answers 404 media_not_found on getMedia and on createProject. For another language, use createProjectCopies, or upload the file again.
The other way round has one limit: API v2 cannot read or edit the text of a project created through v3 until its dub is charged.

​
5. How long v2 stays

No end date is set for API v2. It works as it did before v3, its responses carry no deprecation headers, and its documentation stays under v2 in this site’s version selector. If that changes, this page will say so. API v3 is in alpha, so its operations may still change before the beta: the changelog lists what changed. There is no deadline to move. Move when you need what v2 does not have, and keep v2 for what already works until then.