# FUSARA INTEGRATION API DOCUMENTATION
## For LLM Coding Agents

Last Updated: 2026-03-21
Version: 4.0

---

## TABLE OF CONTENTS

1. [QUICK START](#1-quick-start)
2. [AUTHENTICATION](#2-authentication)
3. [RESPONSE FORMAT](#3-response-format)
4. [PROVIDER CATALOG](#4-provider-catalog)
5. [PRESET SYSTEM](#5-preset-system)
6. [TEMPLATE TYPES](#6-template-types)
7. [PROVIDER COMPATIBILITY MATRIX](#7-provider-compatibility-matrix)
8. [REQUEST STRUCTURE & POLYMORPHISM](#8-request-structure--polymorphism)
9. [WORKFLOW EXAMPLES](#9-workflow-examples)
10. [COMMON MISTAKES & FIXES](#10-common-mistakes--fixes)
11. [ENDPOINT REFERENCE](#11-endpoint-reference)

---

## 1. QUICK START

### Workflow Overview

```
1. Choose Provider → 2. Build Request → 3. Send → 4. Poll Status → 5. Retrieve Result
```

**2-Minute Guide:**

```bash
# 1. Generate Image (Flux1Dev)
POST /api/integration/imaging/generate
Headers: X-API-Key: your_api_key
Body:
{
  "__type": 5,
  "Prompt": "A serene mountain landscape at sunset",
  "Width": 1024,
  "Height": 1024,
  "NumberOfImages": 1
}

# Response:
{
  "statusCode": 200,
  "succeeded": true,
  "statusCodeInt": 200,
  "data": {
    "taskId": 12345,
    "images": [],
    "workflowStatusId": 10,
    "errorCategoryId": null,
    "errorCode": null,
    "userStandardMessage": null,
    "userDetailedMessage": null
  }
}

# 2. Poll Task Status
GET /api/integration/imaging/tasks/12345/status
Headers: X-API-Key: your_api_key

# Response (processing):
{ "statusCode": 200, "succeeded": true, "statusCodeInt": 200, "data": 20 }

# 3. Retrieve Result (when data = 100, meaning Succeeded)
GET /api/integration/imaging/tasks/12345
Headers: X-API-Key: your_api_key

# Response:
{
  "statusCode": 200,
  "succeeded": true,
  "statusCodeInt": 200,
  "data": {
    "taskId": 12345,
    "images": [
      { "id": 67890, "url": "https://storage.fusara.com/media/67890.png" }
    ],
    "workflowStatusId": 100,
    "errorCategoryId": null,
    "errorCode": null,
    "userStandardMessage": null,
    "userDetailedMessage": null
  }
}
```

---

## 2. AUTHENTICATION

All Integration API endpoints require authentication via API key.

**Header:**
```
X-API-Key: your_api_key_here
```

**Error Response (403 Forbidden):**
```json
{
  "statusCode": 403,
  "succeeded": false,
  "statusCodeInt": 403,
  "error": { "code": null, "description": "Invalid or missing API key" }
}
```

**Note:** Invalid or missing API key returns HTTP 403 (Forbidden), not 401.

---

## 3. RESPONSE FORMAT

All API responses are wrapped in a standard envelope.

### 3.1 Success Response

```json
{ "statusCode": 200, "succeeded": true, "statusCodeInt": 200, "data": { ... } }
```

### 3.2 Error Response

```json
{
  "statusCode": 500, "succeeded": false, "statusCodeInt": 500,
  "error": { "code": "ERROR_CODE", "description": "Human-readable error message" }
}
```

### 3.3 Paged Response

```json
{
  "statusCode": 200, "succeeded": true, "statusCodeInt": 200,
  "pageNumber": 1, "pageSize": 20, "totalPages": 5, "totalRecords": 95,
  "data": [ ... ]
}
```

### 3.4 Task Response (GenerateMediaTaskSimpleResponse)

| Field | Type | Description |
|-------|------|-------------|
| `taskId` | uint | Unique task identifier |
| `images` | array | Generated media results (empty until completed) |
| `images[].id` | uint | Media ID |
| `images[].url` | string | Direct URL to the generated media |
| `workflowStatusId` | int | Task status (see below) |
| `errorCategoryId` | int? | Error category if failed |
| `errorCode` | string? | Provider-specific error code |
| `userStandardMessage` | string? | Short error description |
| `userDetailedMessage` | string? | Detailed error description |

### 3.5 Workflow Status Values (workflowStatusId)

| Value | Name | Description |
|-------|------|-------------|
| 10 | Initial | Task created, queued |
| 20 | Processing | Being processed |
| 100 | Succeeded | Completed successfully |
| 200 | Failed | Failed |

### 3.6 Error Categories (errorCategoryId)

| Value | Name |
|-------|------|
| 0 | Unknown |
| 1 | QuotaExceeded |
| 2 | ContentModeration |
| 3 | InvalidInput |
| 4 | ProviderError |
| 5 | Timeout |

---

## 4. PROVIDER CATALOG

### 4.1 Overview Table

| ID  | Name                     | Category | Base Request Type               |
|-----|--------------------------|----------|---------------------------------|
| 1   | Midjourney               | Image    | CreateGenerateMediaTaskRequest  |
| 2   | SD                       | Image    | GenerateSDImageTaskBase         |
| 3   | Upscale                  | Image    | UpscaleImageTaskBase            |
| 4   | SDXL                     | Image    | GenerateSDImageTaskBase         |
| 5   | Flux1Dev                 | Image    | GenerateSDImageTaskBase         |
| 6   | RMBG                     | Image    | RemoveBackgroundTaskBase        |
| 7   | Supir                    | Image    | UpscaleImageTaskBase            |
| 8   | Clarity                  | Image    | UpscaleImageTaskBase            |
| 9   | Flux1FillInpaint         | Image    | InpaintTaskBase                 |
| 10  | Flux1Redux               | Image    | VaryTaskBase                    |
| 11  | HiDreamI1Full            | Image    | GenerateSDImageTaskBase         |
| 12  | HiDreamE1Full            | Image    | ModifyTaskBase                  |
| 13  | HyperLoRA                | Image    | ModifyTaskBase                  |
| 14  | Flux1KontextDev          | Image    | ModifyTaskBase                  |
| 15  | GoogleImagenCreate       | Image    | CreateGenerateMediaTaskRequest  |
| 16  | OpenAIGptImage1Create    | Image    | CreateGenerateMediaTaskRequest  |
| 17  | OpenAIGptImage1Edit      | Image    | ModifyTaskBase                  |
| 18  | GoogleGeminiCreate       | Image    | CreateGenerateMediaTaskRequest  |
| 19  | GoogleGeminiEdit         | Image    | ModifyTaskBase                  |
| 20  | Flux1FillOutpaint        | Image    | OutpaintTaskBase                |
| 21  | QwenCreate               | Image    | GenerateSDImageTaskBase         |
| 22  | Seedream                 | Image    | CreateGenerateMediaTaskRequest  |
| 23  | Seededit                 | Image    | ModifyTaskBase                  |
| 24  | QwenEdit                 | Image    | ModifyTaskBase                  |
| 25  | QwenEditOutpaint         | Image    | OutpaintTaskBase                |
| 26  | Flux1KontextMaxOutpaint  | Image    | OutpaintTaskBase                |
| 27  | ZImageTurbo              | Image    | GenerateSDImageTaskBase         |
| 28  | TopazUpscale             | Image    | UpscaleImageTaskBase            |
| 29  | GrokImageCreate          | Image    | CreateGenerateMediaTaskRequest  |
| 30  | GrokImageEdit            | Image    | ModifyTaskBase                  |
| 100 | GoogleVeoVideoCreate     | Video    | GenerateVideoTask               |
| 101 | KlingVideoCreate         | Video    | GenerateVideoTask               |
| 102 | SeedanceVideoCreate      | Video    | GenerateVideoTask               |
| 103 | Wan22VideoCreate         | Video    | GenerateSDVideoTaskBase         |
| 104 | OpenAISoraVideoCreate    | Video    | GenerateVideoTask               |
| 105 | HailuoVideoCreate        | Video    | GenerateVideoTask               |
| 106 | RunwayVideoCreate        | Video    | GenerateVideoTask               |
| 107 | Wan26VideoCreate         | Video    | GenerateVideoTask               |
| 108 | Seedance15VideoCreate    | Video    | GenerateVideoTask               |
| 109 | KlingV3VideoCreate       | Video    | GenerateVideoTask               |
| 110 | KlingO3VideoCreate       | Video    | GenerateVideoTask               |
| 111 | GrokVideoCreate          | Video    | GenerateVideoTask               |
| 200 | AudioSourceSeparationMDX | Audio    | AudioSourceSeparationTask       |

---

### 4.2 Detailed Provider Specifications — Image Providers

#### **Midjourney (ID: 1)**
| Property | Type | Valid Values | Default |
|----------|------|-------------|---------|
| `AspectRatio` | string? | "9:16", "3:4", "1:1", "4:3", "16:9" | "1:1" |
| `Chaos` | int? | 0-100 (step 5) | 0 |
| `Quality` | string? | ".25", ".5", "1", "2" | "1" |
| `Seed` | long? | any | null |
| `CharacterReference` | string? | URL | null |
| `CharacterWeight` | int? | 0-100 | 100 |
| `ImagePrompt` | string? | URL | null |
| `ImageWeight` | float? | 0-3 | 33 |
| `Style` | string? | "raw", "expressive" | null |
| `StyleReference` | string? | URL | null |
| `StyleWeight` | int? | 0-1000 | 10 |
| `Stylize` | int? | 0-1000 (step 50) | 100 |
| `Tile` | bool? | true/false | false |
| `Weird` | int? | 0-3000 (step 100) | 0 |
| `ModelVersion` | string? | varies | null |

**Note:** Does NOT support LoRA. NegativePrompt is inherited from base but ignored by provider.

---

#### **SD (ID: 2), SDXL (ID: 4), Flux1Dev (ID: 5), HiDreamI1Full (ID: 11), ZImageTurbo (ID: 27)**
**Base: GenerateSDImageTaskBaseRequest**

| Property | Type | Valid Values | Default (varies by provider) |
|----------|------|-------------|-----|
| `NumberOfImages` | int? | 1+ | 1 |
| `Width` | int? | 512-2048 | 1024 |
| `Height` | int? | 512-2048 | 1024 |
| `NumberOfInferenceSteps` | int? | 1-100 | SD:40, SDXL:25, Flux:40 |
| `GuidanceScale` | float? | 1-20 (step 0.5) | SD:4.5, SDXL:6.5, Flux:3.5 |
| `SamplingShift` | float? | float | null |
| `CheckpointName` | string? | checkpoint model name | null |
| `ClipSkip` | int? | 1-5 | SDXL:1 |

**SDXL only:** `EnableFaceDetailer` (bool?) — Enable face enhancement.

**ComfyUI Support:** These providers support LoRA, NegativePrompt, and presets.

---

#### **QwenCreate (ID: 21)**
**Base: GenerateSDImageTaskBaseRequest**

| Property | Type | Valid Values | Default |
|----------|------|-------------|---------|
| `Width` | int? | per aspect ratio (see below) | 1328 |
| `Height` | int? | per aspect ratio | 1328 |
| `NumberOfInferenceSteps` | int? | 1-100 | varies |
| `GuidanceScale` | float? | 1-20 | varies |
| `SamplingShift` | float? | float | varies |
| `WorkflowVariantId` | int? | int | null |

**Aspect Ratio → Size mapping:**
16:9→1664×928, 4:3→1472×1104, 3:2→1584×1056, 1:1→1328×1328, 2:3→1056×1584, 3:4→1104×1472, 9:16→928×1664

---

#### **Google Imagen (ID: 15)**
| Property | Type | Valid Values | Default |
|----------|------|-------------|---------|
| `Model` | string | "imagen-4.0-fast-generate-001", "imagen-4.0-generate-001", "imagen-4.0-ultra-generate-001" | "imagen-4.0-generate-001" |
| `AspectRatio` | string? | "9:16", "3:4", "1:1", "4:3", "16:9" | "1:1" |
| `SampleCount` | int | 1-8 | 1 |
| `EnhancePrompt` | bool? | true/false | false |
| `AddWatermark` | bool? | true/false | false |
| `Seed` | long? | any | null |

**Note:** Does NOT support LoRA or presets. Supports NegativePrompt.

---

#### **Google Gemini Create (ID: 18)**
| Property | Type | Valid Values | Default |
|----------|------|-------------|---------|
| `Model` | string? | "2.5-flash", "3.0-pro", "3.1-flash" | "3.0-pro" |
| `AspectRatio` | string? | "9:16", "2:3", "3:4", "4:5", "1:1", "5:4", "4:3", "3:2", "16:9", "21:9" | "1:1" |
| `Size` | string? | "1K", "2K", "3K", "4K" | "2K" |
| `Temperature` | float? | 0.0-2.0 | 1.0 |
| `TopP` | float? | 0.0-1.0 | 0.95 |
| `NumberOfImages` | int? | 1-4 | 1 |
| `Seed` | long? | any | null |

**Model mapping:** "2.5-flash"→gemini-2.5-flash-image, "3.0-pro"→gemini-3-pro-image-preview, "3.1-flash"→NanoBanana2 provider.

---

#### **Google Gemini Edit (ID: 19)**
**Base:** ModifyTaskBase. Same parameters as Gemini Create (Temperature, TopP, Seed, Size, Model, NumberOfImages).

---

#### **OpenAI GPT-Image1 Create (ID: 16)**
| Property | Type | Valid Values | Default |
|----------|------|-------------|---------|
| `N` | int | 1-4 | 1 |
| `Size` | string | "1024x1024", "1536x1024", "1024x1536", "auto" | "1024x1024" |
| `Quality` | string? | "low", "medium", "high" | "medium" |
| `Background` | string? | "transparent", "opaque", "auto" | "auto" |

---

#### **OpenAI GPT-Image1 Edit (ID: 17)**
**Base:** ModifyTaskBase.

| Property | Type | Valid Values | Default |
|----------|------|-------------|---------|
| `N` | int | 1-4 | 1 |
| `Size` | string | "1024x1024", "1536x1024", "1024x1536" | "1024x1024" |
| `Quality` | string? | "low", "medium", "high" | "medium" |
| `Background` | string? | "transparent", "opaque", "auto" | "auto" |
| `InputFidelity` | string? | "low", "high" | "low" |

---

#### **Seedream (ID: 22)**
| Property | Type | Valid Values | Default |
|----------|------|-------------|---------|
| `Size` | string | Dimension string per aspect ratio (see below) | "2048x2048" |
| `GuidanceScale` | float? | 1.0-10.0 | 2.5 |

**Aspect Ratios:** "9:21", "9:16", "2:3", "3:4", "1:1", "4:3", "3:2", "16:9", "21:9"

**Size by image quality:**
- 1K: 648×1512, 720×1280, 832×1248, 864×1152, 1024×1024, 1152×864, 1248×832, 1280×720, 1512×648
- 2K: 1296×3024, 1440×2560, 1664×2496, 1728×2304, 2048×2048, 2304×1728, 2496×1664, 2560×1440, 3024×1296
- 4K: 2592×6048, 2880×5120, 3328×4992, 3456×4608, 4096×4096, 4608×3456, 4992×3328, 5120×2880, 6048×2592

---

#### **Seededit (ID: 23)**
**Base:** ModifyTaskBase.

| Property | Type | Valid Values | Default |
|----------|------|-------------|---------|
| `Size` | string | "1K", "2K", "4K" | "2K" |
| `GuidanceScale` | float? | 0-10 | 5.5 |

**Aspect Ratios:** "9:21", "9:16", "2:3", "3:4", "1:1", "4:3", "3:2", "16:9", "21:9"

---

#### **Grok Image Create (ID: 29)**
| Property | Type | Valid Values | Default |
|----------|------|-------------|---------|
| `N` | int | 1-10 | 6 |
| `AspectRatio` | string? | "9:16", "2:3", "1:1", "3:2", "16:9" | "1:1" |

---

#### **Grok Image Edit (ID: 30)**
**Base:** ModifyTaskBase.

| Property | Type | Valid Values | Default |
|----------|------|-------------|---------|
| `NumberOfImages` | int? | 1-10 | 2 |
| `Width` | int? | pixels | null |
| `Height` | int? | pixels | null |
| `GuidanceScale` | float? | float | null |

---

#### **Upscale Providers (IDs: 3, 7, 8, 28)**
**Base:** UpscaleImageTaskBase. **Requires:** `InputMediaIds` or `InputMediaExternalUrls`.

| Provider | ScaleFactor | Extra Properties |
|----------|-------------|------------------|
| Upscale (3) | 1-4 (default: 4) | `UpscaleModelName`: "4x-UltraSharp.pth" (default), "4x_NMKD-Siax_200k.pth", "4x_foolhardy_Remacri.pth" |
| Supir (7) | 1-4 (default: 2) | — |
| Clarity (8) | 1-4 (default: 2) | — |
| TopazUpscale (28) | 1, 2, 4, 8 (default: 2) | — |

---

#### **RMBG — Remove Background (ID: 6)**
**Base:** RemoveBackgroundTaskBase. **Requires:** `InputMediaIds` or `InputMediaExternalUrls`.

| Property | Type | Valid Values | Default |
|----------|------|-------------|---------|
| `RemoveBackgroundModelName` | string | "RMBG-2.0", "INSPYRENET", "BEN", "BEN2" | "BEN2" |
| `Background` | string | "Alpha", "black", "white", "gray", "green", "blue", "red" | "Alpha" |
| `Sensitivity` | float | 0.0-1.0 | 0.5 |
| `ProcessingResolution` | int | pixels | 2048 |
| `MaskBlur` | int | 0+ | 0 |
| `MaskOffset` | int | 0+ | 0 |
| `InvertOutput` | bool | true/false | false |

---

#### **Flux1FillInpaint (ID: 9)**
**Base:** InpaintTaskBase. **Requires:** `InputMediaIds` or `InputMediaExternalUrls`.

| Property | Type | Default |
|----------|------|---------|
| `NumberOfImages` | int? | 1 |
| `NumberOfInferenceSteps` | int? | 20 |
| `GuidanceScale` | float? | 1.0 |
| `SimilarityToOriginal` | float? | 0 |
| `MaskFeatherSize` | int? | 6 |
| `MergeIntoOriginal` | bool? | false |
| `MaskImageId` | uint? | null |
| `MaskJson` | string? | null |

---

#### **Outpaint Providers (IDs: 20, 25, 26)**
**Base:** OutpaintTaskBase. **Requires:** `InputMediaIds` or `InputMediaExternalUrls`.

| Property | Type | Default |
|----------|------|---------|
| `Width` | int? | 1024 |
| `Height` | int? | 1024 |
| `NumberOfImages` | int? | 1 |
| `NumberOfInferenceSteps` | int? | 20 |
| `GuidanceScale` | float? | 1.0 |
| `MaskFeatherSize` | int? | 24 |
| `MergeIntoOriginal` | bool? | false |
| `AutoBackgroundPrompt` | bool? | false |

**Flux1KontextMaxOutpaint (26):** Additional `WorkflowVariantId` (int?). Aspect ratios with specific pixel sizes:
21:9→1568×672, 2:1→1456×720, 16:9→1392×752, 3:2→1248×832, 4:3→1184×880, 5:4→1104×944, 1:1→1024×1024, 4:5→944×1104, 3:4→880×1184, 2:3→832×1248, 9:16→752×1392, 1:2→720×1456, 9:21→672×1568

---

#### **Flux1Redux — Image Variation (ID: 10)**
**Base:** VaryTaskBase. **Requires:** `InputMediaIds` or `InputMediaExternalUrls`.

| Property | Type | Default |
|----------|------|---------|
| `NumberOfImages` | int? | 1 |
| `Width` | int? | 1024 |
| `Height` | int? | 1024 |
| `NumberOfInferenceSteps` | int? | 50 |
| `GuidanceScale` | float? | 5 |
| `Strength` | float? | 0.5 |

---

#### **HyperLoRA (ID: 13)**
**Base:** ModifyTaskBase. **Requires:** `InputMediaIds` or `InputMediaExternalUrls`.

| Property | Type | Valid Values | Default |
|----------|------|-------------|---------|
| `SDXLModelName` | string? | "realvisxlV50_v50Bakedvae.safetensors", "cyberrealisticXL_v11VAE.safetensors" | "realvisxlV50_v50Bakedvae.safetensors" |
| `HyperLoRAModelName` | string? | "sdxl_hyper_id_lora_v1_fidelity", "sdxl_hyper_id_lora_v1_edit" | "sdxl_hyper_id_lora_v1_fidelity" |
| `NumberOfImages` | int? | 1+ | 1 |
| `NumberOfInferenceSteps` | int? | 1-100 | 50 |
| `GuidanceScale` | float? | 1-20 | 5 |
| `StopAtClipLayer` | float? | float | -2 |
| `LoRAWeight` | float? | 0-1 | 0.85 |

---

#### **Flux1KontextDev (ID: 14), QwenEdit (ID: 24)**
**Base:** ModifyTaskBase. **Requires:** `InputMediaIds` or `InputMediaExternalUrls`.

| Property | Type | Default |
|----------|------|---------|
| `NumberOfImages` | int? | 1 |
| `NumberOfInferenceSteps` | int? | 50 (Kontext), 50 (QwenEdit) |
| `GuidanceScale` | float? | 5 (Kontext), 4 (QwenEdit) |
| `KeepOriginalImageSize` | bool? | false |
| `Width` | int? | 1024 |
| `Height` | int? | 1024 |

**QwenEdit only:** `WorkflowVariantId` (int?)

---

### 4.3 Detailed Provider Specifications — Video Providers

**Base class properties for all video providers (CreateGenerateVideoTaskRequest):**

| Property | Type | Description |
|----------|------|-------------|
| `Model` | string? | Model identifier (provider-specific) |
| `Duration` | float? | Duration in SECONDS |
| `Seed` | long? | Reproducibility seed |
| `AspectRatio` | string? | Aspect ratio |
| `Resolution` | string? | Output resolution |
| `FPS` | float? | Frames per second |
| `GenerateAudio` | bool? | Generate audio track |

---

#### **GoogleVeo (ID: 100)**
| Property | Valid Values | Default |
|----------|-------------|---------|
| `Model` | "veo-3.1-generate-preview", "veo-3.1-fast-generate-preview" | "veo-3.1-generate-preview" |
| `Duration` | 4, 6, 8 | 8 |
| `AspectRatio` | "9:16", "16:9" | "16:9" |
| `Resolution` | "720p", "1080p" | "720p" |
| `GenerateAudio` | true/false | false |
| `Seed` | 0-4294967295 | null |

**Presets:** ImageReference, FirstFrameReference, LastFrameReference. Supports NegativePrompt.

---

#### **Kling 2.6 (ID: 101)**
| Property | Valid Values | Default |
|----------|-------------|---------|
| `Duration` | 5, 10 | 5 |
| `AspectRatio` | "9:16", "1:1", "16:9" | "16:9" |
| `GenerateAudio` | true/false | false |
| `GuidanceScale` | float | null |

**Presets:** FirstFrameReference.

---

#### **Seedance 1.0 (ID: 102)**
| Property | Valid Values | Default |
|----------|-------------|---------|
| `Model` | "seedance-1-0-lite-t2v-250428", "seedance-1-0-lite-i2v-250428", "seedance-1-0-pro-250528" | varies |
| `Duration` | 3-15 (step 1) | 5 |
| `AspectRatio` | "9:16", "3:4", "1:1", "4:3", "16:9", "21:9" | "16:9" |
| `Resolution` | "480p", "720p", "1080p" | "720p" |
| `CameraFixed` | true/false | false |

**Presets:** FirstFrameReference.

---

#### **Wan 2.2 (ID: 103) — SD-based**
| Property | Valid Values | Default |
|----------|-------------|---------|
| `Duration` | 3-12 (step 1) | 5 |
| `AspectRatio` | "9:16", "1:1", "16:9" | "16:9" |
| `Resolution` | "480p" | "480p" |
| `FPS` | 16 | 16 |
| `Width` | int | varies |
| `Height` | int | varies |
| `NumberOfInferenceSteps` | int | 4 |
| `GuidanceScale` | float | 1 |
| `SamplingShift` | float | 5 |

**Presets:** FirstFrameReference, LastFrameReference, PreviousVideoReference. Supports LoRA.

---

#### **OpenAI Sora (ID: 104)**
| Property | Valid Values | Default |
|----------|-------------|---------|
| `Model` | "sora-2", "sora-2-pro" | "sora-2" |
| `Duration` | 4, 8, 12 | 8 |
| `Size` | "720x1280" (9:16), "1280x720" (16:9), "1024x1792" (9:16, pro only), "1792x1024" (16:9, pro only) | "1280x720" |

**Note:** Uses `Size` instead of `AspectRatio`/`Resolution`.

**Presets:** FirstFrameReference.

---

#### **Hailuo 2.3 (ID: 105)**
| Property | Valid Values | Default |
|----------|-------------|---------|
| `Model` | "MiniMax-Hailuo-2.3", "MiniMax-Hailuo-2.3-Fast" | "MiniMax-Hailuo-2.3" |
| `Duration` | 3-15 (step 1) | 6 |
| `Resolution` | "768P", "1080P" | "768P" |
| `PromptOptimizer` | true/false | true |

**Presets:** None.

---

#### **Runway (ID: 106)**
| Property | Valid Values | Default |
|----------|-------------|---------|
| `Model` | "gen4_turbo" (I2V), "gen3a_turbo" (I2V), "veo3.1" (T2V), "veo3.1_fast" (T2V), "veo3" (T2V) | varies |
| `Duration` | 3-15 (step 1), mapped: <8→5, >=8→10 | 5 |
| `Resolution` | "720p", "1080p" | "720p" |
| `AspectRatio` | "9:16", "3:4", "1:1", "4:3", "16:9" | "16:9" |

**Presets:** None.

---

#### **Wan 2.6 (ID: 107)**
| Property | Valid Values | Default |
|----------|-------------|---------|
| `Model` | "wan2.6-i2v-flash", "wan2.6-i2v", "wan2.6-t2v", "wan2.6-r2v" | varies |
| `Duration` | float | 5 |
| `Resolution` | "720p", "1080p" | "720p" |

**Presets:** None.

---

#### **Seedance 1.5 Pro (ID: 108)**
| Property | Valid Values | Default |
|----------|-------------|---------|
| `Duration` | 4, 8, 12 | 8 |
| `AspectRatio` | "9:16", "3:4", "1:1", "4:3", "16:9", "21:9", "adaptive" | "16:9" |
| `Resolution` | "480p", "720p", "1080p" | "720p" |
| `CameraFixed` | true/false | false |
| `GenerateAudio` | true/false | true |

**Presets:** FirstFrameReference.

---

#### **Kling V3 (ID: 109)**
| Property | Valid Values | Default |
|----------|-------------|---------|
| `Model` | "standard", "pro" | "standard" |
| `Duration` | 5, 10 | 5 |
| `AspectRatio` | "9:16", "1:1", "16:9" | "16:9" |
| `GuidanceScale` | float | 0.5 |
| `GenerateAudio` | true/false | true |

---

#### **Kling O3 (ID: 110)**
| Property | Valid Values | Default |
|----------|-------------|---------|
| `Model` | "standard", "pro" | "standard" |
| `Duration` | 5, 10 | 5 |
| `AspectRatio` | "9:16", "1:1", "16:9" | "16:9" |
| `GenerateAudio` | true/false | false |

---

#### **Grok Video (ID: 111)**
| Property | Valid Values | Default |
|----------|-------------|---------|
| `Mode` | "fun", "normal", "spicy" | "normal" |
| `Duration` | 6, 10 | 6 |
| `Resolution` | "480p", "720p" | "720p" |
| `AspectRatio` | "9:16", "2:3", "1:1", "3:2", "16:9" | "16:9" |

---

### 4.4 Audio Provider

#### **Audio Source Separation MDX (ID: 200)**
**Requires:** `InputMediaIds` or `InputMediaExternalUrls` (audio file).

| Property | Type | Valid Values |
|----------|------|-------------|
| `Model` | string? | "UVR FT" (Clean Vocal), "Kim Jensen 2" (Natural Vocal), "UVR Main" (Balanced), "UVR Karaoke" (Remove Lead) |

---

## 5. PRESET SYSTEM

Presets enhance generation with visual references or prompt supplements.

### 5.1 Preset Types

| ID | Name                    | Category          | Properties                          |
|----|-------------------------|-------------------|-------------------------------------|
| 1  | ImageReference          | Visual Reference  | Weight, ExternalUrl ⊕ ImageId       |
| 2  | StyleReference          | Visual Reference  | Weight, ExternalUrl ⊕ ImageId       |
| 3  | CharacterReference      | Visual Reference  | Weight, ExternalUrl ⊕ ImageId       |
| 8  | ContourReference        | Visual Reference  | Weight, ExternalUrl ⊕ ImageId       |
| 9  | DepthReference          | Visual Reference  | Weight, ExternalUrl ⊕ ImageId       |
| 10 | CompositionReference    | Visual Reference  | Weight, ExternalUrl ⊕ ImageId       |
| 11 | FirstFrameReference     | Visual Reference  | Weight, ExternalUrl ⊕ ImageId       |
| 12 | LastFrameReference      | Visual Reference  | Weight, ExternalUrl ⊕ ImageId       |
| 13 | PreviousVideoReference  | Visual Reference  | Weight, ExternalUrl ⊕ ImageId       |
| 4  | Emotion                 | Prompt Supplement | Weight                              |
| 5  | Camera                  | Prompt Supplement | Weight                              |
| 6  | ColorPalette            | Prompt Supplement | Weight                              |
| 7  | Lighting                | Prompt Supplement | Weight                              |

**XOR Constraint:** For visual references, provide EITHER `ExternalUrl` OR `ImageId`, NOT both.

---

### 5.2 Preset Examples

**Visual Reference:**
```json
{ "__type": 2, "Weight": 0.75, "ExternalUrl": "https://example.com/style.jpg" }
```
OR
```json
{ "__type": 2, "Weight": 0.75, "ImageId": 12345 }
```

**Prompt Supplement:**
```json
{ "__type": 4, "Weight": 0.5 }
```

---

## 6. TEMPLATE TYPES

| ID | Name                   | Description                          | Key Providers                      |
|----|------------------------|--------------------------------------|------------------------------------|
| 1  | TextToImage            | Generate from text prompt            | Midjourney, Flux1Dev, Imagen, Grok |
| 2  | Upscale                | Increase image resolution            | Upscale, Supir, Clarity, Topaz     |
| 3  | Inpaint                | Fill masked regions                  | Flux1FillInpaint                   |
| 4  | Outpaint               | Extend image boundaries              | Flux1FillOutpaint, Qwen, Kontext   |
| 5  | Vary                   | Create variations                    | Flux1Redux                         |
| 6  | RemoveBackground       | Background removal                   | RMBG                               |
| 7  | Modify                 | Edit existing images                 | HyperLoRA, QwenEdit, Seededit, Grok|
| 8  | TextToVideo            | Generate video from text/image       | Veo, Kling, Hailuo, Runway, Grok  |
| 9  | AudioSourceSeparation  | Separate audio tracks                | MDX                                |

---

## 7. PROVIDER COMPATIBILITY MATRIX

### 7.1 LoRA Support

**ONLY ComfyUI-based providers support LoRA:**
SD (2), SDXL (4), Flux1Dev (5), HiDreamI1Full (11), HyperLoRA (13), Flux1KontextDev (14), QwenCreate (21), QwenEdit (24), ZImageTurbo (27), Wan22VideoCreate (103).

### 7.2 Presets Support per Provider

| Provider              | ID  | Supported Presets                                        |
|-----------------------|-----|----------------------------------------------------------|
| Midjourney            | 1   | ImageRef, StyleRef, CharRef                              |
| SDXL                  | 4   | ImageRef, StyleRef, CharRef, ContourRef, DepthRef, CompositionRef |
| Flux1Dev              | 5   | ImageRef, StyleRef, CharRef, ContourRef, DepthRef        |
| GoogleGeminiCreate    | 18  | ImageRef                                                 |
| OpenAIGptImage1Create | 16  | ImageRef                                                 |
| Seedream              | 22  | ImageRef                                                 |
| GrokImageCreate       | 29  | ImageRef                                                 |
| QwenCreate            | 21  | ImageRef                                                 |
| GoogleVeo             | 100 | ImageRef, FirstFrameRef, LastFrameRef                    |
| Kling                 | 101 | FirstFrameRef                                            |
| Seedance              | 102 | FirstFrameRef                                            |
| Seedance15            | 108 | FirstFrameRef                                            |
| Wan22                 | 103 | FirstFrameRef, LastFrameRef, PreviousVideoRef            |
| OpenAISora            | 104 | FirstFrameRef                                            |

**No presets:** GoogleImagen (15), ZImageTurbo (27), Hailuo (105), Runway (106), Wan26 (107), KlingV3 (109), KlingO3 (110), GrokVideo (111).

---

## 8. REQUEST STRUCTURE & POLYMORPHISM

### 8.1 Base Request Properties

All requests inherit from `CreateGenerateMediaTaskRequest`:

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `__type` | int | required | Provider discriminator (Section 4.1) |
| `Prompt` | string | required | Generation prompt |
| `NegativePrompt` | string? | null | Negative prompt |
| `LoRATriggerString` | string? | null | LoRA trigger words |
| `WorkflowVariantId` | int? | null | ComfyUI workflow variant |
| `SkipPromptPreprocessing` | bool | false | Skip AI prompt enhancement |
| `SkipImageAnalysis` | bool | true | Skip AI image analysis |
| `CompletionCallbackUrl` | string? | null | Webhook URL for completion |
| `CompletionTimeout` | int? | null | Callback timeout (ms) |
| `TaskPresets` | array | [] | Preset parameters (Section 5) |
| `TaskPresetGroups` | array | [] | Grouped presets |
| `TaskModels` | array | [] | LoRA models to apply |

### 8.2 Media-to-Media Requests

Tasks that modify existing media accept:

| Property | Type | Description |
|----------|------|-------------|
| `InputMediaIds` | uint[] | Existing media IDs |
| `InputMediaExternalUrls` | string[] | External URLs (auto-uploaded) |

**XOR Constraint:** Provide EITHER `InputMediaIds` OR `InputMediaExternalUrls`, NOT both. Enforced — returns 400.

### 8.3 TaskModels Structure (LoRA)

```json
{ "TaskModels": [{ "Strength": 0.8, "ModelId": 999 }] }
```

| Property | Type | Description |
|----------|------|-------------|
| `Strength` | float | Model weight/strength |
| `ModelId` | uint? | Pre-uploaded model ID (preferred) |
| `ModelUrl` | string? | Civitai URL (auto-imported, slower) |

### 8.4 Auto-Upload Behavior

- **Preset ExternalUrl:** Downloaded, uploaded (24h TTL), converted to ImageId automatically.
- **InputMediaExternalUrls:** Each URL downloaded & uploaded, set as InputMediaIds.
- **TaskModels ModelUrl:** Civitai URLs auto-imported, converted to ModelId.
- **All media uploaded via Integration API expires after 24 hours.**

---

## 9. WORKFLOW EXAMPLES

### 9.1 Text-to-Image (Flux1Dev)

```json
POST /api/integration/imaging/generate
{
  "__type": 5,
  "Prompt": "A serene mountain landscape at sunset, photorealistic",
  "NegativePrompt": "blurry, low quality, watermark",
  "Width": 1024, "Height": 1024,
  "NumberOfImages": 1, "NumberOfInferenceSteps": 30, "GuidanceScale": 7.5
}
```

### 9.2 Google Gemini with Model Selection

```json
POST /api/integration/imaging/generate
{
  "__type": 18,
  "Prompt": "Cyberpunk city at night",
  "Model": "3.0-pro",
  "Size": "2K",
  "AspectRatio": "16:9",
  "Temperature": 0.8
}
```

### 9.3 Google Imagen 4

```json
POST /api/integration/imaging/generate
{
  "__type": 15,
  "Prompt": "Beautiful sunset over ocean",
  "Model": "imagen-4.0-generate-001",
  "AspectRatio": "16:9",
  "SampleCount": 2
}
```

### 9.4 Video Generation (GoogleVeo with FirstFrame)

```json
POST /api/integration/imaging/generate
{
  "__type": 100,
  "Prompt": "Camera zooms in slowly on a peaceful garden",
  "Model": "veo-3.1-generate-preview",
  "Duration": 8.0, "AspectRatio": "16:9", "Resolution": "1080p",
  "GenerateAudio": true,
  "TaskPresets": [
    { "__type": 11, "Weight": 1.0, "ExternalUrl": "https://example.com/first_frame.jpg" }
  ]
}
```

### 9.5 Kling V3 Video

```json
POST /api/integration/imaging/generate
{
  "__type": 109,
  "Prompt": "A cat playing in the garden",
  "Model": "pro",
  "Duration": 5, "AspectRatio": "16:9",
  "GuidanceScale": 0.5, "GenerateAudio": true
}
```

### 9.6 Grok Video with Mode

```json
POST /api/integration/imaging/generate
{
  "__type": 111,
  "Prompt": "A spaceship launching into space",
  "Mode": "normal",
  "Duration": 6, "Resolution": "720p", "AspectRatio": "16:9"
}
```

### 9.7 LoRA Application (SDXL)

**Step 1: Import model**
```json
POST /api/integration/models
{ "CivitaiModelVersionId": 12345 }
```

**Step 2: Generate**
```json
POST /api/integration/imaging/generate
{
  "__type": 4,
  "Prompt": "anime_style portrait",
  "Width": 1024, "Height": 1024,
  "TaskModels": [{ "ModelId": 999, "Strength": 0.8 }]
}
```

### 9.8 Upscale

```json
POST /api/integration/imaging/upscale
{
  "__type": 7,
  "Prompt": "enhance details",
  "ScaleFactor": 4.0,
  "InputMediaIds": [67890]
}
```

### 9.9 Completion Callback (Webhook)

```json
POST /api/integration/imaging/generate
{
  "__type": 5,
  "Prompt": "Mountain landscape",
  "Width": 1024, "Height": 1024,
  "CompletionCallbackUrl": "https://your-domain.com/webhook"
}
```

**Callback payload (POST to your URL):**
```json
{ "taskId": 12345, "statusId": 100, "statusCode": "COMPLETION_SUCCESS", "statusMessage": "Task completed successfully" }
```
`statusId`: 100=Succeeded, 200=Failed. **Fire-and-forget** (no retries).

### 9.10 Polling Pattern

```javascript
async function waitForCompletion(taskId) {
  while (true) {
    const response = await fetch(`/api/integration/imaging/tasks/${taskId}/status`, {
      headers: { 'X-API-Key': API_KEY }
    });
    const { data: statusId } = await response.json();
    if (statusId === 100 || statusId === 200) break; // 100=Succeeded, 200=Failed
    await sleep(5000); // 3-5 seconds recommended
  }
  const result = await fetch(`/api/integration/imaging/tasks/${taskId}`, {
    headers: { 'X-API-Key': API_KEY }
  });
  return await result.json();
}
```

---

## 10. COMMON MISTAKES & FIXES

### 10.1 Using Width/Height with Non-ComfyUI Providers
**WRONG:** `{ "__type": 1, "Width": 1024 }` — Midjourney uses AspectRatio.
**FIX:** `{ "__type": 1, "AspectRatio": "1:1" }`

### 10.2 Applying LoRA to External API Providers
**WRONG:** `{ "__type": 15, "TaskModels": [...] }` — Imagen ignores LoRA.
**FIX:** Use ComfyUI provider (2, 4, 5, 11, 14, 21, 27).

### 10.3 Wrong Discriminator
`__type: 3` is Upscale (needs InputMediaIds), not TextToImage. Use `__type: 5` for Flux1Dev.

### 10.4 Incorrect AspectRatio Format
**WRONG:** `"16/9"`. **FIX:** `"16:9"` (colon separator).

### 10.5 Wrong Video Duration Units
**WRONG:** `"Duration": 5000` (ms). **FIX:** `"Duration": 5.0` (seconds).

### 10.6 Expecting String Status Values
**WRONG:** `status === "Completed"`. **FIX:** Check integer: `data === 100` (Succeeded).

### 10.7 Expecting Flat Response
**WRONG:** `response.taskId`. **FIX:** `response.data.taskId` (ApiResponse wrapper).

### 10.8 Missing X-API-Key
Returns HTTP 403 (not 401). Always include the header.

### 10.9 Using Invalid Model Values
Each provider has specific valid model strings. See Section 4.2/4.3 for exact values.

### 10.10 Providing Both InputMediaIds and InputMediaExternalUrls
Returns 400 Bad Request. Use one or the other.

---

## 11. ENDPOINT REFERENCE

### 11.1 POST /api/integration/imaging/generate
Create image/video/audio generation task.
**Request:** Polymorphic `CreateGenerateMediaTaskRequest` (Section 8).
**Response:** `ApiResponse<GenerateMediaTaskSimpleResponse>`.
**Status Codes:** 200, 400, 403, 429.

### 11.2 POST /api/integration/imaging/upscale
Upscale existing image.
**Request:** UpscaleImageTaskBase derivatives (__type: 3, 7, 8, 28).
**Required:** `ScaleFactor`, `InputMediaIds` OR `InputMediaExternalUrls`.

### 11.3 POST /api/integration/imaging/outpaint
Extend image boundaries.
**Request:** OutpaintTaskBase derivatives (__type: 20, 25, 26).
**Required:** `Width`, `Height`, `InputMediaIds` OR `InputMediaExternalUrls`.

### 11.4 POST /api/integration/imaging/reframe
Alias for /outpaint (same handler).

### 11.5 POST /api/integration/imaging/hyperlora
Apply HyperLoRA transformation (__type: 13).
**Required:** `InputMediaIds` OR `InputMediaExternalUrls`, `Prompt`.
**Note:** `LoRATriggerString` is set server-side automatically.

### 11.6 GET /api/integration/imaging/tasks/{id}
Get full task details. `id` is uint.
**Response:** `ApiResponse<GenerateMediaTaskSimpleResponse>`.
Users can only retrieve own tasks.

### 11.7 GET /api/integration/imaging/tasks/{id}/status
Lightweight polling endpoint.
**Response:** `ApiResponse<int>` (10=Initial, 20=Processing, 100=Succeeded, 200=Failed).

### 11.8 POST /api/integration/models
Import AI model (LoRA).
```json
{ "CivitaiModelVersionId": 12345, "Url": "https://...", "SHA256Hash": "..." }
```
All fields optional — provide at least `CivitaiModelVersionId` or `Url`.
**Response:** `ApiResponse<AIModelSimpleResponse>` with id, name, baseModel, modelType, trainedWords, files.

### 11.9 GET /api/integration/models
List available models. Query: `PageNumber`, `PageSize`.
**Response:** `ApiPagedResponse<AIModelSimpleResponse>`.

### 11.10 POST /api/integration/assistants/enhance-prompt
Enhance prompt with AI. **Timeout:** 120s.
```json
{ "Prompt": "mountain", "TargetStyleId": 0 }
```
TargetStyleId: 0=Undefined, 1=Photorealistic, 2=Illustration.
**Response:** `ApiResponse<string>` (enhanced prompt text).

### 11.11 POST /api/integration/billing/subscriptions
Provision subscription.
```json
{ "Email": "user@example.com", "PlanId": "plan_123", "BillingPeriodId": 0 }
```
BillingPeriodId: 0=Monthly, 1=Annual.
**Response:** `ApiResponse<ProvisionSubscription>`.

---

## ADDITIONAL NOTES

### Rate Limiting
- **Concurrent requests:** 30 per API key
- **Queue capacity:** 200 queued requests
- **Exceeded:** HTTP 429 Too Many Requests

### Average Processing Times
- Text-to-Image: 10-60 seconds
- Image-to-Image: 15-90 seconds
- Video: 1-10 minutes
- Upscale: 5-30 seconds

### Media Expiration
All media uploaded via Integration API expires after **24 hours**.

### Formats
- **Image Input:** JPEG, PNG, WebP, GIF (first frame)
- **Video Output:** MP4 (H.264), Audio: AAC
- **LoRA Models:** .safetensors format from CivitAI

---

**END OF DOCUMENTATION**