### Webhook Receiver Example (Python)

Source: https://www.mulerouter.ai/docs/api-reference/webhooks

A complete receiver implementation in Python demonstrating how to process and verify incoming MuleRouter webhooks.

```APIDOC
## POST /webhooks/mulerouter

### Description
This endpoint receives and verifies incoming MuleRouter webhooks.

### Method
POST

### Endpoint
`/webhooks/mulerouter`

### Request Headers
- `Content-Type` (string) - Required - Always `application/json`
- `User-Agent` (string) - Optional - Identifies the sender
- `X-MuleRouter-Webhook-Id` (string) - Required - Delivery ID, unique per (event, endpoint)
- `X-MuleRouter-Webhook-Timestamp` (integer) - Required - Unix timestamp (seconds) at signing time
- `X-MuleRouter-Webhook-Signature` (string) - Required - HMAC-SHA256 signature, prefixed with the algorithm version (e.g., `v1=...`)

### Signature Verification
1. **Construct Signed Content**: Concatenate `delivery_id`, `timestamp`, and the raw request body, separated by dots. `signed_content = "{delivery_id}.{timestamp}.{raw_body}"`
2. **Compute Signature**: Calculate the HMAC-SHA256 hash of the `signed_content` using your `whsec_...` secret key.
3. **Compare Signatures**: Compare the computed signature with the signature provided in the `X-MuleRouter-Webhook-Signature` header (after removing the `v1=` prefix). Use a constant-time comparison to prevent timing attacks.

### Request Example
```python
import hmac
import hashlib
import time
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_..."   # from the MuleRouter Console
MAX_SKEW_SECONDS = 300         # 5 minutes

@app.post("/webhooks/mulerouter")
def receive():
    raw_body = request.get_data()  # bytes — do not re-serialize
    delivery_id = request.headers.get("X-MuleRouter-Webhook-Id", "")
    timestamp = request.headers.get("X-MuleRouter-Webhook-Timestamp", "")
    signature_header = request.headers.get("X-MuleRouter-Webhook-Signature", "")

    # Reject stale deliveries (protects against replay attacks).
    try:
        sent_at = int(timestamp)
    except ValueError:
        abort(400, "invalid timestamp")
    if abs(time.time() - sent_at) > MAX_SKEW_SECONDS:
        abort(400, "timestamp outside of allowed window")

    # Only v1 is currently defined; reject anything else so future algorithm
    # upgrades fail loudly instead of being silently trusted.
    if not signature_header.startswith("v1="):
        abort(400, "unsupported signature version")
    received_signature = signature_header[len("v1="):]

    signed_content = f"{delivery_id}.{timestamp}."..encode() + raw_body
    expected_signature = hmac.new(
        WEBHOOK_SECRET.encode(),
        signed_content,
        hashlib.sha256,
    ).hexdigest()

    # Constant-time comparison prevents timing attacks.
    if not hmac.compare_digest(received_signature, expected_signature):
        abort(401, "invalid signature")

    # At this point the payload is trusted. Deduplicate by delivery_id before
    # acting, since retries reuse the same X-MuleRouter-Webhook-Id.
    ...
    return ("", 204)
```

### Response
#### Success Response (204)
No Content. Indicates successful processing of the webhook.
```

--------------------------------

### Basic Image Editing

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/alibaba/wan2.6-image/generation

An example of basic image editing using a prompt and a reference image URL.

```APIDOC
## Basic Image Editing

### Description
Edit an image by providing a text prompt and a reference image.

### Method
POST

### Endpoint
/v1/images/generations

### Parameters
#### Request Body
- **prompt** (string) - Required - The text prompt to guide the image editing.
- **images** (array of string) - Required - Array of image URLs or Base64 encoded data. Max items: 2.
- **n** (integer) - Optional - Number of images to generate. Range: 1-4. Default: 4.

### Request Example
{
  "prompt": "Replace the character's clothing with traditional Chinese Hanfu",
  "images": ["https://example.com/portrait.jpg"],
  "n": 1
}
```

--------------------------------

### cURL Request with Authentication

Source: https://www.mulerouter.ai/docs/api-reference/introduction

Example of how to make a cURL request to the chat completions endpoint, including the necessary Content-Type and Authorization headers.

```shell
curl https://api.mulerouter.ai/v1/chat/completions  \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Your API Token>" \

```

--------------------------------

### Reasoning Effort

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/openai/chat

Guides the reasoning effort for models, affecting response speed and token usage.

```APIDOC
## Reasoning Effort

### Description
Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.

### Type
- string

### Allowed Values
- minimal
- low
- medium
- high

### Default
- medium
```

--------------------------------

