bowong
/
bw-mini-app
6
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
bw-mini-app/API.md

16 KiB
Raw Blame History

Mixvideo Workflow API Documentation

Overview

This document describes the REST API endpoints for the Mixvideo Workflow service, which provides video generation capabilities with Google OAuth integration, payment processing, and template management.

Base URL

https://mixvideo-workflow.bowong.cc/

Authentication

Most endpoints require authentication via OAuth tokens or API keys. Include tokens in the Authorization header:

Authorization: Bearer <access_token>

Auth Controller (/auth/google)

Google OAuth Authentication

GET /auth/google/authorize

Initiates Google OAuth authorization flow.

Query Parameters:

  • redirect_url (optional): URL to redirect after authorization
  • scopes (optional): Comma-separated OAuth scopes (default: openid,email,profile)

Response:

  • Redirects to Google OAuth consent screen

GET /auth/google/callback

Handles OAuth callback from Google.

Query Parameters:

  • code: Authorization code from Google
  • state: State parameter for CSRF protection
  • error (optional): Error code if authorization failed

Success Response (200):

{
  "success": true,
  "code": 200,
  "message": "OAuth authorization successful",
  "data": {
    "user": {
      "id": "user_id",
      "email": "user@example.com",
      "name": "User Name"
    },
    "access_token": "ya29.xxx",
    "expires_in": 3600
  }
}

POST /auth/google/refresh

Refreshes OAuth access token.

Request Body:

{
  "refresh_token": "refresh_token_here",
  "user_id": "optional_user_id"
}

Response (200):

{
  "success": true,
  "code": 200,
  "message": "Token refreshed successfully",
  "data": {
    "access_token": "new_access_token",
    "expires_in": 3600,
    "scope": "openid email profile"
  }
}

GET /auth/google/userinfo

Retrieves user information from Google.

Headers:

  • Authorization: Bearer <access_token> OR
  • Query parameter: access_token=<token>

Response (200):

{
  "success": true,
  "code": 200,
  "message": "User info retrieved successfully",
  "data": {
    "id": "user_id",
    "email": "user@example.com",
    "name": "User Name",
    "picture": "https://..."
  }
}

POST /auth/google/revoke

Revokes OAuth token.

Request Body:

{
  "token": "token_to_revoke",
  "user_id": "optional_user_id"
}

Response (200):

{
  "success": true,
  "code": 200,
  "message": "Token revoked successfully"
}

Payment Controller (/payment)

Stripe Payment Integration

POST /payment/checkout/:templateCode

Creates Stripe checkout session for a template.

Path Parameters:

  • templateCode: Template identifier

Request Body:

{
  "userId": "user_123",
  "metadata": {
    "imageUrl": "https://example.com/image.jpg"
  }
}

Response (200):

{
  "code": 200,
  "message": "Checkout session created successfully",
  "data": {
    "sessionId": "cs_xxx",
    "url": "https://checkout.stripe.com/pay/cs_xxx",
    "paymentId": "payment_123"
  },
  "timestamp": "2024-01-01T00:00:00Z",
  "traceId": "trace_123"
}

POST /payment/webhook

Handles Stripe webhook events.

Headers:

  • stripe-signature: Stripe webhook signature

Request Body: Raw webhook payload from Stripe

Response (200):

{
  "code": 200,
  "message": "Webhook processed successfully"
}

GET /payment/success

Handles successful payment callback.

Query Parameters:

  • session_id: Stripe session ID
  • payment_id: Internal payment ID

Response (200):

{
  "code": 200,
  "message": "Payment successful, template execution started",
  "data": {
    "payment": {
      "id": "payment_123",
      "status": "completed",
      "templateCode": "template_001"
    },
    "execution": {
      "executionId": "exec_123",
      "taskId": "task_123"
    }
  }
}

GET /payment/cancel

Handles payment cancellation.

Query Parameters:

  • session_id: Stripe session ID
  • payment_id: Internal payment ID

Response (200):

{
  "code": 200,
  "message": "Payment cancelled",
  "data": {
    "payment": {
      "id": "payment_123",
      "status": "cancelled"
    }
  }
}

GET /payment/history

Retrieves user payment history.

Query Parameters:

  • userId: User identifier

Response (200):

