Image

Generate high-quality AI images with customizable models, aspect ratios, and quality tiers.

Create Image

Generate AI images from text prompts.

POST /ugc/image

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token with your API key
`Content-Type`	Yes	`application/json`

Request Body

{
  "projectId": "clxxx...",
  "prompt": "A professional product photo of a sleek smartphone on a marble surface with soft lighting",
  "model": "seedream-4.5",
  "tier": "pro",
  "aspectRatio": "1:1",
  "variants": 2
}

Parameters

Parameter	Type	Required	Default	Description
`projectId`	string	Yes	-	Your project ID (CUID format)
`prompt`	string	Yes	-	Image description (10-3000 characters)
`model`	string	Yes	-	Model: `"nano-banana-pro"` or `"seedream-4.5"`
`tier`	string	Yes	-	Quality tier: `"standard"` or `"pro"`
`aspectRatio`	string	No	`"9:16"`	Aspect ratio: `"9:16"`, `"1:1"`, or `"16:9"`
`variants`	number	No	`1`	Number of image variants (1-8)

Models

Model	Description	Best For
`nano-banana-pro`	Fast generation, good quality	Quick iterations, drafts
`seedream-4.5`	High quality, detailed	Final production images

Resolution

Resolution is determined by the combination of model and tier:

Model	Standard Tier	Pro Tier
`nano-banana-pro`	1K	4K
`seedream-4.5`	2K	4K

Response

Success Response (202 Accepted)

{
  "data": {
    "jobs": [
      {
        "ugcId": "clxxx...",
        "variantIndex": 0,
        "status": "PENDING",
        "creditsCharged": 8
      },
      {
        "ugcId": "clyyy...",
        "variantIndex": 1,
        "status": "PENDING",
        "creditsCharged": 8
      }
    ],
    "totalCreditsCharged": 16,
    "remainingCredits": 4984
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}

Examples

curl -X POST https://api.ugclab.app/api/v1/ugc/image \
  -H "Authorization: Bearer ugc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "clxyz123...",
    "prompt": "A stunning product photo of wireless earbuds floating in space with cosmic background",
    "model": "seedream-4.5",
    "tier": "pro",
    "aspectRatio": "1:1",
    "variants": 2
  }'

const response = await fetch('https://api.ugclab.app/api/v1/ugc/image', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ugc_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    projectId: 'clxyz123...',
    prompt: 'A stunning product photo of wireless earbuds',
    model: 'seedream-4.5',
    tier: 'pro',
    aspectRatio: '1:1',
    variants: 2,
  }),
});

const data = await response.json();

if (response.ok) {
  console.log('Images created:', data.data.jobs);
  console.log('Credits charged:', data.data.totalCreditsCharged);
} else {
  console.error('Error:', data.error.message);
}

import requests

response = requests.post(
    'https://api.ugclab.app/api/v1/ugc/image',
    headers={
        'Authorization': 'Bearer ugc_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'projectId': 'clxyz123...',
        'prompt': 'A stunning product photo of wireless earbuds',
        'model': 'seedream-4.5',
        'tier': 'pro',
        'aspectRatio': '1:1',
        'variants': 2,
    }
)

data = response.json()

if response.ok:
    print(f"Images created: {len(data['data']['jobs'])}")
    print(f"Credits charged: {data['data']['totalCreditsCharged']}")
else:
    print(f"Error: {data['error']['message']}")

Error Codes

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Invalid request parameters
`INSUFFICIENT_CREDITS`	402	Not enough credits in workspace
`PROJECT_NOT_FOUND`	404	Project not found in workspace
`IP_RATE_LIMITED`	429	Too many authentication attempts
`RATE_LIMIT_EXCEEDED`	429	API rate limit exceeded
`INTERNAL_ERROR`	500	Internal server error

Best Practices

Use tier: "standard" for testing and iterations before final pro-quality renders.

Detailed prompts: Be specific about lighting, composition, style, and mood for better results.
Test with Standard: Use tier: "standard" for testing and iterations before final pro-quality renders.
Use variants: Generate multiple variants to choose the best result.
Aspect ratio: Match your aspect ratio to your intended use case (9:16 for stories, 1:1 for posts, 16:9 for banners).
Use webhooks: Configure webhooks for real-time status updates instead of polling.

Projects API - Get project IDs
Job Status API - Check job progress
Authentication - API key setup

On this page