### Failed Task Response

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/alibaba/wan2.6-t2i/generation-task

Example JSON response for a text-to-image generation task that failed. Includes task details and an error object with information about the failure.

```json
{
  "task_info": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "failed",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:15Z",
    "error": {
      "code": 400,
      "title": "Invalid Request",
      "detail": "The prompt contains prohibited content"
    }
  }
}
```

--------------------------------

### Authentication Header Example

Source: https://www.mulerouter.ai/docs/api-reference/introduction

Include this header in your requests to authenticate with the MuleRouter API. Replace '<API Key>' with your actual token.

```http
Authorization: Bearer <API Key>
```

--------------------------------

### Completed Task Response

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/alibaba/wan2.6-image/generation-task

Example JSON response when an image generation task has completed successfully. Includes task details and URLs to the generated images.

```json
{
  "task_info": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "completed",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:45Z"
  },
  "images": [
    "https://example.com/generated-image-1.jpg"
  ]
}
```

--------------------------------

### Verify Webhook Signature in Python

Source: https://www.mulerouter.ai/docs/api-reference/webhooks

This Python Flask example demonstrates how to verify the signature of an incoming webhook request. It checks for timestamp validity, supported signature versions, and uses HMAC-SHA256 for signature comparison to prevent timing attacks. Ensure you use the raw request body for signature calculation.

```python
import hmac
import hashlib
import time
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_..."   # from the MuleRouter Console
MAX_SKEW_SECONDS = 300         # 5 minutes

@app.post("/webhooks/mulerouter")
def receive():
    raw_body = request.get_data()  # bytes — do not re-serialize
    delivery_id = request.headers.get("X-MuleRouter-Webhook-Id", "")
    timestamp = request.headers.get("X-MuleRouter-Webhook-Timestamp", "")
    signature_header = request.headers.get("X-MuleRouter-Webhook-Signature", "")

    # Reject stale deliveries (protects against replay attacks).
    try:
        sent_at = int(timestamp)
    except ValueError:
        abort(400, "invalid timestamp")
    if abs(time.time() - sent_at) > MAX_SKEW_SECONDS:
        abort(400, "timestamp outside of allowed window")

    # Only v1 is currently defined; reject anything else so future algorithm
    # upgrades fail loudly instead of being silently trusted.
    if not signature_header.startswith("v1="):
        abort(400, "unsupported signature version")
    received_signature = signature_header[len("v1="):]

    signed_content = f"{delivery_id}.{timestamp}.".encode() + raw_body
    expected_signature = hmac.new(
        WEBHOOK_SECRET.encode(),
        signed_content,
        hashlib.sha256,
    ).hexdigest()

    # Constant-time comparison prevents timing attacks.
    if not hmac.compare_digest(received_signature, expected_signature):
        abort(401, "invalid signature")

    # At this point the payload is trusted. Deduplicate by delivery_id before
    # acting, since retries reuse the same X-MuleRouter-Webhook-Id.
    ...
    return ("", 204)

```

--------------------------------

### Failed Task Response

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/alibaba/wan2.6-image/generation-task

Example JSON response when an image generation task has failed. Includes task details and an error object with information about the failure.

```json
{
  "task_info": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "failed",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:15Z",
    "error": {
      "code": 400,
      "title": "Invalid Request",
      "detail": "The input image format is not supported"
    }
  }
}
```

--------------------------------

### Task Created Event Payload

Source: https://www.mulerouter.ai/docs/api-reference/webhooks

Example payload for a `task.created` event. The `payload` field only contains `task_info` when the task is first accepted.

```json
{
  "id": "evt_01JSGP3X7K9M2N4Q5R6S7T8U9V",
  "type": "task.created",
  "created_at": "2026-04-23T10:00:00Z",
  "data": {
    "vendor": "google",
    "model_name": "nano-banana-2",
    "payload": {
      "task_info": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "status": "pending",
        "created_at": "2026-04-23T10:00:00Z",
        "updated_at": "2026-04-23T10:00:00Z"
      }
    }
  }
}
```

--------------------------------

### RFC 7807 Error Response Example

Source: https://www.mulerouter.ai/docs/api-reference/error-codes

This is an example of an RFC 7807 formatted error response from MuleRouter when an asynchronous task fails. It includes status, title, error code, instance, type, and a detailed description.

```json
{
  "status": 400,
  "title": "Model Not Found",
  "error_code": 2000,
  "instance": "/vendors/openai/v1/chat/completions",
  "type": "https://mulerouter.ai/docs/api-reference/error-codes#2000",
  "detail": "The model does not exist."
}
```

--------------------------------

