API Documentation

Complete reference for the mypiceffects.com REST API — apply photo effects & video animations from any app or script.

⚡ Quick Start — 3 Steps

New to the API? Follow these three steps and you'll have your first result in under 5 minutes.

1

Register & Get Your API Key

Create a free account — your API key is generated instantly. Find it on your Dashboard under the 🔑 API Key card.

J
Dashboard
mypiceffects.com/dashboard
🔑 Your API Key
••••••••••••••••••a4f9c2 👁 Show ⎘ Copy
View API Docs →
→ Go to Dashboard → Copy key
2

Find an Effect ID

Go to the /effects page. Click any effect card. The Effect ID appears in the upload panel — click ⎘ Copy.

✨ Selected Effect
Galaxy Blur
🖼 Image effect
Effect ID
51952891 ⎘ Copy
📂 Drop photo here
✨ Generate Effect
→ Copy this number for your API call
3

Make Your First API Call

Send a POST request with your API key, the effect_id, and either a public photo_url or an uploaded photo file.

POST /api/generate

Authorization:
 Bearer YOUR_API_KEY

Option A — URL:
 "effect_id": "51952891"
 "photo_url": "https://..."

Option B — File upload:
 effect_id: 51952891
 photo: [binary file]

Response:
 "media_url": "https://cdn..."
 "type": "image"
→ Full code examples ↓
🎁 50 free credits on signup — plus 10 free credits every day redeemable from your dashboard. Credits are deducted only on successful requests.

Base URL

https://mypiceffects.com/api

All endpoints are relative to this base URL. All requests and responses use JSON. The API supports both photo effect generation (image output) and video animation generation (MP4 output).

Authentication

All API requests require your API key sent as a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Where to find your API key

After registering a free account, your API key is available instantly — no extra steps needed:

  1. Log in to mypiceffects.com
  2. Go to your Dashboard
  3. Find the 🔑 API Key card — key is masked by default
  4. Click 👁 Show to reveal or ⎘ Copy to copy directly
🔒 Keep your API key secret. Do not commit it to public repositories or expose it in client-side JavaScript. If you believe your key is compromised, contact us via the contact page.

Generate Photo Effect / Video Animation

POST /api/generate

Apply a creative effect to a photo and receive back an image or video URL. Costs 1 credit per image result, 2 credits per video result. Credits are only deducted on success — failed requests are completely free.

Request Parameters

photo_url or photo — provide exactly one. Do not send both in the same request.
Recommended: photo_url keeps your request lightweight and requires no multipart encoding. Use photo file upload when the image is captured locally (e.g. mobile app, Telegram bot) and has no public URL.
Parameter Type Required Description
effect_id string / integer Required The Effect ID. Accepts either the numeric ID (e.g. 51952891) or the combo code (e.g. ED128547). Go to /effects → click any effect card → copy the ID shown in the upload panel. See Step 2 in Quick Start above.
photo_url
OR 		string (URL) Optional * Publicly accessible URL of the photo to process. Supports JPEG, PNG, WebP. Send as application/json or multipart/form-data.
* Required if photo file is not provided.
photo file (multipart) Optional * Raw image file uploaded as multipart/form-data. Accepted formats: JPEG, PNG, WebP. Maximum size: 10 MB. Maximum dimensions: 6000 × 6000 px.
* Required if photo_url is not provided. Do not send both photo and photo_url in the same request. Do not set Content-Type: application/json when uploading a file — let your HTTP client set the multipart/form-data boundary automatically.

Success Response

{
  "success": true,
  "media_url": "https://cdn.mypiceffects.com/result.jpg",
  "type": "image", // "image" or "video"
  "credits_remaining": 48
}

Check Credits

GET /api/credits

Returns the remaining and used credits for the authenticated API key.

Success Response

{
  "success": true,
  "credits": 49,
  "used": 1
}

Error Codes

