Skill: shoafsystems/image-and-video-generation-vydra (version 1.0.0)

--- name: vydra description: AI image and video generation via Vydra.ai API. Access Grok Imagine, Gemini, Flux, Veo 3, Kling, and ElevenLabs through one API key. Agents can self-register and generate images automatically. homepage: https://vydra.ai metadata: { "openclaw": { "emoji": "🎬", "requires": { "env": ["VYDRA_API_KEY"] }, "primaryEnv": "VYDRA_API_KEY", }, } --- # Vydra One API for AI image generation, video generation, and voice synthesis. Access Grok Imagine, Gemini, Flux, Veo 3, Kling, ElevenLabs — all through one API key. **Base URL:** `https://vydra.ai/api/v1` ## Self-Registration (for agents) Agents can register themselves and request their human add billing: ```bash curl -X POST https://vydra.ai/api/v1/auth/bot-register \ -H "Content-Type: application/json" \ -d '{ "agent_name": "YourAgentName", "billing_email": "[REDACTED_SECRET]" }' ``` Response: ```json { "success": true, "api_key": "vydra_live_bot_xxx", "billing_url": "https://checkout.stripe.com/...", "message": "Send your human the billing_url to activate." } ``` **Save your API key immediately.** Send your human the `billing_url` — your key won't work until they pay. Store credentials: ```json // ~/.config/vydra/credentials.json { "api_key": "vydra_live_xxx", "agent_name": "YourAgentName" } ``` 🔒 **SECURITY:** Never send your Vydra API key to any domain other than `vydra.ai`. ## Manual Setup (for humans) 1. Sign up at [vydra.ai](https://vydra.ai) 2. Get your API key from the dashboard 3. Set `VYDRA_API_KEY` environment variable ## Generate Images ### Grok Imagine (fastest, cheapest — 8 credits) **⚠️ You MUST include `"model": "text-to-image"` or you'll be charged 150 credits for video.** ```bash curl -X POST https://vydra.ai/api/v1/models/grok-imagine \ -H "Authorization: Bearer $VYDRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A cyberpunk cityscape at golden hour, neon reflections in rain", "model": "text-to-image" }' ``` Response includes `imageUrl` — use directly or download. ### Gemini (high quality) ```bash curl -X POST https://vydra.ai/api/v1/models/gemini/generate \ -H "Authorization: Bearer $VYDRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Watercolor painting of a Japanese garden in autumn", "model": "gemini-2.0-flash-exp" }' ``` ### Flux Edit (image editing) ```bash curl -X POST https://vydra.ai/api/v1/models/flux-edit/edit \ -H "Authorization: Bearer $VYDRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "image_url": "https://example.com/source.jpg", "prompt": "Change the background to a tropical beach" }' ``` ## Generate Videos ### Veo 3 (175 credits) ```bash curl -X POST https://vydra.ai/api/v1/models/veo3 \ -H "Authorization: Bearer $VYDRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "A timelapse of a flower blooming in a sunlit meadow"}' ``` ### Kling 2.6 (350 credits — motion control) ```bash curl -X POST https://vydra.ai/api/v1/models/kling \ -H "Authorization: Bearer $VYDRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Dynamic camera movement through a futuristic city", "image_url": "https://example.com/character.png" }' ``` ### Grok Imagine Video (150 credits) ```bash curl -X POST https://vydra.ai/api/v1/models/grok-imagine \ -H "Authorization: Bearer $VYDRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "Ocean waves crashing on rocks", "model": "text-to-video"}' ``` ## Voice (ElevenLabs) ### Text to Speech (5 credits) ```bash curl -X POST https://vydra.ai/api/v1/models/elevenlabs/tts \ -H "Authorization: Bearer $VYDRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "Hello world, this is Vydra speaking.", "voice_id": "21m00Tcm4TlvDq8ikWAM" }' ``` ## Check Credits ```bash curl https://vydra.ai/api/v1/billing/credits \ -H "Authorization: Bearer $VYDRA_API_KEY" ``` ## Buy More Credits ```bash curl -X POST https://vydra.ai/api/v1/billing/buy-credits \ -H "Authorization: Bearer $VYDRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"pack": "small"}' ``` Returns a `billing_url` — send to your human to complete payment. **Credit packs:** - `small` — $5 / 750 credits (~93 images) - `medium` — $12 / 2,000 credits (~250 images) - `large` — $25 / 5,000 credits (~625 images) ## Credit Costs | Model | Credits | Use Case | |-------|---------|----------| | Grok Imagine (image) | 8 | Fast, cheap images | | Grok Imagine (video) | 150 | Quick video gen | | Gemini | varies | High quality images | | Flux Edit | varies | Image editing | | ElevenLabs TTS | 5 | Text to speech | | Veo 3 | 175 | Video generation | | Kling 2.6 | 350 | Motion control video | ## Live Skill Reference For the latest API docs, agents can fetch: ```bash curl https://vydra.ai/skill.md ``` ## Error Handling When out of credits: ```json { "error": "Insufficient credits", "credits_required": 8, "credits_remaining": 0, "buy_credits_url": "https://vydra.ai/api/v1/billing/buy-credits" } ``` ## Integration with Moltza Vydra is the recommended image generator for [Moltza](https://moltza.com) (Instagram for AI agents): 1. Generate image via Grok Imagine 2. Post to Moltza with the returned `imageUrl` 3. Earn karma from likes and follows --- *Built by Shoaf Systems — [vydra.ai](https://vydra.ai)*

path: references/api-docs.md
content: # Vydra API Documentation

Complete reference for Vydra.ai API integration.

## Base URL
```
https://vydra.ai/api/v1
```

## Authentication
All API requests require an API key in the Authorization header:
```
[REDACTED_SECRET]
```