### Get Generation Task

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/alibaba/wan2.6-image/generation-task

Retrieve the status and result of a generation task by its unique identifier.

```APIDOC
## GET /vendors/alibaba/v1/wan2.6-image/generation/{task_id}

### Description
Retrieve the status and result of a generation task.

### Method
GET

### Endpoint
/vendors/alibaba/v1/wan2.6-image/generation/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - UUID of the task

### Responses
#### Success Response (200)
- **task_info** (object) - Information about the task, including its status and timestamps.
- **images** (array[string]) - Generated image URLs (only present when status is 'completed').

#### Error Response (400)
- **task_info** (object) - Information about the error, including error code, title, and detail.
```

--------------------------------

### Generate Image with Nano Banana Pro

Source: https://www.mulerouter.ai/docs/api-reference/quickstart

Use this endpoint to generate an image with specified parameters. Ensure your API key is included in the Authorization header.

```bash
curl --request POST \
  --url https://api.mulerouter.ai/vendors/google/v1/nano-banana-pro/generation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "A beautiful sunset over the mountains",
    "aspect_ratio": "5:4",
    "resolution": "2K"
}'
```

--------------------------------

### Create a Task

Source: https://www.mulerouter.ai/docs/api-reference/tasks

Initiate an asynchronous task by sending a POST request to the specified endpoint. The response includes a task ID that can be used to track the task's progress.

```APIDOC
## Create a task

MuleRouter integrates multiple model vendors. Some requests are synchronous or streaming, while others involve longer inference cycles. To improve the developer experience, we expose these as asynchronous tasks.

Create an asynchronous task via `POST` `/vendors/dummy/v1/videos/generation`.

You will receive a response similar to the following:

```json theme={null}
{
  "task_info": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "pending",
    "created_at": "2025-09-16T10:00:00Z",
    "updated_at": "2025-09-16T10:00:00Z"
  },
  ...
}
```
```

--------------------------------

### Task Failed Event Payload

Source: https://www.mulerouter.ai/docs/api-reference/webhooks

Example payload for a `task.failed` event. Error details are located in `payload.task_info.error`.

```json
{
  "id": "evt_01JSGP5Z9M1O4P6Q7R8S9T0U1V",
  "type": "task.failed",
  "created_at": "2026-04-23T10:01:00Z",
  "data": {
    "vendor": "google",
    "model_name": "nano-banana-2",
    "payload": {
      "task_info": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "status": "failed",
        "created_at": "2026-04-23T10:00:00Z",
        "updated_at": "2026-04-23T10:01:00Z",
        "error": {
          "code": 3001,
          "title": "Task Execution Error",
          "detail": "The upstream provider returned an error during task execution."
        }
      }
    }
  }
}
```

--------------------------------

### Basic Text-to-Image Generation

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/alibaba/wan2.5-t2i-preview/generation

Demonstrates a basic request to generate a single image from a text prompt. Ensure the prompt is descriptive for best results.

```json
{
  "prompt": "A sitting orange cat with a joyful expression, lively and cute, realistic and accurate",
  "n": 1
}
```

--------------------------------

### Get Task Result

Source: https://www.mulerouter.ai/docs

Retrieve the result of a previously submitted task using its unique task ID.

```APIDOC
## GET /vendors/google/v1/nano-banana-pro/generation/{taskId}

### Description
Retrieves the result of a specific task using its task ID.

### Method
GET

### Endpoint
https://api.mulerouter.ai/vendors/google/v1/nano-banana-pro/generation/{taskId}

### Parameters
#### Path Parameters
- **taskId** (string) - Required - The ID of the task to retrieve the result for.

### Response
#### Success Response (200)
- **result** (any) - The result of the task.

#### Response Example
{
  "result": "Image data or other task output"
}
```

--------------------------------

### Generate Image with Nano Banana Pro

Source: https://www.mulerouter.ai/docs

Use this cURL command to send a prompt and parameters to the Nano Banana Pro endpoint for image generation. Ensure your API key is correctly formatted in the Authorization header.

```bash
curl --request POST \
    --url https://api.mulerouter.ai/vendors/google/v1/nano-banana-pro/generation \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{ 
      "prompt": "A beautiful sunset over the mountains",
      "aspect_ratio": "5:4",
      "resolution": "2K"
  }'
```

--------------------------------

### Get Task Result

Source: https://www.mulerouter.ai/docs/api-reference/quickstart

Retrieve the result of a previously submitted task using its unique task ID.

