Tasks API

The Tasks API (/api/v1/task) is the main endpoint for processing AI tasks including text generation, image generation, and speech services.

Base URL

POST /api/v1/task

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Request Format

The endpoint accepts both JSON and FormData (multipart/form-data) requests:

JSON Request

{
  "model": "gpt-4",
  "messages": [
    {
      "role": "user",
      "content": "Hello, world!"
    }
  ],
  "max_tokens": 100,
  "temperature": 0.7
}

FormData Request (for file uploads)

curl -X POST https://your-domain.com/api/v1/task \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=eleven-labs-tts" \
  -F "text=Hello world" \
  -F "voice=adam" \
  -F "audio=@input.mp3"

Supported Task Types

Text Generation

Generate text using various language models.

OpenAI Models

• gpt-4
• gpt-4-turbo
• gpt-3.5-turbo

Request Example:

{
  "model": "gpt-4",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Explain quantum computing in simple terms."
    }
  ],
  "max_tokens": 500,
  "temperature": 0.7,
  "stream": false
}

Claude Models

• claude-3-opus
• claude-3-sonnet
• claude-3-haiku

Request Example:

{
  "model": "claude-3-sonnet",
  "messages": [
    {
      "role": "user",
      "content": "Write a short story about a robot."
    }
  ],
  "max_tokens": 1000
}

Mixtral Models

• mixtral-8x7b
• mixtral-8x22b

Image Generation

Generate images from text descriptions.

Black Forest Labs

• flux-1-pro
• flux-1-dev
• flux-1-schnell

Request Example:

{
  "model": "flux-1-pro",
  "prompt": "A beautiful sunset over a mountain lake, photorealistic",
  "width": 1024,
  "height": 1024,
  "num_inference_steps": 50,
  "guidance_scale": 7.5,
  "seed": 42
}

Speech Services

Text-to-Speech (ElevenLabs)

• eleven-labs-tts

Request Example:

{
  "model": "eleven-labs-tts",
  "text": "Hello, this is a test of the text-to-speech service.",
  "voice": "adam",
  "voice_settings": {
    "stability": 0.5,
    "similarity_boost": 0.5
  },
  "output_format": "mp3_44100_128"
}

Speech-to-Speech (ElevenLabs)

• eleven-labs-sts

FormData Request:

curl -X POST https://your-domain.com/api/v1/task \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=eleven-labs-sts" \
  -F "audio=@input.mp3" \
  -F "voice=adam" \
  -F "voice_settings={\"stability\": 0.5, \"similarity_boost\": 0.5}"

Speech-to-Text (ElevenLabs)

• eleven-labs-stt

FormData Request:

curl -X POST https://your-domain.com/api/v1/task \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=eleven-labs-stt" \
  -F "audio=@input.mp3"

Response Format

Success Response

{
  "id": "task_123456789",
  "object": "task.completion",
  "created": 1234567890,
  "model": "gpt-4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Generated response text..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 25,
    "total_tokens": 35
  }
}

Image Generation Response

{
  "id": "img_123456789",
  "object": "image.generation",
  "created": 1234567890,
  "model": "flux-1-pro",
  "data": [
    {
      "url": "https://your-domain.com/generated-image.png",
      "b64_json": "base64-encoded-image-data..."
    }
  ]
}

Speech Response

{
  "id": "speech_123456789",
  "object": "speech.generation",
  "created": 1234567890,
  "model": "eleven-labs-tts",
  "audio": {
    "url": "https://your-domain.com/generated-audio.mp3",
    "b64_json": "base64-encoded-audio-data..."
  }
}

Error Responses

Invalid Model

{
  "error": {
    "message": "Unsupported task type: invalid-model",
    "type": "invalid_request_error",
    "code": "unsupported_model"
  }
}

Rate Limit Exceeded

{
  "error": {
    "message": "Rate limit exceeded. Reset at 2024-01-01T12:00:00Z",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

Insufficient Credits

{
  "error": {
    "message": "Insufficient credits for this operation",
    "type": "insufficient_credits_error",
    "code": "insufficient_credits"
  }
}

Rate Limits

• Requests per minute: Based on your subscription plan
• Concurrent requests: Based on your subscription plan
• Token limits: Model-specific limits apply

Rate limit information is returned in response headers:

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

Usage Tracking

All successful requests are tracked for billing purposes. Usage information includes:

• Model used
• Tokens consumed (for text models)
• Processing time
• Output size

Best Practices

1. Choose the right model: Select the most appropriate model for your use case to optimize cost and performance
2. Set reasonable limits: Use max_tokens to control output length and costs
3. Handle errors gracefully: Implement proper error handling for rate limits and other API errors
4. Monitor usage: Keep track of your API usage to manage costs
5. Use streaming for long responses: Enable streaming for better user experience with long text generation

Examples

Simple Text Generation

const response = await fetch('https://your-domain.com/api/v1/task', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4',
    messages: [
      { role: 'user', content: 'What is the capital of France?' }
    ],
    max_tokens: 50
  })
});

const data = await response.json();
console.log(data.choices[0].message.content);

Image Generation

import requests

response = requests.post(
    'https://your-domain.com/api/v1/task',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'flux-1-pro',
        'prompt': 'A futuristic city at night with neon lights',
        'width': 1024,
        'height': 1024
    }
)

data = response.json()
image_url = data['data'][0]['url']

Text-to-Speech

curl -X POST https://your-domain.com/api/v1/task \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "eleven-labs-tts",
    "text": "Hello, this is a test of our text-to-speech API.",
    "voice": "adam"
  }'