API Documentation

Overview

The AI Visual Studio API enables you to generate stunning AI images and videos programmatically. Build powerful integrations into your applications with our RESTful API.

Quick Start

1. 1
   Get an API Key

   Create an API key from your account dashboard

2. 2
   Make your first request

   Use the code examples below to generate your first image

3. 3
   Set up webhooks (optional)

   Receive real-time notifications when generations complete

Authentication

All API requests require authentication using an API key. Include your key in the Authorization header as a Bearer token.

Authorization: Bearer avs_live_your_api_key_here

API Key Scopes

API keys can have different permission scopes:

Rate Limits

API requests are rate limited to 60 requests per minute per API key. This limit ensures fair resource distribution across all API consumers.

Rate Limit Headers

Every API response includes headers showing your current rate limit status:

Generate Image

Create AI-generated images from text prompts.

Request Body

Example Request

curl -X POST https://aivisualstudio.co/api/v1/generate/image \
  -H "Authorization: Bearer avs_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic city at sunset, cyberpunk style",
    "model": "prunaai/z-image-turbo",
    "aspect_ratio": "16:9"
  }'

Response

{
  "id": "gen_abc123def456",
  "status": "processing",
  "prompt": "A futuristic city at sunset, cyberpunk style",
  "model": "prunaai/z-image-turbo",
  "type": "image",
  "credits_charged": 5,
  "created_at": "2025-01-09T12:00:00Z"
}

Generate Video

Create AI-generated videos from text prompts or images.

Request Body

Example Request

curl -X POST https://aivisualstudio.co/api/v1/generate/video \
  -H "Authorization: Bearer avs_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A spaceship flying through an asteroid field",
    "model": "minimax/hailuo-2.3-fast",
    "duration": 5
  }'

List Generations

Retrieve a list of your generations with pagination support.

Query Parameters

Example Request

curl -X GET "https://aivisualstudio.co/api/v1/generations?limit=10&type=image" \
  -H "Authorization: Bearer avs_live_your_api_key"

Get Single Generation

Retrieve details of a specific generation by ID.

Models

List all available AI models for image and video generation.

Query Parameters

Response Example

{
  "data": [
    {
      "id": "prunaai/z-image-turbo",
      "name": "Z-Image Turbo",
      "type": "image",
      "credits_per_generation": 5,
      "description": "Fast image generation",
      "category": "image-generation"
    },
    {
      "id": "minimax/hailuo-2.3-fast",
      "name": "Hailuo 2.3 Fast",
      "type": "video",
      "credits_per_generation": 450,
      "description": "Fast video generation",
      "category": "video-generation"
    }
  ],
  "total": 18
}

Webhooks

Receive real-time notifications when your generations complete or fail. Webhooks use HMAC-SHA256 signatures for security.

Create Webhook

Request Body

Available Events

• generation.completed - Generation finished successfully
• generation.failed - Generation failed

Example: Create Webhook

curl -X POST https://aivisualstudio.co/api/v1/webhooks \
  -H "Authorization: Bearer avs_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/photoverse",
    "events": ["generation.completed", "generation.failed"]
  }'

Webhook Payload

{
  "event": "generation.completed",
  "data": {
    "id": "gen_abc123def456",
    "type": "image",
    "status": "completed",
    "prompt": "A futuristic city at sunset",
    "output_url": "https://cdn.example.com/image.png",
    "created_at": "2025-01-09T12:00:00Z",
    "completed_at": "2025-01-09T12:00:15Z"
  },
  "created_at": "2025-01-09T12:00:15Z"
}

Verifying Webhook Signatures

Every webhook request includes an X-Webhook-Signature header that you should verify to ensure the request came from AI Visual Studio.

X-Webhook-Signature: t=1704801600,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Verification Example

import crypto from 'crypto';

function verifyWebhookSignature(payload, signature, secret) {
  const [timestamp, hash] = signature.split(',').map(part => {
    const [key, value] = part.split('=');
    return value;
  });

  // Verify timestamp is recent (within 5 minutes)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    return false; // Replay attack protection
  }

  const expectedHash = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${JSON.stringify(payload)}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(hash),
    Buffer.from(expectedHash)
  );
}

// In your webhook handler
app.post('/webhooks/photoverse', (req, res) => {
  const signature = req.headers['x-webhook-signature'];

  if (!verifyWebhookSignature(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook
  const { event, data } = req.body;
  console.log('Received event:', event, data);

  res.status(200).send('OK');
});

Other Webhook Endpoints

API Keys

Manage your API keys programmatically. These endpoints use web session authentication (cookie-based) rather than API key authentication.

Create API Key

Error Handling

The API uses standard HTTP status codes and returns detailed error information in JSON format.

Error Response Format

{
  "error": {
    "code": "insufficient_credits",
    "message": "You need 5 credits but only have 2",
    "details": {
      "required": 5,
      "available": 2
    }
  }
}

Error Codes