HTTP Code Reason Description
401 API key missing No Authorization header sent
401 Invalid API key API key not found in our system
403 Insufficient credits Your credits are 0 — buy more or redeem daily free credits
404 effect_id not found or inactive The provided Effect ID does not exist or has been disabled
422 Provide either a photo file or a photo_url Neither photo nor photo_url was provided, or both were sent together
422 effect_id is required The effect_id parameter is missing from the request
422 photo_url must be a valid URL Invalid or non-public URL format
422 File content does not match an allowed image type Uploaded file failed magic-byte verification — disguised or non-image files are rejected
422 File is not a valid image or is corrupted File bytes could not be decoded as a valid image
422 Image dimensions exceed the allowed limit Image exceeds 6000 × 6000 px — resize before uploading
422 Invalid effect ID or effect could not be processed Effect exists but processing failed on our end — no credit deducted
429 Too many requests Rate limit: 30 requests per minute per API key

Code Examples

Ready-to-paste examples. Replace YOUR_API_KEY with your key from your Dashboard.

Generate Photo Effect

The URL tabs use photo_url (recommended — lighter request). The File tabs use multipart photo upload (for local files with no public URL).

<?php
$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL => 'https://mypiceffects.com/api/generate',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    'effect_id' => '51952891',
    'photo_url' => 'https://yoursite.com/photo.jpg',
  ]),
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json',
  ],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($response['success']) {
  echo $response['media_url'];
}
<?php
// Use CURLFile — do NOT set Content-Type manually
// cURL sets the multipart boundary automatically
$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL => 'https://mypiceffects.com/api/generate',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => [
    'effect_id' => '51952891',
    'photo' => new CURLFile('/path/to/photo.jpg', 'image/jpeg', 'photo.jpg'),
  ],
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer YOUR_API_KEY',
  ],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($response['success']) {
  echo $response['media_url'];
}
curl -X POST https://mypiceffects.com/api/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{'
    "effect_id": "51952891",
    "photo_url": "https://yoursite.com/photo.jpg"
  '}'
# -F sends multipart/form-data automatically — no -H Content-Type needed
curl -X POST https://mypiceffects.com/api/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "effect_id=51952891" \
  -F "photo=@/path/to/photo.jpg;type=image/jpeg"
const response = await fetch('https://mypiceffects.com/api/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    effect_id: '51952891',
    photo_url: 'https://yoursite.com/photo.jpg',
  }),
});

const data = await response.json();
if (data.success) console.log(data.media_url);
import fs from 'fs';
import FormData from 'form-data'; // npm i form-data

const form = new FormData();
form.append('effect_id', '51952891');
form.append('photo', fs.createReadStream('/path/to/photo.jpg'), {
  filename: 'photo.jpg',
  contentType: 'image/jpeg',
});

const response = await fetch('https://mypiceffects.com/api/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    ...form.getHeaders(),
  },
  body: form,
});

const data = await response.json();
if (data.success) console.log(data.media_url);
import requests

response = requests.post(
  'https://mypiceffects.com/api/generate',
  headers={
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  json={
    'effect_id': '51952891',
    'photo_url': 'https://yoursite.com/photo.jpg',
  }
)

data = response.json()
if data['success']:
  print(data['media_url'])
import requests

# 'files' dict triggers multipart/form-data automatically
# Do NOT pass headers={'Content-Type': ...} — requests sets the boundary

with open('/path/to/photo.jpg', 'rb') as f:
  response = requests.post(
    'https://mypiceffects.com/api/generate',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    data={'effect_id': '51952891'},
    files={'photo': ('photo.jpg', f, 'image/jpeg')},
  )

data = response.json()
if data['success']:
  print(data['media_url'])

Check Credits

<?php
$ch = curl_init('https://mypiceffects.com/api/credits');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
]);
$data = json_decode(curl_exec($ch), true);
echo 'Credits: ' . $data['credits'];
curl https://mypiceffects.com/api/credits \
  -H "Authorization: Bearer YOUR_API_KEY"
const res = await fetch('https://mypiceffects.com/api/credits', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await res.json();
console.log('Credits:', data.credits);
import requests
r = requests.get(
  'https://mypiceffects.com/api/credits',
  headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
print(r.json()['credits'])

Daily Free Credits

🎁 10 free credits every day — for all users! Log in to your dashboard and click the "Redeem 10 Credits" button once per calendar day. Credits are added instantly and usable via API immediately.

Use the GET /api/credits endpoint to check your balance at any time. The dashboard also shows a clear redeem button when your daily credits are available.

Not a developer? Try it in your browser
No code needed — upload a photo and download your result in seconds.
Try Effects →