> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.rask.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Move from API v2 to v3

> What an API v2 integration rewrites to run on Rask API v3: a key instead of client credentials, the v3 operation for each v2 method, what behaves differently, and what happens to v2 projects.

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:

```typescript TypeScript theme={null}
const { data: me } = await rask.account.getMe();
```

```python Python theme={null}
me = client.account.get_me()
```

```go Go theme={null}
me, err := client.Account.GetMe(ctx)
if err != nil {
	return err
}
```

```java Java theme={null}
Me me = rask.account().getMe().data();
```

```php PHP theme={null}
$me = $rask->account->getMe();
```

```bash cURL theme={null}
curl https://api.rask.ai/v3/me \
  -H "Authorization: Bearer $RASK_API_KEY"
```

Neither works in place of the other. API v2 credentials answer 401 [`invalid_token`](https://docs.api.rask.ai/errors/invalid_token) on v3.

Create the key in the web app, as [Authentication](https://docs.api.rask.ai/authentication.md#get-a-key) 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](https://docs.api.rask.ai/authentication.md#scopes) with `credits:spend`.
* **The limits.** A key that can spend gets [monthly caps](https://docs.api.rask.ai/authentication.md#spend-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 v2 | API v3 | What changes |
| - | - | - |
| [Upload media by file](https://docs.api.rask.ai/api-reference/media/upload_media_file.md) | [createUpload](https://docs.api.rask.ai/operations/createUpload.md), then a PUT of the file, then [completeUpload](https://docs.api.rask.ai/operations/completeUpload.md) | The file goes straight to storage by a presigned URL, not through the API |
| [Upload media by link](https://docs.api.rask.ai/api-reference/media/upload_media_link.md) | [importMedia](https://docs.api.rask.ai/operations/importMedia.md) | Only YouTube, Google Drive, Vimeo and allow-listed hosts: another host answers 422 [`source_url_not_allowed`](https://docs.api.rask.ai/errors/source_url_not_allowed). Upload a file from anywhere else |
| [Get media](https://docs.api.rask.ai/api-reference/media/get_media.md) | [getMedia](https://docs.api.rask.ai/operations/getMedia.md) | Only media uploaded or imported through v3. A v2 media id answers 404 [`media_not_found`](https://docs.api.rask.ai/errors/media_not_found), here and on createProject |
| [Create project](https://docs.api.rask.ai/api-reference/project/create_project.md) | [estimateProject](https://docs.api.rask.ai/operations/estimateProject.md), then [createProject](https://docs.api.rask.ai/operations/createProject.md) | `video_id` is `media_id`, `src_lang` is `source_language`, `dst_lang` is `target_language`. `num_speakers` and `glossary_id` keep their names. The answer has a job, and the request names the most it may cost |
| [Get project](https://docs.api.rask.ai/api-reference/project/get_project.md) | [getProject](https://docs.api.rask.ai/operations/getProject.md) | To follow the work, wait for its [job](https://docs.api.rask.ai/v3/concepts/jobs.md) |
| [Get project list](https://docs.api.rask.ai/api-reference/project/get_project_list.md) | [listProjects](https://docs.api.rask.ai/operations/listProjects.md) | Pages by cursor, with no offset and no total. It lists every member's projects in the key's workspace, and none from other workspaces. It also lists projects in folders, which v2 left out: send `folder_id=root` for only those outside folders |
| [Generate project](https://docs.api.rask.ai/api-reference/project/generate_project.md) | [estimateDub](https://docs.api.rask.ai/operations/estimateDub.md), then [createDub](https://docs.api.rask.ai/operations/createDub.md) | A redub is priced, and it can dub only the lines that changed |
| [Patch project](https://docs.api.rask.ai/api-reference/project/patch_project.md) | [updateProject](https://docs.api.rask.ai/operations/updateProject.md) for the name, [updateSpeakerVoice](https://docs.api.rask.ai/operations/updateSpeakerVoice.md) for a voice | One speaker's voice per call, with `If-Match`. The number of speakers cannot be changed after creation |
| [Get project voices](https://docs.api.rask.ai/api-reference/project/get_voices.md) | [listProjectVoices](https://docs.api.rask.ai/operations/listProjectVoices.md), and [listSpeakers](https://docs.api.rask.ai/operations/listSpeakers.md) for who speaks | |
| [Create transcription](https://docs.api.rask.ai/api-reference/project/create_transcription.md) | `subtitles` on [createProject](https://docs.api.rask.ai/operations/createProject.md) | No replacement for a transcript sent as JSON segments, and no `transcript_id`. Send the text as SRT with the project: see [Your own transcript](https://docs.api.rask.ai/v3/recipes/own-transcript.md) |
| [Create transcription srt](https://docs.api.rask.ai/api-reference/project/create_transcription_srt.md) | `subtitles` on [createProject](https://docs.api.rask.ai/operations/createProject.md), or [importTranscript](https://docs.api.rask.ai/operations/importTranscript.md) for a project that exists | The SRT goes inline in the JSON body, not as a file upload |
| [Get transcription](https://docs.api.rask.ai/api-reference/project/get_transcription.md) | [getTranscript](https://docs.api.rask.ai/operations/getTranscript.md) for the summary, [listSegments](https://docs.api.rask.ai/operations/listSegments.md) for the text | Closed on a new project until its dub is charged: see [Paid text](https://docs.api.rask.ai/v3/concepts/paid-text.md) |
| [Add segments](https://docs.api.rask.ai/api-reference/project/add_segments.md) | [createSegment](https://docs.api.rask.ai/operations/createSegment.md) | One segment per call |
| [Patch segments](https://docs.api.rask.ai/api-reference/project/patch_segments.md) | [updateSegment](https://docs.api.rask.ai/operations/updateSegment.md) | One segment per call, with `If-Match`: see [ETags](https://docs.api.rask.ai/v3/concepts/etags.md) |
| [Delete segment](https://docs.api.rask.ai/api-reference/project/delete_segment.md) | [deleteSegment](https://docs.api.rask.ai/operations/deleteSegment.md) | With `If-Match` |
| [Create glossary](https://docs.api.rask.ai/api-reference/glossary/create_glossary.md) | [createGlossary](https://docs.api.rask.ai/operations/createGlossary.md) | |
| [Get glossary](https://docs.api.rask.ai/api-reference/glossary/get_glossary.md) | [getGlossary](https://docs.api.rask.ai/operations/getGlossary.md), and [listGlossaries](https://docs.api.rask.ai/operations/listGlossaries.md) for all of them | |
| [Update glossary](https://docs.api.rask.ai/api-reference/glossary/update_glossary.md) | [updateGlossary](https://docs.api.rask.ai/operations/updateGlossary.md) | |
| [Delete glossary](https://docs.api.rask.ai/api-reference/glossary/delete_glossary.md) | [deleteGlossary](https://docs.api.rask.ai/operations/deleteGlossary.md) | |
| [Run check face](https://docs.api.rask.ai/api-reference/lipsync/run_check_face.md) | None | No step of its own. [createLipsync](https://docs.api.rask.ai/operations/createLipsync.md) checks for a face itself, and [estimateLipsync](https://docs.api.rask.ai/operations/estimateLipsync.md) says whether a check has already found one |
| [Run Lip-sync](https://docs.api.rask.ai/api-reference/lipsync/run_lipsync.md) | [estimateLipsync](https://docs.api.rask.ai/operations/estimateLipsync.md), then [createLipsync](https://docs.api.rask.ai/operations/createLipsync.md) | No `is_multiple_speakers`: the request names the model, whether it is the free run, and the most it may cost. See [Lip-sync](https://docs.api.rask.ai/v3/recipes/lipsync.md) |
| [Get Lip-sync info](https://docs.api.rask.ai/api-reference/lipsync/get_lipsync.md) | [getLipsyncState](https://docs.api.rask.ai/operations/getLipsyncState.md) | |
| [Get credits](https://docs.api.rask.ai/api-reference/user/get_credits.md) | [getBalance](https://docs.api.rask.ai/operations/getBalance.md) | |

API v3 has 82 operations against the 23 methods above. What v2 could not do at all is in [Capabilities](https://docs.api.rask.ai/v3/concepts/capabilities.md): 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](https://docs.api.rask.ai/v3/concepts/jobs.md).
* **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`](https://docs.api.rask.ai/errors/cost_changed) and charges nothing. See
  [Pricing](https://docs.api.rask.ai/v3/concepts/pricing.md).
* **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](https://docs.api.rask.ai/v3/concepts/paid-text.md).
* **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](https://docs.api.rask.ai/v3/concepts/idempotency.md).
* **Errors have a code to branch on.** Every error is `application/problem+json` with a stable `code`, listed in
  [Errors](https://docs.api.rask.ai/errors.md).
* **Lists page by cursor**, and no request takes a workspace id. See [Conventions](https://docs.api.rask.ai/v3/concepts/conventions.md#lists).

## 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`](https://docs.api.rask.ai/errors/project_not_found).

On such a project:

* **The text is open.** [Paid text](https://docs.api.rask.ai/v3/concepts/paid-text.md) 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](https://docs.api.rask.ai/operations/getProject.md) 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`](https://docs.api.rask.ai/errors/media_not_found) on
  [getMedia](https://docs.api.rask.ai/operations/getMedia.md) and on [createProject](https://docs.api.rask.ai/operations/createProject.md). For another language, use
  [createProjectCopies](https://docs.api.rask.ai/operations/createProjectCopies.md), 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](https://docs.api.rask.ai/changelog.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.