# Audio — TTS, Music Generation & Speech-to-Text

All three audio tasks share one endpoint (`POST /api/v1/model/generateAudio`) and the same
submit → poll flow. What changes is the model and its input fields:

| Task | Example models | Main input fields |
|------|----------------|-------------------|
| Text-to-speech (TTS) | `bytedance/seed-audio-1.0`, `xai/tts-v1`, ElevenLabs | `text` (+ voice/format/sample_rate) |
| Music / songs | `suno/chirp-v5`, `minimax/music-2.6` | `prompt` and/or `lyrics` |
| Speech-to-text (ASR) | `bytedance/seed-asr-2.0`, `xai/stt-v1` | `audio_url` (+ language/format) |

> Discover audio models at runtime with `GET /api/v1/models` filtered to `type == "Audio"`,
> then fetch the model's schema before building the request — field names vary by model.
> For local audio files, upload first (see `references/upload.md`) to get a URL.

## Table of Contents
- [Python](#python)
- [Node.js / TypeScript](#nodejs--typescript)
- [cURL](#curl)

---

## Python

```python
import requests
import time
import os

ATLAS_API_KEY = os.environ.get("ATLASCLOUD_API_KEY")
BASE_URL = "https://api.atlascloud.ai/api/v1"

HEADERS = {
    "Authorization": f"Bearer {ATLAS_API_KEY}",
    "Content-Type": "application/json",
}


def run_audio_task(model: str, **params) -> list[str]:
    """
    Submit an audio task (TTS, music, or speech-to-text) and return its outputs.

    Returns:
        List of outputs — audio file URLs for TTS/music, transcribed text for ASR.
    """
    # Step 1: Submit task
    payload = {"model": model, **params}
    resp = requests.post(f"{BASE_URL}/model/generateAudio", json=payload, headers=HEADERS, timeout=50)
    resp.raise_for_status()
    prediction_id = resp.json()["data"]["id"]
    print(f"Task submitted. Prediction ID: {prediction_id}")

    # Step 2: Poll for result (TTS/ASR: ~10-60s; music can take a few minutes)
    for _ in range(120):
        time.sleep(3)
        result = requests.get(f"{BASE_URL}/model/prediction/{prediction_id}", headers=HEADERS, timeout=30)
        result.raise_for_status()
        data = result.json()["data"]
        status = data.get("status")
        if status in ("completed", "succeeded"):
            return data["outputs"]
        if status == "failed":
            raise RuntimeError(f"Audio task failed: {data.get('error')}")
    raise TimeoutError("Audio task timed out")


# --- Text-to-speech ---
urls = run_audio_task("bytedance/seed-audio-1.0", text="Welcome to Atlas Cloud.")
print("audio url:", urls[0])

# --- Music generation ---
urls = run_audio_task("suno/chirp-v5", prompt="upbeat synthwave song about coding at night")
print("song url:", urls[0])

# --- Speech-to-text ---
texts = run_audio_task(
    "bytedance/seed-asr-2.0",
    audio_url="https://example.com/meeting.mp3",
    enable_punc=True,
)
print("transcript:", texts[0])
```

---

## Node.js / TypeScript

```typescript
const BASE_URL = "https://api.atlascloud.ai/api/v1";
const HEADERS = {
  Authorization: `Bearer ${process.env.ATLASCLOUD_API_KEY}`,
  "Content-Type": "application/json",
};

/** Submit an audio task (TTS, music, or ASR) and return its outputs. */
async function runAudioTask(model: string, params: Record<string, unknown>): Promise<string[]> {
  // Step 1: Submit task
  const submit = await fetch(`${BASE_URL}/model/generateAudio`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({ model, ...params }),
  });
  if (!submit.ok) throw new Error(`submit failed: HTTP ${submit.status}`);
  const { data } = await submit.json();
  console.log(`Task submitted. Prediction ID: ${data.id}`);

  // Step 2: Poll for result (TTS/ASR: ~10-60s; music can take a few minutes)
  for (let i = 0; i < 120; i++) {
    await new Promise((r) => setTimeout(r, 3000));
    const poll = await fetch(`${BASE_URL}/model/prediction/${data.id}`, { headers: HEADERS });
    const { data: result } = await poll.json();
    if (["completed", "succeeded"].includes(result.status)) return result.outputs;
    if (result.status === "failed") throw new Error(`Audio task failed: ${result.error}`);
  }
  throw new Error("Audio task timed out");
}

// TTS
console.log(await runAudioTask("bytedance/seed-audio-1.0", { text: "Welcome to Atlas Cloud." }));
// Music
console.log(await runAudioTask("suno/chirp-v5", { prompt: "gentle acoustic morning jingle" }));
// Speech-to-text
console.log(await runAudioTask("bytedance/seed-asr-2.0", { audio_url: "https://example.com/interview.mp3" }));
```

---

## cURL

```bash
# --- Text-to-speech: submit ---
curl -s -X POST "https://api.atlascloud.ai/api/v1/model/generateAudio" \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "bytedance/seed-audio-1.0", "text": "Welcome to Atlas Cloud."}'

# --- Music: submit ---
curl -s -X POST "https://api.atlascloud.ai/api/v1/model/generateAudio" \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "suno/chirp-v5", "prompt": "upbeat synthwave song about coding at night"}'

# --- Speech-to-text: submit ---
curl -s -X POST "https://api.atlascloud.ai/api/v1/model/generateAudio" \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "bytedance/seed-asr-2.0", "audio_url": "https://example.com/meeting.mp3", "enable_punc": true}'

# --- Poll result (same for all three) ---
curl -s "https://api.atlascloud.ai/api/v1/model/prediction/PREDICTION_ID" \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
```

## Notes

- **Model schemas differ** — always fetch the model schema (`references/models.md` explains how) before hardcoding fields. E.g. some TTS models take `references` for voice cloning; Suno accepts `lyrics`/style tags; seed-asr supports `enable_speaker_info`, `show_utterances`.
- **ASR output is text**, not a URL: `outputs[0]` is the transcript itself.
- **Content moderation**: TTS/music inputs go through moderation — medical/violent wording can be blocked.
- **POST is not retried** (billable); GETs can retry with backoff. Same policy as image/video.

# Image Generation — Complete Code Templates

## Table of Contents
- [Python](#python)
- [Node.js / TypeScript](#nodejs--typescript)
- [cURL](#curl)

---

## Python

```python
import requests
import time
import os

ATLAS_API_KEY = os.environ.get("ATLASCLOUD_API_KEY")
BASE_URL = "https://api.atlascloud.ai/api/v1"

HEADERS = {
    "Authorization": f"Bearer {ATLAS_API_KEY}",
    "Content-Type": "application/json",
}


def generate_image(model: str, prompt: str, **kwargs) -> str:
    """
    Generate an image and return the output URL.

    Args:
        model: Model ID, e.g. "bytedance/seedream-v5.0-lite"
        prompt: Text description of the image
        **kwargs: Additional model-specific parameters (image_size, num_inference_steps, etc.)

    Returns:
        URL of the generated image
    """
    # Step 1: Submit generation task
    payload = {"model": model, "prompt": prompt, **kwargs}
    resp = requests.post(f"{BASE_URL}/model/generateImage", json=payload, headers=HEADERS, timeout=50)
    resp.raise_for_status()
    data = resp.json()

    prediction_id = data["data"]["id"]
    print(f"Task submitted. Prediction ID: {prediction_id}")

    # Step 2: Poll for result
    for _ in range(200):  # ~10 min max
        time.sleep(3)
        result = requests.get(f"{BASE_URL}/model/prediction/{prediction_id}", headers=HEADERS, timeout=30)
        result.raise_for_status()
        result_data = result.json()["data"]

        status = result_data.get("status", "unknown")
        if status in ("completed", "succeeded"):
            outputs = result_data.get("outputs") or result_data.get("output", [])
            if isinstance(outputs, str):
                outputs = [outputs]
            print(f"Generation completed: {outputs[0]}")
            return outputs[0]
        elif status == "failed":
            error = result_data.get("error", "Unknown error")
            raise RuntimeError(f"Generation failed: {error}")
        else:
            print(f"Status: {status}...")

    raise TimeoutError("Generation timed out")


# Usage
if __name__ == "__main__":
    url = generate_image(
        model="bytedance/seedream-v5.0-lite",
        prompt="A serene Japanese garden with cherry blossoms",
        image_size="1024x1024",
    )
    print(f"Image URL: {url}")
```

### Image-to-Image (Python)

```python
# For models that accept an input image
url = generate_image(
    model="some-model/image-to-image",
    prompt="Transform this into a watercolor painting",
    image_url="https://example.com/input-photo.jpg",
)
```

---

## Node.js / TypeScript

```typescript
const ATLAS_API_KEY = process.env.ATLASCLOUD_API_KEY;
const BASE_URL = 'https://api.atlascloud.ai/api/v1';

const headers = {
  Authorization: `Bearer ${ATLAS_API_KEY}`,
  'Content-Type': 'application/json',
};

interface GenerationResult {
  id: string;
  status: string;
  outputs?: string[];
  output?: string | string[];
  error?: string;
}

async function generateImage(
  model: string,
  prompt: string,
  extraParams: Record<string, unknown> = {}
): Promise<string> {
  // Step 1: Submit generation task
  const submitResp = await fetch(`${BASE_URL}/model/generateImage`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ model, prompt, ...extraParams }),
  });

  if (!submitResp.ok) {
    throw new Error(`Submit failed: ${submitResp.status} ${await submitResp.text()}`);
  }

  const submitData = await submitResp.json();
  const predictionId = submitData.data.id;
  console.log(`Task submitted. Prediction ID: ${predictionId}`);

  // Step 2: Poll for result
  for (let i = 0; i < 200; i++) {
    await new Promise((r) => setTimeout(r, 3000));

    const pollResp = await fetch(`${BASE_URL}/model/prediction/${predictionId}`, { headers });
    if (!pollResp.ok) {
      throw new Error(`Poll failed: ${pollResp.status}`);
    }

    const result: GenerationResult = (await pollResp.json()).data;

    if (result.status === 'completed' || result.status === 'succeeded') {
      const outputs = result.outputs ?? (Array.isArray(result.output) ? result.output : result.output ? [result.output] : []);
      console.log(`Generation completed: ${outputs[0]}`);
      return outputs[0];
    }

    if (result.status === 'failed') {
      throw new Error(`Generation failed: ${result.error || 'Unknown error'}`);
    }

    console.log(`Status: ${result.status}...`);
  }

  throw new Error('Generation timed out');
}

// Usage
const imageUrl = await generateImage(
  'bytedance/seedream-v5.0-lite',
  'A serene Japanese garden with cherry blossoms',
  { image_size: '1024x1024' }
);
console.log(`Image URL: ${imageUrl}`);
```

---

## cURL

```bash
# Step 1: Submit generation task
PREDICTION_ID=$(curl -s -X POST "https://api.atlascloud.ai/api/v1/model/generateImage" \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedream-v5.0-lite",
    "prompt": "A serene Japanese garden with cherry blossoms",
    "image_size": "1024x1024"
  }' | jq -r '.data.id')

echo "Prediction ID: $PREDICTION_ID"

# Step 2: Poll for result
while true; do
  sleep 3
  RESULT=$(curl -s "https://api.atlascloud.ai/api/v1/model/prediction/$PREDICTION_ID" \
    -H "Authorization: Bearer $ATLASCLOUD_API_KEY")

  STATUS=$(echo "$RESULT" | jq -r '.data.status')

  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "succeeded" ]; then
    echo "Image URL:"
    echo "$RESULT" | jq -r '.data.outputs[0]'
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Failed:"
    echo "$RESULT" | jq -r '.data.error'
    break
  else
    echo "Status: $STATUS..."
  fi
done
```

# LLM Chat API — Complete Code Templates

Atlas Cloud LLM API is fully OpenAI-compatible. You can use the OpenAI SDK or raw HTTP requests.

## Table of Contents
- [Python (OpenAI SDK)](#python-openai-sdk)
- [Python (Raw HTTP)](#python-raw-http)
- [Node.js / TypeScript (OpenAI SDK)](#nodejs--typescript-openai-sdk)
- [Node.js / TypeScript (Raw fetch)](#nodejs--typescript-raw-fetch)
- [Streaming Responses](#streaming-responses)
- [cURL](#curl)

---

## Python (OpenAI SDK)

```python
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("ATLASCLOUD_API_KEY"),
    base_url="https://api.atlascloud.ai/v1",
)

response = client.chat.completions.create(
    model="qwen/qwen3.5-397b-a17b",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain quantum computing in simple terms."},
    ],
    max_tokens=1024,
    temperature=0.7,
)

print(response.choices[0].message.content)
print(f"Tokens used: {response.usage.total_tokens}")
```

---

## Python (Raw HTTP)

```python
import requests
import os

ATLAS_API_KEY = os.environ.get("ATLASCLOUD_API_KEY")

response = requests.post(
    "https://api.atlascloud.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {ATLAS_API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen/qwen3.5-397b-a17b",
        "messages": [
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "Explain quantum computing in simple terms."},
        ],
        "max_tokens": 1024,
        "temperature": 0.7,
    },
    timeout=120,
)

data = response.json()
print(data["choices"][0]["message"]["content"])
```

---

## Node.js / TypeScript (OpenAI SDK)

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ATLASCLOUD_API_KEY,
  baseURL: 'https://api.atlascloud.ai/v1',
});

const response = await client.chat.completions.create({
  model: 'qwen/qwen3.5-397b-a17b',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Explain quantum computing in simple terms.' },
  ],
  max_tokens: 1024,
  temperature: 0.7,
});

console.log(response.choices[0].message.content);
console.log(`Tokens used: ${response.usage?.total_tokens}`);
```

---

## Node.js / TypeScript (Raw fetch)

```typescript
const response = await fetch('https://api.atlascloud.ai/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ATLASCLOUD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'qwen/qwen3.5-397b-a17b',
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'Explain quantum computing in simple terms.' },
    ],
    max_tokens: 1024,
    temperature: 0.7,
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);
```

---

## Streaming Responses

### Python (OpenAI SDK)

```python
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("ATLASCLOUD_API_KEY"),
    base_url="https://api.atlascloud.ai/v1",
)

stream = client.chat.completions.create(
    model="qwen/qwen3.5-397b-a17b",
    messages=[{"role": "user", "content": "Write a short poem about the ocean."}],
    max_tokens=512,
    stream=True,
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)
print()
```

### Node.js / TypeScript (OpenAI SDK)

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ATLASCLOUD_API_KEY,
  baseURL: 'https://api.atlascloud.ai/v1',
});

const stream = await client.chat.completions.create({
  model: 'qwen/qwen3.5-397b-a17b',
  messages: [{ role: 'user', content: 'Write a short poem about the ocean.' }],
  max_tokens: 512,
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) {
    process.stdout.write(content);
  }
}
console.log();
```

### Raw SSE Streaming (Node.js)

```typescript
const response = await fetch('https://api.atlascloud.ai/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ATLASCLOUD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'qwen/qwen3.5-397b-a17b',
    messages: [{ role: 'user', content: 'Write a short poem about the ocean.' }],
    max_tokens: 512,
    stream: true,
  }),
});

const reader = response.body!.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const text = decoder.decode(value, { stream: true });
  const lines = text.split('\n').filter((line) => line.startsWith('data: '));

  for (const line of lines) {
    const data = line.slice(6); // Remove "data: "
    if (data === '[DONE]') break;

    const parsed = JSON.parse(data);
    const content = parsed.choices[0]?.delta?.content;
    if (content) {
      process.stdout.write(content);
    }
  }
}
```

---

## cURL

### Basic Request

```bash
curl -X POST "https://api.atlascloud.ai/v1/chat/completions" \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3.5-397b-a17b",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain quantum computing in simple terms."}
    ],
    "max_tokens": 1024,
    "temperature": 0.7
  }'
```

### Streaming

```bash
curl -X POST "https://api.atlascloud.ai/v1/chat/completions" \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "qwen/qwen3.5-397b-a17b",
    "messages": [
      {"role": "user", "content": "Write a short poem about the ocean."}
    ],
    "max_tokens": 512,
    "stream": true
  }'
```

# Atlas Cloud — Model Reference

## CRITICAL: Fetch From the API — Do Not Fabricate

> The tables in this file are a **snapshot, not a source of truth**. Model IDs, prices, parameter names, defaults, and enums all change. Any ID, parameter, or schema detail in code or user-facing output MUST come from a live API fetch performed in the current session.

**Mandatory workflow — no exceptions:**

1. **Always fetch the model list first.** No authentication required:
   ```
   GET https://api.atlascloud.ai/api/v1/models
   ```
   If the MCP server is installed, call `atlas_list_models` or `atlas_search_docs` instead — same live data.

2. **Filter to `display_console: true`.** Any model with `display_console: false` is internal and will fail for regular users. Do not surface those IDs.

3. **Before writing a request body, fetch the schema.** Never guess parameter names, enums, defaults, or required fields. For any target model:
   - MCP: `atlas_get_model_info` with the exact model ID
   - HTTP: GET the `schema` URL from the model entry (OpenAPI JSON) and read `components.schemas.Input.properties`

   Build the payload strictly from the fields listed there. If a parameter you want isn't in the schema, it doesn't exist on that model.

4. **Hardcoded IDs are only acceptable after verification.** Either fetch and filter at runtime, or confirm the ID against a live `GET /models` response in the same session before embedding it.

**Red flags — stop and fetch if you catch yourself doing any of these:**
- Copying a model ID from memory or from these tables without a same-session API check
- Guessing a parameter name (e.g. assuming `aspect_ratio` when the model uses `ratio`, or `image_url` when it uses `image`)
- Sending a parameter not listed in the schema
- Reporting a price to the user that wasn't in the live API response

---

## Image Models (priced per image)

| Model ID | Name | Price |
|----------|------|-------|
| `google/nano-banana-2/text-to-image` | Nano Banana 2 Text-to-Image | $0.072/image |
| `google/nano-banana-2/text-to-image-developer` | Nano Banana 2 Developer | $0.056/image |
| `google/nano-banana-2/edit` | Nano Banana 2 Edit | $0.072/image |
| `google/nano-banana-2/edit-developer` | Nano Banana 2 Edit Developer | $0.056/image |
| `bytedance/seedream-v5.0-lite` | Seedream v5.0 Lite | $0.032/image |
| `bytedance/seedream-v5.0-lite/edit` | Seedream v5.0 Lite Edit | $0.032/image |
| `bytedance/seedream-v5.0-lite/sequential` | Seedream v5.0 Lite Sequential | $0.032/image |
| `alibaba/qwen-image/edit-plus-20251215` | Qwen-Image Edit Plus | $0.021/image |
| `alibaba/wan-2.6/image-edit` | Wan-2.6 Image Edit | $0.021/image |
| `z-image/turbo` | Z-Image Turbo | $0.01/image |
| `bytedance/seedream-v4.5` | Seedream v4.5 | $0.036/image |

## Video Models (priced per second of output; figures are the 480p entry price — 720p/1080p cost more)

| Model ID | Name | Price |
|----------|------|-------|
| `bytedance/seedance-2.5/text-to-video` | **Seedance 2.5 Text-to-Video** (native audio, 4-30s, native up to 1080p / 4K via SR) | $0.134/s |
| `bytedance/seedance-2.5/image-to-video` | **Seedance 2.5 Image-to-Video** (first+last frame, native audio) | $0.134/s |
| `bytedance/seedance-2.5/reference-to-video` | **Seedance 2.5 Reference-to-Video** (multimodal: up to 30 images + 10 videos + 10 audio) | $0.134/s |
| `bytedance/seedance-2.0/text-to-video` | Seedance 2.0 Text-to-Video (native audio, 4-15s) | $0.112/s |
| `bytedance/seedance-2.0-fast/text-to-video` | Seedance 2.0 Fast Text-to-Video | $0.072/s |
| `bytedance/seedance-2.0-fast/image-to-video` | Seedance 2.0 Fast Image-to-Video | $0.072/s |
| `bytedance/seedance-2.0-fast/reference-to-video` | Seedance 2.0 Fast Reference-to-Video | $0.072/s |
| `bytedance/seedance-2.0-mini/text-to-video` | Seedance 2.0 Mini Text-to-Video (cheapest Seedance tier) | $0.039/s |
| `kwaivgi/kling-v3.0-std/text-to-video` | Kling v3.0 Std Text-to-Video | $0.071/s |
| `kwaivgi/kling-v3.0-std/image-to-video` | Kling v3.0 Std Image-to-Video | $0.071/s |
| `kwaivgi/kling-v3.0-pro/text-to-video` | Kling v3.0 Pro Text-to-Video | $0.095/s |
| `kwaivgi/kling-v3.0-pro/image-to-video` | Kling v3.0 Pro Image-to-Video | $0.095/s |
| `kwaivgi/kling-video-o3-pro/text-to-video` | Kling Video O3 Pro Text-to-Video | $0.095/s |
| `vidu/q3-pro/text-to-video` | Vidu Q3 Pro Text-to-Video | $0.042/s |
| `vidu/q3-pro/image-to-video` | Vidu Q3 Pro Image-to-Video | $0.042/s |
| `alibaba/wan-2.7/image-to-video` | Wan-2.7 Image-to-Video (newest Wan on Atlas Cloud) | $0.1/s |
| `bytedance/seedance-v1.5-pro/text-to-video` | Seedance v1.5 Pro Text-to-Video | $0.047/s |
| `bytedance/seedance-v1.5-pro/image-to-video` | Seedance v1.5 Pro Image-to-Video | $0.047/s |
| `bytedance/seedance-v1.5-pro/image-to-video-fast` | Seedance v1.5 Pro I2V Fast | $0.018/s |
| `alibaba/wan-2.6/image-to-video-flash` | Wan-2.6 Image-to-Video Flash | $0.018/s |
| `kwaivgi/kling-v2.6-pro/avatar` | Kling v2.6 Pro Avatar | $0.095/s |
| `kwaivgi/kling-v2.6-std/avatar` | Kling v2.6 Std Avatar | $0.048/s |
| `kwaivgi/kling-v3.0-pro/motion-control` | Kling v3.0 Pro Motion Control | $0.143/s |

## LLM Models (priced per million tokens)

| Model ID | Name | Input | Output |
|----------|------|-------|--------|
| `qwen/qwen3.5-397b-a17b` | Qwen3.5 397B A17B | $0.55/M | $3.5/M |
| `qwen/qwen3.5-122b-a10b` | Qwen3.5 122B A10B | $0.3/M | $2.4/M |
| `qwen/qwen3.5-35b-a3b` | Qwen3.5 35B A3B | $0.225/M | $1.8/M |
| `qwen/qwen3.5-27b` | Qwen3.5 27B | $0.27/M | $2.16/M |
| `qwen/qwen3-coder-next` | Qwen3 Coder Next | $0.18/M | $1.35/M |
| `moonshotai/kimi-k2.5` | Kimi K2.5 | $0.5/M | $2.6/M |
| `zai-org/glm-5` | GLM 5 | $0.95/M | $3.15/M |
| `minimaxai/minimax-m2.5` | MiniMax M2.5 | $0.295/M | $1.2/M |
| `deepseek-ai/deepseek-v3.2-speciale` | DeepSeek V3.2 Speciale | $0.4/M | $1.2/M |
| `qwen/qwen3-max-2026-01-23` | Qwen3 Max | $1.2/M | $6/M |
| `zai-org/glm-4.7` | GLM 4.7 | $0.52/M | $1.75/M |
| `minimaxai/minimax-m2.1` | MiniMax M2.1 | $0.29/M | $0.95/M |

## Model Type → Endpoint Mapping

| Type | Endpoint |
|------|----------|
| `"Image"` | `POST https://api.atlascloud.ai/api/v1/model/generateImage` |
| `"Video"` | `POST https://api.atlascloud.ai/api/v1/model/generateVideo` |
| `"Audio"` | `POST https://api.atlascloud.ai/api/v1/model/generateAudio` |
| `"Text"` | `POST https://api.atlascloud.ai/v1/chat/completions` |

Type notes: 3D models (image/text-to-3D) are `"Image"` type; TTS, music, and speech-to-text (ASR) models are all `"Audio"` type; lipsync / talking-avatar models are `"Video"` type. See `references/audio-gen.md` for audio patterns.

## Price Structure

The price field in the API response has this structure:

- **Image/Video models**: Use `price.actual.base_price` — this is the cost per generation
- **LLM models**: Use `price.actual.input_price` and `price.actual.output_price` — cost per million tokens
- Fallback chain: `price.actual` → `price.sku.text` → top-level `inputPrice`/`basePrice`
- `price.discount`: Discount percentage (e.g., "70" means 70% of original price)

## Model Schema

Each model has a `schema` field pointing to an OpenAPI JSON file that describes all available parameters. Fetch it to understand what a specific model accepts:

```python
import requests

# Get public model list
models = requests.get("https://api.atlascloud.ai/api/v1/models").json()["data"]
public_models = [m for m in models if m.get("display_console") == True]

# Find a specific model
model = next(m for m in public_models if m["model"] == "bytedance/seedream-v5.0-lite")

# Fetch its parameter schema
if model.get("schema"):
    schema = requests.get(model["schema"]).json()
    # schema["components"]["schemas"]["Input"]["properties"] contains all parameters
```

# Quick Generate — Complete Code Templates

One-step generation that automatically searches for a model by keyword, fetches its schema, builds parameters, and submits the task. No need to know exact model IDs.

## Table of Contents
- [Python](#python)
- [Node.js / TypeScript](#nodejs--typescript)

---

## Python

```python
import requests
import time
import os
import re

ATLAS_API_KEY = os.environ.get("ATLASCLOUD_API_KEY")
BASE_URL = "https://api.atlascloud.ai/api/v1"
MODELS_URL = "https://api.atlascloud.ai/api/v1/models"

HEADERS = {
    "Authorization": f"Bearer {ATLAS_API_KEY}",
    "Content-Type": "application/json",
}


def search_models(keyword: str, model_type: str = None) -> list:
    """
    Search models by keyword with fuzzy matching.

    Args:
        keyword: Search keyword (e.g. "seedream", "kling v3", "nano banana")
        model_type: Filter by type: "Image", "Video", or "Text"

    Returns:
        List of matching model dicts
    """
    resp = requests.get(MODELS_URL, timeout=30)
    resp.raise_for_status()
    models = resp.json()["data"]

    # Filter public models only
    models = [m for m in models if m.get("display_console") == True]

    if model_type:
        models = [m for m in models if m.get("type") == model_type]

    # Normalize keyword for fuzzy matching
    keyword_normalized = re.sub(r"[-_/\s.]+", "", keyword.lower())

    results = []
    for m in models:
        searchable = f"{m.get('model', '')} {m.get('displayName', '')} {' '.join(m.get('tags', []))}".lower()
        searchable_normalized = re.sub(r"[-_/\s.]+", "", searchable)

        if keyword_normalized in searchable_normalized:
            results.append(m)

    return results


def get_model_schema(model: dict) -> dict | None:
    """Fetch the OpenAPI schema for a model."""
    schema_url = model.get("schema")
    if not schema_url:
        return None
    try:
        resp = requests.get(schema_url, timeout=30)
        resp.raise_for_status()
        return resp.json()
    except Exception:
        return None


def build_params(
    schema: dict | None,
    model_id: str,
    prompt: str,
    image_url: str = None,
    extra_params: dict = None,
) -> dict:
    """Build request params from schema, auto-filling prompt and image_url fields."""
    params = {"model": model_id}

    if schema:
        input_schema = schema.get("components", {}).get("schemas", {}).get("Input", {})
        properties = input_schema.get("properties", {})
        required = input_schema.get("required", [])

        # Find and set prompt field
        prompt_field = None
        for key in properties:
            if key in ("prompt", "text", "text_prompt"):
                prompt_field = key
                break
            desc = properties[key].get("description", "").lower()
            if "prompt" in desc:
                prompt_field = key
                break
        if prompt_field:
            params[prompt_field] = prompt

        # Find and set image URL field
        if image_url:
            image_field = None
            for key in properties:
                if key in ("image_url", "image", "input_image", "init_image", "source_image"):
                    image_field = key
                    break
                desc = properties[key].get("description", "").lower()
                if "image url" in desc or "input image" in desc:
                    image_field = key
                    break
            if image_field:
                params[image_field] = image_url

        # Fill required fields with defaults
        for key in required:
            if key not in params:
                prop = properties.get(key, {})
                if prop.get("default") is not None:
                    params[key] = prop["default"]
    else:
        params["prompt"] = prompt
        if image_url:
            params["image_url"] = image_url

    # Apply user overrides
    if extra_params:
        params.update(extra_params)

    return params


def quick_generate(
    model_keyword: str,
    gen_type: str,
    prompt: str,
    image_url: str = None,
    extra_params: dict = None,
) -> str:
    """
    One-step generation: search model → fetch schema → build params → submit.

    Args:
        model_keyword: Keyword to search for the model (e.g. "seedream v5", "kling v3")
        gen_type: "Image" or "Video"
        prompt: Text description of what to generate
        image_url: Optional source image URL for image-to-video or image editing
        extra_params: Optional dict of additional model parameters

    Returns:
        Prediction ID to check result with
    """
    # Step 1: Search for model
    matches = search_models(model_keyword, gen_type)
    if not matches:
        raise ValueError(f"No {gen_type} model found for '{model_keyword}'. Check available models first.")

    model = matches[0]
    model_id = model["model"]
    print(f"Using model: {model.get('displayName', model_id)} ({model_id})")

    if len(matches) > 1:
        others = [m.get("displayName", m["model"]) for m in matches[1:5]]
        print(f"Other candidates: {', '.join(others)}")

    # Step 2: Fetch schema
    schema = get_model_schema(model)

    # Step 3: Build params
    params = build_params(schema, model_id, prompt, image_url, extra_params)

    # Step 4: Submit generation
    endpoint = "generateImage" if gen_type == "Image" else "generateVideo"
    resp = requests.post(f"{BASE_URL}/model/{endpoint}", json=params, headers=HEADERS, timeout=50)
    resp.raise_for_status()

    prediction_id = resp.json()["data"]["id"]
    wait_time = "10-30 seconds" if gen_type == "Image" else "1-5 minutes"
    print(f"Generation submitted! Prediction ID: {prediction_id}")
    print(f"Expected wait time: {wait_time}")

    return prediction_id


def poll_result(prediction_id: str) -> str:
    """Poll for generation result and return the output URL."""
    for _ in range(200):
        time.sleep(3)
        result = requests.get(f"{BASE_URL}/model/prediction/{prediction_id}", headers=HEADERS, timeout=30)
        result.raise_for_status()
        data = result.json()["data"]
        status = data.get("status", "unknown")

        if status in ("completed", "succeeded"):
            outputs = data.get("outputs") or data.get("output", [])
            if isinstance(outputs, str):
                outputs = [outputs]
            return outputs[0]
        elif status == "failed":
            raise RuntimeError(f"Generation failed: {data.get('error')}")
        print(f"Status: {status}...")

    raise TimeoutError("Generation timed out")


# Usage examples
if __name__ == "__main__":
    # Example 1: Quick image generation
    pred_id = quick_generate(
        model_keyword="seedream v5",
        gen_type="Image",
        prompt="A serene Japanese garden with cherry blossoms",
        extra_params={"image_size": "1024x1024"},
    )
    url = poll_result(pred_id)
    print(f"Image URL: {url}")

    # Example 2: Quick video generation
    pred_id = quick_generate(
        model_keyword="kling v3",
        gen_type="Video",
        prompt="A rocket launching into space with dramatic clouds",
        extra_params={"duration": 5, "aspect_ratio": "16:9"},
    )
    url = poll_result(pred_id)
    print(f"Video URL: {url}")

    # Example 3: Image-to-video with local file upload
    # First upload local image
    with open("/path/to/photo.jpg", "rb") as f:
        files = {"file": (os.path.basename("/path/to/photo.jpg"), f)}
        upload_resp = requests.post(
            f"{BASE_URL}/model/uploadMedia",
            headers={"Authorization": f"Bearer {ATLAS_API_KEY}"},
            files=files,
            timeout=60,
        )
    image_url = upload_resp.json()["data"]["download_url"]

    # Then quick generate video from uploaded image
    pred_id = quick_generate(
        model_keyword="kling v3 image",
        gen_type="Video",
        prompt="Camera slowly pans right with cinematic lighting",
        image_url=image_url,
        extra_params={"duration": 5},
    )
    url = poll_result(pred_id)
    print(f"Video URL: {url}")
```

---

## Node.js / TypeScript

```typescript
const ATLAS_API_KEY = process.env.ATLASCLOUD_API_KEY;
const BASE_URL = 'https://api.atlascloud.ai/api/v1';
const MODELS_URL = 'https://api.atlascloud.ai/api/v1/models';

const headers = {
  Authorization: `Bearer ${ATLAS_API_KEY}`,
  'Content-Type': 'application/json',
};

interface Model {
  model: string;
  displayName?: string;
  type: string;
  tags?: string[];
  schema?: string;
  display_console?: boolean;
}

async function searchModels(keyword: string, type?: string): Promise<Model[]> {
  const resp = await fetch(MODELS_URL);
  if (!resp.ok) throw new Error(`Failed to fetch models: ${resp.status}`);
  const models: Model[] = (await resp.json()).data;

  // Filter public models
  let filtered = models.filter((m) => m.display_console === true);
  if (type) filtered = filtered.filter((m) => m.type === type);

  // Fuzzy match
  const normalized = keyword.toLowerCase().replace(/[-_/\s.]+/g, '');
  return filtered.filter((m) => {
    const searchable = `${m.model} ${m.displayName || ''} ${(m.tags || []).join(' ')}`
      .toLowerCase()
      .replace(/[-_/\s.]+/g, '');
    return searchable.includes(normalized);
  });
}

async function getModelSchema(model: Model): Promise<Record<string, any> | null> {
  if (!model.schema) return null;
  try {
    const resp = await fetch(model.schema);
    if (!resp.ok) return null;
    return await resp.json();
  } catch {
    return null;
  }
}

function buildParams(
  schema: Record<string, any> | null,
  modelId: string,
  prompt: string,
  imageUrl?: string,
  extraParams?: Record<string, unknown>
): Record<string, unknown> {
  const params: Record<string, unknown> = { model: modelId };

  if (schema) {
    const inputSchema = schema.components?.schemas?.Input || {};
    const properties = inputSchema.properties || {};
    const required: string[] = inputSchema.required || [];

    // Find prompt field
    const promptField = Object.keys(properties).find(
      (k) =>
        ['prompt', 'text', 'text_prompt'].includes(k) ||
        properties[k]?.description?.toLowerCase().includes('prompt')
    );
    if (promptField) params[promptField] = prompt;

    // Find image URL field
    if (imageUrl) {
      const imageField = Object.keys(properties).find(
        (k) =>
          ['image_url', 'image', 'input_image', 'init_image', 'source_image'].includes(k) ||
          properties[k]?.description?.toLowerCase().includes('image url') ||
          properties[k]?.description?.toLowerCase().includes('input image')
      );
      if (imageField) params[imageField] = imageUrl;
    }

    // Fill required defaults
    for (const key of required) {
      if (params[key] === undefined && properties[key]?.default !== undefined) {
        params[key] = properties[key].default;
      }
    }
  } else {
    params.prompt = prompt;
    if (imageUrl) params.image_url = imageUrl;
  }

  if (extraParams) Object.assign(params, extraParams);
  return params;
}

async function quickGenerate(options: {
  modelKeyword: string;
  type: 'Image' | 'Video';
  prompt: string;
  imageUrl?: string;
  extraParams?: Record<string, unknown>;
}): Promise<string> {
  const { modelKeyword, type, prompt, imageUrl, extraParams } = options;

  // Step 1: Search for model
  const matches = await searchModels(modelKeyword, type);
  if (matches.length === 0) {
    throw new Error(`No ${type} model found for "${modelKeyword}". Check available models first.`);
  }

  const model = matches[0];
  console.log(`Using model: ${model.displayName || model.model} (${model.model})`);

  if (matches.length > 1) {
    const others = matches.slice(1, 5).map((m) => m.displayName || m.model);
    console.log(`Other candidates: ${others.join(', ')}`);
  }

  // Step 2: Fetch schema
  const schema = await getModelSchema(model);

  // Step 3: Build params
  const requestBody = buildParams(schema, model.model, prompt, imageUrl, extraParams);

  // Step 4: Submit generation
  const endpoint = type === 'Image' ? 'generateImage' : 'generateVideo';
  const resp = await fetch(`${BASE_URL}/model/${endpoint}`, {
    method: 'POST',
    headers,
    body: JSON.stringify(requestBody),
  });

  if (!resp.ok) {
    throw new Error(`Generation failed: ${resp.status} ${await resp.text()}`);
  }

  const predictionId = (await resp.json()).data.id;
  const waitTime = type === 'Image' ? '10-30 seconds' : '1-5 minutes';
  console.log(`Generation submitted! Prediction ID: ${predictionId}`);
  console.log(`Expected wait time: ${waitTime}`);

  return predictionId;
}

async function pollResult(predictionId: string): Promise<string> {
  for (let i = 0; i < 200; i++) {
    await new Promise((r) => setTimeout(r, 3000));

    const resp = await fetch(`${BASE_URL}/model/prediction/${predictionId}`, { headers });
    if (!resp.ok) throw new Error(`Poll failed: ${resp.status}`);

    const data = (await resp.json()).data;

    if (data.status === 'completed' || data.status === 'succeeded') {
      const outputs = data.outputs ?? (Array.isArray(data.output) ? data.output : data.output ? [data.output] : []);
      return outputs[0];
    }

    if (data.status === 'failed') {
      throw new Error(`Generation failed: ${data.error || 'Unknown error'}`);
    }

    console.log(`Status: ${data.status}...`);
  }

  throw new Error('Generation timed out');
}

// Usage examples

// Quick image generation
const predId = await quickGenerate({
  modelKeyword: 'seedream v5',
  type: 'Image',
  prompt: 'A serene Japanese garden with cherry blossoms',
  extraParams: { image_size: '1024x1024' },
});
const imageUrl = await pollResult(predId);
console.log(`Image URL: ${imageUrl}`);

// Quick video generation
const videoPredId = await quickGenerate({
  modelKeyword: 'kling v3',
  type: 'Video',
  prompt: 'A rocket launching into space with dramatic clouds',
  extraParams: { duration: 5, aspect_ratio: '16:9' },
});
const videoUrl = await pollResult(videoPredId);
console.log(`Video URL: ${videoUrl}`);
```

# Upload Media — Complete Code Templates

Upload local image/media files to Atlas Cloud to get a publicly accessible URL. Use this when you need to provide an `image_url` to image-editing or image-to-video models but only have a local file.

> **WARNING**: This upload endpoint is strictly for temporary use with Atlas Cloud generation tasks only. Do NOT use it as permanent file hosting, CDN, or for any purpose unrelated to Atlas Cloud image/video generation. Abuse (e.g., bulk uploads, hosting illegal or unrelated content) may result in immediate API key suspension.

## Table of Contents
- [Python](#python)
- [Node.js / TypeScript](#nodejs--typescript)
- [cURL](#curl)
- [Workflow: Local File → Image-to-Video](#workflow-local-file--image-to-video)

---

## Python

```python
import requests
import os

ATLAS_API_KEY = os.environ.get("ATLASCLOUD_API_KEY")
BASE_URL = "https://api.atlascloud.ai/api/v1"


def upload_media(file_path: str) -> dict:
    """
    Upload a local file to Atlas Cloud and get a public URL.

    Args:
        file_path: Absolute path to the local file

    Returns:
        dict with download_url, filename, and size
    """
    with open(file_path, "rb") as f:
        files = {"file": (os.path.basename(file_path), f)}
        resp = requests.post(
            f"{BASE_URL}/model/uploadMedia",
            headers={"Authorization": f"Bearer {ATLAS_API_KEY}"},
            files=files,
            timeout=60,
        )
    resp.raise_for_status()
    data = resp.json()["data"]
    print(f"Uploaded: {data['download_url']}")
    print(f"Filename: {data['filename']}, Size: {data['size']} bytes")
    return data


# Usage
if __name__ == "__main__":
    result = upload_media("/path/to/local/photo.jpg")
    print(f"Public URL: {result['download_url']}")
```

---

## Node.js / TypeScript

```typescript
import { readFile } from 'fs/promises';
import { basename } from 'path';

const ATLAS_API_KEY = process.env.ATLASCLOUD_API_KEY;
const BASE_URL = 'https://api.atlascloud.ai/api/v1';

interface UploadResult {
  download_url: string;
  filename: string;
  size: number;
}

async function uploadMedia(filePath: string): Promise<UploadResult> {
  const fileBuffer = await readFile(filePath);
  const fileName = basename(filePath);

  const formData = new FormData();
  formData.append('file', new Blob([fileBuffer]), fileName);

  const resp = await fetch(`${BASE_URL}/model/uploadMedia`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${ATLAS_API_KEY}`,
    },
    body: formData,
    signal: AbortSignal.timeout(60000),
  });

  if (!resp.ok) {
    throw new Error(`Upload failed: ${resp.status} ${await resp.text()}`);
  }

  const data: UploadResult = (await resp.json()).data;
  console.log(`Uploaded: ${data.download_url}`);
  console.log(`Filename: ${data.filename}, Size: ${data.size} bytes`);
  return data;
}

// Usage
const result = await uploadMedia('/path/to/local/photo.jpg');
console.log(`Public URL: ${result.download_url}`);
```

---

## cURL

```bash
# Upload a local file
RESULT=$(curl -s -X POST "https://api.atlascloud.ai/api/v1/model/uploadMedia" \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  -F "file=@/path/to/local/photo.jpg")

echo "Download URL:"
echo "$RESULT" | jq -r '.data.download_url'

echo "Filename:"
echo "$RESULT" | jq -r '.data.filename'

echo "Size:"
echo "$RESULT" | jq -r '.data.size'
```

---

## Workflow: Local File → Image-to-Video

### Python

```python
import requests
import time
import os

ATLAS_API_KEY = os.environ.get("ATLASCLOUD_API_KEY")
BASE_URL = "https://api.atlascloud.ai/api/v1"
HEADERS = {
    "Authorization": f"Bearer {ATLAS_API_KEY}",
    "Content-Type": "application/json",
}


def upload_media(file_path: str) -> str:
    """Upload a local file and return the public URL."""
    with open(file_path, "rb") as f:
        files = {"file": (os.path.basename(file_path), f)}
        resp = requests.post(
            f"{BASE_URL}/model/uploadMedia",
            headers={"Authorization": f"Bearer {ATLAS_API_KEY}"},
            files=files,
            timeout=60,
        )
    resp.raise_for_status()
    return resp.json()["data"]["download_url"]


def generate_video(model: str, prompt: str, **kwargs) -> str:
    """Submit a video generation task and poll for result."""
    payload = {"model": model, "prompt": prompt, **kwargs}
    resp = requests.post(f"{BASE_URL}/model/generateVideo", json=payload, headers=HEADERS, timeout=50)
    resp.raise_for_status()
    prediction_id = resp.json()["data"]["id"]
    print(f"Video generation submitted. Prediction ID: {prediction_id}")

    for _ in range(200):
        time.sleep(3)
        result = requests.get(f"{BASE_URL}/model/prediction/{prediction_id}", headers=HEADERS, timeout=30)
        result.raise_for_status()
        result_data = result.json()["data"]
        status = result_data.get("status", "unknown")
        if status in ("completed", "succeeded"):
            outputs = result_data.get("outputs") or result_data.get("output", [])
            if isinstance(outputs, str):
                outputs = [outputs]
            return outputs[0]
        elif status == "failed":
            raise RuntimeError(f"Generation failed: {result_data.get('error')}")
        print(f"Status: {status}...")

    raise TimeoutError("Generation timed out")


# Complete workflow: local image → upload → image-to-video
if __name__ == "__main__":
    # Step 1: Upload local image
    image_url = upload_media("/path/to/local/photo.jpg")
    print(f"Uploaded image URL: {image_url}")

    # Step 2: Generate video from the uploaded image
    video_url = generate_video(
        model="kwaivgi/kling-v3.0-std/image-to-video",
        prompt="Camera slowly zooms in, cinematic lighting",
        image_url=image_url,
        duration=5,
        aspect_ratio="16:9",
    )
    print(f"Video URL: {video_url}")
```

### cURL

```bash
# Step 1: Upload local image
IMAGE_URL=$(curl -s -X POST "https://api.atlascloud.ai/api/v1/model/uploadMedia" \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  -F "file=@/path/to/local/photo.jpg" | jq -r '.data.download_url')

echo "Uploaded image URL: $IMAGE_URL"

# Step 2: Generate video from uploaded image
PREDICTION_ID=$(curl -s -X POST "https://api.atlascloud.ai/api/v1/model/generateVideo" \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"kwaivgi/kling-v3.0-std/image-to-video\",
    \"prompt\": \"Camera slowly zooms in, cinematic lighting\",
    \"image_url\": \"$IMAGE_URL\",
    \"duration\": 5,
    \"aspect_ratio\": \"16:9\"
  }" | jq -r '.data.id')

echo "Prediction ID: $PREDICTION_ID"

# Step 3: Poll for result
while true; do
  sleep 3
  RESULT=$(curl -s "https://api.atlascloud.ai/api/v1/model/prediction/$PREDICTION_ID" \
    -H "Authorization: Bearer $ATLASCLOUD_API_KEY")

  STATUS=$(echo "$RESULT" | jq -r '.data.status')

  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "succeeded" ]; then
    echo "Video URL:"
    echo "$RESULT" | jq -r '.data.outputs[0]'
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Failed:"
    echo "$RESULT" | jq -r '.data.error'
    break
  else
    echo "Status: $STATUS..."
  fi
done
```

# Video Generation — Complete Code Templates

## Table of Contents
- [Python](#python)
- [Node.js / TypeScript](#nodejs--typescript)
- [cURL](#curl)

---

## Python

```python
import requests
import time
import os

ATLAS_API_KEY = os.environ.get("ATLASCLOUD_API_KEY")
BASE_URL = "https://api.atlascloud.ai/api/v1"

HEADERS = {
    "Authorization": f"Bearer {ATLAS_API_KEY}",
    "Content-Type": "application/json",
}


def generate_video(model: str, prompt: str, **kwargs) -> str:
    """
    Generate a video and return the output URL.

    Args:
        model: Model ID, e.g. "kwaivgi/kling-v3.0-std/text-to-video"
        prompt: Text description of the video
        **kwargs: Additional parameters (duration, aspect_ratio, image_url, etc.)

    Returns:
        URL of the generated video
    """
    # Step 1: Submit generation task
    payload = {"model": model, "prompt": prompt, **kwargs}
    resp = requests.post(f"{BASE_URL}/model/generateVideo", json=payload, headers=HEADERS, timeout=50)
    resp.raise_for_status()
    data = resp.json()

    prediction_id = data["data"]["id"]
    print(f"Task submitted. Prediction ID: {prediction_id}")

    # Step 2: Poll for result (videos take longer, up to 10 min)
    for _ in range(200):
        time.sleep(3)
        result = requests.get(f"{BASE_URL}/model/prediction/{prediction_id}", headers=HEADERS, timeout=30)
        result.raise_for_status()
        result_data = result.json()["data"]

        status = result_data.get("status", "unknown")
        if status in ("completed", "succeeded"):
            outputs = result_data.get("outputs") or result_data.get("output", [])
            if isinstance(outputs, str):
                outputs = [outputs]
            print(f"Generation completed: {outputs[0]}")
            return outputs[0]
        elif status == "failed":
            error = result_data.get("error", "Unknown error")
            raise RuntimeError(f"Generation failed: {error}")
        else:
            print(f"Status: {status}...")

    raise TimeoutError("Generation timed out")


# Text-to-Video
if __name__ == "__main__":
    url = generate_video(
        model="kwaivgi/kling-v3.0-std/text-to-video",
        prompt="A rocket launching into space with dramatic clouds",
        duration=5,
        aspect_ratio="16:9",
    )
    print(f"Video URL: {url}")
```

### Image-to-Video (Python)

```python
url = generate_video(
    model="kwaivgi/kling-v3.0-std/image-to-video",
    prompt="Camera slowly zooms in, petals gently falling",
    image_url="https://example.com/cherry-blossom.jpg",
    duration=5,
    aspect_ratio="16:9",
)
print(f"Video URL: {url}")
```

---

## Node.js / TypeScript

```typescript
const ATLAS_API_KEY = process.env.ATLASCLOUD_API_KEY;
const BASE_URL = 'https://api.atlascloud.ai/api/v1';

const headers = {
  Authorization: `Bearer ${ATLAS_API_KEY}`,
  'Content-Type': 'application/json',
};

async function generateVideo(
  model: string,
  prompt: string,
  extraParams: Record<string, unknown> = {}
): Promise<string> {
  // Step 1: Submit generation task
  const submitResp = await fetch(`${BASE_URL}/model/generateVideo`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ model, prompt, ...extraParams }),
  });

  if (!submitResp.ok) {
    throw new Error(`Submit failed: ${submitResp.status} ${await submitResp.text()}`);
  }

  const submitData = await submitResp.json();
  const predictionId = submitData.data.id;
  console.log(`Task submitted. Prediction ID: ${predictionId}`);

  // Step 2: Poll for result (videos take 1-5 minutes)
  for (let i = 0; i < 200; i++) {
    await new Promise((r) => setTimeout(r, 3000));

    const pollResp = await fetch(`${BASE_URL}/model/prediction/${predictionId}`, { headers });
    if (!pollResp.ok) {
      throw new Error(`Poll failed: ${pollResp.status}`);
    }

    const result = (await pollResp.json()).data;

    if (result.status === 'completed' || result.status === 'succeeded') {
      const outputs = result.outputs ?? (Array.isArray(result.output) ? result.output : result.output ? [result.output] : []);
      console.log(`Generation completed: ${outputs[0]}`);
      return outputs[0];
    }

    if (result.status === 'failed') {
      throw new Error(`Generation failed: ${result.error || 'Unknown error'}`);
    }

    console.log(`Status: ${result.status}...`);
  }

  throw new Error('Generation timed out');
}

// Text-to-Video
const videoUrl = await generateVideo(
  'kwaivgi/kling-v3.0-std/text-to-video',
  'A rocket launching into space with dramatic clouds',
  { duration: 5, aspect_ratio: '16:9' }
);

// Image-to-Video
const videoUrl2 = await generateVideo(
  'kwaivgi/kling-v3.0-std/image-to-video',
  'Camera slowly zooms in, petals gently falling',
  { image_url: 'https://example.com/cherry-blossom.jpg', duration: 5 }
);
```

---

## cURL

### Text-to-Video

```bash
PREDICTION_ID=$(curl -s -X POST "https://api.atlascloud.ai/api/v1/model/generateVideo" \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kwaivgi/kling-v3.0-std/text-to-video",
    "prompt": "A rocket launching into space with dramatic clouds",
    "duration": 5,
    "aspect_ratio": "16:9"
  }' | jq -r '.data.id')

echo "Prediction ID: $PREDICTION_ID"

while true; do
  sleep 3
  RESULT=$(curl -s "https://api.atlascloud.ai/api/v1/model/prediction/$PREDICTION_ID" \
    -H "Authorization: Bearer $ATLASCLOUD_API_KEY")

  STATUS=$(echo "$RESULT" | jq -r '.data.status')

  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "succeeded" ]; then
    echo "Video URL:"
    echo "$RESULT" | jq -r '.data.outputs[0]'
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Failed:"
    echo "$RESULT" | jq -r '.data.error'
    break
  else
    echo "Status: $STATUS..."
  fi
done
```

### Image-to-Video

```bash
PREDICTION_ID=$(curl -s -X POST "https://api.atlascloud.ai/api/v1/model/generateVideo" \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kwaivgi/kling-v3.0-std/image-to-video",
    "prompt": "Camera slowly zooms in, petals gently falling",
    "image_url": "https://example.com/cherry-blossom.jpg",
    "duration": 5,
    "aspect_ratio": "16:9"
  }' | jq -r '.data.id')

echo "Prediction ID: $PREDICTION_ID"
# ... same polling loop as above
```