# CelebifyAI API Reference
# Last updated: 2026-02-22
# Base URL: https://celebifyai.com/api/v1

## Authentication
All requests require a Bearer token in the Authorization header.
Format: Authorization: Bearer cel_your_api_key
API keys start with the prefix "cel_". Manage keys at https://celebifyai.com/dashboard/developers

## Rate Limits
Concurrent generation limits by plan (shared between web UI and API):
- Free: No API access (1 concurrent via web only)
- Base: 4 concurrent generations
- Plus: 6 concurrent generations
- Pro: 10 concurrent generations

## Error Codes
| HTTP | Code | Description |
|------|------|-------------|
| 400 | invalid_json | Request body is not valid JSON |
| 400 | missing_prompt | A required field is missing |
| 400 | invalid_model | The specified model ID does not exist |
| 400 | invalid_url | A provided URL is malformed or unreachable |
| 401 | unauthorized | Invalid or missing API key |
| 402 | insufficient_credits | Not enough credits to complete the request |
| 429 | rate_limit_exceeded | Concurrent generation limit reached |
| 404 | not_found | The requested resource was not found |
| 500 | internal_error | An unexpected server error occurred |

Error response format:
{
  "error": {
    "code": "error_code",
    "message": "Human-readable message",
    "details": {}
  }
}

## Pagination
List endpoints use cursor-based pagination.
Query params: limit (1-100, default 20), cursor (from previous response)
Response includes: data[], has_more (boolean), next_cursor (string|null)

---

## Endpoints

### GET /api/v1/account
Returns current account info, credit balance, plan, and concurrency status.
Response: { credits, plan, frequency, concurrency: { current, limit, available } }

### GET /api/v1/models
Returns all available models with credit costs and capabilities.
Query params: type (optional, "image" or "video")
Response: { image_models: [...], video_models: [...], upscale_models: [...], face_swap_models: [...] }

### POST /api/v1/images/generate/{model}
Start an image generation.
Body params:
- prompt (string, required) — Text prompt describing the image
- negative_prompt (string, optional) — What to exclude
- aspect_ratio (string, optional, default "1:1") — e.g. "1:1", "16:9", "9:16"
- image_url (string, optional) — Input image for I2I models
- num_images (integer, optional, 1-4, default 1)
- seed (integer, optional)
Response: { id, status: "pending", model, credits_charged, estimated_seconds }

### GET /api/v1/images/{id}
Get status and result of an image generation. Poll until status is "completed" or "failed".
Response: { id, model, status, credits_charged, created_at, images: [{ url, width, height }] }

### GET /api/v1/images
List image generations with pagination.
Query params: limit, cursor, model, status ("pending"|"processing"|"completed"|"failed")
Response: { data: [...], has_more, next_cursor }

### POST /api/v1/videos/generate/{model}
Start a video generation.
Body params:
- prompt (string, required for T2V models)
- image_url (string, required for I2V models) — Input image
- aspect_ratio (string, optional, default "16:9")
- duration (number, optional) — Duration in seconds
- seed (integer, optional)
Response: { id, status: "pending", model, credits_charged, estimated_seconds }

### GET /api/v1/videos/{id}
Get status and result of a video generation. Poll until status is "completed" or "failed".
Response: { id, model, status, credits_charged, created_at, video: { url, duration, width, height } }

### GET /api/v1/videos
List video generations with pagination.
Query params: limit, cursor, model, status
Response: { data: [...], has_more, next_cursor }

### POST /api/v1/face-swap/image
Swap a face in an image. Costs 5 credits.
Body params:
- swap_image_url (string, required) — URL of the source face image
- target_image_url (string, required) — URL of the target image to modify
Response: { id, status: "pending", model: "face-swap-image", credits_charged: 5, estimated_seconds: 30 }

### POST /api/v1/face-swap/video
Swap a face in a video. Costs 30 credits.
Body params:
- swap_image_url (string, required) — URL of the source face image
- target_video_url (string, required) — URL of the target video to modify
Response: { id, status: "pending", model: "face-swap-video", credits_charged: 30, estimated_seconds: 120 }

### POST /api/v1/upscale/image
Upscale an image. Costs 5 credits.
Body params:
- image_url (string, required) — URL of the image to upscale
- prompt (string, optional) — Enhancement prompt
Response: { id, status: "pending", model: "image-upscale", credits_charged: 5, estimated_seconds: 30 }

### POST /api/v1/upscale/video
Upscale a video. Costs ~20 credits (varies by resolution/frames).
Body params:
- video_url (string, required) — URL of the video to upscale
Response: { id, status: "pending", model: "video-upscale", credits_charged, estimated_seconds: 120 }

---

## Image Models