```APIDOC
## GET /vendors/google/v1/nano-banana-pro/generation/{taskId}

### Description
Retrieves the result of a generation task using its ID.

### Method
GET

### Endpoint
/vendors/google/v1/nano-banana-pro/generation/{taskId}

### Parameters
#### Path Parameters
- **taskId** (string) - Required - The ID of the task to retrieve the result for.

### Request Example
```bash
curl --request GET \
  --url https://api.mulerouter.ai/vendors/google/v1/nano-banana-pro/generation/f81d4fae-7dec-11d0-a765-00a0c91e6bf6 \
  --header 'Authorization: Bearer <token>'
```

### Response
#### Success Response (200)
- **result** (string) - The result of the task (e.g., image URL or status).

#### Response Example
```json
{
  "result": "https://example.com/image.png"
}
```
```

--------------------------------

### Generate Image

Source: https://www.mulerouter.ai/docs/api-reference/quickstart

Use the Nano Banana Pro endpoint to generate an image with a specified prompt, aspect ratio, and resolution.

```APIDOC
## POST /vendors/google/v1/nano-banana-pro/generation

### Description
Generates an image based on the provided prompt and parameters.

### Method
POST

### Endpoint
/vendors/google/v1/nano-banana-pro/generation

### Parameters
#### Request Body
- **prompt** (string) - Required - The text prompt to generate an image from.
- **aspect_ratio** (string) - Optional - The desired aspect ratio of the image (e.g., "5:4").
- **resolution** (string) - Optional - The desired resolution of the image (e.g., "2K").

### Request Example
```json
{
  "prompt": "A beautiful sunset over the mountains",
  "aspect_ratio": "5:4",
  "resolution": "2K"
}
```

### Response
#### Success Response (200)
- **task_id** (string) - The ID of the generated task.

#### Response Example
```json
{
  "task_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
}
```
```

--------------------------------

### Create Generation Task

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/alibaba/wan2.6-t2i/generation

Initiates an image generation task using the Wan2.6-t2i model. Accepts a text prompt and optional parameters to control the generation process.

```APIDOC
## POST /vendors/alibaba/v1/wan2.6-t2i/generation

### Description
Generate images from text prompts using the wan2.6-t2i model.

### Method
POST

### Endpoint
/vendors/alibaba/v1/wan2.6-t2i/generation

### Parameters
#### Request Body
- **prompt** (string) - Required - Text description for the image (max 2000 characters).
- **negative_prompt** (string | null) - Optional - Negative prompt describing unwanted content (max 500 characters).
- **size** (string) - Optional - Image resolution in format "width*height" (e.g., "1280*1280"). Default: 1280*1280. Supported resolutions: [768*768, 1440*1440], aspect ratios: [1:4, 4:1].
- **n** (integer) - Optional - Number of images to generate (1-4). Default: 4.
- **prompt_extend** (boolean) - Optional - Enable intelligent prompt rewriting (improves short prompts but increases processing time). Default: false.
- **seed** (integer) - Optional - Random seed for reproducibility [0, 2147483647].
- **safety_filter** (boolean | null) - Optional - Enable content safety filter. Defaults to true. Set to false to disable content safety inspection.

### Request Example
```json
{
  "prompt": "A majestic dragon soaring through a cloudy sky, digital art",
  "negative_prompt": "low quality, blurry, watermark",
  "size": "1024*1024",
  "n": 2,
  "prompt_extend": true,
  "seed": 12345,
  "safety_filter": true
}
```

### Response
#### Success Response (200)
- **task_info** (object) - Information about the created task.
  - **id** (string) - UUID of the task.
  - **status** (string) - Task status (pending when created).
  - **created_at** (string) - Task creation timestamp (ISO 8601).
  - **updated_at** (string) - Task last update timestamp (ISO 8601).

#### Response Example
```json
{
  "task_info": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "status": "pending",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:00:00Z"
  }
}
```
```

--------------------------------

### Create Generation Task

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/alibaba/wan2.5-t2i-preview/generation

Initiates an image generation task using the wan2.5-t2i-preview model. Accepts a JSON payload with prompt details and returns a task ID for tracking.