{
  "code": 200,
  "message": "Payment history retrieved successfully",
  "data": {
    "payments": [
      {
        "id": "payment_123",
        "templateCode": "template_001",
        "status": "completed",
        "amount": 1000,
        "currency": "usd",
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 1
  }
}

POST /payment/refund/:paymentId

Processes refund for a payment.

Path Parameters:

  • paymentId: Payment identifier

Request Body:

{
  "reason": "user_request",
  "amount": 1000,
  "metadata": {
    "note": "Customer requested refund"
  }
}

Response (200):

{
  "code": 200,
  "message": "Refund processed successfully",
  "data": {
    "refundId": "re_xxx",
    "amount": 1000,
    "status": "succeeded"
  }
}

GET /payment/:paymentId

Retrieves payment details.

Path Parameters:

  • paymentId: Payment identifier

Response (200):

{
  "code": 200,
  "message": "Payment details retrieved successfully",
  "data": {
    "id": "payment_123",
    "templateCode": "template_001",
    "userId": "user_123",
    "status": "completed",
    "amount": 1000,
    "currency": "usd",
    "stripeSessionId": "cs_xxx",
    "executionId": "exec_123",
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

GET /payment/health

Payment service health check.

Response (200):

{
  "code": 200,
  "message": "Payment service is healthy",
  "data": {
    "timestamp": "2024-01-01T00:00:00Z",
    "service": "PaymentController"
  }
}

Task Controller (/task)

Task Management

GET /task/:taskId

Retrieves task status and details.

Path Parameters:

  • taskId: Task identifier

Response (200):

{
  "code": 200,
  "message": "Task status retrieved",
  "data": {
    "id": "task_123",
    "status": "completed",
    "progress": 100,
    "result": {
      "videoUrl": "https://example.com/output.mp4"
    },
    "createdAt": "2024-01-01T00:00:00Z",
    "completedAt": "2024-01-01T00:05:00Z"
  }
}

POST /task

Creates a new task.

Request Body:

{
  "type": "video_generation",
  "templateCode": "template_001",
  "userId": "user_123",
  "parameters": {
    "imageUrl": "https://example.com/input.jpg"
  }
}

Response (200):

{
  "code": 200,
  "message": "Sent message to the queue",
  "data": "task_123"
}

POST /task/:taskId

Creates task with specific ID.

Path Parameters:

  • taskId: Desired task identifier

Request Body:

{
  "type": "video_generation",
  "templateCode": "template_001",
  "parameters": {
    "imageUrl": "https://example.com/input.jpg"
  }
}

Response (200):

{
  "code": 200,
  "message": "Sent message to the queue",
  "data": "task_123"
}

Template Controller (/templates)

Template Management

GET /templates

Retrieves all active templates.

Response (200):

{
  "code": 200,
  "message": "Templates retrieved successfully",
  "data": {
    "templates": [
      {
        "code": "template_001",
        "name": "AI Video Generator",
        "description": "Generate videos from images using AI",
        "creditCost": 10,
        "templateType": "VIDEO",
        "isActive": true,
        "tags": ["ai", "video", "generation"]
      }
    ],
    "total": 1
  }
}

GET /templates/get/:code

Retrieves specific template by code.

Path Parameters:

  • code: Template code

Response (200):

{
  "code": 200,
  "message": "Template retrieved successfully",
  "data": {
    "code": "template_001",
    "name": "AI Video Generator",
    "description": "Generate videos from images using AI",
    "creditCost": 10,
    "templateType": "VIDEO",
    "workflow": "video-generation-workflow",
    "isActive": true,
    "stripeProductId": "prod_xxx",
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

POST /templates

Creates a new template.

Request Body:

{
  "code": "template_002",
  "name": "New Template",
  "description": "Template description",
  "workflow": "workflow-name",
  "creditCost": 15,
  "version": "1.0.0",
  "templateType": "IMAGE",
  "tags": ["new", "template"],
  "imageModel": "dall-e-3",
  "imagePrompt": "Generate image based on: {prompt}"
}

Response (200):

{
  "code": 200,
  "message": "Template created successfully",
  "data": {
    "code": "template_002",
    "stripeProductId": "prod_yyy",
    "stripePriceId": "price_yyy"
  }
}

PUT /templates/update/:code

Updates existing template.

Path Parameters:

  • code: Template code

Request Body:

{
  "name": "Updated Template Name",
  "description": "Updated description",
  "creditCost": 20,
  "isActive": true
}

Response (200):

{
  "code": 200,
  "message": "Template updated successfully",
  "data": {
    "updated": true,
    "stripeSynced": true
  }
}

DELETE /templates/delete/:code

Deletes template.

Path Parameters:

  • code: Template code

Response (200):

{
  "code": 200,
  "message": "Template deleted successfully",
  "data": {
    "deleted": true
  }
}

POST /templates/execute/:code

Executes template workflow.

Path Parameters:

  • code: Template code

Request Body:

{
  "userId": "user_123",
  "imageUrl": "https://example.com/input.jpg"
}

Response (200):

{
  "code": 200,
  "message": "Template execution started",
  "data": {
    "executionId": "exec_123",
    "taskId": "task_123",
    "status": "running"
  }
}

POST /templates/activate/:code

Activates template and syncs to Stripe.

Path Parameters:

  • code: Template code

Response (200):

{
  "code": 200,
  "message": "Template activated successfully",
  "data": {
    "isActive": true,
    "stripeSynced": true
  }
}

POST /templates/deactivate/:code

Deactivates template.

Path Parameters:

  • code: Template code

Response (200):

{
  "code": 200,
  "message": "Template deactivated successfully",
  "data": {
    "isActive": false,
    "stripeSynced": true
  }
}

POST /templates/sync/:code

Syncs template to Stripe.

Path Parameters:

  • code: Template code

Request Body (optional):

{
  "forceUpdate": true
}

Response (200):

{
  "code": 200,
  "message": "Template sync completed",
  "data": {
    "synced": true,
    "stripeProductId": "prod_xxx",
    "stripePriceId": "price_xxx"
  }
}

GET /templates/execution/:taskId/progress

Gets execution progress.

Path Parameters:

  • taskId: Task identifier

Response (200):

{
  "code": 200,
  "message": "Execution progress retrieved",
  "data": {
    "taskId": "task_123",
    "executionId": "exec_123",
    "status": "completed",
    "progress": 100,
    "result": {
      "videoUrl": "https://example.com/output.mp4"
    }
  }
}

GET /templates/executions/user/:userId

Gets user execution history.

Path Parameters:

  • userId: User identifier

Response (200):

{
  "code": 200,
  "message": "User executions retrieved successfully",
  "data": {
    "executions": [
      {
        "executionId": "exec_123",
        "templateCode": "template_001",
        "status": "completed",
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 1
  }
}

POST /templates/bulk

Performs bulk operations on templates.

Request Body:

{
  "templateCodes": ["template_001", "template_002"],
  "operation": "sync_stripe"
}

Response (200):

{
  "code": 200,
  "message": "Bulk operation completed",
  "data": {
    "successful": ["template_001", "template_002"],
    "failed": [],
    "total": 2
  }
}

GET /templates/sync-all-stripe

Syncs all templates to Stripe.

Response (200):

{
  "code": 200,
  "message": "All templates synced to Stripe",
  "data": {
    "successful": 10,
    "failed": 0,
    "total": 10
  }
}

GET /templates/sync-status

Checks template-Stripe sync status.

Response (200):

{
  "code": 200,
  "message": "Sync status retrieved",
  "data": {
    "totalTemplates": 10,
    "withStripeProduct": 8,
    "activeTemplates": 9,
    "needsSync": 1,
    "templates": [
      {
        "code": "template_001",
        "name": "Template Name",
        "isActive": true,
        "hasStripeProduct": true,
        "lastStripeSyncAt": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

GET /templates/verify-sync/:code

Verifies template Stripe sync status.

Path Parameters:

  • code: Template code

Response (200):

{
  "code": 200,
  "message": "Template sync verified successfully",
  "data": {
    "templateCode": "template_001",
    "synced": true,
    "issues": [],
    "stripeProductId": "prod_xxx",
    "stripePriceId": "price_xxx",
    "recommendations": ["Template is properly synced with Stripe"]
  }
}

GET /templates/diagnose-stripe

Diagnoses Stripe environment and configuration.

Response (200):

{
  "code": 200,
  "message": "Stripe environment is healthy",
  "data": {
    "environment": "test",
    "apiKeyValid": true,
    "issues": [],
    "accountInfo": {
      "chargesEnabled": true,
      "country": "US"
    },
    "recommendations": ["Stripe configuration appears healthy"]
  }
}

GET /templates/health

Template service health check.

Response (200):

{
  "code": 200,
  "message": "Template service is healthy",
  "data": {
    "totalTemplates": 10,
    "timestamp": "2024-01-01T00:00:00Z",
    "service": "TemplateService"
  }
}

GET /templates/init

Initializes templates from JSON data.

Response (200):

{
  "code": 200,
  "message": "Templates initialization completed",
  "data": {
    "total": 10,
    "imported": 9,
    "failed": 1,
    "details": [
      {
        "code": "template_001",
        "status": "success"
      },
      {
        "code": "template_002",
        "status": "error",
        "error": "Template already exists"
      }
    ]
  }
}

POST /templates/test/create

Creates a test template for development.

Response (200):

{
  "code": 200,
  "message": "Test template created successfully",
  "data": {
    "code": "test-image-generation",
    "stripeProductId": "prod_test",
    "stripePriceId": "price_test"
  }
}

Error Responses

All endpoints return standardized error responses:

Error Response Format:

{
  "code": 400,
  "message": "Error description",
  "timestamp": "2024-01-01T00:00:00Z",
  "traceId": "trace_123"
}

Common HTTP Status Codes:

  • 200 - Success
  • 400 - Bad Request (validation errors, missing parameters)
  • 401 - Unauthorized (missing or invalid authentication)
  • 404 - Not Found (resource not found)
  • 500 - Internal Server Error (server-side errors)

Rate Limiting

API endpoints may be subject to rate limiting. Check response headers for rate limit information:

  • X-RateLimit-Limit: Requests per time window
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Time when rate limit resets

Data Types

Template Types

  • IMAGE - Image generation templates
  • VIDEO - Video generation templates

Payment Status

  • pending - Payment initiated but not completed
  • completed - Payment successfully processed
  • failed - Payment failed
  • cancelled - Payment cancelled by user
  • refunded - Payment refunded

Task Status

  • pending - Task queued but not started
  • running - Task currently executing
  • completed - Task finished successfully
  • failed - Task failed with error

Refund Reasons

  • user_request - User requested refund
  • technical_issue - Technical problem occurred
  • duplicate - Duplicate payment
  • fraudulent - Fraudulent transaction