creaa-ai

Creaa AI - Generate and edit images, plus generate videos via Creaa.ai API. Text-to-image, image edit, text-to-video, image-to-video with multiple AI models.

metadata: {"openclaw":{"requires":{"env":["CREAA_API_KEY"]},"primaryEnv":"CREAA_API_KEY"}}

# Creaa AI - Image, Edit & Video Generation

Generate and edit AI images, and generate AI videos directly from your terminal using the Creaa API.

Get your API key at: https://creaa.ai/profile -> API Keys
Top up API credits at: https://creaa.ai/pricing

## Available Models

### Image Models

| Model ID | Name | Credits/Image | Free Daily | Default Ratio | Max Ref Images | Capabilities |
|----------|------|--------------|-----------|---------------|----------------|-------------|
| `seedream-5.0` | Seedream 5.0 | 4 | 10 | 1:1 | 4 | text_to_image, image_to_image |
| `nano-banana-2` | Nano Banana 2 | 10 | 5 | auto | 14 | text_to_image, image_to_image, multi_image_edit |
| `nano-banana-pro` | Nano Banana Pro | 20 | 1 | auto | 10 | text_to_image, image_to_image, multi_image_edit |
| `gpt-image-1.5` | GPT Image 1.5 | 15 | 0 | 1:1 | 10 | text_to_image, image_to_image, multi_image_edit |
| `z-image-turbo` | Z-Image Turbo | 1 | - | 1:1 | - | text_to_image |

**Aspect ratio options per model:**
- `seedream-5.0`: auto, 1:1, 3:4, 4:3, 16:9, 9:16, 2:3, 3:2, 21:9
- `nano-banana-2` / `nano-banana-pro`: auto, 1:1, 9:16, 16:9, 3:2, 2:3
- `gpt-image-1.5`: 1:1, 3:2, 2:3
- `z-image-turbo`: 1:1, 9:16, 16:9

### Video Models

| Model ID | Name | Credits/sec | Durations (sec) | Default Duration | Capabilities |
|----------|------|------------|-----------------|-----------------|-------------|
| `veo-3.1` | Veo 3.1 | 22 | 8 | 8 | text_to_video, image_to_video |
| `seedance-2.0` | Seedance 2.0 | 25 | 5, 10, 15 | 5 | text_to_video, image_to_video |
| `sora-2-pro` | Sora 2 Pro | 12 | 4, 8, 12, 16, 20 | 12 | text_to_video, image_to_video |
| `seedance-1.5-pro` | Seedance 1.5 Pro | 12 | 5, 8, 12 | 5 | text_to_video, image_to_video, first_last_frame |
| `kling-3.0` | Kling 3.0 | 25 | 5, 10, 15 | 5 | text_to_video, image_to_video |
| `hailuo-2.3` | Hailuo 2.3 | 25 | 6, 10 | 6 | text_to_video, image_to_video |
| `runway-gen-4.5` | Runway Gen-4.5 | 30 | 5, 10 | 5 | image_to_video |

**Aspect ratio options per model:**
- `veo-3.1`: 16:9, 9:16
- `seedance-2.0`: 9:16, 16:9, 1:1, 3:4, 4:3
- `sora-2-pro`: 9:16, 16:9
- `seedance-1.5-pro`: 9:16, 16:9, 1:1, 3:4, 4:3
- `kling-3.0`: 16:9, 9:16
- `hailuo-2.3`: 9:16, 16:9
- `runway-gen-4.5`: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9

## Available Commands

All generation and edit tasks are asynchronous: submit a task, get a `task_id`, then poll for results.

### Generate Image

**Step 1: Submit task**
```bash
curl -s -X POST "https://creaa.ai/api/open/v1/images/generate" \
  -H "Authorization: Bearer $CREAA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Source: openclaw" \
  -d '{
    "prompt": "<user prompt here>",
    "model": "<model_id>",
    "aspect_ratio": "<ratio>",
    "n": <count>
  }'
```

**Parameters:**
- `prompt` (required): Image description
- `model` (optional): Model ID from the image models table above. Default: `nano-banana-2`
- `aspect_ratio` (optional): Aspect ratio like `1:1`, `16:9`, `9:16`. Must match the model's supported ratios. Default varies by model.
- `n` (optional): Number of images, 1-4. Default 1

**Response:**
```json
{
  "success": true,
  "task_id": "abc123-def456",
  "task_type": "image",
  "model": "nano-banana-2"
}
```

**Step 2: Poll status** (wait 5-10 seconds between polls for images)
```bash
curl -s "https://creaa.ai/api/open/v1/tasks/<task_id>" \
  -H "Authorization: Bearer $CREAA_API_KEY" \
  -H "X-Source: openclaw"
```

