domains / media / atlas-cloud-media-generation / atlas-cloud-media

atlas-cloud-media

Skill card

combined

The two skills describe the same high-level workflow (discover models, inspect schema, submit one paid request, poll with bounds) but implement it via fundamentally different mechanisms. The first skill relies on a bundled Python CLI (`scripts/atlas_media.py`) that abstracts away the HTTP details, while the second skill is a 'source-only' skill that provides raw `curl` and `jq` commands for direct API interaction. The second skill also introduces specific operational constraints (private per-run workspace with `umask 077`, specific polling intervals of 3s/200 attempts, explicit API endpoint table) that are absent from the first. Conversely, the first skill provides a specific CLI interface and safety rules regarding the `--confirm-paid` flag. Combining them is necessary to capture both the high-level CLI abstraction and the low-level manual API contract details.

Repositories

Other copies

Combined skill

---
name: atlas-cloud-media
category: media-content
description: Discover Atlas Cloud image and video models, inspect their live schemas, and submit one confirmed media generation request with bounded GET polling. Supports both a bundled CLI and direct API interaction.
---

# Atlas Cloud Media

Use this skill to generate images or videos via Atlas Cloud. You may use the bundled `scripts/atlas_media.py` CLI if available, or interact directly with the REST API using `curl` and `jq`.

## When to Use This Skill

- The user wants to find an available Atlas Cloud image or video model.
- An integration needs the current model ID, input fields, endpoint, or price.
- The user wants one explicitly confirmed media generation request.
- An asynchronous Atlas Cloud task needs bounded status polling.

## Setup

Set the API key in the environment. Never pass it as a CLI argument or commit it to a repository.

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

`ATLASCLOUD_BASE_URL` may point to a compatible deployment. It defaults to `https://api.atlascloud.ai`.

## Workflow Option A: Using the Bundled CLI

If `scripts/atlas_media.py` is present, use it for a streamlined experience.

### 1. Discover current models

```bash
python3 scripts/atlas_media.py models --type Image --query flux
```

### 2. Inspect the exact schema

```bash
python3 scripts/atlas_media.py describe black-forest-labs/flux-schnell
```

### 3. Prepare parameters in a file

Create a JSON file with the required fields (e.g., `prompt`, `size`). Do not include the `model` field; the CLI inserts it.

### 4. Confirm cost and generate once

```bash
python3 scripts/atlas_media.py generate \
  black-forest-labs/flux-schnell \
  --params-file request.json \
  --confirm-paid
```

The `--confirm-paid` flag is mandatory. The CLI sends exactly one POST and polls with a fixed interval.

## Workflow Option B: Direct API Interaction

If the CLI is not available, use the following raw API steps.

### 0. Create a Private Per-Run Workspace

Create a private directory to store prompts, responses, and IDs securely.

```bash
umask 077
atlas_tmp_dir=$(mktemp -d "${TMPDIR:-/tmp}/atlas-cloud-media.XXXXXXXX") || exit 1
chmod 700 -- "$atlas_tmp_dir"
trap 'rm -rf -- "$atlas_tmp_dir"' EXIT
```

### 1. Discover and Validate a Model

Fetch the catalog and filter by type.

```bash
curl --fail --silent --show-error \
  "https://api.atlascloud.ai/api/v1/models" \
  --output "${atlas_tmp_dir:?run private workspace setup first}/models.json"

jq -r '.data[] | select(.type == "Image") | [.model, .displayName, .schema] | @tsv' \
  "$atlas_tmp_dir/models.json"
```

Fetch the specific model's schema URL from the catalog entry and validate your parameters against it. Do not guess parameters.

### 2. Submit One Generation Task

Build the JSON body in a file. Ensure the `model` field is included in the payload for direct API calls.

**Image Example:**
```bash
jq -n \
  --arg model "qwen-image-3.0/text-to-image" \
  --arg prompt "A paper-cut city map" \
  '{model: $model, prompt: $prompt, size: "1024*1024", n: 1}' \
  > "${atlas_tmp_dir:?run private workspace setup first}/request.json"

curl --fail --silent --show-error \
  --request POST \
  "https://api.atlascloud.ai/api/v1/model/generateImage" \
  --header "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data @"$atlas_tmp_dir/request.json" \
  --output "$atlas_tmp_dir/submit.json"
```

**Video Example:**
```bash
jq -n \
  --arg model "bytedance/seedance-2.0-fast/text-to-video" \
  --arg prompt "A small paper boat" \
  '{model: $model, prompt: $prompt, duration: 4, resolution: "480p", ratio: "16:9"}' \
  > "${atlas_tmp_dir:?run private workspace setup first}/request.json"

curl --fail --silent --show-error \
  --request POST \
  "https://api.atlascloud.ai/api/v1/model/generateVideo" \
  --header "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data @"$atlas_tmp_dir/request.json" \
  --output "$atlas_tmp_dir/submit.json"
```

Check that `.data.id` is a non-empty string. Do not retry on failure.

### 3. Poll with a Deadline

Poll every 3 seconds. Stop after 200 attempts (10 minutes) or on terminal status.

```bash
prediction_id=$(jq -er '.data.id | select(type == "string" and length > 0)' \
  "${atlas_tmp_dir:?run private workspace setup first}/submit.json")

for attempt in $(seq 1 200); do
  sleep 3
  curl --fail --silent --show-error \
    "https://api.atlascloud.ai/api/v1/model/prediction/$prediction_id" \
    --header "Authorization: Bearer $ATLASCLOUD_API_KEY" \
    --output "$atlas_tmp_dir/prediction.json"

  status=$(jq -r '.data.status // "unknown"' "$atlas_tmp_dir/prediction.json")
  case "$status" in
    completed|succeeded)
      echo "Success"
      break
      ;;
    failed|timeout)
      echo "Failed"
      break
      ;;
  esac
done
```

## Safety Rules

- Keep `ATLASCLOUD_API_KEY` server-side and out of logs, prompts, or committed files.
- Never retry a generation POST automatically. If submission fails, report the error and require a new explicit confirmation.
- Poll only with GET and stop at the defined maximum.
- Validate the live schema again when changing models.
- Download returned media URLs before they expire when persistent storage is required.
- Require human review for sensitive, regulated, or high-impact content.

## Output

- **CLI:** Writes structured JSON to stdout including prediction ID, status, and URLs.
- **Direct API:** Files in the temporary workspace (`submit.json`, `prediction.json`) contain the raw API responses.