```APIDOC
## POST /vendors/alibaba/v1/wan2.5-t2i-preview/generation

### Description
Generate images from text prompts using the wan2.5-t2i-preview model.

### Method
POST

### Endpoint
/vendors/alibaba/v1/wan2.5-t2i-preview/generation

### Parameters
#### Request Body
- **prompt** (string) - Required - Text description for the image (max 2000 characters).
- **negative_prompt** (string | null) - Optional - Negative prompt describing unwanted content (max 500 characters).
- **size** (string) - Optional - Image resolution in format "width*height" (e.g., "1280*1280"). Default: 1280*1280. Total pixels: [768*768, 1440*1440], aspect ratio: [1:4, 4:1].
- **n** (integer) - Optional - Number of images to generate (1-4). Default: 4.
- **prompt_extend** (boolean) - Optional - Enable intelligent prompt rewriting (improves short prompts but increases processing time). Default: false.
- **seed** (integer) - Optional - Random seed for reproducibility [0, 2147483647].
- **safety_filter** (boolean | null) - Optional - Enable content safety filter. Defaults to true. Set to false to disable content safety inspection.

### Request Example
{
  "prompt": "A majestic dragon soaring through a starry night sky",
  "negative_prompt": "cartoon, low quality, blurry",
  "size": "1024*1024",
  "n": 2,
  "prompt_extend": true,
  "seed": 12345,
  "safety_filter": true
}

### Response
#### Success Response (202)
- **task_info** (object) - Information about the created task.
  - **id** (string) - UUID of the task.
  - **status** (string) - Task status (pending when created).
  - **created_at** (string) - Task creation timestamp (ISO 8601).
  - **updated_at** (string) - Task last update timestamp (ISO 8601).

#### Response Example
{
  "task_info": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "status": "pending",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:00:00Z"
  }
}
```

--------------------------------

### Web Search Context Size

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/openai/chat

Provides high-level guidance for the amount of context window space to use for web search.

```APIDOC
## Web Search Context Size

### Description
High level guidance for the amount of context window space to use for the web search.
```

--------------------------------

### Generate Content

Source: https://www.mulerouter.ai/docs

Use this endpoint to generate content using various models. You need to provide a prompt and specify aspect ratio and resolution.

```APIDOC
## POST /vendors/google/v1/nano-banana-pro/generation

### Description
Generates content based on a provided prompt, aspect ratio, and resolution.

### Method
POST

### Endpoint
https://api.mulerouter.ai/vendors/google/v1/nano-banana-pro/generation

### Parameters
#### Request Body
- **prompt** (string) - Required - The prompt for content generation.
- **aspect_ratio** (string) - Required - The desired aspect ratio (e.g., "5:4").
- **resolution** (string) - Required - The desired resolution (e.g., "2K").

### Request Example
{
  "prompt": "A beautiful sunset over the mountains",
  "aspect_ratio": "5:4",
  "resolution": "2K"
}

### Response
#### Success Response (200)
- **taskId** (string) - The ID of the generated task.

#### Response Example
{
  "taskId": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
}
```

--------------------------------

### Get Generation Task Status and Result

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/alibaba/wan2.6-t2i/generation-task

Retrieve the status and result of a specific image generation task using its unique task ID.

```APIDOC
## GET /vendors/alibaba/v1/wan2.6-t2i/generation/{task_id}

### Description
Retrieve the status and result of a generation task.

### Method
GET

### Endpoint
/vendors/alibaba/v1/wan2.6-t2i/generation/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The unique identifier for the generation task.

### Responses
#### Success Response (200)
- **Wan26T2IResponse** - Contains the task information and generated images if the task is completed.
  - **task_info** (TaskInfoResponse) - Information about the task.
  - **images** (array of strings) - Generated image URLs (only present when status is 'completed').

#### Error Response (400)
- **ErrorResponse** - Contains details about the error.
  - **task_info** (TaskInfoErrorResponse) - Information about the task, including error details.

### Components
#### Schemas
##### Wan26T2IResponse
- **task_info** (TaskInfoResponse) - Task details.
- **images** (array of strings) - URLs of generated images.

##### ErrorResponse
- **task_info** (TaskInfoErrorResponse) - Error details.

##### TaskInfoResponse
- **id** (string) - UUID of the task.
- **status** (string) - Task status (e.g., 'completed', 'pending', 'processing', 'failed').
- **created_at** (string) - Task creation timestamp.
- **updated_at** (string) - Task last update timestamp.

##### TaskInfoErrorResponse
- **id** (string) - UUID of the task.
- **status** (string) - Task status (always 'failed' for error responses).
- **created_at** (string) - Task creation timestamp.
- **updated_at** (string) - Task last update timestamp.
- **error** (TaskInfoErrorObject) - Detailed error information.

##### TaskInfoErrorObject
- **code** (integer) - MuleRouter Error code.
- **title** (string) - MuleRouter Error title.
- **detail** (string) - MuleRouter Error detail.
```

--------------------------------

### Task Succeeded Event Payload

Source: https://www.mulerouter.ai/docs/api-reference/webhooks

Example payload for a `task.succeeded` event. The `payload` field includes the full task response, such as generated images or videos.

