Developers

Xomily REST API

The exact API that powers our website and mobile apps. JSON in, JSON out. Base URL: https://xomily.com/api/v1

1. Authenticate

curl -X POST https://xomily.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"••••••••","device_name":"My App"}'

→ {"data":{"user":{...,"tokens":120},"token":"xom_…","token_type":"Bearer"}}

Send Authorization: Bearer xom_… with every request.

2. Discover options & prices

curl https://xomily.com/api/v1/catalog   # models, voices, templates, styles, cameras, aspect ratios

3. Upload a photo (optional)

curl -X POST https://xomily.com/api/v1/uploads -H "Authorization: Bearer $TOKEN" \
  -F file=@family.jpg -F consent=1
→ {"data":{"id":42,"url":"…"}}

4. Create a video

curl -X POST https://xomily.com/api/v1/generations -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{
    "kind":"video", "model":"kling_std", "prompt":"The family laughing together in a sunny park",
    "style":"warm", "camera":"dolly", "aspect_ratio":"9:16", "duration":10,
    "upload_ids":[42], "consent":true,
    "voice_id":1, "voiceover_text":"Some moments are worth keeping forever."
  }'
→ 201 {"data":{"id":"6f1c…","status":"processing","progress":20,"step":"Animating your scene",…},"meta":{"balance":37}}

5. Poll for the result

curl https://xomily.com/api/v1/generations/6f1c… -H "Authorization: Bearer $TOKEN"
→ {"data":{"status":"completed","outputs":[{"type":"video","url":"…mp4","download_url":"…"}],"captions_url":"…vtt",…}}

Poll every 3–5 seconds. Statuses: queued, processing, completed, failed, blocked. Failed and blocked creations are refunded automatically.

Errors

{"error":{"message":"You need 80 tokens…","code":"insufficient_tokens","fields":{"tokens":"…"}}}

Common codes: validation (422), content_policy (422), insufficient_tokens (402), unauthenticated (401), rate_limited (429).

All endpoints

Full OpenAPI 3 specification: docs/openapi.yaml in the project (import into Postman, Insomnia, or generate Swift/Kotlin/Dart clients with openapi-generator).

• POST /auth/register · /auth/login · /auth/logout · /auth/forgot-password · /auth/reset-password
• GET|PATCH /me · POST /me/delete · GET /me/tokens · DELETE /me/tokens/{id}
• GET /catalog · GET /library · GET /voices/{id}/sample · POST /estimate · POST /prompt/enhance
• GET|POST /uploads · DELETE /uploads/{id}
• GET|POST /generations · GET|PATCH|DELETE /generations/{id}
• GET /wallet · GET /packages · POST /checkout · POST /checkout/confirm · POST /promo/redeem
• GET /gallery · POST /reports · POST /contact · GET /health

All content created through the API is subject to our Acceptable Use Policy.