Apply your first image effect

Use curl and jq to register a test device, choose an effect from the live catalog, upload a JPEG, and download the result.

Ask the Backapp team for an AppKey for your test app and the API origin for its environment. The production origin is https://api.backapp.dev. Use an origin without a trailing slash or /v2. The image-processing request can incur provider charges.

Configure the example

Set these variables in the same shell. Replace the example AppKey, use a stable ID for your test installation, and place a JPEG named sample.jpg in your current directory.

BACKAPP_BASE_URL='https://api.backapp.dev'
BACKAPP_APP_KEY='your-app-key'
BACKAPP_APP_VERSION='1.0.0'
BACKAPP_DEVICE_ID='your-unique-test-installation-id'

Register the device

session=$(jq -n --arg id "$BACKAPP_DEVICE_ID" '{device_id: $id}' |
  curl --fail-with-body --silent --show-error \
    "$BACKAPP_BASE_URL/v2/auth/device" \
    -H "X-App-Key: $BACKAPP_APP_KEY" \
    -H "X-App-Version: $BACKAPP_APP_VERSION" \
    -H 'Content-Type: application/json' --data-binary @-)
BACKAPP_ACCESS_TOKEN=$(printf '%s' "$session" | jq -er '.access_token')

Continue when you have an access token. The response also includes user_id, refresh_token, and a subscription summary. See Authentication for token handling.

Choose an effect

curl --fail-with-body --silent --show-error \
  "$BACKAPP_BASE_URL/v2/image_effects" \
  -H "X-App-Key: $BACKAPP_APP_KEY" \
  -H "X-App-Version: $BACKAPP_APP_VERSION" \
  -H "Authorization: Bearer $BACKAPP_ACCESS_TOKEN" |
  jq -r '.categories[].effects[] | [.id, .title] | @tsv'

Pick an integer ID from your response and assign it to BACKAPP_EFFECT_ID.

Apply the effect and download the result

result=$(curl --fail-with-body --silent --show-error \
  "$BACKAPP_BASE_URL/v2/image_effects/apply" \
  -H "X-App-Key: $BACKAPP_APP_KEY" \
  -H "X-App-Version: $BACKAPP_APP_VERSION" \
  -H "Authorization: Bearer $BACKAPP_ACCESS_TOKEN" \
  -F "effect_id=$BACKAPP_EFFECT_ID" \
  -F 'image=@sample.jpg')
image_url=$(printf '%s' "$result" | jq -er '.image_url')
curl --fail --silent --show-error --location "$image_url" -o result-image

The API returns HTTP 200 with image_url once processing completes. Open the downloaded file to see the result. An optional prompt form field overrides the effect’s configured prompt when it is nonempty.

See Errors and retries if a command fails.