> ## 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.

# 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.

```bash theme={null}
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

```bash theme={null}
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](https://docs.backapp.dev/authentication.md) for token handling.

## Choose an effect

```bash theme={null}
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

```bash theme={null}
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](https://docs.backapp.dev/errors.md) if a command fails.


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