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

# Existing AI integration examples

> HTTP examples for apps already configured to use the original Backapp API.

These examples are for existing integrations using the original `/api/` routes. Use the API origin assigned to your existing application and its legacy access token. For a new app using `api.backapp.dev`, start with the [v2 image effects guide](https://docs.backapp.dev/quickstart.md).

## Prepare your connection

Set `LEGACY_API_ORIGIN` to the origin assigned to your app, without a trailing slash or `/api`. Set `LEGACY_ACCESS_TOKEN` to its legacy session token. If your app already uses device sign-in, its `POST /api/user/device_id` request accepts JSON with `device_id` and returns the token in `accessToken`. Continue using the same identity as your integration so the token can access its existing uploads and tasks.

The examples use curl and jq. Provider-backed operations can incur charges.

## Transcribe audio

Upload a short audio fixture using a unique file name. This example sends the complete file in one chunk. Byte offsets are measured on the original file before base64 encoding.

```bash theme={null}
audio_file='sample.m4a'
upload_name="sample-$(date +%s).m4a"
byte_count=$(wc -c < "$audio_file" | tr -d '[:space:]')

base64 < "$audio_file" | tr -d '\n' |
  jq -Rs --arg name "$upload_name" --argjson bytes "$byte_count" \
    '{file_chunk: ., file_name: $name, start_byte: 0, end_byte: $bytes}' |
  curl --fail-with-body --silent --show-error "$LEGACY_API_ORIGIN/api/upload" \
    -H "Authorization: Bearer $LEGACY_ACCESS_TOKEN" \
    -H 'Content-Type: application/json' --data-binary @-
```

Request transcription after the upload succeeds.

```bash theme={null}
jq -n --arg name "$upload_name" '{file_name: $name, language: "en"}' |
  curl --fail-with-body --silent --show-error --include \
    "$LEGACY_API_ORIGIN/api/transcribe_queue" \
    -H "Authorization: Bearer $LEGACY_ACCESS_TOKEN" \
    -H 'Content-Type: application/json' --data-binary @-
```

The first request can return HTTP 202 when it queues the work. Use the same file name and language in a subsequent request on the same route to read `title` and `content`. Content can be empty while processing. Wait between checks and stop after a bounded wait.

## Convert text to speech

```bash theme={null}
speech=$(curl --fail-with-body --silent --show-error \
  "$LEGACY_API_ORIGIN/api/text_to_speech" \
  -H "Authorization: Bearer $LEGACY_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"text":"Welcome to Backapp.","voice":"alloy"}')
speech_task_id=$(printf '%s' "$speech" | jq -er '.task_id')
```

The start request returns HTTP 202. Check the task with the same user's token.

```bash theme={null}
curl --fail-with-body --silent --show-error --get \
  "$LEGACY_API_ORIGIN/api/text_to_speech" \
  -H "Authorization: Bearer $LEGACY_ACCESS_TOKEN" \
  --data-urlencode "task_id=$speech_task_id" |
  jq '{status, output_path, error_message}'
```

Read `output_path` when the task completes. On failure, inspect `error_message`.

## Identify a postage stamp

Upload a stamp image as multipart data. The queued endpoint accepts an optional `text` field with OCR text and an optional `language` field that defaults to `en`.

```bash theme={null}
stamp=$(curl --fail-with-body --silent --show-error \
  "$LEGACY_API_ORIGIN/api/stamp_identify_queue" \
  -H "Authorization: Bearer $LEGACY_ACCESS_TOKEN" \
  -F 'image=@stamp.jpg' -F 'language=en')
stamp_task_id=$(printf '%s' "$stamp" | jq -er '.task_id')

curl --fail-with-body --silent --show-error --get \
  "$LEGACY_API_ORIGIN/api/stamp_identify_queue" \
  -H "Authorization: Bearer $LEGACY_ACCESS_TOKEN" \
  --data-urlencode "task_id=$stamp_task_id" |
  jq '{status, result, market_listings, error}'
```

The submit request returns HTTP 202. Check again after a delay while the task is pending or processing. A completed task can include stamp details and market listings. This workflow is designed for postage stamps.

## Translate text

```bash theme={null}
curl --fail-with-body --silent --show-error "$LEGACY_API_ORIGIN/api/translate" \
  -H "Authorization: Bearer $LEGACY_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"content":"Hello, world!","target_language":"Spanish"}' |
  jq '.content'
```

The response contains the translated text in `content`.

## Ask the note assistant

```bash theme={null}
curl --fail-with-body --silent --show-error \
  "$LEGACY_API_ORIGIN/api/note_assistant" \
  -H "Authorization: Bearer $LEGACY_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"question":"How can I organize lecture notes?"}' |
  jq '{answer, response_id}'
```

For a follow-up question, supply the returned `response_id` as `previous_response_id`.

## Summarize text

```bash theme={null}
curl --fail-with-body --silent --show-error "$LEGACY_API_ORIGIN/api/summarize_queue" \
  -H "Authorization: Bearer $LEGACY_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"content":"The team reviewed the prototype and agreed to test the onboarding flow next week."}' |
  jq '{title, content, emoji}'
```

The response is synchronous and contains `title`, `content`, and `emoji`. Short inputs can be returned as-is in `content`.

## Compare two images

```bash theme={null}
curl --fail-with-body --silent --show-error "$LEGACY_API_ORIGIN/api/compare_images" \
  -H "Authorization: Bearer $LEGACY_ACCESS_TOKEN" \
  -F 'image1=@before.jpg' -F 'image2=@after.jpg' -F 'language=en' |
  jq '.difference'
```

Both images are required. The default comparison round is `visual`, and the response includes a `difference` string.


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