| ID | Name | Type | Credits | Max Quantity |
|----|------|------|---------|-------------|
| celebify-pro | CelebifyAI Pro | T2I | 15 | 4 |
| celebify-noir | CelebifyAI Noir | T2I | 5 | 4 |
| celebify-x-plus | CelebifyAI X Plus | T2I | 5 | 4 |
| z-image | Z-Image | T2I | 0.5 | 4 |
| seedream-3 | Seedream 3.0 | T2I | 2.2 | 4 |
| seedream-4-t2i | Seedream 4.0 T2I | T2I | 2.2 | 6 |
| seedream-4-edit | Seedream 4.0 Edit | I2I | 2.2 | 6 |
| seedream-4.5-t2i | Seedream 4.5 T2I | T2I | 2.2-4.4 | 4 |
| seedream-4.5-edit | Seedream 4.5 Edit | I2I | 2.2-4.4 | 4 |
| flux-2-pro-t2i | Flux 2 Pro T2I | T2I | 3.1 | 4 |
| flux-2-pro-i2i | Flux 2 Pro I2I | I2I | 3.1 | 4 |
| flux-2-flex-t2i | Flux 2 Flex T2I | T2I | 2.5 | 4 |
| flux-2-flex-i2i | Flux 2 Flex I2I | I2I | 2.5 | 4 |
| qwen-t2i | Qwen T2I | T2I | 0.6-2.2 | 4 |
| qwen-i2i | Qwen I2I | I2I | 0.6-2.2 | 1 |
| qwen-edit | Qwen Edit | I2I | 0.6-2.2 | 4 |
| grok-imagine-t2i | Grok Imagine T2I | T2I | 2.5 | 6 |
| grok-imagine-i2i | Grok Imagine I2I | I2I | 2.5 | 2 |

## Video Models

| ID | Name | Type | Credits |
|----|------|------|---------|
| seedance-v1-lite-t2v | Seedance V1 Lite T2V | T2V | varies |
| seedance-v1-pro-t2v | Seedance V1 Pro T2V | T2V | varies |
| seedance-1-5-pro-t2v | Seedance 1.5 Pro T2V | T2V | varies |
| kling-2-5-turbo-t2v | Kling 2.5 Turbo T2V | T2V | varies |
| kling-2-6-t2v | Kling 2.6 T2V | T2V | varies |
| kling-2-1-master-t2v | Kling 2.1 Master T2V | T2V | varies |
| wan-2-6-t2v | Wan 2.6 T2V | T2V | varies |
| wan-2-5-t2v | Wan 2.5 T2V | T2V | varies |
| veo-3-fast-t2v | Veo 3 Fast T2V | T2V | varies |
| veo-3-quality-t2v | Veo 3 Quality T2V | T2V | varies |
| sora-2-t2v | Sora 2 T2V | T2V | varies |
| sora-2-pro-t2v | Sora 2 Pro T2V | T2V | varies |
| hailuo-02-t2v-pro | Hailuo 02 Pro T2V | T2V | varies |
| hailuo-02-t2v-standard | Hailuo 02 Standard T2V | T2V | varies |
| grok-imagine-t2v | Grok Imagine T2V | T2V | varies |
| seedance-v1-lite-i2v | Seedance V1 Lite I2V | I2V | varies |
| seedance-v1-pro-i2v | Seedance V1 Pro I2V | I2V | varies |
| seedance-1-5-pro-i2v | Seedance 1.5 Pro I2V | I2V | varies |
| kling-2-5-turbo-i2v | Kling 2.5 Turbo I2V | I2V | varies |
| kling-2-6-i2v | Kling 2.6 I2V | I2V | varies |
| kling-2-1-master-i2v | Kling 2.1 Master I2V | I2V | varies |
| wan-2-6-i2v | Wan 2.6 I2V | I2V | varies |
| wan-2-5-i2v | Wan 2.5 I2V | I2V | varies |
| veo-3-fast-i2v | Veo 3 Fast I2V | I2V | varies |
| veo-3-quality-i2v | Veo 3 Quality I2V | I2V | varies |
| sora-2-i2v | Sora 2 I2V | I2V | varies |
| sora-2-pro-i2v | Sora 2 Pro I2V | I2V | varies |
| hailuo-02-i2v-pro | Hailuo 02 Pro I2V | I2V | varies |
| hailuo-02-i2v-standard | Hailuo 02 Standard I2V | I2V | varies |
| grok-imagine-i2v | Grok Imagine I2V | I2V | varies |

## Other Operations

| Operation | Credits |
|-----------|---------|
| Image Upscale | 5 |
| Video Upscale | ~20 (varies by resolution/frames) |
| Face Swap (Image) | 5 |
| Face Swap (Video) | 30 |

---

Notes:
- Credits are deducted when a generation starts. Failed generations are refunded automatically.
- T2I = Text-to-Image, I2I = Image-to-Image, T2V = Text-to-Video, I2V = Image-to-Video
- Video model credit costs vary by model, duration, and resolution. Use GET /api/v1/models for current pricing.
- Check your balance anytime with GET /api/v1/account.
- Full interactive documentation: https://celebifyai.com/docs