atlas-cloud

What this skill does

# Atlas Cloud API Integration Guide

Atlas Cloud is an AI API aggregation platform that provides access to 300+ image, video, and LLM models through a unified interface. This skill helps you quickly integrate Atlas Cloud API into any project.

## Quick Start

### 1. Get an API Key

Create an API Key at [Atlas Cloud Console](https://www.atlascloud.ai/console/api-keys).

### 2. Set Environment Variable

```bash
export ATLASCLOUD_API_KEY="your-api-key-here"
```

## API Architecture

Atlas Cloud has the following API endpoints:

| Endpoint | Base URL | Purpose |
|----------|----------|---------|
| **Media Generation API** | `https://api.atlascloud.ai/api/v1` | Image generation, video generation, poll results, upload media |
| **LLM API** | `https://api.atlascloud.ai/v1` | Chat completions (OpenAI-compatible) |

All requests require the following headers:
```
Authorization: Bearer $ATLASCLOUD_API_KEY
Content-Type: application/json
```

### Full Endpoint List

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/v1/model/generateImage` | Submit image generation task |
| `POST` | `/api/v1/model/generateVideo` | Submit video generation task |
| `GET` | `/api/v1/model/prediction/{id}` | Check generation task status and result |
| `POST` | `/api/v1/model/uploadMedia` | Upload local media file to get a public URL |
| `POST` | `/v1/chat/completions` | LLM chat (OpenAI-compatible format) |
| `GET` | `api.atlascloud.ai/api/v1/models` | List all available models (no auth required) |

## MCP Tools (9 Tools)

If the user has installed the Atlas Cloud MCP Server (`npx atlascloud-mcp`), the following 9 tools are available for direct invocation:

### Model Discovery Tools

#### `atlas_list_models` — List All Models
- **Params**: `type` (optional): `"Text"` | `"Image"` | `"Video"`
- **Purpose**: List all available models, optionally filtered by type
- **Examples**: No params to list all; `type="Image"` for image models only

#### `atlas_search_docs` — Search Models & Docs
- **Params**: `query` (required): Search keyword matching model names, types, providers, tags
- **Purpose**: Fuzzy search models by keyword. Returns detailed API schema info when there's only one match
- **Examples**: `"video generation"`, `"deepseek"`, `"image edit"`, `"qwen"`

#### `atlas_get_model_info` — Get Model Details
- **Params**: `model` (required): Model ID, e.g. `"deepseek-ai/deepseek-v3.2"`
- **Purpose**: Get full model info including API docs, input/output schema, pricing, cURL examples, Playground link
- **Examples**: `model="deepseek-ai/deepseek-v3.2"`

### Generation Tools

#### `atlas_generate_image` — Generate Image
- **Params**:
  - `model` (required): Exact image model ID
  - `params` (required): Model-specific parameter JSON object (e.g. `prompt`, `image_size`, etc.)
- **Purpose**: Submit image generation task, returns prediction ID. Must verify model ID first via `atlas_list_models` or `atlas_search_docs`
- **Returns**: prediction ID — use `atlas_get_prediction` to check result

#### `atlas_generate_video` — Generate Video
- **Params**:
  - `model` (required): Exact video model ID
  - `params` (required): Model-specific parameter JSON object (e.g. `prompt`, `duration`, `aspect_ratio`, `image_url`, etc.)
- **Purpose**: Submit video generation task, returns prediction ID
- **Returns**: prediction ID — video generation typically takes 1-5 minutes

#### `atlas_quick_generate` — Quick Generate (One-Step)
- **Params**:
  - `model_keyword` (required): Model search keyword, e.g. `"nano banana"`, `"seedream"`, `"kling v3"`
  - `type` (required): `"Image"` | `"Video"`
  - `prompt` (required): Text description of what to generate
  - `image_url` (optional): Source image URL for image-to-video or image editing models
  - `extra_params` (optional): Additional model-specific parameters to override defaults
- **Purpose**: One-step generation — automatically searches model → fetches schema → builds params → submits task. No need to know exact model IDs
- **Examples**: `model_keyword="seedream v5", type="Image", prompt="a cute cat"`

#### `atlas_chat` — LLM Chat
- **Params**:
  - `model` (required): LLM model ID
  - `messages` (required): Array of message objects with `role` and `content`
  - `temperature` (optional): Sampling temperature 0-2
  - `max_tokens` (optional): Maximum response tokens
  - `top_p` (optional): Nucleus sampling parameter 0-1
- **Purpose**: Send OpenAI-compatible chat completion request

### Utility Tools

#### `atlas_get_prediction` — Check Generation Result
- **Params**: `prediction_id` (required): Prediction ID returned from a generation request
- **Purpose**: Check image/video generation task status and result
- **Status values**: `starting` → `processing` → `completed`/`succeeded`/`failed`
- **On completion**: Returns output URL list — can download locally via curl/wget

#### `atlas_upload_media` — Upload Media File
- **Params**: `file_path` (required): Absolute path to the local file
- **Purpose**: Upload local image/media file to Atlas Cloud and get a publicly accessible URL. Use this to provide `image_url` for image editing or image-to-video models
- **Workflow**:
  1. Upload local file with this tool to get a URL
  2. Use the returned URL as the `image_url` parameter for `atlas_generate_image`, `atlas_generate_video`, or `atlas_quick_generate`
- **Note**: Only for Atlas Cloud generation tasks. Uploaded files are temporary and will be cleaned up periodically. Uploading content unrelated to generation tasks (e.g., bulk hosting, illegal content, or abuse) may result in API key suspension

## Image Generation

Image generation is an asynchronous two-step process: **submit task → poll result**.

### Submit Image Generation Task

```
POST https://api.atlascloud.ai/api/v1/model/generateImage
```

Request body:
```json
{
  "model": "bytedance/seedream-v5.0-lite",
  "prompt": "A beautiful sunset over mountains",
  "image_size": "1024x1024"
}
```

Response:
```json
{
  "code": 200,
  "data": {
    "id": "prediction_abc123",
    "status": "starting"
  }
}
```

Different models accept different parameters. Common parameters include:
- `prompt` (required): Image description
- `image_size` / `width` + `height`: Dimensions
- `num_inference_steps`: Inference steps
- `guidance_scale`: Guidance scale
- `image_url`: Input image (for image-to-image models)

### Poll Generation Result

```
GET https://api.atlascloud.ai/api/v1/model/prediction/{prediction_id}
```

Response:
```json
{
  "code": 200,
  "data": {
    "id": "prediction_abc123",
    "status": "completed",
    "outputs": ["https://cdn.atlascloud.ai/generated/xxx.png"]
  }
}
```

Possible `status` values: `starting` → `processing` → `completed` / `failed`

Image generation typically takes **10-30 seconds**. Poll every **3 seconds**.

## Video Generation

Video generation follows the exact same flow as image generation, just with a different endpoint.

### Submit Video Generation Task

```
POST https://api.atlascloud.ai/api/v1/model/generateVideo
```

Request body:
```json
{
  "model": "bytedance/seedance-2.0/text-to-video",
  "prompt": "A rocket launching into space, cinematic lighting",
  "duration": 5,
  "resolution": "1080p",
  "ratio": "16:9",
  "generate_audio": true
}
```

Common video model parameters:
- `prompt` (required for T2V): Video description
- `image` / `image_url`: Input image (for image-to-video models — Seedance 2.0 uses `image`, Kling uses `image_url`)
- `duration`: Video duration in seconds (Seedance 2.0 supports 4-15, or `-1` for auto)
- `resolution`: `"480p"` / `"720p"` / `"1080p"` (Seedance 2.0)
- `aspect_ratio` / `ratio`: Aspect ratio (e.g., `"16:9"`, `"9:16"`, `"1:1"`, `"21:9"`, `"adaptive"`)
- `generate_audio`: Seedance 2.0 generates synchronized native audio (voice/SFX/BGM) jointly with video. Default `true`
- `web_search`: Seedance 2.0 T2V only — enable to ground generation in real-world references. Default `false`

> Different video models accept different par