```json
{
  "id": "evt_01JSGP4Y8L0N3O5P6Q7R8S9T0U",
  "type": "task.succeeded",
  "created_at": "2026-04-23T10:01:00Z",
  "data": {
    "vendor": "google",
    "model_name": "nano-banana-2",
    "payload": {
      "task_info": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "status": "completed",
        "created_at": "2026-04-23T10:00:00Z",
        "updated_at": "2026-04-23T10:01:00Z"
      },
      "images": [
        "https://mulerouter.muleusercontent.com/public/123e4567/image.png"
      ]
    }
  }
}
```

--------------------------------

### Chat Completion Stream Options

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/openai/chat

Options for configuring the streaming response. These settings are only applicable when the `stream` parameter is set to `true`.

```APIDOC
## ChatCompletionStreamOptions

### Description
Options for streaming response. Only set this when you set `stream: true`.

### Properties
- **include_usage** (boolean) - Optional - If set, an additional chunk will be streamed before the `data: [DONE]` message. The `usage` field on this chunk shows the token usage statistics for the entire request, and the `choices` field will always be an empty array. All other chunks will also include a `usage` field, but with a null value. NOTE: If the stream is interrupted, you may not receive the final usage chunk which contains the total token usage for the request.
- **include_obfuscation** (boolean) - Optional - When true, stream obfuscation will be enabled. Stream obfuscation adds random characters to an `obfuscation` field on streaming delta events to normalize payload sizes as a mitigation to certain side-channel attacks. These obfuscation fields are included by default, but add a small amount of overhead to the data stream. You can set `include_obfuscation` to false to optimize for bandwidth if you trust the network links between your application and the OpenAI API.

### Default
`null`
```

--------------------------------

### Create Generation Task

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/alibaba/wan2.6-image/generation

Initiates an image generation or editing task using the wan2.6-image model. You can provide text prompts, reference images, and specify various parameters to control the output.

```APIDOC
## POST /vendors/alibaba/v1/wan2.6-image/generation

### Description
Edit images using the wan2.6-image model with text prompts and reference images.

### Method
POST

### Endpoint
/vendors/alibaba/v1/wan2.6-image/generation

### Parameters
#### Request Body
- **prompt** (string) - Required - Text description for the desired edit (max 2000 characters)
- **negative_prompt** (string | null) - Optional - Negative prompt (max 500 characters)
- **images** (array[string]) - Required - Array of image URLs or Base64 encoded data (max 3 images). Supported formats: JPEG, JPG, PNG, BMP, WEBP. Dimensions: [384, 5000] pixels for both width and height. Max file size: 10MB per image
- **size** (string | null) - Optional - Output image resolution (format: "width*height"). Default: 1280*1280. Total pixels: [768*768, 1440*1440], aspect ratio: [1:4, 4:1]
- **n** (integer) - Optional - Number of images to generate (1-4). Default: 4
- **seed** (integer) - Optional - Random seed [0, 2147483647]
- **prompt_extend** (boolean) - Optional - Enable intelligent prompt rewriting. Default: false
- **safety_filter** (boolean | null) - Optional - Enable content safety filter. Defaults to true. Set to false to disable content safety inspection.

### Request Example
```json
{
  "prompt": "A majestic dragon soaring through a starry night sky",
  "images": ["https://example.com/image1.jpg"],
  "n": 1,
  "size": "1024*1024"
}
```

### Response
#### Success Response (202)
- **task_info** (object) - Information about the created task.
  - **id** (string) - UUID of the task
  - **status** (string) - Task status (pending when created)
  - **created_at** (string) - Task creation timestamp (ISO 8601)
  - **updated_at** (string) - Task last update timestamp (ISO 8601)

#### Response Example
```json
{
  "task_info": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "status": "pending",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:00:00Z"
  }
}
```
```

--------------------------------

### Basic Text-to-Image Request

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/alibaba/wan2.6-t2i/generation

Use this snippet for a simple image generation request with a text prompt and the number of images.

```json
{
  "prompt": "A small cat running in the moonlight",
  "n": 1
}
```

--------------------------------

### Webhook Payload Interface

Source: https://www.mulerouter.ai/docs/api-reference/webhooks

Defines the structure of the data received in webhook deliveries. The `data.payload` field mirrors the response of the synchronous GET task endpoint.

```typescript
interface WebhookPayload {
  id: string            // Event ID, use for idempotent deduplication
  type: string          // Event type, e.g. "task.succeeded"
  created_at: string    // Event creation time, ISO 8601
  data: {
    vendor: string                // Model vendor
    model_name: string            // Model name
    payload: Record<string, unknown>  // Same shape as the matching GET task response
  }
}
```

--------------------------------

### Text-to-Image Generation with Negative Prompt and Custom Size

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/alibaba/wan2.6-t2i/generation

