\r \r

Animate Old Photos\r

\r Animate old photos into AI-generated videos via the Animate Old Photos API. The agent uploads a photo, submits an animation task, polls for completion, and downloads the resulting MP4 video.\r \r

Prerequisites\r

\r

This is a paid service. You need an API key and credits.\r \r

• Official Website: Animate Old Photos\r
• Get your API key: Profile > API Key\r
• Purchase credits: Buy Credits\r \r Each animation costs 3 credits. View pricing plans\r \r System requirements: curl and jq must be available in the shell.\r \r

Workflow\r

\r

Before starting\r

\r

1. Ask the user for their API key if environment variable AOP_API_KEY is not set.\r
2. Ask for the image path. Verify the file exists, is JPEG or PNG, and is under 10 MB.\r
3. Ask for an optional prompt describing desired motion (e.g. "grandmother smiling and waving"). If omitted the AI auto-generates motion.\r
4. Confirm with the user: "This will cost 3 credits. Proceed?"\r \r

Step 1 — Authenticate\r

\r Exchange the API key for a short-lived access token and check the credit balance.\r \r

API_KEY="${AOP_API_KEY}"\r
AUTH=$(curl -s -X POST https://animateoldphotos.org/api/extension/auth \\r
  -H "Content-Type: application/json" \\r
  -d "{\"licenseKey\":\"${API_KEY}\"}")\r
