AI workflows for existing integrations

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.

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.

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.

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

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.

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.

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

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

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

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

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.