Generates multiple images with specified size and a negative prompt to exclude certain elements.

```APIDOC
## Text-to-Image Generation with Negative Prompt and Custom Size

### Description
Generates images with a specified size and a negative prompt to refine the output.

### Method
POST

### Endpoint
/v1/wan2.6-t2i/generation

### Parameters
#### Request Body
- **prompt** (string) - Required - The text description for image generation.
- **negative_prompt** (string) - Optional - Text describing elements to exclude from the image.
- **size** (string) - Optional - The desired resolution of the image (e.g., "1280*720").
- **n** (integer) - Optional - The number of images to generate. Defaults to 4. Range: 1-4.

### Request Example
```json
{
  "prompt": "A serene mountain landscape at sunset, dramatic clouds, vibrant colors",
  "negative_prompt": "low resolution, error, worst quality, low quality",
  "size": "1280*720",
  "n": 4
}
```

### Response
#### Success Response (200)
- **images** (array) - A list of generated image URLs or data.

#### Response Example
```json
{
  "images": [
    "https://example.com/image1.png",
    "https://example.com/image2.png"
  ]
}
```
```

--------------------------------

### Get Task Result by ID

Source: https://www.mulerouter.ai/docs

Retrieve the result of a previously submitted task using its unique task ID. This is useful for checking the status and obtaining the output of asynchronous operations.

```bash
curl --request GET \
  --url https://api.mulerouter.ai/vendors/google/v1/nano-banana-pro/generation/f81d4fae-7dec-11d0-a765-00a0c91e6bf6 \
  --header 'Authorization: Bearer <token>'
```

--------------------------------

### Create Asynchronous Task

Source: https://www.mulerouter.ai/docs/api-reference/tasks

Initiate an asynchronous task by sending a POST request to the specified endpoint. The response includes a task ID that can be used to track the task's progress and retrieve its results.

```json
{
  "task_info": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "pending",
    "created_at": "2025-09-16T10:00:00Z",
    "updated_at": "2025-09-16T10:00:00Z"
  },
  ...
}
```

--------------------------------

### Text-to-Image Request with Negative Prompt and Size

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/alibaba/wan2.6-t2i/generation

Generate images using a detailed prompt, specifying a negative prompt to exclude certain elements, and a custom resolution.

```json
{
  "prompt": "A serene mountain landscape at sunset, dramatic clouds, vibrant colors",
  "negative_prompt": "low resolution, error, worst quality, low quality",
  "size": "1280*720",
  "n": 4
}
```

--------------------------------

### Retrieve Task Status and Result

Source: https://www.mulerouter.ai/docs/api-reference/tasks

Check the status and retrieve the result of an asynchronous task using its unique task ID. Send a GET request to the endpoint including the task ID.

```APIDOC
## Retrieve task status and result

In the above example, the task ID is `123e4567-e89b-12d3-a456-426614174000`.

To retrieve the latest status and result for the task ID.

Use `GET` `/vendors/dummy/v1/videos/generation/123e4567-e89b-12d3-a456-426614174000`.

For example, when the task status is `succeeded`, you may receive a response like the following:

```json theme={null}
{
  "task_info": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "succeeded",
    "created_at": "2025-09-16T10:00:00Z",
    "updated_at": "2025-09-16T10:00:00Z"
  },
  "videos": [
    "https://example.com/video-749337402830284.mp4"
  ]
}
```

The exact result payload varies by endpoint, refer to the model documentation. The task info response envelope remains consistent.
```

--------------------------------

### Create Chat Completion

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/openai/chat

Creates a new chat completion for the given model and prompt. This API is compatible with OpenAI's format.

