Usage Examples

The DesignCombo API is built on REST principles, enforcing HTTPS for all requests to ensure data security, integrity, and privacy.

Base URL

https://api.designcombo.dev/v1

Making Your First Request

Here's a simple example to get you started with text-to-speech:

Terminal

$ curl -X POST 'https://api.designcombo.dev/v1/text-to-speech' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"text": "Hello world", "voiceId": "69nXRvRvFpjSXhH7IM5l"}'

Request Format

Content-Type

All requests must include the Content-Type: application/json header.

Request Body

For POST requests, send data as JSON in the request body:

{
  "text": "Hello world",
  "voiceId": "69nXRvRvFpjSXhH7IM5l",
  "format": "mp3"
}

File Uploads

For file uploads, use multipart/form-data:

Terminal

$ curl -X POST 'https://api.designcombo.dev/v1/speech-to-text' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@audio.mp3' \
  -F 'language=en'

Response Format

Success Responses

Successful responses include the requested data:

{
  "id": "job_123456789",
  "status": "completed",
  "result": {
    "audioUrl": "https://cdn.designcombo.dev/audio/123.mp3",
    "duration": 2.5
  },
  "createdAt": "2024-01-01T12:00:00Z"
}

Pagination

For endpoints that return lists, responses include pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "hasMore": true
  }
}

Code Examples

JavaScript/Node.js

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.designcombo.dev/v1';

// Text-to-speech
async function textToSpeech(text, voiceId) {
  const response = await fetch(`${BASE_URL}/text-to-speech`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      text,
      voiceId,
      format: 'mp3'
    })
  });
  
  return response.json();
}

// Speech-to-text
async function speechToText(audioFile) {
  const formData = new FormData();
  formData.append('file', audioFile);
  formData.append('language', 'en');
  
  const response = await fetch(`${BASE_URL}/speech-to-text`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    },
    body: formData
  });
  
  return response.json();
}

// Usage
textToSpeech('Hello world!', '69nXRvRvFpjSXhH7IM5l')
  .then(result => console.log('Audio URL:', result.result.audioUrl))
  .catch(error => console.error('Error:', error));

Python

import requests
import json

API_KEY = 'your_api_key_here'
BASE_URL = 'https://api.designcombo.dev/v1'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

def text_to_speech(text, voice_id):
    """Convert text to speech"""
    url = f'{BASE_URL}/text-to-speech'
    data = {
        'text': text,
        'voiceId': voice_id,
        'format': 'mp3'
    }
    
    response = requests.post(url, headers=headers, json=data)
    return response.json()

def speech_to_text(audio_file_path):
    """Convert speech to text"""
    url = f'{BASE_URL}/speech-to-text'
    
    with open(audio_file_path, 'rb') as audio_file:
        files = {'file': audio_file}
        data = {'language': 'en'}
        
        response = requests.post(
            url, 
            headers={'Authorization': f'Bearer {API_KEY}'},
            files=files,
            data=data
        )
    
    return response.json()

# Usage
result = text_to_speech('Hello world!', '69nXRvRvFpjSXhH7IM5l')
print('Audio URL:', result['result']['audioUrl'])

PHP

<?php

$api_key = 'your_api_key_here';
$base_url = 'https://api.designcombo.dev/v1';

function textToSpeech($text, $voiceId) {
    global $api_key, $base_url;
    
    $url = $base_url . '/text-to-speech';
    $data = [
        'text' => $text,
        'voiceId' => $voiceId,
        'format' => 'mp3'
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $api_key,
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Usage
$result = textToSpeech('Hello world!', '69nXRvRvFpjSXhH7IM5l');
echo 'Audio URL: ' . $result['result']['audioUrl'] . "\n";
?>

Service Categories

Voice Services

Text-to-Speech - Convert text to natural-sounding speech
Speech-to-Text - Transcribe audio files to text
Voice Cloning - Change voice in audio files
Dubbing - Create dubbed versions in different languages
Voice Search - Browse available voices

Avatar Services

Avatar Expansion - Extend avatar video duration
Avatar Search - Browse available avatars

Video Processing

Video Trimming - Trim videos to specific time ranges

Content Generation

Sound Generation - Create audio from text prompts
Image Generation - Generate images from text descriptions

Best Practices

1. Handle Responses Properly

Always check the response status and handle errors:

async function makeApiRequest(url, options) {
  const response = await fetch(url, options);
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }
  
  return response.json();
}

2. Use Environment Variables

Store your API key securely:

// .env file
DESIGNCOMBO_API_KEY=your_api_key_here

// Usage
const apiKey = process.env.DESIGNCOMBO_API_KEY;

3. Implement Retry Logic

For production applications, implement retry logic:

async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
    }
  }
}

4. Validate Input

Always validate your input before making requests:

function validateTextToSpeechParams(params) {
  if (!params.text || params.text.trim().length === 0) {
    throw new Error('Text is required');
  }
  
  if (params.text.length > 5000) {
    throw new Error('Text cannot exceed 5000 characters');
  }
  
  if (!params.voiceId) {
    throw new Error('Voice ID is required');
  }
}

Next Steps

Authentication - Learn about API authentication
Rate Limiting - Understand API limits
Errors - Handle errors properly
Reference - Complete API documentation