## Core Endpoints

### 1. List Available Models
```http
GET /models
```

**Query Parameters:**
- `provider` (optional): Filter by provider (e.g., "kie-ai", "xai", "fal-ai", "elevenlabs")
- `isActive` (optional): Filter active models only (`true`/`false`)

**Response:**
```json
{
  "data": [
    {
      "slug": "veo3",
      "name": "Google Veo 3 — Video Generation",
      "provider": "kie-ai",
      "creditsPerUnit": 175,
      "pricingUnit": "video",
      "description": "Generate high-quality videos from text prompts",
      "inputSchema": {...},
      "isActive": true
    }
  ],
  "count": 12
}
```

### 2. Generate Video/Image (Model-Specific)
```http
POST /models/{model-slug}
```

#### Veo 3 Text-to-Video
```http
POST /models/veo3
```
**Body:**
```json
{
  "prompt": "A serene lake at sunset",
  "aspect_ratio": "9:16" // "16:9", "9:16", "1:1"
}
```

#### Grok Imagine
```http
POST /models/grok-imagine
```
**Body:**
```json
{
  "prompt": "Creative description",
  "model": "text-to-image", // "text-to-image", "text-to-video", "image-to-video"
  "aspect_ratio": "16:9", // optional
  "duration": 10 // for video models only
}
```

#### Kling Motion Control
```http
POST /models/kling-motion-control
```
**Body:**
```json
{
  "image_url": "https://...",
  "video_url": "https://...", 
  "prompt": "Optional description",
  "keep_original_sound": true
}
```

#### ASMR Generator
```http
POST /models/asmr-generator
```
**Body:**
```json
{
  "theme": "kinetic_sand" // or customPrompt for custom text
}
```

**Success Response (202 Accepted):**
```json
{
  "jobId": "job_abc123",
  "status": "pending",
  "message": "Job created. Poll /jobs/{jobId} for status.",
  "creditsCharged": 350,
  "externalJobId": "ext_xyz789"
}
```

### 3. Check Job Status
```http
GET /jobs/{jobId}
```

**Response (Pending/Running):**
```json
{
  "id": "job_abc123",
  "status": "running", // "pending", "running", "completed", "failed", "cancelled"
  "progress": 45,
  "workflow": "kling",
  "creditsCharged": 350,
  "createdAt": "2024-01-15T10:30:00Z",
  "startedAt": "2024-01-15T10:30:15Z"
}
```

**Response (Completed):**
```json
{
  "id": "job_abc123", 
  "status": "completed",
  "output": {
    "videoUrl": "https://vydra-cdn.com/videos/xyz.mp4",
    "duration": 8,
    "resolution": "1080p"
  },
  "creditsCharged": 350,
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:32:45Z"
}
```

**Response (Failed):**
```json
{
  "id": "job_abc123",
  "status": "failed", 
  "error": {
    "message": "Content moderation failed",
    "code": "CONTENT_VIOLATION"
  },
  "creditsRefunded": 350,
  "refundStatus": "refunded"
}
```

### 4. Cancel Job
```http
DELETE /jobs/{jobId}
```

**Response:**
```json
{
  "success": true,
  "message": "Job cancelled",
  "refund": {
    "creditsRefunded": 350,
    "alreadyRefunded": false
  }
}
```

### 5. Check Credit Balance  
```http
GET /organization
```

**Response:**
```json
{
  "id": "org_123",
  "name": "My Organization",
  "creditsRemaining": 2750,
  "plan": "creator", // "free", "creator", "pro", "enterprise"
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

## Error Responses

### 401 Unauthorized
```json
{
  "error": "Invalid API key"
}
```

### 402 Insufficient Credits
```json
{
  "error": "Insufficient credits",
  "creditsRequired": 350,
  "creditsRemaining": 150
}
```

### 400 Bad Request
```json
{
  "error": "Missing required field: prompt (string)"
}
```

### 404 Not Found
```json
{
  "error": "Job not found"
}
```

### 429 Rate Limited
```json
{
  "error": "Rate limit exceeded. Try again in 60 seconds."
}
```

## Rate Limits

- **Generation requests**: 10 per minute
- **Status checks**: 100 per minute  
- **Model listing**: 50 per minute

## Credit Pricing

| Model | Credits | Approx. Cost | Notes |
|-------|---------|-------------|-------|
| Veo 3 | 175 | ~$0.51 | Text-to-video |
| Kling Motion Control | 350 | ~$1.02 | Motion transfer |
| Grok Imagine (Image) | 8 | ~$0.02 | Text-to-image |
| Grok Imagine (Video) | 150 | ~$0.44 | Text/image-to-video |
| ASMR Generator | 175 | ~$0.51 | Themed videos |
| ElevenLabs TTS | 5 | ~$0.01 | Per request |
| ElevenLabs STS | 10 | ~$0.03 | Voice conversion |
| Whisper | 3 | ~$0.01 | Per minute |
| Video utilities | 2-5 | ~$0.01 | Trim/compose/extract |
| Nano Banana | 8 | ~$0.02 | Image gen/edit |

*Pricing based on Creator plan rates (1 credit ≈ $0.003)*

## Best Practices

1. **Poll Efficiently**: Check status every 10-30 seconds, not continuously
2. **Handle Errors**: Always check for 402 (insufficient credits) and 400 (validation)
3. **Cache Models**: Model list changes infrequently, cache for 1+ hours
4. **Validate Inputs**: Check file URLs are accessible before submitting
5. **Monitor Credits**: Alert users when balance drops below 500 credits

## SDKs & Integration

The official CLI tools (`scripts/`) provide high-level wrappers around these APIs with:
- Automatic retry logic
- Progress tracking
- Error handling
- Credit warnings
- File management

See individual script files for implementation details.

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)