```APIDOC
## Create Chat Completion

### Description
Creates a new chat completion for the given model and prompt.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Request Body
- **model** (string) - Required - The model to use for generating the completion.
- **messages** (array) - Required - A list of messages comprising the conversation.
  - **role** (string) - Required - The role of the author of the message (e.g., system, user, assistant).
  - **content** (string) - Required - The content of the message.
- **temperature** (number) - Optional - Controls randomness. Lower values make the output more focused and deterministic.
- **top_p** (number) - Optional - Controls diversity via nucleus sampling. The model considers only the tokens comprising the top p probability mass.
- **n** (integer) - Optional - How many chat completion choices to generate for each input message.
- **stream** (boolean) - Optional - Whether to stream back partial message deltas as they are generated.
- **stop** (string or array) - Optional - Up to 4 sequences where the API will stop generating further tokens.
- **max_tokens** (integer) - Optional - The maximum number of tokens to generate in the chat completion.
- **presence_penalty** (number) - Optional - Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
- **frequency_penalty** (number) - Optional - Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the completion so far, decreasing the model's likelihood to repeat the same line verbatim.
- **logit_bias** (object) - Optional - A map of token IDs to be biased, specified in [-100, 100].
- **user** (string) - Optional - A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse.

### Request Example
```json
{
  "model": "gpt-3.5-turbo",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Who won the world series in 2020?"}
  ]
}
```

### Response
#### Success Response (200)
- **id** (string) - A unique identifier for the completion.
- **object** (string) - The type of object returned, usually 'chat.completion'.
- **created** (integer) - Unix timestamp of when the completion was created.
- **model** (string) - The model used for the completion.
- **choices** (array) - A list of completion choices.
  - **index** (integer) - The index of the choice.
  - **message** (object) - The message content.
    - **role** (string) - The role of the author of the message (e.g., assistant).
    - **content** (string) - The content of the message.
  - **finish_reason** (string) - The reason the model stopped generating tokens (e.g., stop, length).
- **usage** (object) - Usage statistics for the completion.
  - **prompt_tokens** (integer) - The number of tokens in the prompt.
  - **completion_tokens** (integer) - The number of tokens in the completion.
  - **total_tokens** (integer) - The total number of tokens used.

#### Response Example
```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-3.5-turbo-0613",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The Los Angeles Dodgers won the World Series in 2020."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}
```
```

--------------------------------

### Text-to-Image Generation with Negative Prompt

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/alibaba/wan2.5-t2i-preview/generation

Generates multiple images with a specified size and includes a negative prompt to exclude unwanted elements. Useful for refining image content and quality.

```json
{
  "prompt": "A serene mountain landscape at sunset, dramatic clouds, vibrant colors",
  "negative_prompt": "low resolution, error, worst quality, low quality, incomplete, extra fingers, poor proportions",
  "size": "1280*720",
  "n": 4
}
```

--------------------------------

### Chat Completion Tool Choice Options

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/openai/chat

Controls which tool, if any, is called by the model. Options include 'none', 'auto', 'required', or specifying a particular tool.

```APIDOC
## ChatCompletionToolChoiceOption

### Description
Controls which (if any) tool is called by the model.

- `none`: The model will not call any tool and instead generates a message.
- `auto`: The model can pick between generating a message or calling one or more tools. This is the default if tools are present.
- `required`: The model must call one or more tools.

Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool.

`none` is the default when no tools are present.

### Type
string | object

### Enum (for string type)
- none
- auto
- required

### Schema Reference
- `#/components/schemas/ChatCompletionAllowedToolsChoice`
- `#/components/schemas/ChatCompletionNamedToolChoice`
- `#/components/schemas/ChatCompletionNamedToolChoiceCustom`
```

--------------------------------

### Basic Text-to-Image Generation

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/alibaba/wan2.6-t2i/generation

Generates a single image based on a provided text prompt.

```APIDOC
## Basic Text-to-Image Generation

### Description
Generates an image from a text prompt.

### Method
POST

### Endpoint
/v1/wan2.6-t2i/generation

### Request Body
- **prompt** (string) - Required - The text description for image generation.
- **n** (integer) - Optional - The number of images to generate. Defaults to 4. Range: 1-4.

### Request Example
```json
{
  "prompt": "A small cat running in the moonlight",
  "n": 1
}
```

### Response
#### Success Response (200)
- **images** (array) - A list of generated image URLs or data.

#### Response Example
```json
{
  "images": [
    "https://example.com/image1.png"
  ]
}
```
```

--------------------------------

### Image Editing with Negative Prompt

Source: https://www.mulerouter.ai/docs/api-reference/endpoint/alibaba/wan2.6-image/generation

Demonstrates image editing with a negative prompt to exclude unwanted elements or styles.

```APIDOC
## Image Editing with Negative Prompt

### Description
Edit an image using a prompt and a negative prompt to refine the output.

### Method
POST

### Endpoint
/v1/images/generations

### Parameters
#### Request Body
- **prompt** (string) - Required - The text prompt to guide the image editing.
- **negative_prompt** (string) - Optional - A prompt describing what to avoid in the generated image.
- **images** (array of string) - Required - Array of image URLs or Base64 encoded data. Max items: 2.
- **size** (string) - Optional - The desired size of the generated image (e.g., "1280*1280").
- **n** (integer) - Optional - Number of images to generate. Range: 1-4. Default: 4.

### Request Example
{
  "prompt": "Transform the image into an oil painting style",
  "negative_prompt": "blurry, low quality, distorted",
  "images": ["https://example.com/photo.jpg"],
  "size": "1280*1280",
  "n": 1
}
```