HTTP/REST API
Direct HTTP API access for any programming language or platform
Base URL
https://api.deepcreativelabs.com/v1All API requests should be made to this base URL. The current API version is v1.
Authentication
All API requests require authentication using an API key. Include your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY⚠️ Security: Never expose your API key in client-side code. Always make API requests from your backend server.
API Endpoints
/models/{provider}/{model}/predictionsCreate a new prediction (generate image or video) from a text prompt.
Request Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| provider | string | Yes | Model provider (e.g., 'black-forest-labs', 'google', 'openai') |
| model | string | Yes | Model ID (e.g., 'flux-kontext-max', 'nano-banana', 'sora-2') |
| input | object | Yes | Model-specific input parameters (prompt, width, height, etc.) |
| webhook | string | No | Webhook URL for completion notification |
Response Format
Success Response (Processing)
{
"job_id": "pred_abc123xyz",
"status": "processing",
"model": "flux-kontext-max",
"created_at": "2024-01-15T10:30:00Z",
"urls": {
"get": "https://api.deepcreativelabs.com/v1/status/pred_abc123xyz",
"cancel": "https://api.deepcreativelabs.com/v1/cancel/pred_abc123xyz"
}
}Success Response (Completed)
{
"job_id": "pred_abc123xyz",
"status": "succeeded",
"model": "flux-kontext-max",
"created_at": "2024-01-15T10:30:00Z",
"completed_at": "2024-01-15T10:30:45Z",
"output": [
"https://cdn.deepcreativelabs.com/outputs/abc123.png"
],
"metrics": {
"predict_time": 45.2
}
}Error Response
{
"error": {
"code": "invalid_request",
"message": "Missing required parameter: prompt",
"details": {
"param": "prompt",
"type": "missing_field"
}
}
}HTTP Status Codes
| Status Code | Meaning | Description |
|---|---|---|
| 200 | OK | Request successful |
| 201 | Created | Prediction created successfully |
| 400 | Bad Request | Invalid request parameters |
| 401 | Unauthorized | Invalid or missing API key |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Server error occurred |
Rate Limits
Free Tier
100 requests per day
Pro Tier
1,000 requests per day
Enterprise Tier
Custom limits based on your needs
Rate limit information is included in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Code Examples
1curl -X POST https://api.deepcreativelabs.com/v1/black-forest-labs/flux-kontext-max/predictions \
2 -H "Authorization: Bearer YOUR_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "input": {
6 "prompt": "A beautiful sunset over mountains",
7 "width": 1024,
8 "height": 768
9 }
10 }'Best Practices
✓ Use Webhooks
Webhooks are more efficient than polling. They reduce API calls and provide instant notifications.
✓ Handle Errors Gracefully
Always check HTTP status codes and handle errors appropriately. Implement retry logic with exponential backoff for transient errors.
✓ Respect Rate Limits
Monitor rate limit headers and implement appropriate throttling to avoid 429 errors.
✓ Secure Your API Key
Never expose your API key in client-side code. Always make API requests from your backend server.
✓ Cache Results
If you're generating the same content multiple times, consider caching the results to reduce API usage.
Need Help?
If you have questions or need assistance with the HTTP/REST API: