# Atlas Cloud API Reference

## Credentials
- **API Key:** `apikey-57dc1390dbca46b593d8cc420db26a1b`
- **Base URL:** `https://api.atlascloud.ai/api/v1`
- **Auth header:** `Authorization: Bearer apikey-57dc1390dbca46b593d8cc420db26a1b`

## 1) Still generation

### Wan 2.7
**Endpoint:** `POST /model/generateImage`
**Model:** `alibaba/wan-2.7/image-edit`
- Max 4 images in `images[]`
- Use `size`, usually `"1280*720"` for 16:9
- Async flow: `enable_sync_mode: false`

```json
{
  "model": "alibaba/wan-2.7/image-edit",
  "images": ["url1", "url2", "url3"],
  "prompt": "...",
  "negative_prompt": "...",
  "size": "1280*720",
  "enable_prompt_expansion": false,
  "enable_base64_output": false,
  "enable_sync_mode": false
}
```

### Nano Banana 2
**Endpoint:** `POST /model/generateImage`
**Model:** `google/nano-banana-2/edit`
- Better for complex multi-character stills and tricky staging
- Use `aspect_ratio` + `resolution`
- `images` is a required URL-based array for edit flow
- If refs are attached through `images[]`, explicitly name them in the prompt text by character/location and reference image URL or filename

```json
{
  "model": "google/nano-banana-2/edit",
  "aspect_ratio": "16:9",
  "enable_base64_output": false,
  "enable_sync_mode": false,
  "enable_web_search": false,
  "enable_image_search": false,
  "images": ["ref1", "ref2", "ref3"],
  "output_format": "png",
  "prompt": "...",
  "resolution": "2k",
  "media_resolution": "high"
}
```

### Aspect ratio note
For vertical-drama stills, adapt the still stage to the target delivery format when the model supports it. If a clean vertical still is not available, use the best approved composition that preserves identity and geography.

## 2) Video generation

### Kling O3 PRO reference-to-video
**Endpoint:** `POST /model/generateVideo`
**Primary model:** `kwaivgi/kling-video-o3-pro/reference-to-video`

```json
{
  "model": "kwaivgi/kling-video-o3-pro/reference-to-video",
  "images": ["face_url", "halfbody_url", "approved_still_url"],
  "prompt": "...",
  "negative_prompt": "...",
  "duration": 10,
  "aspect_ratio": "16:9",
  "sound": false
}
```

Rules:
- Use `images[]`, not `image`
- Keep refs lean; usually 3 is enough
- Keep total refs <= 4
- Prefer approved still as one of the refs
- For spoken lines, set `sound: true` and include the exact line in the prompt

### Aspect ratio note
- **Blended Leading** usually uses `16:9`
- **Romantic Dorama** and similar vertical serial formats may need `9:16` when supported for the target shot/output
- Match the profile and delivery target instead of assuming one universal ratio

## 3) Polling
**Endpoint:** `GET /model/prediction/{id}`
- Statuses: `created` -> `processing` -> `completed` / `failed`
- Poll every 2–5s, depending on task cost and queue sensitivity
- A simple working pattern is: request generation -> read `data.id` -> poll `GET /model/prediction/{id}` until `completed` or `failed`
- Result URL usually at `data.outputs[0]`
- Download immediately; URLs expire

## 4) Image hosting
- Save public working images under `/home/kira/images/`
- `chmod 644`
- Public URL form: `https://img.britemedia.eu/{filename}`

## 5) Model comparison
| Model | Use case | Notes |
|-------|----------|-------|
| `google/nano-banana-2/edit` | Complex stills | Preferred for hard staging / identity / reflections |
| `alibaba/wan-2.7/image-edit` | Simpler faster stills | Use when refs fit and cost/speed matter |
| `kwaivgi/kling-video-o3-pro/reference-to-video` | Main multi-ref video model | Current baseline for identity-led motion |
| `kwaivgi/kling-v2.1-i2v-pro` | Legacy fallback | Older BL pipeline |
| `bytedance/seedance-v1.5-pro/image-to-video` | Alternative video | One-ref I2V option |
| `bytedance/seedance-2.0/reference-to-video` | Experimental multi-ref video | Treat as unstable until proven |
| `kwaivgi/kling-v3.0-pro/image-to-video` | Newer one-ref video | Useful when a single strong start frame is enough |