TOKEN=$(echo "$AUTH" | jq -r '.accessToken')\r
CREDITS=$(echo "$AUTH" | jq -r '.creditBalance')\r
echo "Authenticated. Credits available: $CREDITS"\r
```\r
\r
If `accessToken` is missing or `error_code` is `4010`/`4011`, tell the user their API key is invalid and link to \x3Chttps://animateoldphotos.org/profile/interface-key>.\r
\r
If credits \x3C 3, tell the user to purchase more at \x3Chttps://animateoldphotos.org/pricing> and stop.\r
\r
### Step 2 — Upload image\r
\r
Get a presigned upload URL, then PUT the image binary to cloud storage.\r
\r
```bash\r
IMAGE_PATH="photo.jpg"\r
FILE_SIZE=$(stat -f%z "$IMAGE_PATH" 2>/dev/null || stat -c%s "$IMAGE_PATH" 2>/dev/null)\r
CONTENT_TYPE="image/jpeg"  # use image/png for .png files\r
\r
UPLOAD=$(curl -s -X POST https://animateoldphotos.org/api/extension/upload-token \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d "{\"fileName\":\"$(basename "$IMAGE_PATH")\",\"contentType\":\"${CONTENT_TYPE}\",\"fileSize\":${FILE_SIZE}}")\r
UPLOAD_URL=$(echo "$UPLOAD" | jq -r '.uploadUrl')\r
KEY=$(echo "$UPLOAD" | jq -r '.key')\r
PUBLIC_URL=$(echo "$UPLOAD" | jq -r '.publicUrl')\r
\r
curl -s -X PUT "$UPLOAD_URL" \\r
  -H "Content-Type: ${CONTENT_TYPE}" \\r
  --data-binary "@${IMAGE_PATH}"\r
echo "Image uploaded."\r
```\r
\r
### Step 3 — Finalize upload\r
\r
Confirm the upload and receive the encrypted payload needed for task submission.\r
\r
```bash\r
FINALIZE=$(curl -s -X POST https://animateoldphotos.org/api/extension/upload-finalize \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -F "key=${KEY}" \\r
  -F "publicUrl=${PUBLIC_URL}")\r
IMAGE_URL=$(echo "$FINALIZE" | jq -r '.url')\r
SS_MESSAGE=$(echo "$FINALIZE" | jq -r '.message')\r
DNT=$(echo "$FINALIZE" | jq -r '.dnt')\r
echo "Upload finalized."\r
```\r
\r
### Step 4 — Submit animation task\r
\r
Submit the animation job. The `Ss` header **must** contain the `message` value from Step 3.\r
\r
```bash\r
PROMPT=""  # optional user prompt\r
TASK=$(curl -s -X POST https://animateoldphotos.org/api/extension/animate \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Ss: ${SS_MESSAGE}" \\r
  -F "prompt=${PROMPT}" \\r
  -F "input_image_url=${IMAGE_URL}" \\r
  -F "dnt=${DNT}" \\r
  -F "type=m2v_img2video" \\r
  -F "duration=5" \\r
  -F "public=false")\r
TASK_ID=$(echo "$TASK" | jq -r '.taskId')\r
TASK_DNT=$(echo "$TASK" | jq -r '.dnt')\r
TASK_DID=$(echo "$TASK" | jq -r '.did')\r
echo "Task submitted (ID: $TASK_ID). Polling for result..."\r
```\r
\r
If the response contains `error_code` `999990` or `10009`, the user has insufficient credits — link to \x3Chttps://animateoldphotos.org/pricing>.\r
\r
### Step 5 — Poll until done\r
\r
Poll every 30 seconds. Typical completion time is 2–5 minutes.\r
\r
```bash\r
OUTPUT="output.mp4"\r
while true; do\r
  sleep 30\r
  STATUS=$(curl -s -G "https://animateoldphotos.org/api/extension/animate" \\r
    --data-urlencode "taskId=${TASK_ID}" \\r
    --data-urlencode "dnt=${TASK_DNT}" \\r
    --data-urlencode "did=${TASK_DID}" \\r
    --data-urlencode "type=m2v_img2video" \\r
    -H "Authorization: Bearer $TOKEN")\r
\r
  ERR_MSG=$(echo "$STATUS" | jq -r '.message // empty')\r
  if [ -n "$ERR_MSG" ]; then\r
    echo "Task failed: $ERR_MSG"\r
    break\r
  fi\r
\r
  S=$(echo "$STATUS" | jq -r '.status')\r
  RESOURCE=$(echo "$STATUS" | jq -r '.resource // empty')\r
  if [ "$S" -ge 99 ] 2>/dev/null && [ -n "$RESOURCE" ]; then\r
    curl -s -o "$OUTPUT" "$RESOURCE"\r
    echo "Video saved to $OUTPUT"\r
    break\r
  fi\r
  echo "Still processing (status: $S)..."\r
done\r
```\r
\r
Report the saved video path to the user when done.\r
\r
### One-liner alternative\r
\r
You can run the full pipeline with the bundled script:\r
\r
```bash\r
bash scripts/animate.sh \x3CAPI_KEY> \x3CIMAGE_PATH> [PROMPT] [OUTPUT_PATH]\r
```\r
\r
See [scripts/animate.sh](scripts/animate.sh) for details.\r
\r
## Error Handling\r
\r
| error_code | Meaning | Action |\r
|------------|---------|--------|\r
| `4010` | Invalid API key | Direct user to [get a key](https://animateoldphotos.org/profile/interface-key) |\r
| `4011` | API key expired | Direct user to [renew key](https://animateoldphotos.org/profile/interface-key) |\r
| `999998` | Access token invalid | Re-run Step 1 to get a new token |\r
| `999990` | Insufficient credits | Direct user to [buy credits](https://animateoldphotos.org/pricing) |\r
| `10009` | Insufficient credits | Direct user to [buy credits](https://animateoldphotos.org/pricing) |\r
\r
For network errors, retry up to 3 times with exponential backoff (2s, 4s, 8s).\r
\r
## Interaction Flow\r
\r
1. **Trigger**: User says "animate this photo", "turn old photos into videos", "bring this photo to life", or similar.\r
2. **Gather inputs**: Ask for API key (if `AOP_API_KEY` not set), image path, and optional prompt.\r
3. **Confirm**: "This will cost 3 credits. You currently have {N} credits. Proceed?"\r
4. **Execute**: Run Steps 1–5, reporting progress at each stage.\r
5. **Complete**: "Your animated video has been saved to `{output_path}`."\r
6. **On error**:\r
   - Insufficient credits → "You need more credits. Purchase at: https://animateoldphotos.org/stripe"\r
   - Invalid API key → "Your API key is invalid or expired. Get one at: https://animateoldphotos.org/profile/interface-key"\r
   - Task failure → Show the error message and suggest the user retry or adjust the prompt.\r
\r
## Constraints\r
\r
- **Supported formats**: JPEG, PNG only\r
- **Max file size**: 10 MB\r
- **Min image dimension**: 300 × 300 px\r
- **Cost per animation**: 3 credits\r
- **Video duration**: 5 seconds\r
- **Typical processing time**: 2–5 minutes\r
\r
For the complete API reference, see [animate-old-photos-api.md](reference/animate-old-photos-api.md).\r