**Status Response (completed):**
```json
{
  "success": true,
  "task_id": "abc123-def456",
  "status": "completed",
  "progress": 1.0,
  "result_url": "https://...",
  "result_urls": ["https://...", "https://..."]
}
```

Image generation typically takes 10-60 seconds. Poll every 5 seconds.

### Edit Image

Use this endpoint for:
- Single-image edit: `image_url` or `image_data` (base64)
- Multi-image reference edit / composition: `image_urls` or `image_data_list` (base64)

**Step 1: Submit task (with URL)**
```bash
curl -s -X POST "https://creaa.ai/api/open/v1/images/edit" \
  -H "Authorization: Bearer $CREAA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Source: openclaw" \
  -d '{
    "prompt": "<edit prompt here>",
    "image_url": "https://...",
    "model": "<model_id>",
    "aspect_ratio": "<ratio>",
    "n": <count>
  }'
```

**Step 1: Submit task (with base64 image data)**
```bash
curl -s -X POST "https://creaa.ai/api/open/v1/images/edit" \
  -H "Authorization: Bearer $CREAA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Source: openclaw" \
  -d '{
    "prompt": "<edit prompt here>",
    "image_data": "data:image/png;base64,iVBOR...",
    "model": "<model_id>",
    "aspect_ratio": "<ratio>",
    "n": <count>
  }'
```

**Single-image edit parameters:**
- `prompt` (required): Edit instruction
- `image_url` (option A): Public source image URL
- `image_data` (option B): Base64-encoded image data. Supports `data:image/png;base64,...` prefix or raw base64 string. Max 20MB.
- `model` (optional): Model ID from the image models table above. Default: `nano-banana-2`
- `aspect_ratio` (optional): Must match the model's supported ratios
- `n` (optional): Number of output images, 1-4. Default 1

Provide either `image_url` or `image_data` for single-image edit. If both are provided, `image_url` takes priority.

**Multi-image edit / composition example:**
```bash
curl -s -X POST "https://creaa.ai/api/open/v1/images/edit" \
  -H "Authorization: Bearer $CREAA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Source: openclaw" \
  -d '{
    "prompt": "<combine these references into one result>",
    "image_urls": ["https://...", "https://..."],
    "model": "nano-banana-2",
    "aspect_ratio": "16:9",
    "n": 1
  }'
```

You can also use `image_data_list` with base64 strings instead of `image_urls`.

**Multi-image edit notes:**
- `image_urls` or `image_data_list`: 2-N images, where N depends on the model
- Max reference images by model:
  - `seedream-5.0`: up to 4 input images
  - `nano-banana-2`: up to 14 input images
  - `nano-banana-pro`: up to 10 input images
  - `gpt-image-1.5`: up to 10 input images
- Only models with `multi_image_edit` capability support this mode
- URLs must be public `http(s)` URLs; base64 data is uploaded to storage automatically

**Response:**
```json
{
  "success": true,
  "task_id": "abc123-def456",
  "task_type": "image_edit",
  "model": "nano-banana-2"
}
```

**Step 2: Poll status**
```bash
curl -s "https://creaa.ai/api/open/v1/tasks/<task_id>" \
  -H "Authorization: Bearer $CREAA_API_KEY" \
  -H "X-Source: openclaw"
```

**Status Response (completed):**
```json
{
  "success": true,
  "task_id": "abc123-def456",
  "status": "completed",
  "progress": 1.0,
  "result_url": "https://...",
  "result_urls": ["https://...", "https://..."]
}
```

Image editing typically takes 10-90 seconds. Poll every 5 seconds.

### Generate Video

**Step 1: Submit task**
```bash
curl -s -X POST "https://creaa.ai/api/open/v1/videos/generate" \
  -H "Authorization: Bearer $CREAA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Source: openclaw" \
  -d '{
    "prompt": "<user prompt here>",
    "model": "<model_id>",
    "mode": "<text_to_video|image_to_video>",
    "duration": <seconds>,
    "aspect_ratio": "<ratio>"
  }'
```

**Parameters:**
- `prompt` (required): Video description
- `model` (optional): Model ID from the video models table above. Default: `veo-3.1`
- `mode` (optional): `text_to_video` (default) or `image_to_video`
- `image_url` (option A, required for image_to_video): URL of the source image
- `image_data` (option B, required for image_to_video): Base64-encoded image data. Supports `data:image/png;base64,...` prefix or raw base64 string. Max 20MB.
- `duration` (optional): Duration in seconds, must match the model's supported durations. Default varies by model.
- `aspect_ratio` (optional): e.g. `16:9`, `9:16`, `1:1`. Must match the m