# API reference
Source: https://docs.higgsfield.ai/docs/api-reference/overview

Reference for Higgsfield image and video generation operations, request status, and cancellation.

The API reference is generated from the public OpenAPI specification. It includes model-specific generation schemas plus the shared status and cancellation operations.

**Base URL:** `https://api.higgsfield.ai`

All endpoints require the [`Authorization` header](/docs/authentication). Generation submissions also accept an optional [`Idempotency-Key`](/docs/concepts/idempotency) for safe retries.

Use the generation endpoint available to your account. Use **Get request status** in the sidebar to retrieve state and output for an existing request. Use **Cancel a queued request** to stop work that has not started processing.

For the complete integration flow, start with the [Quickstart](/docs/quickstart) and [Requests and lifecycle](/docs/concepts/requests).


# Cancel a queued request
Source: https://docs.higgsfield.ai/docs/api-reference/requests/cancel-a-queued-request

/openapi.json post /requests/{request_id}/cancel
Cancel a request that has not started processing. A successful response has no body.



# Get request status
Source: https://docs.higgsfield.ai/docs/api-reference/requests/get-request-status

/openapi.json get /requests/{request_id}/status
Retrieve the current state and output of a generation request.



# Authentication
Source: https://docs.higgsfield.ai/docs/authentication

Authenticate server-side API requests with your Higgsfield key and secret.

Create and manage API credentials in [Higgsfield Console](https://console.higgsfield.ai). Each credential consists of a key ID and a secret.

## Authorization header

Send both values in the `Authorization` header:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
Authorization: Key YOUR_KEY_ID:YOUR_KEY_SECRET
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.higgsfield.ai/requests/REQUEST_ID/status \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}"
```

The API also accepts the legacy `hf-api-key` and `hf-secret` headers. New integrations should use the `Authorization` header.

## Keep credentials server-side

<Warning>
  Do not call the API directly from browser or mobile application code. Anyone who can inspect the application can extract its API secret and use your account.
</Warning>

* Store credentials in a secrets manager or encrypted environment variables.
* Use separate credentials for development and production.
* Never include credentials in URLs, logs, screenshots, or support messages.
* Rotate a credential immediately if it may have been exposed.

## Authentication errors

Missing, malformed, or invalid credentials return `401 Unauthorized`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Invalid credentials"
}
```

Authentication identifies the account, but individual models may have separate access restrictions. A model unavailable to the authenticated account can return `404`, `423`, or `503` depending on its operational state.


# Billing and retention
Source: https://docs.higgsfield.ai/docs/concepts/billing-and-retention

Understand charging, refunds, estimation, and output retention.

Higgsfield charges successful generation requests using account credits. The exact cost depends on the selected model and parameters.

## Credit expiration

Credits expire one year after they are added to your account balance. Plan purchases and usage with this expiration period in mind.

## Estimate a request

Use the estimate endpoint with the same model parameters before submitting generation:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  --url https://api.higgsfield.ai/estimate/higgsfield-ai/soul/v2/standard \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
    "prompt": "Editorial portrait in soft daylight"
  }'
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "credits": "1.500",
  "usd": "0.094"
}
```

<Note>
  The values above illustrate the response format. Use the estimate returned for your authenticated account as the authoritative amount.
</Note>

## Failed and moderated requests

Requests ending as `failed` or `nsfw` are not charged. If credits were reserved when the request was accepted, they are refunded automatically.

## Canceled requests

A request can be canceled only before processing starts. A successfully canceled queued request is refunded.

## Output retention

Generated output is accessible for at least seven days after creation and may be removed after that period. Download completed files to your own storage for long-term retention.


# Errors and retries
Source: https://docs.higgsfield.ai/docs/concepts/errors

Handle synchronous API errors and terminal generation failures.

Errors can occur before a request is accepted or later during generation.

## Synchronous errors

Most HTTP errors use the FastAPI error envelope:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Invalid credentials"
}
```

Validation errors may return a list in `detail`. Do not parse human-readable messages to make permanent business decisions.

| Status | Typical meaning | Retry? |
| - | - | :-: |
| `400` | Invalid parameters, rejected input, or concurrency reached | After correcting the request or waiting |
| `401` | Missing or invalid credentials | No |
| `403` | Insufficient credits | After funding the account |
| `404` | Request or model not found for this account | No |
| `422` | Request validation failed or an idempotency key was reused with different parameters | No |
| `423` | Model is temporarily blocked | Later |
| `500` | Unexpected server error | Yes, with backoff |
| `503` | Model is disabled or not ready | Later |

## Terminal failures

An accepted request can later finish with `failed` or `nsfw`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "failed",
  "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
  "error": "Generation failed"
}
```

Failed and NSFW requests are not charged; any reserved credits are refunded.

## Safe retry policy

* Retry `GET` status requests after network failures and `5xx` responses.
* Do not retry authentication or validation failures without changing the request.
* Use exponential backoff with jitter.
* Set maximum attempts and a total retry deadline.
* Send an [`Idempotency-Key`](/docs/concepts/idempotency) with every generation submission.
* After an ambiguous timeout, network failure, or `5xx`, repeat the same generation request with the same idempotency key.

Every API response includes an `X-Correlation-ID` header. Record it with the `request_id` and include both when contacting support.


# File uploads
Source: https://docs.higgsfield.ai/docs/concepts/file-uploads

Upload images, video, or audio for use as model input.

Use a presigned upload URL when your input media is not already available through a public HTTPS URL.

## 1. Create an upload URL

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
UPLOAD=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url https://api.higgsfield.ai/files/generate-upload-url \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{"content_type":"image/jpeg"}')

echo "$UPLOAD" | jq
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "public_url": "https://cdn.example.com/input/example.jpeg",
  "upload_url": "https://storage.example.com/presigned-upload-url",
  "content_type": "image/jpeg",
  "upload_headers": {
    "Content-Type": "image/jpeg",
    "x-amz-tagging": "retention=temporary"
  }
}
```

The upload URL expires after one hour.

## 2. Upload the file

Send the file to `upload_url` with every header returned in `upload_headers`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request PUT \
  --url "$(echo "$UPLOAD" | jq --raw-output '.upload_url')" \
  --header "Content-Type: $(echo "$UPLOAD" | jq --raw-output '.upload_headers["Content-Type"]')" \
  --header "x-amz-tagging: $(echo "$UPLOAD" | jq --raw-output '.upload_headers["x-amz-tagging"]')" \
  --upload-file ./input.jpg
```

Do not send Higgsfield API credentials to the presigned storage URL.

## 3. Use the public URL

Pass `public_url` in the model parameter that accepts an input URL, such as `image_url`, `video_url`, or `audio_url`.

## Supported content types

* `image/jpeg`, `image/jpg`, `image/png`, `image/webp`, `image/gif`
* `audio/wav`, `audio/x-wav`
* `video/mp4`

The content type used for the upload must match the value used to create the presigned URL.


# Idempotent requests
Source: https://docs.higgsfield.ai/docs/concepts/idempotency

Retry generation submissions safely without creating duplicate requests.

Generation submissions accept an optional `Idempotency-Key` header. Use it when a network failure or timeout leaves you unsure whether a request was accepted.

Generate one unique key for each intended generation and keep it until you receive the initial response:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export IDEMPOTENCY_KEY=$(uuidgen | tr '[:upper:]' '[:lower:]')

curl --request POST \
  --url https://api.higgsfield.ai/higgsfield-ai/soul/v2/standard \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --data '{
    "prompt": "A quiet alpine lake at sunrise, editorial photography"
  }'
```

If the response is lost, repeat the same request with the same key. Higgsfield returns the original `request_id` without creating or charging for another generation.

## Key rules

* Keys must contain 1–255 visible ASCII characters without whitespace. UUIDs are recommended.
* A key identifies one generation intent within your account. API key rotation does not change that identity.
* Reuse the key only when the endpoint, JSON body, and webhook are unchanged.
* JSON object field order does not matter. Array order, omitted fields, explicit `null` values, and different URLs do matter.
* A completed, failed, NSFW, or canceled request keeps its identity. Retrying does not restart it.
* A request rejected before acceptance, such as an authentication or validation failure, does not consume the key.

<Warning>
  Create a new key when you deliberately want a new generation, even if its parameters are identical to an earlier request.
</Warning>

## Parameter mismatch

Reusing a key with different request parameters returns `422 Unprocessable Entity`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Idempotency-Key was already used with different request parameters"
}
```

Do not handle this response by generating a new key automatically. First determine whether the changed request represents a deliberate new generation or a client bug.

## Retry after an ambiguous failure

1. Create the key before sending the generation request.
2. Store the key with your local operation or job record.
3. After a network error, timeout, or `5xx`, retry the same endpoint and parameters with the same key.
4. Store the returned `request_id` and use its `status_url` for subsequent checks.

The replay response is an acceptance receipt and can contain `"status": "queued"` even when the original request has already finished. Read `status_url` for its current status and output.

Idempotency keys apply to generation submission endpoints in the Model API reference. Status polling, cancellation, uploads, estimates, and webhook deliveries use their existing retry behavior.


# Polling
Source: https://docs.higgsfield.ai/docs/concepts/polling

Poll request status without creating unnecessary load or duplicate generations.

Poll the `status_url` returned by the submission response until the request reaches a terminal state.

## Recommended strategy

1. Start with a two-second interval.
2. Increase the interval gradually up to ten seconds.
3. Add random jitter when many workers poll concurrently.
4. Stop on `completed`, `failed`, `nsfw`, or `canceled`.
5. Set an application-level timeout appropriate for the selected model.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import random
import time

import httpx

terminal_statuses = {"completed", "failed", "nsfw", "canceled"}
delay = 2.0

while True:
    response = httpx.get(
        status_url,
        headers={"Authorization": f"Key {key_id}:{key_secret}"},
        timeout=30,
    )
    response.raise_for_status()
    result = response.json()

    if result["status"] in terminal_statuses:
        break

    time.sleep(delay + random.uniform(0, 0.5))
    delay = min(delay * 1.5, 10.0)
```

## Retry decisions

| Response | Recommended action |
| - | - |
| `200` with a non-terminal status | Continue polling with backoff. |
| `401` | Stop and fix the credentials. |
| `404` | Stop and verify the request ID and account. |
| `5xx` or network failure | Retry the status request with exponential backoff. |

For long-running production workloads, use [webhooks](/docs/how-to/webhooks) and keep polling as a recovery path.


# Rate limits
Source: https://docs.higgsfield.ai/docs/concepts/rate-limits

Design integrations for account and model concurrency limits.

Rate limits depend on the account and the selected model. View the limits assigned to your account in [Higgsfield Console](https://console.higgsfield.ai).

The primary generation limit is concurrency: the number of requests that may be queued or processing at the same time. Some models can also have model-specific limits.

## When concurrency is reached

The API currently returns `400 Bad Request` with a message similar to:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Maximum number of concurrent requests (4) has been reached"
}
```

Wait for an existing request to reach a terminal status before submitting more work.

## Client recommendations

* Limit generation submissions with a worker pool or semaphore.
* Track each accepted `request_id` until it becomes terminal.
* Use backoff and jitter instead of retrying in a tight loop.
* Keep polling traffic separate from generation submission concurrency.
* Let us know in [Discord](https://discord.gg/BEea92KeR9) before a planned traffic increase if you need higher limits.

<Note>
  The API does not currently publish standard rate-limit response headers or `Retry-After`. Treat the limits shown in your dashboard as the authoritative values for your account.
</Note>


# Requests and lifecycle
Source: https://docs.higgsfield.ai/docs/concepts/requests

Understand asynchronous generation requests and their terminal states.

Generation is asynchronous. A successful submission creates a request and returns immediately while the work continues in the background.

## Request lifecycle

| Status | Terminal | Meaning |
| - | :-: | - |
| `queued` | No | The request is waiting to start and may still be canceled. |
| `in_progress` | No | Generation has started and can no longer be canceled. |
| `completed` | Yes | Output URLs are available in the response. |
| `failed` | Yes | Generation failed. The response may include an `error`. |
| `nsfw` | Yes | Input or output was rejected by content moderation. |
| `canceled` | Yes | The request was canceled before processing started. |

Store the `request_id` as soon as a request is accepted. It is the stable identifier used by polling, cancellation, webhook deduplication, and support.

<Tip>
  Send an [`Idempotency-Key`](/docs/concepts/idempotency) with generation submissions so an ambiguous timeout can be retried without creating a duplicate request.
</Tip>

## Initial response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
  "status_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status",
  "cancel_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel"
}
```

Use the URLs from the response instead of constructing them manually.

## Completed output

The output field depends on the model's output type.

<CodeGroup>
  ```json Image theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "status": "completed",
    "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
    "images": [
      { "url": "https://cdn.example.com/image-1.jpg" },
      { "url": "https://cdn.example.com/image-2.jpg" }
    ]
  }
  ```

  ```json Video theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "status": "completed",
    "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
    "video": {
      "url": "https://cdn.example.com/video.mp4"
    }
  }
  ```

  ```json Audio theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "status": "completed",
    "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
    "audio": {
      "url": "https://cdn.example.com/audio.mp3"
    },
    "audios": [
      { "url": "https://cdn.example.com/audio.mp3" }
    ]
  }
  ```
</CodeGroup>

Some video and 3D operations can return additional artifacts such as `zip`, `mov`, `jsx`, `fbx`, or `ply`.

## Cancel a request

Cancellation is available only while every job in the request remains queued.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  --url "https://api.higgsfield.ai/requests/${REQUEST_ID}/cancel" \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}"
```

A successful cancellation returns `202 Accepted` with an empty body. If processing has started, the API returns `400 Bad Request`.

<Note>
  Output URLs are retained for at least seven days. Copy completed media to your own storage if you need it for longer.
</Note>


# FAQ
Source: https://docs.higgsfield.ai/docs/help/faq

Answers about Higgsfield API authentication, asynchronous requests, model selection, billing, limits, and output retention.

# Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What base URL and authentication header should I use?">
    Send requests to `https://api.higgsfield.ai` and authenticate server-side with `Authorization: Key YOUR_KEY_ID:YOUR_KEY_SECRET`. Do not use a Bearer token or expose the secret in browser or mobile code. See [Authentication](/docs/authentication).
  </Accordion>

  <Accordion title="Why does a generation request not return the media immediately?">
    Generation is asynchronous. A successful submission returns `request_id`, `status_url`, and `cancel_url`. Poll `status_url` or configure a webhook, then read the output URL after the status becomes `completed`. See [Requests and lifecycle](/docs/concepts/requests).
  </Accordion>

  <Accordion title="Which model or endpoint should I use?">
    Choose by input and output workflow: text-to-image, image editing, text-to-video, image-to-video, or frame-controlled video. Model availability depends on your account. Not sure which endpoint fits your case? Ask in our [Discord](https://discord.gg/BEea92KeR9).
  </Accordion>

  <Accordion title="What is the retention policy for generated output files?">
    Generated output files are stored and accessible for a minimum of 7 days from the time of creation. We strongly recommend downloading and storing files in your own infrastructure for long-term retention. Files may be removed from our servers at any time after the 7-day retention period.
  </Accordion>

  <Accordion title="Are failed requests charged?">
    No. Failed generation requests are not charged to your account. You are only billed for successful completions. In the event of a failure, any credits or costs associated with that request are automatically refunded.
  </Accordion>

  <Accordion title="What does NSFW status mean?">
    NSFW (Not Safe For Work) indicates that either your input parameters or the generated output did not pass our content moderation system due to content policy violations. Content policy rules and restrictions may vary depending on the specific model being used.
  </Accordion>

  <Accordion title="Are NSFW-flagged requests charged?">
    No. Requests flagged as NSFW are not charged to your account. When content is rejected by our moderation system, any associated credits or costs are automatically refunded.
  </Accordion>

  <Accordion title="Do you offer invoice-based billing?">
    The API runs on pay-as-you-go by default: you top up a balance and pay per generation. Invoice-based billing is available for customers on a committed-use contract. To discuss one, [contact sales](https://open.higgsfield.ai/contact-sales).
  </Accordion>

  <Accordion title="What are the API rate limits?">
    Rate limits depend on your account and the selected model. You can view your current limits and usage in your [dashboard](https://console.higgsfield.ai). Need a higher limit? Let us know in our [Discord](https://discord.gg/BEea92KeR9).
  </Accordion>

  <Accordion title="How do I monitor my API usage?">
    You can monitor your API usage, credit consumption, and request history through the [Higgsfield Console dashboard](https://console.higgsfield.ai). The dashboard provides real-time analytics and detailed usage reports.
  </Accordion>

  <Accordion title="Which programming languages are supported?">
    We provide official Python and Node.js/TypeScript SDKs. You can also integrate directly through the REST API from any language with an HTTP client. See [Client libraries](/docs/how-to/sdk).
  </Accordion>

  <Accordion title="How do I get started with the API?">
    To get started:

    1. Create an account at [console.higgsfield.ai](https://console.higgsfield.ai)

    2. Generate your API credentials from the dashboard

    3. Follow our [Quickstart](/docs/quickstart) for your first integration

    4. Read [How the API works](/docs/how-to/introduction), then use a generation endpoint available to your account
  </Accordion>

  <Accordion title="What happens if a generation takes too long?">
    Generation requests have model-specific timeout limits. If a request exceeds the timeout, it will be marked as failed and you will not be charged. You can resubmit the request. If timeouts keep happening, reach out in our [Discord](https://discord.gg/BEea92KeR9) with your `request_id`.
  </Accordion>
</AccordionGroup>

## Still have questions?

If you didn't find your answer, here is where to go next:

* **Discord community**: [Join the Higgsfield Discord](https://discord.gg/BEea92KeR9) and ask your question there
* **Account and billing**: email [support@higgsfield.ai](mailto:support@higgsfield.ai)
* **Documentation**: [Read the Quickstart](/docs/quickstart)
* **API Reference**: [Request endpoint reference](/docs/api-reference/overview)


# Support
Source: https://docs.higgsfield.ai/docs/help/support

Get help with the Higgsfield API

Need help with the Higgsfield API? The Higgsfield team and the developer community are on Discord.

## Contact us

The fastest way to get help is our Discord server:

<Card title="Join the Higgsfield Discord" icon="discord" href="https://discord.gg/BEea92KeR9">
  Ask in the Discord community. The Higgsfield team and other developers are there to help.
</Card>

We can help with:

* Technical issues and troubleshooting
* API integration questions
* Choosing a model or endpoint
* Feature requests and feedback

For account, billing, or invoice questions, email [support@higgsfield.ai](mailto:support@higgsfield.ai) and the team will follow up with you directly.

### Before you post

* Check [status.higgsfield.ai](https://status.higgsfield.ai) for ongoing incidents
* Include the `request_id` and the `X-Correlation-ID` response header of the failing request (see [Errors and retries](/docs/concepts/errors))
* Include the model or endpoint and the time of the request (UTC)

<Warning>
  Never share your API key secret, payment details, or personal data in public channels. If we need account details, a team member will continue with you in a private message.
</Warning>

## Documentation

Before reaching out, check the documentation:

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/docs/quickstart">
    Get started with the Higgsfield API in minutes
  </Card>

  <Card title="API Reference" icon="code" href="/docs/api-reference/overview">
    Complete API endpoint documentation
  </Card>

  <Card title="Client Libraries" icon="book" href="/docs/how-to/sdk">
    Official SDKs for Python and TypeScript
  </Card>

  <Card title="Request lifecycle" icon="arrows-rotate" href="/docs/concepts/requests">
    Understand asynchronous requests and results
  </Card>
</CardGroup>

## Resources

### API Dashboard

Manage your API keys, monitor usage, and view analytics at [console.higgsfield.ai](https://console.higgsfield.ai)

### Status Page

Check the current status of Higgsfield services and view incident history at our status page: [status.higgsfield.ai](https://status.higgsfield.ai)

### GitHub

* **Python SDK**: [higgsfield-ai/higgsfield-client](https://github.com/higgsfield-ai/higgsfield-client)
* **TypeScript SDK**: [higgsfield-ai/higgsfield-js](https://github.com/higgsfield-ai/higgsfield-js)
* Found a bug in an SDK? Open an issue in its repository. For everything else, reach out in [Discord](https://discord.gg/BEea92KeR9).

## Feedback

We read all feedback. Let us know how we can improve:

* Share ideas and suggestions in the [Discord community](https://discord.gg/BEea92KeR9)
* Report SDK bugs on [GitHub](https://github.com/higgsfield-ai/higgsfield-client)

***

**Need a quick answer?** Ask in [Discord](https://discord.gg/BEea92KeR9) or start with the [Quickstart](/docs/quickstart).


# How the API works
Source: https://docs.higgsfield.ai/docs/how-to/introduction

Learn the common authentication and asynchronous request lifecycle shared by Higgsfield image and video models.

The Higgsfield API uses an asynchronous request lifecycle:

1. Submit JSON parameters to a model endpoint.
2. Store the returned `request_id`.
3. Poll `status_url` or wait for a webhook.
4. Download output when the request becomes `completed`.

<CardGroup>
  <Card title="Start with the Quickstart" icon="rocket" href="/docs/quickstart">
    Run a complete request using cURL.
  </Card>

  <Card title="Understand requests" icon="rotate" href="/docs/concepts/requests">
    Learn statuses, output shapes, cancellation, and retention.
  </Card>
</CardGroup>

**Base URL:** `https://api.higgsfield.ai`

Every request requires server-side [authentication](/docs/authentication). For production integrations, read the [polling](/docs/concepts/polling), [webhook](/docs/how-to/webhooks), and [error handling](/docs/concepts/errors) guides.


# Client libraries
Source: https://docs.higgsfield.ai/docs/how-to/sdk

Use the official Python and TypeScript SDKs.

Official SDKs handle authentication, submission, polling, cancellation, and file uploads. Use them only in trusted server-side environments.

<CardGroup>
  <Card title="Python" icon="python" href="https://github.com/higgsfield-ai/higgsfield-client">
    Synchronous and asynchronous APIs for Python 3.8+.
  </Card>

  <Card title="Node.js and TypeScript" icon="js" href="https://github.com/higgsfield-ai/higgsfield-js">
    Typed server-side client with automatic polling and retries.
  </Card>
</CardGroup>

## Python

### Install

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install higgsfield-client
```

### Configure credentials

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export HF_KEY="your-api-key-id:your-api-key-secret"
```

### Submit and wait

<CodeGroup>
  ```python Synchronous theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  result = higgsfield_client.subscribe(
      "higgsfield-ai/soul/v2/standard",
      arguments={
          "prompt": "Editorial portrait in soft daylight",
      },
  )

  print(result["images"][0]["url"])
  ```

  ```python Asynchronous theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import asyncio

  import higgsfield_client


  async def main():
      result = await higgsfield_client.subscribe_async(
          "higgsfield-ai/soul/v2/standard",
          arguments={
              "prompt": "Editorial portrait in soft daylight",
          },
      )
      print(result["images"][0]["url"])


  asyncio.run(main())
  ```
</CodeGroup>

Use `submit` or `submit_async` when you need a request controller for explicit polling, status checks, or cancellation. The Python SDK also provides `upload`, `upload_file`, and `upload_image` helpers.

## Node.js and TypeScript

### Install

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install @higgsfield/client
```

### Configure credentials

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export HF_CREDENTIALS="your-api-key-id:your-api-key-secret"
```

### Submit and wait

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { config, higgsfield } from "@higgsfield/client/v2";

config({
  credentials: process.env.HF_CREDENTIALS,
});

const result = await higgsfield.subscribe(
  "higgsfield-ai/soul/v2/standard",
  {
    input: {
      prompt: "Editorial portrait in soft daylight",
    },
    withPolling: true,
  },
);

if (result.status === "completed") {
  console.log(result.images?.[0]?.url);
}
```

The v2 TypeScript client is server-side only and blocks browser use to prevent credential exposure.

## Choose an integration style

| Requirement | Recommended API |
| - | - |
| Script or prototype | `subscribe` / `subscribe_async` |
| Worker with explicit lifecycle control | `submit` / `submit_async` |
| Existing request ID | `status`, `result`, or `cancel` |
| Production event-driven integration | Submit with a webhook and keep status polling as recovery |

See the [Python SDK repository](https://github.com/higgsfield-ai/higgsfield-client) and [TypeScript SDK repository](https://github.com/higgsfield-ai/higgsfield-js) for the complete client APIs.


# Webhooks
Source: https://docs.higgsfield.ai/docs/how-to/webhooks

Receive terminal generation results without continuous polling.

Pass an HTTPS endpoint in the `hf_webhook` query parameter when submitting generation. Higgsfield sends one or more HTTP `POST` deliveries after the request reaches `completed`, `failed`, or `nsfw`.

## Configure a webhook

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  --url "https://api.higgsfield.ai/higgsfield-ai/soul/v2/standard?hf_webhook=https%3A%2F%2Fexample.com%2Fwebhooks%2Fhiggsfield" \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
    "prompt": "Editorial portrait in soft daylight"
  }'
```

Your endpoint must be publicly reachable over HTTPS, accept a JSON request body, and respond within ten seconds.

## Payload envelope

All deliveries use the same top-level envelope. Successful output is nested in `payload`.

<CodeGroup>
  ```json Completed image theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "request_id": "9417a243-e457-4075-895b-b68f3cda5303",
    "status": "completed",
    "error": null,
    "payload": {
      "images": [
        {
          "url": "https://cdn.example.com/generated-image.jpg",
          "content_type": "image/jpeg"
        }
      ]
    }
  }
  ```

  ```json Completed video theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "request_id": "9417a243-e457-4075-895b-b68f3cda5303",
    "status": "completed",
    "error": null,
    "payload": {
      "video": {
        "url": "https://cdn.example.com/generated-video.mp4",
        "content_type": "video/mp4"
      }
    }
  }
  ```

  ```json Failed theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "request_id": "9417a243-e457-4075-895b-b68f3cda5303",
    "status": "failed",
    "error": "Generation failed",
    "payload": null
  }
  ```

  ```json NSFW theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "request_id": "9417a243-e457-4075-895b-b68f3cda5303",
    "status": "nsfw",
    "error": null,
    "payload": null
  }
  ```
</CodeGroup>

Audio responses contain `payload.audio`. Some video and 3D operations can also include `zip`, `mov`, `jsx`, `fbx`, or `ply` artifacts.

## Delivery and retries

* Return any `2xx` response after durably recording the event.
* Network failures and `5xx` responses are retried for up to two hours.
* `4xx` responses are treated as permanent and are not retried.
* Duplicate deliveries are possible. Deduplicate by `request_id` and terminal `status`.
* If delivery fails permanently, retrieve the result through the authenticated status endpoint.

Reject request bodies that do not match the documented envelope, but acknowledge valid duplicate deliveries with `2xx`.


# Higgsfield API
Source: https://docs.higgsfield.ai/docs/index

Generate images and videos through one authenticated, asynchronous API.

Higgsfield provides one integration point for generative media models. Submit a request to a model endpoint, then poll for the result or receive a webhook when processing finishes.

<CardGroup>
  <Card title="Run your first request" icon="rocket" href="/docs/quickstart">
    Create credentials and complete a generation from submission to result.
  </Card>

  <Card title="Get an API key" icon="key" href="https://console.higgsfield.ai">
    Create and manage server-side credentials in Higgsfield Console.
  </Card>
</CardGroup>

## Make a request

Every model uses the same authentication and asynchronous request lifecycle. The JSON body depends on the selected model.

Start with [Genjutsu motion transfer](/docs/models/genjutsu/motion-transfer). Replace the example media URLs with publicly accessible URLs for your own video and reference image. The source video must be at least 4 seconds long.

<CodeGroup>
  ```bash Genjutsu theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/higgsfield/genjutsu/motion-transfer/v1.0 \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --data '{
      "video_url": "https://example.com/input.mp4",
      "image_urls": ["https://example.com/input.jpg"]
    }'
  ```

  ```bash SOUL V2 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/higgsfield-ai/soul/v2/standard \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --data '{
      "prompt": "Editorial portrait in soft daylight"
    }'
  ```
</CodeGroup>

The API immediately returns a request identifier and links for checking or canceling the request.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
  "status_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status",
  "cancel_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel"
}
```

## Choose your path

<CardGroup>
  <Card title="Build a prototype" icon="code" href="/docs/how-to/sdk">
    Use the Python or TypeScript SDK to submit a request and wait for its result.
  </Card>

  <Card title="Ship to production" icon="server" href="/docs/concepts/requests">
    Learn the request lifecycle, polling, webhooks, errors, and limits.
  </Card>

  <Card title="Upload media" icon="upload" href="/docs/concepts/file-uploads">
    Upload input files to Higgsfield storage before generation.
  </Card>
</CardGroup>

<Note>
  Output files are available for at least seven days. Download completed output to your own storage for long-term retention.
</Note>


# Model API Reference
Source: https://docs.higgsfield.ai/docs/models

Choose a Higgsfield image or video model and open its API reference or Playground.

<div />

Use the Higgsfield API to generate images and videos with leading foundation models through one asynchronous request lifecycle.

## Choose a model category

<div>
  <a href="/docs/models/video-generation">
    <span>▶</span>

    <span>
      <span>Video Generation API</span>
      <span>Genjutsu, Seedance, Kling, Wan, Happy Horse, Cinema Studio, MiniMax, LTX, PixVerse, and Grok.</span>
    </span>

    <span>↗</span>
  </a>

  <a href="/docs/models/image-generation">
    <span>◇</span>

    <span>
      <span>Image Generation API</span>
      <span>SOUL, Soul ID training, Marketing Studio, Ads Studio, Grok, Recraft, Qwen Image, Ideogram, and Z-Image.</span>
    </span>

    <span>↗</span>
  </a>
</div>

## How the catalog works

The sidebar is organized by output type and model family. Every workflow page includes its request schema, required fields, supported values, examples, and response instructions. Generation endpoints also link to the API Playground.

<Note>
  Endpoint fields vary by model and workflow. Use the exact schema documented on the selected model page.
</Note>

## Availability

The catalog documents 84 entries: 17 Image and 67 Video. Soul ID is a training workflow. Availability and access can change; check the [API Console](https://console.higgsfield.ai) for your account.


# Ads Studio API
Source: https://docs.higgsfield.ai/docs/models/ads-studio

Turn a marketing brief and optional product references into 1–8 ad concepts rendered as images with GPT Image 2.5 Flare.

<div />

Turn a marketing brief and optional product references into 1–8 ad concepts rendered as images with GPT Image 2.5 Flare.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Generate ads](/docs/models/ads-studio/generate) | `POST /higgsfield/ads-studio/v1.0` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Ads Studio — Generate ads API
Source: https://docs.higgsfield.ai/docs/models/ads-studio/generate

Generate ads with Ads Studio: request parameters, examples and response handling.

<div />

[← Ads Studio](/docs/models/ads-studio)

**Endpoint:** `POST https://api.higgsfield.ai/higgsfield/ads-studio/v1.0`

**Endpoint ID:** `higgsfield/ads-studio/v1.0`

<a href="https://console.higgsfield.ai/models/higgsfield%2Fads-studio%2Fv1.0/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Ads Studio · Generate ads</span></span>
  <span>↗</span>
</a>

## Usage notes

* Submit one request with your brief. Ad concepts are prepared automatically, then rendered as images; no separate preparation or generate call is required.
* batch\_size selects 1–8 ad concepts. Each concept produces one image, so a fully successful batch returns batch\_size images.
* Rendering uses GPT Image 2.5 Flare with fixed 2k resolution and high quality. Exact dimensions depend on aspect\_ratio. quality, resolution, renderer and fallback model are not public inputs.
* All outputs in a batch use the requested aspect\_ratio. Omitting it selects 1:1. The value auto is not supported.
* Set HF\_API\_KEY\_ID and HF\_API\_KEY\_SECRET to your API credentials. Set a unique IDEMPOTENCY\_KEY for each intended generation; reuse it only when retrying that same request.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/higgsfield/ads-studio/v1.0 \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "Create two distinct ads for a fictional herbal tea called Quiet Evening. Use a green tea tin, warm light and the headline Make time for yourself. No people.",
    "target_audience": "Busy professionals looking for a relaxing evening ritual",
    "niche": "Herbal tea",
    "language": "en",
    "aspect_ratio": "9:16",
    "batch_size": 2
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'Create two distinct ads for a fictional herbal tea called Quiet '
                 'Evening. Use a green tea tin, warm light and the headline Make '
                 'time for yourself. No people.',
       'target_audience': 'Busy professionals looking for a relaxing evening ritual',
       'niche': 'Herbal tea',
       'language': 'en',
       'aspect_ratio': '9:16',
       'batch_size': 2}
  )
  result = higgsfield_client.subscribe(
      "higgsfield/ads-studio/v1.0",
      arguments=arguments,
  )
  print(result["images"][0]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("higgsfield/ads-studio/v1.0", {
    input:
      {
        "prompt": "Create two distinct ads for a fictional herbal tea called Quiet Evening. Use a green tea tin, warm light and the headline Make time for yourself. No people.",
        "target_audience": "Busy professionals looking for a relaxing evening ritual",
        "niche": "Herbal tea",
        "language": "en",
        "aspect_ratio": "9:16",
        "batch_size": 2
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.images?.[0]?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Optional product category or business niche used to guide ad concepts.
  Maximum characters: `1000`.
</ParamField>

<ParamField type="string">
  Required marketing brief describing the product or service, desired message and visual direction. Must contain non-whitespace text.
  Minimum characters: `1`.
  Maximum characters: `8000`.
  Pattern: `\S`.
</ParamField>

<ParamField type="string">
  Optional language guidance for ad copy, for example en or ru. This is free text, not a fixed language-code enum.
  Maximum characters: `80`.
</ParamField>

<ParamField type="integer">
  Number of ad concepts and requested output images. Billing is summed across the rendered images.
  Minimum: `1`.
  Maximum: `8`.
</ParamField>

<ParamField type="array">
  Optional product or visual reference images. Supply up to 10 directly downloadable HTTP(S) URLs. Omit or send \[] for text-only generation.
  Maximum items: `10`.
  Each item: string. Minimum characters: `1`. Maximum characters: `8192`. Pattern: `^https?://`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio shared by every image in the batch.
  Allowed values: `"1:1"`, `"4:5"`, `"5:4"`, `"16:9"`, `"9:16"`, `"4:3"`, `"3:4"`, `"21:9"`, `"3:2"`, `"2:3"`, `"2:1"`, `"1:2"`, `"3:1"`, `"1:3"`.
</ParamField>

<ParamField type="string">
  Optional description of the intended audience, such as interests, needs or use cases.
  Maximum characters: `2000`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "required": [
      "prompt"
    ],
    "properties": {
      "niche": {
        "type": "string",
        "default": "",
        "maxLength": 1000
      },
      "prompt": {
        "type": "string",
        "pattern": "\\S",
        "maxLength": 8000,
        "minLength": 1
      },
      "language": {
        "type": "string",
        "default": "",
        "maxLength": 80
      },
      "batch_size": {
        "type": "integer",
        "default": 1,
        "maximum": 8,
        "minimum": 1
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "pattern": "^https?://",
          "maxLength": 8192,
          "minLength": 1
        },
        "default": [],
        "maxItems": 10
      },
      "aspect_ratio": {
        "enum": [
          "1:1",
          "4:5",
          "5:4",
          "16:9",
          "9:16",
          "4:3",
          "3:4",
          "21:9",
          "3:2",
          "2:3",
          "2:1",
          "1:2",
          "3:1",
          "1:3"
        ],
        "type": "string",
        "default": "1:1"
      },
      "target_audience": {
        "type": "string",
        "default": "",
        "maxLength": 2000
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Product references

Omit `image_urls` for text-only generation. To guide the ad with your product, send direct image URLs that the service can download without browser cookies or custom authentication headers. An unexpired signed HTTPS URL is suitable. Keep the URLs valid while the request is being processed.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "prompt": "Create three distinct premium perfume ads. Preserve the bottle and label. Use the headline Leave a lasting note.",
  "image_urls": ["https://example.com/product.png"],
  "target_audience": "People looking for a distinctive gift",
  "niche": "Fragrance",
  "language": "en",
  "aspect_ratio": "4:5",
  "batch_size": 3
}
```

Reference images guide generation; exact preservation of a product, label or text is not guaranteed. Supported oversized references are normalized before rendering. The output remains a PNG at the selected aspect ratio.

## Pricing

**Illustrative estimate: approximately \$0.084 per image.** This is a budgeting example, not a fixed charge or maximum price. Actual cost varies with the aspect ratio, prepared prompt, reference images and measured token usage. Consult the current model pricing in the Playground before submitting work.

| Token category | USD per 1 million tokens |
| - | -: |
| Text input | \$5.00 |
| Cached text input | \$1.25 |
| Text output | \$10.00 |
| Image input | \$8.00 |
| Cached image input | \$2.00 |
| Image output | \$30.00 |

The initial charge is an estimate reconciled to actual rendering usage on completion, with standard credit rounding. Cached input is charged at the cached rate instead of being counted again as uncached input. Ad concept preparation is not billed separately.

For a batch, the final price is the **sum of the actual image charges**. Do not multiply aggregated batch token usage by `batch_size` again. Three images at the illustrative estimate would budget approximately \$0.252; the actual total can differ.

## Check request status

Use the returned `status_url` with the same API credentials. Set `REQUEST_ID` to the identifier returned when you submit the request:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request GET \
  --url "https://api.higgsfield.ai/requests/${REQUEST_ID}/status" \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}"
```

Follow the shared [polling guidance](/docs/concepts/polling). A request handle confirms acceptance, not successful image generation. Stop polling on `completed`, `failed`, `nsfw`, or `canceled`, and inspect the returned outputs and errors.

## Response

Submission returns one request handle for the entire batch:

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A fully successful two-image batch returns two indexed images:

```json Completed theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel",
  "status": "completed",
  "images": [
    {"index": 0, "url": "https://example.com/ad-1.png"},
    {"index": 1, "url": "https://example.com/ad-2.png"}
  ],
  "errors": []
}
```

Process every returned image rather than only `images[0]`. Use its zero-based `index` to identify its batch slot and inspect `errors` for unsuccessful slots. After `subscribe` returns, extend the Python quick start with:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
for image in result.get("images", []):
    print(image["index"], image["url"])
for error in result.get("errors", []):
    print(error)
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Cinema Studio 4.0 API
Source: https://docs.higgsfield.ai/docs/models/cinema-studio-4

Create video shots with camera and style controls and media references.

<div />

Create video shots with camera and style controls and media references.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Generate](/docs/models/cinema-studio-4/generate) | `POST /higgsfield/cinema-studio/4.0` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Cinema Studio 4.0 — Generate API
Source: https://docs.higgsfield.ai/docs/models/cinema-studio-4/generate

Generate with Cinema Studio 4.0: request parameters, examples and response handling.

<div />

[← Cinema Studio 4.0](/docs/models/cinema-studio-4)

**Endpoint:** `POST https://api.higgsfield.ai/higgsfield/cinema-studio/4.0`

**Endpoint ID:** `higgsfield/cinema-studio/4.0`

<a href="https://console.higgsfield.ai/models/higgsfield%2Fcinema-studio%2F4.0/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Cinema Studio 4.0 · Generate</span></span>
  <span>↗</span>
</a>

## Usage notes

* This is the public Cinema Studio 4.0 workflow. It uses text-to-video when references are absent and reference-to-video when any media array is nonempty.
* Omit creative-control fields to let the director choose them automatically; the literal value "auto" is not accepted for these enum fields.
* Optional prompt references use one-based tokens such as \<\<\<image\_1>>>, \<\<\<video\_1>>> and \<\<\<audio\_1>>>. Each token must refer to an attached item of the same media type.
* This endpoint produces a new video. Editing and extension use the separate Seedance 2.5 endpoints.
* Reference media are limited to 30 images, 10 videos and 10 audio files, with at most 50 items total. Video and audio may be normalized to separate 30-second total budgets.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/higgsfield/cinema-studio/4.0 \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.'}
  )
  result = higgsfield_client.subscribe(
      "higgsfield/cinema-studio/4.0",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("higgsfield/cinema-studio/4.0", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Allowed values: `"1960s"`, `"1980s"`, `"1990s"`, `"2000s"`, `"2020s"`.
</ParamField>

<ParamField type="string">
  Allowed values: `"epic"`, `"drama"`, `"noir"`, `"comedy"`, `"horror"`, `"action"`.
</ParamField>

<ParamField type="string">
  Allowed values: `"silhouette"`, `"practicals"`, `"window"`, `"overhead-fall"`, `"contre-jour"`, `"soft-cross"`.
</ParamField>

<ParamField type="string">
  Allowed values: `"chaotic"`, `"dynamic"`, `"calm"`, `"single-shot"`.
</ParamField>

<ParamField type="string">
  Text instructions for the generation or edit.
  Minimum characters: `1`.
  Pattern: `\S`.
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `4`.
  Maximum: `30`.
</ParamField>

<ParamField type="array">
  Ordered public audio reference URLs.
  Maximum items: `10`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Maximum items: `30`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"480p"`, `"720p"`.
</ParamField>

<ParamField type="array">
  Ordered public video reference URLs.
  Maximum items: `10`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Allowed values: `"clean-sharp"`, `"anamorphic"`, `"vintage-anamorphic"`, `"warm-vintage"`, `"halation-vintage"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"21:9"`.
</ParamField>

<ParamField type="string">
  Allowed values: `"modern"`, `"35mm-film"`, `"8mm-film"`, `"dv-camcorder"`.
</ParamField>

<ParamField type="string">
  Allowed values: `"static-noon"`, `"twilight-fable"`, `"back-row-kissing-seats"`, `"on-the-other-side-of-the-porthole"`, `"the-emerald-ambush"`, `"highway-standoff"`, `"the-faded-fresco"`, `"oil-ochre"`, `"the-mountain-convent"`, `"ghost-in-the-code"`, `"pink-velvet"`, `"two-days-to-the-horizon"`, `"industrial-fog"`, `"stairs-go-up"`, `"field-post"`, `"home-is-the-next-gas-station"`, `"glossy-flesh"`, `"the-crimson-ballet"`, `"neon-rain-at-midnight"`, `"the-morning-after-rain"`, `"the-iron-borough"`, `"the-ground"`, `"the-investigation"`, `"turquoise-mirage"`, `"a-dream-in-color"`, `"breakfast-on-schedule"`, `"favela-gold"`, `"a-hotel-for-one"`, `"after-dark"`, `"crimson-vigi"`, `"the-neighbors-saw-everything"`, `"the-grey-channel"`, `"mirage-at-noon"`, `"bubblegum-boulevard"`, `"yellow-room"`, `"the-earth-keeps-things-reluctantly"`, `"tropic-fever-dream"`, `"bioluminescent-night"`, `"dont-turn-it-off-im-watching"`, `"the-silk-curtain-falls"`, `"the-butterfly"`, `"playtime"`, `"wallpaper-romance"`, `"overtime"`, `"the-way-home-is-longer"`, `"everyone-speaks-in-whispers"`, `"runaway-summer"`, `"amber-wasteland"`, `"the-circus"`, `"gasoline-sunset"`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<ParamField type="string">
  Allowed values: `"f14-wide-open"`, `"f4-moderate"`, `"f11-deep-focus"`.
</ParamField>

<ParamField type="string">
  Allowed values: `"snorricam"`, `"robot-arm"`, `"tilt-up"`, `"rack-focus"`, `"tilt-down"`, `"pov"`, `"pan-left"`, `"crane-up"`, `"pan-right"`, `"crane-down"`, `"side-tracking"`, `"pedestal-up"`, `"pedestal-down"`, `"handheld"`, `"tracking"`, `"drone-orbit"`, `"dolly-zoom"`, `"aerial-pullback"`, `"static-shot"`, `"bullet-time"`, `"whip-pan"`, `"slow-zoom-in"`, `"arc-left"`, `"slow-zoom-out"`, `"arc-right"`, `"truck-right"`, `"dolly-in"`, `"truck-left"`, `"dolly-out"`, `"slider-right"`, `"crush-zoom"`, `"slider-left"`, `"helicopter-shot"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "required": [
      "prompt"
    ],
    "properties": {
      "era": {
        "enum": [
          "1960s",
          "1980s",
          "1990s",
          "2000s",
          "2020s"
        ],
        "type": "string"
      },
      "genre": {
        "enum": [
          "epic",
          "drama",
          "noir",
          "comedy",
          "horror",
          "action"
        ],
        "type": "string"
      },
      "light": {
        "enum": [
          "silhouette",
          "practicals",
          "window",
          "overhead-fall",
          "contre-jour",
          "soft-cross"
        ],
        "type": "string"
      },
      "pacing": {
        "enum": [
          "chaotic",
          "dynamic",
          "calm",
          "single-shot"
        ],
        "type": "string"
      },
      "prompt": {
        "type": "string",
        "pattern": "\\S",
        "minLength": 1
      },
      "duration": {
        "type": "integer",
        "default": 5,
        "maximum": 30,
        "minimum": 4
      },
      "audio_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "maxItems": 10
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "maxItems": 30
      },
      "resolution": {
        "enum": [
          "480p",
          "720p"
        ],
        "type": "string",
        "default": "720p"
      },
      "video_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "maxItems": 10
      },
      "camera_lens": {
        "enum": [
          "clean-sharp",
          "anamorphic",
          "vintage-anamorphic",
          "warm-vintage",
          "halation-vintage"
        ],
        "type": "string"
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "4:3",
          "1:1",
          "3:4",
          "9:16",
          "21:9"
        ],
        "type": "string",
        "default": "16:9"
      },
      "camera_model": {
        "enum": [
          "modern",
          "35mm-film",
          "8mm-film",
          "dv-camcorder"
        ],
        "type": "string"
      },
      "color_palette": {
        "enum": [
          "static-noon",
          "twilight-fable",
          "back-row-kissing-seats",
          "on-the-other-side-of-the-porthole",
          "the-emerald-ambush",
          "highway-standoff",
          "the-faded-fresco",
          "oil-ochre",
          "the-mountain-convent",
          "ghost-in-the-code",
          "pink-velvet",
          "two-days-to-the-horizon",
          "industrial-fog",
          "stairs-go-up",
          "field-post",
          "home-is-the-next-gas-station",
          "glossy-flesh",
          "the-crimson-ballet",
          "neon-rain-at-midnight",
          "the-morning-after-rain",
          "the-iron-borough",
          "the-ground",
          "the-investigation",
          "turquoise-mirage",
          "a-dream-in-color",
          "breakfast-on-schedule",
          "favela-gold",
          "a-hotel-for-one",
          "after-dark",
          "crimson-vigi",
          "the-neighbors-saw-everything",
          "the-grey-channel",
          "mirage-at-noon",
          "bubblegum-boulevard",
          "yellow-room",
          "the-earth-keeps-things-reluctantly",
          "tropic-fever-dream",
          "bioluminescent-night",
          "dont-turn-it-off-im-watching",
          "the-silk-curtain-falls",
          "the-butterfly",
          "playtime",
          "wallpaper-romance",
          "overtime",
          "the-way-home-is-longer",
          "everyone-speaks-in-whispers",
          "runaway-summer",
          "amber-wasteland",
          "the-circus",
          "gasoline-sunset"
        ],
        "type": "string"
      },
      "generate_audio": {
        "type": "boolean",
        "default": true
      },
      "camera_aperture": {
        "enum": [
          "f14-wide-open",
          "f4-moderate",
          "f11-deep-focus"
        ],
        "type": "string"
      },
      "camera_movement": {
        "enum": [
          "snorricam",
          "robot-arm",
          "tilt-up",
          "rack-focus",
          "tilt-down",
          "pov",
          "pan-left",
          "crane-up",
          "pan-right",
          "crane-down",
          "side-tracking",
          "pedestal-up",
          "pedestal-down",
          "handheld",
          "tracking",
          "drone-orbit",
          "dolly-zoom",
          "aerial-pullback",
          "static-shot",
          "bullet-time",
          "whip-pan",
          "slow-zoom-in",
          "arc-left",
          "slow-zoom-out",
          "arc-right",
          "truck-right",
          "dolly-in",
          "truck-left",
          "dolly-out",
          "slider-right",
          "crush-zoom",
          "slider-left",
          "helicopter-shot"
        ],
        "type": "string"
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Genjutsu API
Source: https://docs.higgsfield.ai/docs/models/genjutsu

Transfer motion, replace objects, or restyle a source video.

<div />

Transfer motion, replace objects, or restyle a source video.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Motion transfer](/docs/models/genjutsu/motion-transfer) | `POST /higgsfield/genjutsu/motion-transfer/v1.0` |
| [Object swap](/docs/models/genjutsu/object-swap) | `POST /higgsfield/genjutsu/object-swap/v1.0` |
| [Restyle](/docs/models/genjutsu/restyle) | `POST /higgsfield/genjutsu/restyle/v1.0` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Genjutsu — Motion transfer API
Source: https://docs.higgsfield.ai/docs/models/genjutsu/motion-transfer

Motion transfer with Genjutsu: request parameters, examples and response handling.

<div />

[← Genjutsu](/docs/models/genjutsu)

**Endpoint:** `POST https://api.higgsfield.ai/higgsfield/genjutsu/motion-transfer/v1.0`

**Endpoint ID:** `higgsfield/genjutsu/motion-transfer/v1.0`

<a href="https://console.higgsfield.ai/models/higgsfield%2Fgenjutsu%2Fmotion-transfer%2Fv1.0/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Genjutsu · Motion transfer</span></span>
  <span>↗</span>
</a>

## Usage notes

* Use higgsfield/genjutsu/motion-transfer/v1.0 for new integrations. The legacy endpoint higgsfiled/genjutsu/motion-transfer/v1.0 remains callable for existing clients but is hidden from model discovery.
* The source video must be at least 4 seconds. Videos longer than 30 seconds are trimmed to 30 seconds; output duration follows the prepared source video.
* Provide 1–8 image references. The prompt is optional and defaults to an empty string.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/higgsfield/genjutsu/motion-transfer/v1.0 \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "video_url": "https://example.com/input.mp4",
    "image_urls": [
      "https://example.com/input.jpg"
    ]
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'video_url': 'https://example.com/input.mp4',
       'image_urls': ['https://example.com/input.jpg']}
  )
  result = higgsfield_client.subscribe(
      "higgsfield/genjutsu/motion-transfer/v1.0",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("higgsfield/genjutsu/motion-transfer/v1.0", {
    input:
      {
        "video_url": "https://example.com/input.mp4",
        "image_urls": [
          "https://example.com/input.jpg"
        ]
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Text instructions for the generation or edit.
  Maximum characters: `10000`.
</ParamField>

<ParamField type="string">
  Public URL of the source video.
  Minimum characters: `1`.
  Maximum characters: `2083`.
  Format: `uri`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Minimum items: `1`.
  Maximum items: `8`.
  Each item: string. Minimum characters: `1`. Maximum characters: `2083`. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"480p"`, `"1080p"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "MotionTransferParams",
    "required": [
      "video_url",
      "image_urls"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "default": "",
        "maxLength": 10000
      },
      "video_url": {
        "type": "string",
        "title": "Video Url",
        "format": "uri",
        "maxLength": 2083,
        "minLength": 1
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri",
          "maxLength": 2083,
          "minLength": 1
        },
        "title": "Image Urls",
        "maxItems": 8,
        "minItems": 1
      },
      "resolution": {
        "enum": [
          "720p",
          "480p",
          "1080p"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "720p"
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Genjutsu — Object swap API
Source: https://docs.higgsfield.ai/docs/models/genjutsu/object-swap

Object swap with Genjutsu: request parameters, examples and response handling.

<div />

[← Genjutsu](/docs/models/genjutsu)

**Endpoint:** `POST https://api.higgsfield.ai/higgsfield/genjutsu/object-swap/v1.0`

**Endpoint ID:** `higgsfield/genjutsu/object-swap/v1.0`

<a href="https://console.higgsfield.ai/models/higgsfield%2Fgenjutsu%2Fobject-swap%2Fv1.0/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Genjutsu · Object swap</span></span>
  <span>↗</span>
</a>

## Usage notes

* Use higgsfield/genjutsu/object-swap/v1.0 for new integrations. The legacy endpoint higgsfiled/genjutsu/object-swap/v1.0 remains callable for existing clients but is hidden from model discovery.
* The source video must be at least 4 seconds. Videos longer than 30 seconds are trimmed to 30 seconds; output duration follows the prepared source video.
* Provide 1–8 image references. The prompt is optional and defaults to an empty string.
* The source video must contain at least 409,600 pixels per frame (width × height).

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/higgsfield/genjutsu/object-swap/v1.0 \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "video_url": "https://example.com/input.mp4",
    "image_urls": [
      "https://example.com/input.jpg"
    ]
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'video_url': 'https://example.com/input.mp4',
       'image_urls': ['https://example.com/input.jpg']}
  )
  result = higgsfield_client.subscribe(
      "higgsfield/genjutsu/object-swap/v1.0",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("higgsfield/genjutsu/object-swap/v1.0", {
    input:
      {
        "video_url": "https://example.com/input.mp4",
        "image_urls": [
          "https://example.com/input.jpg"
        ]
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Text instructions for the generation or edit.
  Maximum characters: `10000`.
</ParamField>

<ParamField type="string">
  Public URL of the source video.
  Minimum characters: `1`.
  Maximum characters: `2083`.
  Format: `uri`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Minimum items: `1`.
  Maximum items: `8`.
  Each item: string. Minimum characters: `1`. Maximum characters: `2083`. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"480p"`, `"1080p"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "ObjectSwapParams",
    "required": [
      "video_url",
      "image_urls"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "default": "",
        "maxLength": 10000
      },
      "video_url": {
        "type": "string",
        "title": "Video Url",
        "format": "uri",
        "maxLength": 2083,
        "minLength": 1
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri",
          "maxLength": 2083,
          "minLength": 1
        },
        "title": "Image Urls",
        "maxItems": 8,
        "minItems": 1
      },
      "resolution": {
        "enum": [
          "720p",
          "480p",
          "1080p"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "720p"
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Genjutsu — Restyle API
Source: https://docs.higgsfield.ai/docs/models/genjutsu/restyle

Restyle with Genjutsu: request parameters, examples and response handling.

<div />

[← Genjutsu](/docs/models/genjutsu)

**Endpoint:** `POST https://api.higgsfield.ai/higgsfield/genjutsu/restyle/v1.0`

**Endpoint ID:** `higgsfield/genjutsu/restyle/v1.0`

<a href="https://console.higgsfield.ai/models/higgsfield%2Fgenjutsu%2Frestyle%2Fv1.0/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Genjutsu · Restyle</span></span>
  <span>↗</span>
</a>

## Usage notes

* Restyle changes the visual style of a source video while retaining its motion, shot composition, and source audio. Each request produces one video.
* Select a current style from GET /models/higgsfield/genjutsu/restyle/v1.0/presets and send its UUID as preset\_id. The example UUID below is illustrative of a published preset; fetch the current catalog before submitting.
* The source must be at least 4 seconds and no larger than 200 MiB. Videos longer than 30 seconds are trimmed to their first 30 seconds, including audio.
* Character references are optional: omit image\_urls or send \[] to restyle the existing source subjects. Supply up to 5 character images to guide their appearance.
* Defaults apply to omitted optional fields. Use \[] or an empty string where appropriate; null is not accepted.
* Output framing is derived from the source and animation cadence can depend on the selected style. Exact output duration and FPS may differ from the source.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/higgsfield/genjutsu/restyle/v1.0 \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "video_url": "https://example.com/input.mp4",
    "preset_id": "c2143317-f28d-4c3c-a0b8-39bd547e08a7",
    "image_urls": [],
    "prompt": "Preserve the original movement and camera composition.",
    "resolution": "720p"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'video_url': 'https://example.com/input.mp4',
       'preset_id': 'c2143317-f28d-4c3c-a0b8-39bd547e08a7',
       'image_urls': [],
       'prompt': 'Preserve the original movement and camera composition.',
       'resolution': '720p'}
  )
  result = higgsfield_client.subscribe(
      "higgsfield/genjutsu/restyle/v1.0",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("higgsfield/genjutsu/restyle/v1.0", {
    input:
      {
        "video_url": "https://example.com/input.mp4",
        "preset_id": "c2143317-f28d-4c3c-a0b8-39bd547e08a7",
        "image_urls": [],
        "prompt": "Preserve the original movement and camera composition.",
        "resolution": "720p"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Optional additional guidance for the final video alongside the preset, source motion, and character references. Describe subject roles or details to retain, for example: “Keep the referenced character’s pink hair consistent across shots.” An empty string uses the visual inputs without additional instructions. This supplements preset\_id; it does not create a custom style or set duration, resolution, FPS, or audio behavior. Instructions guide a generative result and do not guarantee exact preservation.
  Maximum characters: `10000`.
</ParamField>

<ParamField type="string">
  Required UUID from items\[].id in the [available styles](#available-styles) response. Selects one visual style for the subjects and scene. Send the ID, not the style name, preview URL, or list index. A prompt or character image does not replace this field. Hidden or unavailable presets fail input preparation; no alternative style is selected automatically. Custom/personal presets and multiple simultaneous styles are not supported.
  Format: `uuid`.
</ParamField>

<ParamField type="string">
  Direct URL of the source video that supplies motion, camera movement, composition, and the source scene. It must be downloadable without browser cookies or custom authentication headers; an unexpired signed HTTPS URL is suitable. Minimum duration: 4 seconds. Maximum download size: 200 MiB (209,715,200 bytes), including files that will be trimmed. Longer clips use only their first 30 seconds; trim your upload first if you need another segment. Use a decodable video such as MP4, not a player page or local file path. Original audio is retained when present; there is no new-soundtrack control.
  Minimum characters: `1`.
  Format: `uri`.
</ParamField>

<ParamField type="array">
  Optional character appearance references, in a stable order. Omit this field or send \[] to derive the styled subjects and scene from the source video. With references, each character image is restyled and the source background is cleaned and styled separately before video generation. Each URL must point directly to a downloadable image; JPEG and PNG are practical choices. Maximum download size: 64 MiB (67,108,864 bytes) per image. Images are normalized, so their dimensions do not set the output video size. These are character references, not style previews or background-only inputs. For multiple characters, describe the intended roles in prompt; the public API provides no explicit reference-to-person mapping.
  Maximum items: `5`.
  Each item: string. Minimum characters: `1`. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier; strings are case-sensitive. Defaults to 720p. Send a supported string such as "720p", not the number 720 or "HD". This setting selects the video price tier and does not set the aspect ratio, duration, or FPS.
  Allowed values: `"480p"`, `"720p"`, `"1080p"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Genjutsu Restyle",
    "required": [
      "video_url",
      "preset_id"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "default": "",
        "maxLength": 10000
      },
      "preset_id": {
        "type": "string",
        "title": "Style preset",
        "format": "uuid"
      },
      "video_url": {
        "type": "string",
        "title": "Source video",
        "format": "uri",
        "minLength": 1,
        "description": "Source video, 4–30 seconds. Longer videos are trimmed to 30 seconds."
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri",
          "minLength": 1
        },
        "title": "Character images",
        "default": [],
        "maxItems": 5,
        "description": "Optional character references. Leave empty to restyle the source frame."
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "720p"
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Available styles

Styles are called **presets** in the API. Fetch the catalog before selecting a style:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --fail-with-body --silent --show-error \
  'https://api.higgsfield.ai/models/higgsfield/genjutsu/restyle/v1.0/presets' \
  -H "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}"
```

No request body, query parameters, or pagination parameters are needed. The endpoint requires authentication and access to the Restyle model. It returns all currently selectable system presets, ordered by name and ID. Hidden or unusable presets are omitted; personal/custom styles are not included.

Example response, shortened to one item:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "model": "higgsfield/genjutsu/restyle/v1.0",
  "items": [
    {
      "id": "c2143317-f28d-4c3c-a0b8-39bd547e08a7",
      "name": "Cel-Shaded CG Anime",
      "preview_url": "https://cdn.higgsfield.ai/restyle_presets/259d7ddb-4201-49f7-8a91-cee5bce28715.webp"
    }
  ]
}
```

| Response field | Meaning |
| - | - |
| `model` | The generation model to which this catalog belongs. |
| `items` | Array of available styles. Treat an empty array as no selectable styles. |
| `items[].id` | Style UUID. Copy this value into the generation request's `preset_id`. |
| `items[].name` | Human-readable style name for a menu or style picker. |
| `items[].preview_url` | Style preview image for display. This is not the value of `preset_id` and does not need to be sent in `image_urls`. |

Select exactly one item. Use its `id`, not its name, list position, or preview URL. The example ID above was available when this documentation was written; always use the current catalog in your application. If a saved selection disappears, refresh the list and select an available style.

## Character references

Without `image_urls`, Restyle takes the existing source subject and scene as its appearance reference. With `image_urls`, it styles each supplied character image and prepares a styled background from the source scene. In both cases, `video_url` supplies the motion and `preset_id` supplies the visual style.

For example, use this generation body to include a character reference. Replace the media URLs and select a current preset ID:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "video_url": "https://example.com/input.mp4",
  "preset_id": "c2143317-f28d-4c3c-a0b8-39bd547e08a7",
  "image_urls": ["https://example.com/character.png"],
  "prompt": "Keep the referenced character consistent across shots while preserving the original movement.",
  "resolution": "1080p"
}
```

There are only five public model inputs: `video_url`, `preset_id`, `image_urls`, `prompt`, and `resolution`. Batch size, duration, aspect ratio, FPS, scene mode, a separate background image, seed, and provider selection are not exposed by this model.

## Approximate pricing

| Resolution | Approximate price per source-video second |
| - | - |
| `480p` | \$0.318 |
| `720p` | \$0.681 |
| `1080p` | \$1.632 |

These are approximate per-second rates, not an exact total quote. Source duration is rounded up to whole seconds after trimming to 30 seconds: an 8.1-second source is billed as 9 seconds.

## Check request status

The same API key is used to list styles, submit generation, and poll the result. Set `HF_API_KEY_ID` and `HF_API_KEY_SECRET` to your API credentials. Set a unique `IDEMPOTENCY_KEY` for each intended generation, and reuse it only when retrying that request.

After submission, poll the returned `status_url`, or set `REQUEST_ID` to the returned ID:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --fail-with-body --silent --show-error \
  "https://api.higgsfield.ai/requests/${REQUEST_ID}/status" \
  -H "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}"
```

A request can be `queued` or `in_progress` before it completes. Stop polling on `completed`, `failed`, `nsfw`, or `canceled`. A failed response includes an `error` message. Media download and unavailable-preset errors can occur after acceptance; a request handle alone does not mean that generation succeeded. Keep signed media URLs valid while inputs are fetched.

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Grok Image 2.0 API
Source: https://docs.higgsfield.ai/docs/models/grok-image-2

Generate and edit images with up to ten image references.

<div />

Generate and edit images with up to ten image references.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Generate and edit](/docs/models/grok-image-2/generate-and-edit) | `POST /xai/grok-imagine-image-2.0` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Grok Image 2.0 — Generate and edit API
Source: https://docs.higgsfield.ai/docs/models/grok-image-2/generate-and-edit

Generate and edit with Grok Image 2.0: request parameters, examples and response handling.

<div />

[← Grok Image 2.0](/docs/models/grok-image-2)

**Endpoint:** `POST https://api.higgsfield.ai/xai/grok-imagine-image-2.0`

**Endpoint ID:** `xai/grok-imagine-image-2.0`

<a href="https://console.higgsfield.ai/models/xai%2Fgrok-imagine-image-2.0/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Grok Image 2.0 · Generate and edit</span></span>
  <span>↗</span>
</a>

## Usage notes

* Supports both text-to-image and editing: omit image\_urls for generation, or supply up to 10 references for editing.
* quality accepts low or medium only; resolution accepts 1k or 2k. aspect\_ratio defaults to auto.
* Reference images may be resized during preprocessing before submission. The request produces one image; no batch count is declared.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/xai/grok-imagine-image-2.0 \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
    "resolution": "1k",
    "aspect_ratio": "1:1",
    "quality": "medium"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A ceramic vase on a wooden table beside a sunlit window, soft '
                 'natural shadows, editorial photograph.',
       'resolution': '1k',
       'aspect_ratio': '1:1',
       'quality': 'medium'}
  )
  result = higgsfield_client.subscribe(
      "xai/grok-imagine-image-2.0",
      arguments=arguments,
  )
  print(result["images"][0]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("xai/grok-imagine-image-2.0", {
    input:
      {
        "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
        "resolution": "1k",
        "aspect_ratio": "1:1",
        "quality": "medium"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.images?.[0]?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="string">
  Allowed values: `"low"`, `"medium"`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Minimum items: `0`.
  Maximum items: `10`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"1k"`, `"2k"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"auto"`, `"1:1"`, `"1:2"`, `"2:1"`, `"3:2"`, `"2:3"`, `"4:3"`, `"3:4"`, `"16:9"`, `"9:16"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Grok Imagine 2.0 Playground",
    "required": [
      "prompt"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "quality": {
        "enum": [
          "low",
          "medium"
        ],
        "type": "string",
        "title": "Quality",
        "default": "medium"
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "title": "Image",
          "format": "uri"
        },
        "title": "Input Images",
        "maxItems": 10,
        "minItems": 0
      },
      "resolution": {
        "enum": [
          "1k",
          "2k"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "1k"
      },
      "aspect_ratio": {
        "enum": [
          "auto",
          "1:1",
          "1:2",
          "2:1",
          "3:2",
          "2:3",
          "4:3",
          "3:4",
          "16:9",
          "9:16"
        ],
        "type": "string",
        "default": "auto"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "images": [
    {
      "url": "https://example.com/output.png"
    }
  ]
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Grok Imagine Video 1.5 API
Source: https://docs.higgsfield.ai/docs/models/grok-video-1-5

Generate videos from text, images or an audio reference.

<div />

Generate videos from text, images or an audio reference.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Reference to video](/docs/models/grok-video-1-5/reference-to-video) | `POST /xai/grok-imagine-video/v1.5/reference-to-video` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Grok Imagine Video 1.5 — Reference to video API
Source: https://docs.higgsfield.ai/docs/models/grok-video-1-5/reference-to-video

Reference to video with Grok Imagine Video 1.5: request parameters, examples and response handling.

<div />

[← Grok Imagine Video 1.5](/docs/models/grok-video-1-5)

**Endpoint:** `POST https://api.higgsfield.ai/xai/grok-imagine-video/v1.5/reference-to-video`

**Endpoint ID:** `xai/grok-imagine-video/v1.5/reference-to-video`

<a href="https://console.higgsfield.ai/models/xai%2Fgrok-imagine-video%2Fv1.5%2Freference-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Grok Imagine Video 1.5 · Reference to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* This endpoint also accepts text-only requests or one first-frame image. Choose either image\_url or reference media (image\_urls/audio\_url); do not combine these modes.
* When image\_urls or audio\_url is provided, resolution must be 480p or 720p. The shared schema also lists 1080p, which is rejected in reference mode.
* Input images must decode as JPEG, PNG, WebP or GIF; SVG and XML are unsupported.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/xai/grok-imagine-video/v1.5/reference-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
    "image_urls": [
      "https://example.com/input.jpg"
    ]
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.',
       'image_urls': ['https://example.com/input.jpg']}
  )
  result = higgsfield_client.subscribe(
      "xai/grok-imagine-video/v1.5/reference-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("xai/grok-imagine-video/v1.5/reference-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
        "image_urls": [
          "https://example.com/input.jpg"
        ]
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `1`.
  Maximum: `15`.
</ParamField>

<ParamField type="string">
  Public URL of the audio reference.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Minimum items: `0`.
  Maximum items: `7`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"480p"`, `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"auto"`, `"1:1"`, `"16:9"`, `"9:16"`, `"4:3"`, `"3:4"`, `"3:2"`, `"2:3"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Grok Imagine Video 1.5 Reference Playground",
    "required": [
      "prompt"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 1
      },
      "audio_url": {
        "type": "string",
        "title": "Reference audio",
        "format": "uri"
      },
      "image_url": {
        "type": "string",
        "title": "First-frame image",
        "format": "uri"
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "title": "Image",
          "format": "uri"
        },
        "title": "Reference images",
        "maxItems": 7,
        "minItems": 0
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "480p"
      },
      "aspect_ratio": {
        "enum": [
          "auto",
          "1:1",
          "16:9",
          "9:16",
          "4:3",
          "3:4",
          "3:2",
          "2:3"
        ],
        "type": "string",
        "default": "auto"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Hailuo 2.3 API
Source: https://docs.higgsfield.ai/docs/models/hailuo-2-3

Generate videos from text or an image with Hailuo 2.3 Standard.

<div />

Generate videos from text or an image with Hailuo 2.3 Standard.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Standard text to video](/docs/models/hailuo-2-3/standard-text-to-video) | `POST /minimax/hailuo-2.3/standard/text-to-video` |
| [Standard image to video](/docs/models/hailuo-2-3/standard-image-to-video) | `POST /minimax/hailuo-2.3/standard/image-to-video` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Hailuo 2.3 — Standard image to video API
Source: https://docs.higgsfield.ai/docs/models/hailuo-2-3/standard-image-to-video

Standard image to video with Hailuo 2.3: request parameters, examples and response handling.

<div />

[← Hailuo 2.3](/docs/models/hailuo-2-3)

**Endpoint:** `POST https://api.higgsfield.ai/minimax/hailuo-2.3/standard/image-to-video`

**Endpoint ID:** `minimax/hailuo-2.3/standard/image-to-video`

<a href="https://console.higgsfield.ai/models/minimax%2Fhailuo-2.3%2Fstandard%2Fimage-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Hailuo 2.3 · Standard image to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* This Standard endpoint uses a fixed 768P output resolution; resolution is not a configurable field in the production schema.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/minimax/hailuo-2.3/standard/image-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
    "image_url": "https://example.com/input.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.',
       'image_url': 'https://example.com/input.jpg'}
  )
  result = higgsfield_client.subscribe(
      "minimax/hailuo-2.3/standard/image-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("minimax/hailuo-2.3/standard/image-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
        "image_url": "https://example.com/input.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Allowed values: `6`, `10`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="boolean">
  See the complete JSON schema below.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Minimax Hailuo 2.3 Playground",
    "required": [
      "prompt",
      "image_url"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "enum": [
          6,
          10
        ],
        "type": "integer",
        "title": "Duration",
        "default": 6
      },
      "image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      },
      "prompt_optimizer": {
        "type": "boolean",
        "title": "Prompt optimizer",
        "default": true
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Hailuo 2.3 — Standard text to video API
Source: https://docs.higgsfield.ai/docs/models/hailuo-2-3/standard-text-to-video

Standard text to video with Hailuo 2.3: request parameters, examples and response handling.

<div />

[← Hailuo 2.3](/docs/models/hailuo-2-3)

**Endpoint:** `POST https://api.higgsfield.ai/minimax/hailuo-2.3/standard/text-to-video`

**Endpoint ID:** `minimax/hailuo-2.3/standard/text-to-video`

<a href="https://console.higgsfield.ai/models/minimax%2Fhailuo-2.3%2Fstandard%2Ftext-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Hailuo 2.3 · Standard text to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* This Standard endpoint uses a fixed 768P output resolution; resolution is not a configurable field in the production schema.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/minimax/hailuo-2.3/standard/text-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.'}
  )
  result = higgsfield_client.subscribe(
      "minimax/hailuo-2.3/standard/text-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("minimax/hailuo-2.3/standard/text-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Allowed values: `6`, `10`.
</ParamField>

<ParamField type="boolean">
  See the complete JSON schema below.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Minimax Hailuo 2.3 Playground",
    "required": [
      "prompt"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "enum": [
          6,
          10
        ],
        "type": "integer",
        "title": "Duration",
        "default": 6
      },
      "prompt_optimizer": {
        "type": "boolean",
        "title": "Prompt optimizer",
        "default": true
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Happy Horse 1.0 API
Source: https://docs.higgsfield.ai/docs/models/happy-horse-1

Generate videos from text, a starting image or reference images.

<div />

Generate videos from text, a starting image or reference images.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to video](/docs/models/happy-horse-1/text-to-video) | `POST /alibaba/happy-horse/text-to-video` |
| [Image to video](/docs/models/happy-horse-1/image-to-video) | `POST /alibaba/happy-horse/image-to-video` |
| [Reference to video](/docs/models/happy-horse-1/reference-to-video) | `POST /alibaba/happy-horse/reference-to-video` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# HappyHorse 1.1 API
Source: https://docs.higgsfield.ai/docs/models/happy-horse-1-1

Generate videos from text, a starting image or reference images.

<div />

Generate videos from text, a starting image or reference images.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to video](/docs/models/happy-horse-1-1/text-to-video) | `POST /alibaba/happy-horse/v1.1/text-to-video` |
| [Image to video](/docs/models/happy-horse-1-1/image-to-video) | `POST /alibaba/happy-horse/v1.1/image-to-video` |
| [Reference to video](/docs/models/happy-horse-1-1/reference-to-video) | `POST /alibaba/happy-horse/v1.1/reference-to-video` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# HappyHorse 1.1 — Image to video API
Source: https://docs.higgsfield.ai/docs/models/happy-horse-1-1/image-to-video

Image to video with HappyHorse 1.1: request parameters, examples and response handling.

<div />

[← HappyHorse 1.1](/docs/models/happy-horse-1-1)

**Endpoint:** `POST https://api.higgsfield.ai/alibaba/happy-horse/v1.1/image-to-video`

**Endpoint ID:** `alibaba/happy-horse/v1.1/image-to-video`

<a href="https://console.higgsfield.ai/models/alibaba%2Fhappy-horse%2Fv1.1%2Fimage-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>HappyHorse 1.1 · Image to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* The prompt is optional. This endpoint accepts one first-frame image; it does not support a last-frame image.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/alibaba/happy-horse/v1.1/image-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "image_url": "https://example.com/input.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'image_url': 'https://example.com/input.jpg'}
  )
  result = higgsfield_client.subscribe(
      "alibaba/happy-horse/v1.1/image-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("alibaba/happy-horse/v1.1/image-to-video", {
    input:
      {
        "image_url": "https://example.com/input.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `1`.
  Maximum: `2147483646`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `2`.
  Maximum: `15`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Happy horse",
    "required": [
      "image_url"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "maximum": 2147483646,
        "minimum": 1
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 2
      },
      "image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      },
      "resolution": {
        "enum": [
          "720p",
          "1080p"
        ],
        "type": "string",
        "default": "1080p"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# HappyHorse 1.1 — Reference to video API
Source: https://docs.higgsfield.ai/docs/models/happy-horse-1-1/reference-to-video

Reference to video with HappyHorse 1.1: request parameters, examples and response handling.

<div />

[← HappyHorse 1.1](/docs/models/happy-horse-1-1)

**Endpoint:** `POST https://api.higgsfield.ai/alibaba/happy-horse/v1.1/reference-to-video`

**Endpoint ID:** `alibaba/happy-horse/v1.1/reference-to-video`

<a href="https://console.higgsfield.ai/models/alibaba%2Fhappy-horse%2Fv1.1%2Freference-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>HappyHorse 1.1 · Reference to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Provide 1–9 reference images. This limit is enforced at submission even though the stored JSON Schema does not set minItems or maxItems. Reference videos are unsupported.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/alibaba/happy-horse/v1.1/reference-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "image_urls": [
      "https://example.com/input.jpg"
    ],
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'image_urls': ['https://example.com/input.jpg'],
       'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.'}
  )
  result = higgsfield_client.subscribe(
      "alibaba/happy-horse/v1.1/reference-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("alibaba/happy-horse/v1.1/reference-to-video", {
    input:
      {
        "image_urls": [
          "https://example.com/input.jpg"
        ],
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `1`.
  Maximum: `2147483646`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `2`.
  Maximum: `15`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Happy horse",
    "required": [
      "image_urls",
      "prompt"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "maximum": 2147483646,
        "minimum": 1
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 2
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "title": "Image URL",
          "format": "uri"
        }
      },
      "resolution": {
        "enum": [
          "720p",
          "1080p"
        ],
        "type": "string",
        "default": "1080p"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# HappyHorse 1.1 — Text to video API
Source: https://docs.higgsfield.ai/docs/models/happy-horse-1-1/text-to-video

Text to video with HappyHorse 1.1: request parameters, examples and response handling.

<div />

[← HappyHorse 1.1](/docs/models/happy-horse-1-1)

**Endpoint:** `POST https://api.higgsfield.ai/alibaba/happy-horse/v1.1/text-to-video`

**Endpoint ID:** `alibaba/happy-horse/v1.1/text-to-video`

<a href="https://console.higgsfield.ai/models/alibaba%2Fhappy-horse%2Fv1.1%2Ftext-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>HappyHorse 1.1 · Text to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* The prompt must contain text; an empty string is rejected during submission.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/alibaba/happy-horse/v1.1/text-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.'}
  )
  result = higgsfield_client.subscribe(
      "alibaba/happy-horse/v1.1/text-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("alibaba/happy-horse/v1.1/text-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `1`.
  Maximum: `2147483646`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `3`.
  Maximum: `15`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, `"3:4"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Happy Horse",
    "required": [
      "prompt"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "maximum": 2147483646,
        "minimum": 1
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 3
      },
      "resolution": {
        "enum": [
          "720p",
          "1080p"
        ],
        "type": "string",
        "default": "1080p"
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16",
          "1:1",
          "4:3",
          "3:4"
        ],
        "type": "string",
        "title": "Aspect Ratio",
        "default": "16:9"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Happy Horse 1.0 — Image to video API
Source: https://docs.higgsfield.ai/docs/models/happy-horse-1/image-to-video

Image to video with Happy Horse 1.0: request parameters, examples and response handling.

<div />

[← Happy Horse 1.0](/docs/models/happy-horse-1)

**Endpoint:** `POST https://api.higgsfield.ai/alibaba/happy-horse/image-to-video`

**Endpoint ID:** `alibaba/happy-horse/image-to-video`

<a href="https://console.higgsfield.ai/models/alibaba%2Fhappy-horse%2Fimage-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Happy Horse 1.0 · Image to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* The prompt is optional. This endpoint accepts one first-frame image; it does not support a last-frame image.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/alibaba/happy-horse/image-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "image_url": "https://example.com/input.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'image_url': 'https://example.com/input.jpg'}
  )
  result = higgsfield_client.subscribe(
      "alibaba/happy-horse/image-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("alibaba/happy-horse/image-to-video", {
    input:
      {
        "image_url": "https://example.com/input.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `1`.
  Maximum: `2147483646`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `2`.
  Maximum: `15`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Happy horse",
    "required": [
      "image_url"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "maximum": 2147483646,
        "minimum": 1
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 2
      },
      "image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      },
      "resolution": {
        "enum": [
          "720p",
          "1080p"
        ],
        "type": "string",
        "default": "720p"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Happy Horse 1.0 — Reference to video API
Source: https://docs.higgsfield.ai/docs/models/happy-horse-1/reference-to-video

Reference to video with Happy Horse 1.0: request parameters, examples and response handling.

<div />

[← Happy Horse 1.0](/docs/models/happy-horse-1)

**Endpoint:** `POST https://api.higgsfield.ai/alibaba/happy-horse/reference-to-video`

**Endpoint ID:** `alibaba/happy-horse/reference-to-video`

<a href="https://console.higgsfield.ai/models/alibaba%2Fhappy-horse%2Freference-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Happy Horse 1.0 · Reference to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Provide 1–9 reference images. This limit is enforced at submission even though the stored JSON Schema does not set minItems or maxItems. Reference videos are unsupported.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/alibaba/happy-horse/reference-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "image_urls": [
      "https://example.com/input.jpg"
    ],
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'image_urls': ['https://example.com/input.jpg'],
       'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.'}
  )
  result = higgsfield_client.subscribe(
      "alibaba/happy-horse/reference-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("alibaba/happy-horse/reference-to-video", {
    input:
      {
        "image_urls": [
          "https://example.com/input.jpg"
        ],
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `1`.
  Maximum: `2147483646`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `2`.
  Maximum: `15`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Happy horse",
    "required": [
      "image_urls",
      "prompt"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "maximum": 2147483646,
        "minimum": 1
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 2
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "title": "Image URL",
          "format": "uri"
        }
      },
      "resolution": {
        "enum": [
          "720p",
          "1080p"
        ],
        "type": "string",
        "default": "720p"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Happy Horse 1.0 — Text to video API
Source: https://docs.higgsfield.ai/docs/models/happy-horse-1/text-to-video

Text to video with Happy Horse 1.0: request parameters, examples and response handling.

<div />

[← Happy Horse 1.0](/docs/models/happy-horse-1)

**Endpoint:** `POST https://api.higgsfield.ai/alibaba/happy-horse/text-to-video`

**Endpoint ID:** `alibaba/happy-horse/text-to-video`

<a href="https://console.higgsfield.ai/models/alibaba%2Fhappy-horse%2Ftext-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Happy Horse 1.0 · Text to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* The prompt must contain text; an empty string is rejected during submission.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/alibaba/happy-horse/text-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.'}
  )
  result = higgsfield_client.subscribe(
      "alibaba/happy-horse/text-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("alibaba/happy-horse/text-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `1`.
  Maximum: `2147483646`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `3`.
  Maximum: `15`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, `"3:4"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Happy Horse",
    "required": [
      "prompt"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "maximum": 2147483646,
        "minimum": 1
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 3
      },
      "resolution": {
        "enum": [
          "720p",
          "1080p"
        ],
        "type": "string",
        "default": "720p"
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16",
          "1:1",
          "4:3",
          "3:4"
        ],
        "type": "string",
        "title": "Aspect Ratio",
        "default": "16:9"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Ideogram 4.0 API
Source: https://docs.higgsfield.ai/docs/models/ideogram-4

Generate images with an optional image reference and selectable rendering speed.

<div />

Generate images with an optional image reference and selectable rendering speed.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Generate](/docs/models/ideogram-4/generate) | `POST /ideogram/v4.0` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Ideogram 4.0 — Generate API
Source: https://docs.higgsfield.ai/docs/models/ideogram-4/generate

Generate with Ideogram 4.0: request parameters, examples and response handling.

<div />

[← Ideogram 4.0](/docs/models/ideogram-4)

**Endpoint:** `POST https://api.higgsfield.ai/ideogram/v4.0`

**Endpoint ID:** `ideogram/v4.0`

<a href="https://console.higgsfield.ai/models/ideogram%2Fv4.0/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Ideogram 4.0 · Generate</span></span>
  <span>↗</span>
</a>

## Usage notes

* Omit image\_url for text-to-image; provide image\_url for remix/editing.
* image\_weight controls preservation of the input image and applies to editing requests only; values are integers from 1 to 100.
* The square 1:1 aspect ratio is applied by default, including when an input image is supplied.
* rendering\_speed values are case-sensitive: TURBO, DEFAULT, QUALITY. prompt must contain 2–2048 characters.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/ideogram/v4.0 \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
    "aspect_ratio": "1:1",
    "rendering_speed": "DEFAULT"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A ceramic vase on a wooden table beside a sunlit window, soft '
                 'natural shadows, editorial photograph.',
       'aspect_ratio': '1:1',
       'rendering_speed': 'DEFAULT'}
  )
  result = higgsfield_client.subscribe(
      "ideogram/v4.0",
      arguments=arguments,
  )
  print(result["images"][0]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("ideogram/v4.0", {
    input:
      {
        "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
        "aspect_ratio": "1:1",
        "rendering_speed": "DEFAULT"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.images?.[0]?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
  Minimum characters: `2`.
  Maximum characters: `2048`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"1:1"`, `"1:2"`, `"2:1"`, `"2:3"`, `"3:2"`, `"4:5"`, `"5:4"`, `"9:16"`, `"16:9"`, `"5:8"`, `"8:5"`, `"3:4"`, `"4:3"`, `"9:22"`, `"22:9"`, `"9:23"`, `"23:9"`, `"3:8"`, `"8:3"`, `"5:12"`, `"12:5"`, `"1:3"`, `"3:1"`.
</ParamField>

<ParamField type="integer">
  How strongly the output should preserve the input image.
  Minimum: `1`.
  Maximum: `100`.
</ParamField>

<ParamField type="string">
  Allowed values: `"TURBO"`, `"DEFAULT"`, `"QUALITY"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Ideogram 4.0 Playground",
    "required": [
      "prompt"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "maxLength": 2048,
        "minLength": 2,
        "description": "Write your prompt here"
      },
      "image_url": {
        "type": "string",
        "title": "Input image",
        "format": "uri"
      },
      "aspect_ratio": {
        "enum": [
          "1:1",
          "1:2",
          "2:1",
          "2:3",
          "3:2",
          "4:5",
          "5:4",
          "9:16",
          "16:9",
          "5:8",
          "8:5",
          "3:4",
          "4:3",
          "9:22",
          "22:9",
          "9:23",
          "23:9",
          "3:8",
          "8:3",
          "5:12",
          "12:5",
          "1:3",
          "3:1"
        ],
        "type": "string",
        "title": "Aspect ratio",
        "default": "1:1"
      },
      "image_weight": {
        "type": "integer",
        "title": "Image weight",
        "maximum": 100,
        "minimum": 1,
        "description": "How strongly the output should preserve the input image."
      },
      "rendering_speed": {
        "enum": [
          "TURBO",
          "DEFAULT",
          "QUALITY"
        ],
        "type": "string",
        "title": "Rendering speed",
        "default": "DEFAULT"
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "images": [
    {
      "url": "https://example.com/output.png"
    }
  ]
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Image Generation API
Source: https://docs.higgsfield.ai/docs/models/image-generation

Explore image models and their API request schemas.

<div />

Choose from **14 model families** and **17 catalog entries**. Each workflow has its own parameters and examples.

Soul ID is a character-training workflow.

## Models

<div>
  <a href="/docs/models/soul-standard">
    <span><span>Higgsfield</span><span>Image · 1 workflow</span></span>
    <span>SOUL</span>
    <span>Generate images with selectable styles and adjustable style strength.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/soul-2">
    <span><span>Higgsfield</span><span>Image · 1 workflow</span></span>
    <span>SOUL V2</span>
    <span>Generate portraits, fashion and editorial images with SOUL styles.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/soul-cinema">
    <span><span>Higgsfield</span><span>Image · 1 workflow</span></span>
    <span>SOUL Cinema</span>
    <span>Generate cinema-inspired still images from text prompts.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/soul-id">
    <span><span>Higgsfield</span><span>Image · 1 workflow</span></span>
    <span>Soul ID</span>
    <span>Train a personal character from reference images for use with compatible SOUL workflows.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/marketing-studio-image">
    <span><span>Higgsfield</span><span>Image · 3 workflows</span></span>
    <span>Marketing Studio Image</span>
    <span>Generate and edit campaign images, with optional preset-based prompt enhancement.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/ads-studio">
    <span><span>Higgsfield</span><span>Image · 1 workflow</span></span>
    <span>Ads Studio</span>
    <span>Turn a marketing brief and optional product references into 1–8 ad concepts rendered as images with GPT Image 2.5 Flare.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/grok-image-2">
    <span><span>xAI</span><span>Image · 1 workflow</span></span>
    <span>Grok Image 2.0</span>
    <span>Generate and edit images with up to ten image references.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/recraft-v4-1">
    <span><span>Recraft</span><span>Image · 1 workflow</span></span>
    <span>Recraft V4.1</span>
    <span>Generate 1K images with RGB palette and background controls.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/recraft-v4-1-pro">
    <span><span>Recraft</span><span>Image · 1 workflow</span></span>
    <span>Recraft V4.1 Pro</span>
    <span>Generate 2K images with RGB palette and background controls.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/recraft-v4-1-utility">
    <span><span>Recraft</span><span>Image · 1 workflow</span></span>
    <span>Recraft V4.1 Utility</span>
    <span>Generate 1K images with RGB palette and background controls.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/recraft-v4-1-utility-pro">
    <span><span>Recraft</span><span>Image · 1 workflow</span></span>
    <span>Recraft V4.1 Utility Pro</span>
    <span>Generate 2K images with RGB palette and background controls.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/qwen-image-3">
    <span><span>Alibaba</span><span>Image · 2 workflows</span></span>
    <span>Qwen Image 3</span>
    <span>Generate images or edit one to three reference images with optional prompt reasoning.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/ideogram-4">
    <span><span>Ideogram</span><span>Image · 1 workflow</span></span>
    <span>Ideogram 4.0</span>
    <span>Generate images with an optional image reference and selectable rendering speed.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/z-image-turbo">
    <span><span>Alibaba</span><span>Image · 1 workflow</span></span>
    <span>Z-Image Turbo</span>
    <span>Generate images at 1K or 2K with optional prompt enhancement.</span>
    <span>View API reference <span>→</span></span>
  </a>
</div>

## Quick start

1. Choose a model and the workflow that matches your inputs.
2. Submit its documented JSON body with your [API credentials](/docs/authentication).
3. Follow that workflow’s response instructions to retrieve the result.


# Kling 2.5 Turbo API
Source: https://docs.higgsfield.ai/docs/models/kling-2-5-turbo

Generate videos with Standard and Pro workflow variants.

<div />

Generate videos with Standard and Pro workflow variants.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Pro text to video](/docs/models/kling-2-5-turbo/pro-text-to-video) | `POST /kling-video/v2.5-turbo/pro/text-to-video` |
| [Pro image to video](/docs/models/kling-2-5-turbo/pro-image-to-video) | `POST /kling-video/v2.5-turbo/pro/image-to-video` |
| [Standard image to video](/docs/models/kling-2-5-turbo/standard-image-to-video) | `POST /kling-video/v2.5-turbo/standard/image-to-video` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Kling 2.5 Turbo — Pro image to video API
Source: https://docs.higgsfield.ai/docs/models/kling-2-5-turbo/pro-image-to-video

Pro image to video with Kling 2.5 Turbo: request parameters, examples and response handling.

<div />

[← Kling 2.5 Turbo](/docs/models/kling-2-5-turbo)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/v2.5-turbo/pro/image-to-video`

**Endpoint ID:** `kling-video/v2.5-turbo/pro/image-to-video`

<a href="https://console.higgsfield.ai/models/kling-video%2Fv2.5-turbo%2Fpro%2Fimage-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling 2.5 Turbo · Pro image to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* duration accepts 5 or 10 seconds; 5 is the default.
* This endpoint does not expose a sound or aspect\_ratio field.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/v2.5-turbo/pro/image-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic tracking shot along a sunlit coastal road.",
    "image_url": "https://example.com/first-frame.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic tracking shot along a sunlit coastal road.',
       'image_url': 'https://example.com/first-frame.jpg'}
  )
  result = higgsfield_client.subscribe(
      "kling-video/v2.5-turbo/pro/image-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/v2.5-turbo/pro/image-to-video", {
    input:
      {
        "prompt": "A slow cinematic tracking shot along a sunlit coastal road.",
        "image_url": "https://example.com/first-frame.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Allowed values: `5`, `10`.
</ParamField>

<ParamField type="number">
  Minimum: `0`.
  Maximum: `1`.
  Multiple of: `0.01`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Content or visual features to avoid.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling 2.5 Playground",
    "required": [
      "prompt",
      "image_url"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "enum": [
          5,
          10
        ],
        "type": "integer",
        "title": "Duration",
        "default": 5
      },
      "cfg_scale": {
        "type": "number",
        "title": "CFG Scale",
        "default": 0.5,
        "maximum": 1,
        "minimum": 0,
        "multipleOf": 0.01
      },
      "image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      },
      "negative_prompt": {
        "type": "string",
        "title": "Negative Prompt",
        "default": ""
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling 2.5 Turbo — Pro text to video API
Source: https://docs.higgsfield.ai/docs/models/kling-2-5-turbo/pro-text-to-video

Pro text to video with Kling 2.5 Turbo: request parameters, examples and response handling.

<div />

[← Kling 2.5 Turbo](/docs/models/kling-2-5-turbo)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/v2.5-turbo/pro/text-to-video`

**Endpoint ID:** `kling-video/v2.5-turbo/pro/text-to-video`

<a href="https://console.higgsfield.ai/models/kling-video%2Fv2.5-turbo%2Fpro%2Ftext-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling 2.5 Turbo · Pro text to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* duration accepts 5 or 10 seconds; 5 is the default.
* This endpoint does not expose a sound or aspect\_ratio field.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/v2.5-turbo/pro/text-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic tracking shot along a sunlit coastal road."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic tracking shot along a sunlit coastal road.'}
  )
  result = higgsfield_client.subscribe(
      "kling-video/v2.5-turbo/pro/text-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/v2.5-turbo/pro/text-to-video", {
    input:
      {
        "prompt": "A slow cinematic tracking shot along a sunlit coastal road."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Allowed values: `5`, `10`.
</ParamField>

<ParamField type="number">
  Minimum: `0`.
  Maximum: `1`.
  Multiple of: `0.01`.
</ParamField>

<ParamField type="string">
  Content or visual features to avoid.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling 2.5 Playground",
    "required": [
      "prompt"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "enum": [
          5,
          10
        ],
        "type": "integer",
        "title": "Duration",
        "default": 5
      },
      "cfg_scale": {
        "type": "number",
        "title": "CFG Scale",
        "default": 0.5,
        "maximum": 1,
        "minimum": 0,
        "multipleOf": 0.01
      },
      "negative_prompt": {
        "type": "string",
        "title": "Negative Prompt",
        "default": ""
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling 2.5 Turbo — Standard image to video API
Source: https://docs.higgsfield.ai/docs/models/kling-2-5-turbo/standard-image-to-video

Standard image to video with Kling 2.5 Turbo: request parameters, examples and response handling.

<div />

[← Kling 2.5 Turbo](/docs/models/kling-2-5-turbo)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/v2.5-turbo/standard/image-to-video`

**Endpoint ID:** `kling-video/v2.5-turbo/standard/image-to-video`

<a href="https://console.higgsfield.ai/models/kling-video%2Fv2.5-turbo%2Fstandard%2Fimage-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling 2.5 Turbo · Standard image to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* duration accepts 5 or 10 seconds; 5 is the default.
* This endpoint does not expose a sound or aspect\_ratio field.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/v2.5-turbo/standard/image-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic tracking shot along a sunlit coastal road.",
    "image_url": "https://example.com/first-frame.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic tracking shot along a sunlit coastal road.',
       'image_url': 'https://example.com/first-frame.jpg'}
  )
  result = higgsfield_client.subscribe(
      "kling-video/v2.5-turbo/standard/image-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/v2.5-turbo/standard/image-to-video", {
    input:
      {
        "prompt": "A slow cinematic tracking shot along a sunlit coastal road.",
        "image_url": "https://example.com/first-frame.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Allowed values: `5`, `10`.
</ParamField>

<ParamField type="number">
  Minimum: `0`.
  Maximum: `1`.
  Multiple of: `0.01`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Content or visual features to avoid.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling 2.5 Playground",
    "required": [
      "prompt",
      "image_url"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "enum": [
          5,
          10
        ],
        "type": "integer",
        "title": "Duration",
        "default": 5
      },
      "cfg_scale": {
        "type": "number",
        "title": "CFG Scale",
        "default": 0.5,
        "maximum": 1,
        "minimum": 0,
        "multipleOf": 0.01
      },
      "image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      },
      "negative_prompt": {
        "type": "string",
        "title": "Negative Prompt",
        "default": ""
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling 2.6 API
Source: https://docs.higgsfield.ai/docs/models/kling-2-6

Generate videos from text or a starting image, with optional sound.

<div />

Generate videos from text or a starting image, with optional sound.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Pro text to video](/docs/models/kling-2-6/pro-text-to-video) | `POST /kling-video/v2.6/pro/text-to-video` |
| [Pro image to video](/docs/models/kling-2-6/pro-image-to-video) | `POST /kling-video/v2.6/pro/image-to-video` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Kling 2.6 Motion Control API
Source: https://docs.higgsfield.ai/docs/models/kling-2-6-motion-control

Apply motion from a source video to an image with Standard or Pro processing.

<div />

Apply motion from a source video to an image with Standard or Pro processing.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Pro](/docs/models/kling-2-6-motion-control/pro) | `POST /kling-video/motion-control/pro` |
| [Standard](/docs/models/kling-2-6-motion-control/std) | `POST /kling-video/motion-control/std` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Kling 2.6 Motion Control — Pro API
Source: https://docs.higgsfield.ai/docs/models/kling-2-6-motion-control/pro

Pro with Kling 2.6 Motion Control: request parameters, examples and response handling.

<div />

[← Kling 2.6 Motion Control](/docs/models/kling-2-6-motion-control)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/motion-control/pro`

**Endpoint ID:** `kling-video/motion-control/pro`

<a href="https://console.higgsfield.ai/models/kling-video%2Fmotion-control%2Fpro/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling 2.6 Motion Control · Pro</span></span>
  <span>↗</span>
</a>

## Usage notes

* Use a motion-reference video from 3 to 30 seconds long. The output duration follows the source video; do not send a separate duration field.
* Use a character image up to 10 MB with each dimension between 300 and 65,536 pixels. Images outside the 0.4–2.5 width-to-height range are adjusted before generation.
* Videos larger than 100 MB are compressed before generation.
* Set character\_orientation to image or video. keep\_original\_sound uses the strings yes and no, with yes as the default.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/motion-control/pro \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "image_url": "https://example.com/character.jpg",
    "video_url": "https://example.com/motion-reference.mp4"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'image_url': 'https://example.com/character.jpg',
       'video_url': 'https://example.com/motion-reference.mp4'}
  )
  result = higgsfield_client.subscribe(
      "kling-video/motion-control/pro",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/motion-control/pro", {
    input:
      {
        "image_url": "https://example.com/character.jpg",
        "video_url": "https://example.com/motion-reference.mp4"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Public URL of the source video.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Allowed values: `"yes"`, `"no"`.
</ParamField>

<ParamField type="string">
  Generate the orientation of the characters in the video, which can be selected to match the image or the video
  Allowed values: `"image"`, `"video"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling Motion Control Playground",
    "required": [
      "image_url",
      "video_url"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "default": "",
        "description": "Write your prompt here"
      },
      "image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      },
      "video_url": {
        "type": "string",
        "title": "Video URL",
        "format": "uri"
      },
      "keep_original_sound": {
        "enum": [
          "yes",
          "no"
        ],
        "type": "string",
        "title": "Keep original sound",
        "default": "yes"
      },
      "character_orientation": {
        "enum": [
          "image",
          "video"
        ],
        "type": "string",
        "title": "Character orientation",
        "default": "video",
        "description": "Generate the orientation of the characters in the video, which can be selected to match the image or the video"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling 2.6 Motion Control — Standard API
Source: https://docs.higgsfield.ai/docs/models/kling-2-6-motion-control/std

Standard with Kling 2.6 Motion Control: request parameters, examples and response handling.

<div />

[← Kling 2.6 Motion Control](/docs/models/kling-2-6-motion-control)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/motion-control/std`

**Endpoint ID:** `kling-video/motion-control/std`

<a href="https://console.higgsfield.ai/models/kling-video%2Fmotion-control%2Fstd/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling 2.6 Motion Control · Standard</span></span>
  <span>↗</span>
</a>

## Usage notes

* Use a motion-reference video from 3 to 30 seconds long. The output duration follows the source video; do not send a separate duration field.
* Use a character image up to 10 MB with each dimension between 300 and 65,536 pixels. Images outside the 0.4–2.5 width-to-height range are adjusted before generation.
* Videos larger than 100 MB are compressed before generation.
* Set character\_orientation to image or video. keep\_original\_sound uses the strings yes and no, with yes as the default.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/motion-control/std \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "image_url": "https://example.com/character.jpg",
    "video_url": "https://example.com/motion-reference.mp4"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'image_url': 'https://example.com/character.jpg',
       'video_url': 'https://example.com/motion-reference.mp4'}
  )
  result = higgsfield_client.subscribe(
      "kling-video/motion-control/std",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/motion-control/std", {
    input:
      {
        "image_url": "https://example.com/character.jpg",
        "video_url": "https://example.com/motion-reference.mp4"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Public URL of the source video.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Allowed values: `"yes"`, `"no"`.
</ParamField>

<ParamField type="string">
  Generate the orientation of the characters in the video, which can be selected to match the image or the video
  Allowed values: `"image"`, `"video"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling Motion Control Playground",
    "required": [
      "image_url",
      "video_url"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "default": "",
        "description": "Write your prompt here"
      },
      "image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      },
      "video_url": {
        "type": "string",
        "title": "Video URL",
        "format": "uri"
      },
      "keep_original_sound": {
        "enum": [
          "yes",
          "no"
        ],
        "type": "string",
        "title": "Keep original sound",
        "default": "yes"
      },
      "character_orientation": {
        "enum": [
          "image",
          "video"
        ],
        "type": "string",
        "title": "Character orientation",
        "default": "video",
        "description": "Generate the orientation of the characters in the video, which can be selected to match the image or the video"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling 2.6 — Pro image to video API
Source: https://docs.higgsfield.ai/docs/models/kling-2-6/pro-image-to-video

Pro image to video with Kling 2.6: request parameters, examples and response handling.

<div />

[← Kling 2.6](/docs/models/kling-2-6)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/v2.6/pro/image-to-video`

**Endpoint ID:** `kling-video/v2.6/pro/image-to-video`

<a href="https://console.higgsfield.ai/models/kling-video%2Fv2.6%2Fpro%2Fimage-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling 2.6 · Pro image to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* duration accepts 5 or 10 seconds; 5 is the default.
* Native audio uses sound: on or off and defaults to on.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/v2.6/pro/image-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic tracking shot along a sunlit coastal road.",
    "image_url": "https://example.com/first-frame.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic tracking shot along a sunlit coastal road.',
       'image_url': 'https://example.com/first-frame.jpg'}
  )
  result = higgsfield_client.subscribe(
      "kling-video/v2.6/pro/image-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/v2.6/pro/image-to-video", {
    input:
      {
        "prompt": "A slow cinematic tracking shot along a sunlit coastal road.",
        "image_url": "https://example.com/first-frame.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Enable sound for the output video.
  Allowed values: `"on"`, `"off"`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Allowed values: `5`, `10`.
</ParamField>

<ParamField type="number">
  Minimum: `0`.
  Maximum: `1`.
  Multiple of: `0.01`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`, `"1:1"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling 2.6 Playground",
    "required": [
      "prompt",
      "image_url"
    ],
    "properties": {
      "sound": {
        "enum": [
          "on",
          "off"
        ],
        "type": "string",
        "title": "Generate sound",
        "default": "on"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "enum": [
          5,
          10
        ],
        "type": "integer",
        "title": "Duration",
        "default": 5
      },
      "cfg_scale": {
        "type": "number",
        "title": "CFG Scale",
        "default": 0.5,
        "maximum": 1,
        "minimum": 0,
        "multipleOf": 0.01
      },
      "image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "type": "string",
        "title": "Aspect ratio"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling 2.6 — Pro text to video API
Source: https://docs.higgsfield.ai/docs/models/kling-2-6/pro-text-to-video

Pro text to video with Kling 2.6: request parameters, examples and response handling.

<div />

[← Kling 2.6](/docs/models/kling-2-6)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/v2.6/pro/text-to-video`

**Endpoint ID:** `kling-video/v2.6/pro/text-to-video`

<a href="https://console.higgsfield.ai/models/kling-video%2Fv2.6%2Fpro%2Ftext-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling 2.6 · Pro text to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* duration accepts 5 or 10 seconds; 5 is the default.
* Native audio uses sound: on or off and defaults to on.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/v2.6/pro/text-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic tracking shot along a sunlit coastal road."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic tracking shot along a sunlit coastal road.'}
  )
  result = higgsfield_client.subscribe(
      "kling-video/v2.6/pro/text-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/v2.6/pro/text-to-video", {
    input:
      {
        "prompt": "A slow cinematic tracking shot along a sunlit coastal road."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Enable sound for the output video.
  Allowed values: `"on"`, `"off"`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Allowed values: `5`, `10`.
</ParamField>

<ParamField type="number">
  Minimum: `0`.
  Maximum: `1`.
  Multiple of: `0.01`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`, `"1:1"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling 2.6 Playground",
    "required": [
      "prompt"
    ],
    "properties": {
      "sound": {
        "enum": [
          "on",
          "off"
        ],
        "type": "string",
        "title": "Generate sound",
        "default": "on"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "enum": [
          5,
          10
        ],
        "type": "integer",
        "title": "Duration",
        "default": 5
      },
      "cfg_scale": {
        "type": "number",
        "title": "CFG Scale",
        "default": 0.5,
        "maximum": 1,
        "minimum": 0,
        "multipleOf": 0.01
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "type": "string",
        "title": "Aspect ratio",
        "default": "16:9"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling 3.0 API
Source: https://docs.higgsfield.ai/docs/models/kling-3

Generate videos with Standard, Pro, 4K and Turbo workflow variants.

<div />

Generate videos with Standard, Pro, 4K and Turbo workflow variants.

## Workflows

| Workflow | Endpoint |
| - | - |
| [4K · Text to video](/docs/models/kling-3/4k-text-to-video) | `POST /kling-video/v3.0/4k/text-to-video` |
| [Pro · Text to video](/docs/models/kling-3/pro-text-to-video) | `POST /kling-video/v3.0/pro/text-to-video` |
| [Standard · Text to video](/docs/models/kling-3/standard-text-to-video) | `POST /kling-video/v3.0/std/text-to-video` |
| [Turbo · Text to video](/docs/models/kling-3/turbo-text-to-video) | `POST /kling-video/v3.0-turbo/text-to-video` |
| [4K · Image to video](/docs/models/kling-3/4k-image-to-video) | `POST /kling-video/v3.0/4k/image-to-video` |
| [Pro · Image to video](/docs/models/kling-3/pro-image-to-video) | `POST /kling-video/v3.0/pro/image-to-video` |
| [Standard · Image to video](/docs/models/kling-3/standard-image-to-video) | `POST /kling-video/v3.0/std/image-to-video` |
| [Turbo · Image to video](/docs/models/kling-3/turbo-image-to-video) | `POST /kling-video/v3.0-turbo/image-to-video` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Kling 3.0 Motion Control API
Source: https://docs.higgsfield.ai/docs/models/kling-3-motion-control

Apply motion from a source video to an image with Standard or Pro processing.

<div />

Apply motion from a source video to an image with Standard or Pro processing.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Pro](/docs/models/kling-3-motion-control/pro) | `POST /kling-video/v3/motion-control/pro` |
| [Standard](/docs/models/kling-3-motion-control/std) | `POST /kling-video/v3/motion-control/std` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Kling 3.0 Motion Control — Pro API
Source: https://docs.higgsfield.ai/docs/models/kling-3-motion-control/pro

Pro with Kling 3.0 Motion Control: request parameters, examples and response handling.

<div />

[← Kling 3.0 Motion Control](/docs/models/kling-3-motion-control)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/v3/motion-control/pro`

**Endpoint ID:** `kling-video/v3/motion-control/pro`

<a href="https://console.higgsfield.ai/models/kling-video%2Fv3%2Fmotion-control%2Fpro/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling 3.0 Motion Control · Pro</span></span>
  <span>↗</span>
</a>

## Usage notes

* Use a motion-reference video from 3 to 30 seconds long. The output duration follows the source video; do not send a separate duration field.
* Use a character image up to 10 MB with each dimension between 300 and 65,536 pixels. Images outside the 0.4–2.5 width-to-height range are adjusted before generation.
* Videos larger than 100 MB are compressed before generation.
* Set character\_orientation to image or video. keep\_original\_sound uses the strings yes and no, with yes as the default.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/v3/motion-control/pro \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "image_url": "https://example.com/character.jpg",
    "video_url": "https://example.com/motion-reference.mp4"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'image_url': 'https://example.com/character.jpg',
       'video_url': 'https://example.com/motion-reference.mp4'}
  )
  result = higgsfield_client.subscribe(
      "kling-video/v3/motion-control/pro",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/v3/motion-control/pro", {
    input:
      {
        "image_url": "https://example.com/character.jpg",
        "video_url": "https://example.com/motion-reference.mp4"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Public URL of the source video.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Allowed values: `"yes"`, `"no"`.
</ParamField>

<ParamField type="string">
  Generate the orientation of the characters in the video, which can be selected to match the image or the video
  Allowed values: `"image"`, `"video"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling V3 Motion Control Playground",
    "required": [
      "image_url",
      "video_url"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "default": "",
        "description": "Write your prompt here"
      },
      "image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      },
      "video_url": {
        "type": "string",
        "title": "Video URL",
        "format": "uri"
      },
      "keep_original_sound": {
        "enum": [
          "yes",
          "no"
        ],
        "type": "string",
        "title": "Keep original sound",
        "default": "yes"
      },
      "character_orientation": {
        "enum": [
          "image",
          "video"
        ],
        "type": "string",
        "title": "Character orientation",
        "default": "video",
        "description": "Generate the orientation of the characters in the video, which can be selected to match the image or the video"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling 3.0 Motion Control — Standard API
Source: https://docs.higgsfield.ai/docs/models/kling-3-motion-control/std

Standard with Kling 3.0 Motion Control: request parameters, examples and response handling.

<div />

[← Kling 3.0 Motion Control](/docs/models/kling-3-motion-control)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/v3/motion-control/std`

**Endpoint ID:** `kling-video/v3/motion-control/std`

<a href="https://console.higgsfield.ai/models/kling-video%2Fv3%2Fmotion-control%2Fstd/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling 3.0 Motion Control · Standard</span></span>
  <span>↗</span>
</a>

## Usage notes

* Use a motion-reference video from 3 to 30 seconds long. The output duration follows the source video; do not send a separate duration field.
* Use a character image up to 10 MB with each dimension between 300 and 65,536 pixels. Images outside the 0.4–2.5 width-to-height range are adjusted before generation.
* Videos larger than 100 MB are compressed before generation.
* Set character\_orientation to image or video. keep\_original\_sound uses the strings yes and no, with yes as the default.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/v3/motion-control/std \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "image_url": "https://example.com/character.jpg",
    "video_url": "https://example.com/motion-reference.mp4"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'image_url': 'https://example.com/character.jpg',
       'video_url': 'https://example.com/motion-reference.mp4'}
  )
  result = higgsfield_client.subscribe(
      "kling-video/v3/motion-control/std",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/v3/motion-control/std", {
    input:
      {
        "image_url": "https://example.com/character.jpg",
        "video_url": "https://example.com/motion-reference.mp4"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Public URL of the source video.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Allowed values: `"yes"`, `"no"`.
</ParamField>

<ParamField type="string">
  Generate the orientation of the characters in the video, which can be selected to match the image or the video
  Allowed values: `"image"`, `"video"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling V3 Motion Control Playground",
    "required": [
      "image_url",
      "video_url"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "default": "",
        "description": "Write your prompt here"
      },
      "image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      },
      "video_url": {
        "type": "string",
        "title": "Video URL",
        "format": "uri"
      },
      "keep_original_sound": {
        "enum": [
          "yes",
          "no"
        ],
        "type": "string",
        "title": "Keep original sound",
        "default": "yes"
      },
      "character_orientation": {
        "enum": [
          "image",
          "video"
        ],
        "type": "string",
        "title": "Character orientation",
        "default": "video",
        "description": "Generate the orientation of the characters in the video, which can be selected to match the image or the video"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling 3.0 — 4K · Image to video API
Source: https://docs.higgsfield.ai/docs/models/kling-3/4k-image-to-video

4K · Image to video with Kling 3.0: request parameters, examples and response handling.

<div />

[← Kling 3.0](/docs/models/kling-3)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/v3.0/4k/image-to-video`

**Endpoint ID:** `kling-video/v3.0/4k/image-to-video`

<a href="https://console.higgsfield.ai/models/kling-video%2Fv3.0%2F4k%2Fimage-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling 3.0 · 4K · Image to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* image\_url is the first frame; last\_image\_url optionally sets the final frame.
* Always include a non-empty top-level prompt, including when using multi\_prompt. Keep it within 2,500 characters; longer prompts are truncated.
* For custom shots, set multi\_shots to true and provide 1–6 multi\_prompt objects. Each object needs prompt (at most 512 characters) and duration (a positive integer from 1 to 15 seconds).
* Custom-shot durations are summed for generation and billing; the top-level duration does not override that sum. With multi\_shots enabled and no custom shots, the top-level duration is retained.
* Native audio uses sound: on or off and defaults to on.
* elements contains Kling element IDs as decimal strings. Each ID must belong to the account making the request; arbitrary provider IDs are rejected.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/v3.0/4k/image-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic tracking shot along a sunlit coastal road.",
    "image_url": "https://example.com/first-frame.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic tracking shot along a sunlit coastal road.',
       'image_url': 'https://example.com/first-frame.jpg'}
  )
  result = higgsfield_client.subscribe(
      "kling-video/v3.0/4k/image-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/v3.0/4k/image-to-video", {
    input:
      {
        "prompt": "A slow cinematic tracking shot along a sunlit coastal road.",
        "image_url": "https://example.com/first-frame.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Enable sound for the output video.
  Allowed values: `"on"`, `"off"`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `3`.
  Maximum: `15`.
</ParamField>

<ParamField type="array">
  Each item: string.
</ParamField>

<ParamField type="number">
  Minimum: `0`.
  Maximum: `1`.
  Multiple of: `0.01`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="boolean">
  See the complete JSON schema below.
</ParamField>

<ParamField type="array">
  Minimum items: `0`.
  Maximum items: `6`.

  <Expandable title="Nested fields">
    <ParamField type="string">
      Text instructions for the generation or edit.
      Maximum characters: `512`.
    </ParamField>

    <ParamField type="integer">
      Requested output duration in seconds.
      Minimum: `1`.
      Maximum: `15`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Format: `uri`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling 3.0 Playground",
    "required": [
      "image_url"
    ],
    "properties": {
      "sound": {
        "enum": [
          "on",
          "off"
        ],
        "type": "string",
        "title": "Generate sound",
        "default": "on"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 3
      },
      "elements": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "cfg_scale": {
        "type": "number",
        "title": "CFG Scale",
        "default": 0.5,
        "maximum": 1,
        "minimum": 0,
        "multipleOf": 0.01
      },
      "image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      },
      "multi_shots": {
        "type": "boolean",
        "default": false
      },
      "multi_prompt": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "prompt": {
              "type": "string",
              "maxLength": 512
            },
            "duration": {
              "type": "integer",
              "maximum": 15,
              "minimum": 1
            }
          }
        },
        "maxItems": 6,
        "minItems": 0
      },
      "last_image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling 3.0 — 4K · Text to video API
Source: https://docs.higgsfield.ai/docs/models/kling-3/4k-text-to-video

4K · Text to video with Kling 3.0: request parameters, examples and response handling.

<div />

[← Kling 3.0](/docs/models/kling-3)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/v3.0/4k/text-to-video`

**Endpoint ID:** `kling-video/v3.0/4k/text-to-video`

<a href="https://console.higgsfield.ai/models/kling-video%2Fv3.0%2F4k%2Ftext-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling 3.0 · 4K · Text to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Always include a non-empty top-level prompt, including when using multi\_prompt. Keep it within 2,500 characters; longer prompts are truncated.
* For custom shots, set multi\_shots to true and provide 1–6 multi\_prompt objects. Each object needs prompt (at most 512 characters) and duration (a positive integer from 1 to 15 seconds).
* Custom-shot durations are summed for generation and billing; the top-level duration does not override that sum. With multi\_shots enabled and no custom shots, the top-level duration is retained.
* Native audio uses sound: on or off and defaults to on.
* elements contains Kling element IDs as decimal strings. Each ID must belong to the account making the request; arbitrary provider IDs are rejected.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/v3.0/4k/text-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic tracking shot along a sunlit coastal road."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic tracking shot along a sunlit coastal road.'}
  )
  result = higgsfield_client.subscribe(
      "kling-video/v3.0/4k/text-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/v3.0/4k/text-to-video", {
    input:
      {
        "prompt": "A slow cinematic tracking shot along a sunlit coastal road."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Enable sound for the output video.
  Allowed values: `"on"`, `"off"`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `3`.
  Maximum: `15`.
</ParamField>

<ParamField type="array">
  Each item: string.
</ParamField>

<ParamField type="number">
  Minimum: `0`.
  Maximum: `1`.
  Multiple of: `0.01`.
</ParamField>

<ParamField type="boolean">
  See the complete JSON schema below.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`, `"1:1"`.
</ParamField>

<ParamField type="array">
  Minimum items: `0`.
  Maximum items: `6`.

  <Expandable title="Nested fields">
    <ParamField type="string">
      Text instructions for the generation or edit.
      Maximum characters: `512`.
    </ParamField>

    <ParamField type="integer">
      Requested output duration in seconds.
      Minimum: `1`.
      Maximum: `15`.
    </ParamField>
  </Expandable>
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling 3.0 Playground",
    "properties": {
      "sound": {
        "enum": [
          "on",
          "off"
        ],
        "type": "string",
        "title": "Generate sound",
        "default": "on"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 3
      },
      "elements": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "cfg_scale": {
        "type": "number",
        "title": "CFG Scale",
        "default": 0.5,
        "maximum": 1,
        "minimum": 0,
        "multipleOf": 0.01
      },
      "multi_shots": {
        "type": "boolean",
        "default": false
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "type": "string",
        "title": "Aspect ratio",
        "default": "16:9"
      },
      "multi_prompt": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "prompt": {
              "type": "string",
              "maxLength": 512
            },
            "duration": {
              "type": "integer",
              "maximum": 15,
              "minimum": 1
            }
          }
        },
        "maxItems": 6,
        "minItems": 0
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling 3.0 — Pro · Image to video API
Source: https://docs.higgsfield.ai/docs/models/kling-3/pro-image-to-video

Pro · Image to video with Kling 3.0: request parameters, examples and response handling.

<div />

[← Kling 3.0](/docs/models/kling-3)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/v3.0/pro/image-to-video`

**Endpoint ID:** `kling-video/v3.0/pro/image-to-video`

<a href="https://console.higgsfield.ai/models/kling-video%2Fv3.0%2Fpro%2Fimage-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling 3.0 · Pro · Image to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* image\_url is the first frame; last\_image\_url optionally sets the final frame.
* Always include a non-empty top-level prompt, including when using multi\_prompt. Keep it within 2,500 characters; longer prompts are truncated.
* For custom shots, set multi\_shots to true and provide 1–6 multi\_prompt objects. Each object needs prompt (at most 512 characters) and duration (a positive integer from 1 to 15 seconds).
* Custom-shot durations are summed for generation and billing; the top-level duration does not override that sum. With multi\_shots enabled and no custom shots, the top-level duration is retained.
* Native audio uses sound: on or off and defaults to on.
* elements contains Kling element IDs as decimal strings. Each ID must belong to the account making the request; arbitrary provider IDs are rejected.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/v3.0/pro/image-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic tracking shot along a sunlit coastal road.",
    "image_url": "https://example.com/first-frame.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic tracking shot along a sunlit coastal road.',
       'image_url': 'https://example.com/first-frame.jpg'}
  )
  result = higgsfield_client.subscribe(
      "kling-video/v3.0/pro/image-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/v3.0/pro/image-to-video", {
    input:
      {
        "prompt": "A slow cinematic tracking shot along a sunlit coastal road.",
        "image_url": "https://example.com/first-frame.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Enable sound for the output video.
  Allowed values: `"on"`, `"off"`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `3`.
  Maximum: `15`.
</ParamField>

<ParamField type="array">
  Each item: string.
</ParamField>

<ParamField type="number">
  Minimum: `0`.
  Maximum: `1`.
  Multiple of: `0.01`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="boolean">
  See the complete JSON schema below.
</ParamField>

<ParamField type="array">
  Minimum items: `0`.
  Maximum items: `6`.

  <Expandable title="Nested fields">
    <ParamField type="string">
      Text instructions for the generation or edit.
      Maximum characters: `512`.
    </ParamField>

    <ParamField type="integer">
      Requested output duration in seconds.
      Minimum: `1`.
      Maximum: `15`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Format: `uri`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling 3.0 Playground",
    "required": [
      "image_url"
    ],
    "properties": {
      "sound": {
        "enum": [
          "on",
          "off"
        ],
        "type": "string",
        "title": "Generate sound",
        "default": "on"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 3
      },
      "elements": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "cfg_scale": {
        "type": "number",
        "title": "CFG Scale",
        "default": 0.5,
        "maximum": 1,
        "minimum": 0,
        "multipleOf": 0.01
      },
      "image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      },
      "multi_shots": {
        "type": "boolean",
        "default": false
      },
      "multi_prompt": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "prompt": {
              "type": "string",
              "maxLength": 512
            },
            "duration": {
              "type": "integer",
              "maximum": 15,
              "minimum": 1
            }
          }
        },
        "maxItems": 6,
        "minItems": 0
      },
      "last_image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling 3.0 — Pro · Text to video API
Source: https://docs.higgsfield.ai/docs/models/kling-3/pro-text-to-video

Pro · Text to video with Kling 3.0: request parameters, examples and response handling.

<div />

[← Kling 3.0](/docs/models/kling-3)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/v3.0/pro/text-to-video`

**Endpoint ID:** `kling-video/v3.0/pro/text-to-video`

<a href="https://console.higgsfield.ai/models/kling-video%2Fv3.0%2Fpro%2Ftext-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling 3.0 · Pro · Text to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Always include a non-empty top-level prompt, including when using multi\_prompt. Keep it within 2,500 characters; longer prompts are truncated.
* For custom shots, set multi\_shots to true and provide 1–6 multi\_prompt objects. Each object needs prompt (at most 512 characters) and duration (a positive integer from 1 to 15 seconds).
* Custom-shot durations are summed for generation and billing; the top-level duration does not override that sum. With multi\_shots enabled and no custom shots, the top-level duration is retained.
* Native audio uses sound: on or off and defaults to on.
* elements contains Kling element IDs as decimal strings. Each ID must belong to the account making the request; arbitrary provider IDs are rejected.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/v3.0/pro/text-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic tracking shot along a sunlit coastal road."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic tracking shot along a sunlit coastal road.'}
  )
  result = higgsfield_client.subscribe(
      "kling-video/v3.0/pro/text-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/v3.0/pro/text-to-video", {
    input:
      {
        "prompt": "A slow cinematic tracking shot along a sunlit coastal road."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Enable sound for the output video.
  Allowed values: `"on"`, `"off"`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `3`.
  Maximum: `15`.
</ParamField>

<ParamField type="array">
  Each item: string.
</ParamField>

<ParamField type="number">
  Minimum: `0`.
  Maximum: `1`.
  Multiple of: `0.01`.
</ParamField>

<ParamField type="boolean">
  See the complete JSON schema below.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`, `"1:1"`.
</ParamField>

<ParamField type="array">
  Minimum items: `0`.
  Maximum items: `6`.

  <Expandable title="Nested fields">
    <ParamField type="string">
      Text instructions for the generation or edit.
      Maximum characters: `512`.
    </ParamField>

    <ParamField type="integer">
      Requested output duration in seconds.
      Minimum: `1`.
      Maximum: `15`.
    </ParamField>
  </Expandable>
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling 3.0 Playground",
    "properties": {
      "sound": {
        "enum": [
          "on",
          "off"
        ],
        "type": "string",
        "title": "Generate sound",
        "default": "on"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 3
      },
      "elements": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "cfg_scale": {
        "type": "number",
        "title": "CFG Scale",
        "default": 0.5,
        "maximum": 1,
        "minimum": 0,
        "multipleOf": 0.01
      },
      "multi_shots": {
        "type": "boolean",
        "default": false
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "type": "string",
        "title": "Aspect ratio",
        "default": "16:9"
      },
      "multi_prompt": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "prompt": {
              "type": "string",
              "maxLength": 512
            },
            "duration": {
              "type": "integer",
              "maximum": 15,
              "minimum": 1
            }
          }
        },
        "maxItems": 6,
        "minItems": 0
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling 3.0 — Standard · Image to video API
Source: https://docs.higgsfield.ai/docs/models/kling-3/standard-image-to-video

Standard · Image to video with Kling 3.0: request parameters, examples and response handling.

<div />

[← Kling 3.0](/docs/models/kling-3)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/v3.0/std/image-to-video`

**Endpoint ID:** `kling-video/v3.0/std/image-to-video`

<a href="https://console.higgsfield.ai/models/kling-video%2Fv3.0%2Fstd%2Fimage-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling 3.0 · Standard · Image to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* image\_url is the first frame; last\_image\_url optionally sets the final frame.
* Always include a non-empty top-level prompt, including when using multi\_prompt. Keep it within 2,500 characters; longer prompts are truncated.
* For custom shots, set multi\_shots to true and provide 1–6 multi\_prompt objects. Each object needs prompt (at most 512 characters) and duration (a positive integer from 1 to 15 seconds).
* Custom-shot durations are summed for generation and billing; the top-level duration does not override that sum. With multi\_shots enabled and no custom shots, the top-level duration is retained.
* Native audio uses sound: on or off and defaults to on.
* elements contains Kling element IDs as decimal strings. Each ID must belong to the account making the request; arbitrary provider IDs are rejected.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/v3.0/std/image-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic tracking shot along a sunlit coastal road.",
    "image_url": "https://example.com/first-frame.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic tracking shot along a sunlit coastal road.',
       'image_url': 'https://example.com/first-frame.jpg'}
  )
  result = higgsfield_client.subscribe(
      "kling-video/v3.0/std/image-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/v3.0/std/image-to-video", {
    input:
      {
        "prompt": "A slow cinematic tracking shot along a sunlit coastal road.",
        "image_url": "https://example.com/first-frame.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Enable sound for the output video.
  Allowed values: `"on"`, `"off"`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `3`.
  Maximum: `15`.
</ParamField>

<ParamField type="array">
  Each item: string.
</ParamField>

<ParamField type="number">
  Minimum: `0`.
  Maximum: `1`.
  Multiple of: `0.01`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="boolean">
  See the complete JSON schema below.
</ParamField>

<ParamField type="array">
  Minimum items: `1`.
  Maximum items: `6`.

  <Expandable title="Nested fields">
    <ParamField type="string">
      Text instructions for the generation or edit.
      Maximum characters: `512`.
    </ParamField>

    <ParamField type="integer">
      Requested output duration in seconds.
      Minimum: `1`.
      Maximum: `15`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Format: `uri`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling 3.0 Playground",
    "required": [
      "image_url"
    ],
    "properties": {
      "sound": {
        "enum": [
          "on",
          "off"
        ],
        "type": "string",
        "title": "Generate sound",
        "default": "on"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 3
      },
      "elements": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "cfg_scale": {
        "type": "number",
        "title": "CFG Scale",
        "default": 0.5,
        "maximum": 1,
        "minimum": 0,
        "multipleOf": 0.01
      },
      "image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      },
      "multi_shots": {
        "type": "boolean",
        "default": false
      },
      "multi_prompt": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "prompt": {
              "type": "string",
              "maxLength": 512
            },
            "duration": {
              "type": "integer",
              "maximum": 15,
              "minimum": 1
            }
          }
        },
        "maxItems": 6,
        "minItems": 1
      },
      "last_image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling 3.0 — Standard · Text to video API
Source: https://docs.higgsfield.ai/docs/models/kling-3/standard-text-to-video

Standard · Text to video with Kling 3.0: request parameters, examples and response handling.

<div />

[← Kling 3.0](/docs/models/kling-3)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/v3.0/std/text-to-video`

**Endpoint ID:** `kling-video/v3.0/std/text-to-video`

<a href="https://console.higgsfield.ai/models/kling-video%2Fv3.0%2Fstd%2Ftext-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling 3.0 · Standard · Text to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Always include a non-empty top-level prompt, including when using multi\_prompt. Keep it within 2,500 characters; longer prompts are truncated.
* For custom shots, set multi\_shots to true and provide 1–6 multi\_prompt objects. Each object needs prompt (at most 512 characters) and duration (a positive integer from 1 to 15 seconds).
* Custom-shot durations are summed for generation and billing; the top-level duration does not override that sum. With multi\_shots enabled and no custom shots, the top-level duration is retained.
* Native audio uses sound: on or off and defaults to on.
* elements contains Kling element IDs as decimal strings. Each ID must belong to the account making the request; arbitrary provider IDs are rejected.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/v3.0/std/text-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic tracking shot along a sunlit coastal road."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic tracking shot along a sunlit coastal road.'}
  )
  result = higgsfield_client.subscribe(
      "kling-video/v3.0/std/text-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/v3.0/std/text-to-video", {
    input:
      {
        "prompt": "A slow cinematic tracking shot along a sunlit coastal road."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Enable sound for the output video.
  Allowed values: `"on"`, `"off"`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `3`.
  Maximum: `15`.
</ParamField>

<ParamField type="array">
  Each item: string.
</ParamField>

<ParamField type="number">
  Minimum: `0`.
  Maximum: `1`.
  Multiple of: `0.01`.
</ParamField>

<ParamField type="boolean">
  See the complete JSON schema below.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`, `"1:1"`.
</ParamField>

<ParamField type="array">
  Minimum items: `1`.
  Maximum items: `6`.

  <Expandable title="Nested fields">
    <ParamField type="string">
      Text instructions for the generation or edit.
      Maximum characters: `512`.
    </ParamField>

    <ParamField type="integer">
      Requested output duration in seconds.
      Minimum: `1`.
      Maximum: `15`.
    </ParamField>
  </Expandable>
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling 3.0 Playground",
    "properties": {
      "sound": {
        "enum": [
          "on",
          "off"
        ],
        "type": "string",
        "title": "Generate sound",
        "default": "on"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 3
      },
      "elements": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "cfg_scale": {
        "type": "number",
        "title": "CFG Scale",
        "default": 0.5,
        "maximum": 1,
        "minimum": 0,
        "multipleOf": 0.01
      },
      "multi_shots": {
        "type": "boolean",
        "default": false
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "type": "string",
        "title": "Aspect ratio",
        "default": "16:9"
      },
      "multi_prompt": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "prompt": {
              "type": "string",
              "maxLength": 512
            },
            "duration": {
              "type": "integer",
              "maximum": 15,
              "minimum": 1
            }
          }
        },
        "maxItems": 6,
        "minItems": 1
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling 3.0 — Turbo · Image to video API
Source: https://docs.higgsfield.ai/docs/models/kling-3/turbo-image-to-video

Turbo · Image to video with Kling 3.0: request parameters, examples and response handling.

<div />

[← Kling 3.0](/docs/models/kling-3)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/v3.0-turbo/image-to-video`

**Endpoint ID:** `kling-video/v3.0-turbo/image-to-video`

<a href="https://console.higgsfield.ai/models/kling-video%2Fv3.0-turbo%2Fimage-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling 3.0 · Turbo · Image to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* duration accepts integers from 3 to 15 seconds. resolution accepts 720p or 1080p and defaults to 720p.
* This endpoint has no sound, multi\_shots, elements, or last-frame field.
* Keep prompt within 2,500 characters; longer prompts are truncated.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/v3.0-turbo/image-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic tracking shot along a sunlit coastal road.",
    "image_url": "https://example.com/first-frame.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic tracking shot along a sunlit coastal road.',
       'image_url': 'https://example.com/first-frame.jpg'}
  )
  result = higgsfield_client.subscribe(
      "kling-video/v3.0-turbo/image-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/v3.0-turbo/image-to-video", {
    input:
      {
        "prompt": "A slow cinematic tracking shot along a sunlit coastal road.",
        "image_url": "https://example.com/first-frame.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `3`.
  Maximum: `15`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling 3.0 Turbo",
    "required": [
      "prompt",
      "image_url"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 3
      },
      "image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      },
      "resolution": {
        "enum": [
          "720p",
          "1080p"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "720p"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling 3.0 — Turbo · Text to video API
Source: https://docs.higgsfield.ai/docs/models/kling-3/turbo-text-to-video

Turbo · Text to video with Kling 3.0: request parameters, examples and response handling.

<div />

[← Kling 3.0](/docs/models/kling-3)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/v3.0-turbo/text-to-video`

**Endpoint ID:** `kling-video/v3.0-turbo/text-to-video`

<a href="https://console.higgsfield.ai/models/kling-video%2Fv3.0-turbo%2Ftext-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling 3.0 · Turbo · Text to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* duration accepts integers from 3 to 15 seconds. resolution accepts 720p or 1080p and defaults to 720p.
* This endpoint has no sound, multi\_shots, elements, or last-frame field.
* aspect\_ratio accepts 16:9, 9:16, or 1:1 and defaults to 16:9.
* Keep prompt within 3,072 characters; longer prompts are truncated.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/v3.0-turbo/text-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic tracking shot along a sunlit coastal road."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic tracking shot along a sunlit coastal road.'}
  )
  result = higgsfield_client.subscribe(
      "kling-video/v3.0-turbo/text-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/v3.0-turbo/text-to-video", {
    input:
      {
        "prompt": "A slow cinematic tracking shot along a sunlit coastal road."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `3`.
  Maximum: `15`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`, `"1:1"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling 3.0 Turbo",
    "required": [
      "prompt"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 3
      },
      "resolution": {
        "enum": [
          "720p",
          "1080p"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "720p"
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "type": "string",
        "title": "Aspect ratio",
        "default": "16:9"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling O3 API
Source: https://docs.higgsfield.ai/docs/models/kling-o3

Create and edit videos with first/last frames, image references and video references.

<div />

Create and edit videos with first/last frames, image references and video references.

## Workflows

| Workflow | Endpoint |
| - | - |
| [First last frame](/docs/models/kling-o3/first-last-frame) | `POST /kling-video/o3/first-last-frame` |
| [Image reference](/docs/models/kling-o3/image-reference) | `POST /kling-video/o3/image-reference` |
| [Video edit](/docs/models/kling-o3/video-edit) | `POST /kling-video/o3/video-edit` |
| [Video reference](/docs/models/kling-o3/video-reference) | `POST /kling-video/o3/video-reference` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Kling O3 — First last frame API
Source: https://docs.higgsfield.ai/docs/models/kling-o3/first-last-frame

First last frame with Kling O3: request parameters, examples and response handling.

<div />

[← Kling O3](/docs/models/kling-o3)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/o3/first-last-frame`

**Endpoint ID:** `kling-video/o3/first-last-frame`

<a href="https://console.higgsfield.ai/models/kling-video%2Fo3%2Ffirst-last-frame/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling O3 · First last frame</span></span>
  <span>↗</span>
</a>

## Usage notes

* first\_frame\_url supplies the starting frame; last\_frame\_url is optional. These names differ from the image\_url and last\_image\_url fields on Kling 3.0 image-to-video.
* For a single shot, set multi\_shots to false and provide prompt. For multiple shots, set multi\_shots to true and provide 1–6 multi\_prompt objects, each containing prompt and a positive integer duration.
* Always include a non-empty top-level prompt, including when using multi\_prompt.
* Each shot prompt is limited to 512 characters. Custom-shot durations are summed for generation and billing; the top-level duration does not override that sum.
* Native audio uses sound: on or off and defaults to off.
* Keep the top-level prompt within 2,500 characters; longer prompts are truncated.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/o3/first-last-frame \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic camera move around the subject in warm evening light.",
    "first_frame_url": "https://example.com/first-frame.jpg",
    "multi_shots": false
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic camera move around the subject in warm evening '
                 'light.',
       'first_frame_url': 'https://example.com/first-frame.jpg',
       'multi_shots': False}
  )
  result = higgsfield_client.subscribe(
      "kling-video/o3/first-last-frame",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/o3/first-last-frame", {
    input:
      {
        "prompt": "A slow cinematic camera move around the subject in warm evening light.",
        "first_frame_url": "https://example.com/first-frame.jpg",
        "multi_shots": false
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Allowed values: `"std"`, `"pro"`, `"4k"`.
</ParamField>

<ParamField type="string">
  Enable sound for the output video.
  Allowed values: `"on"`, `"off"`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `3`.
  Maximum: `15`.
</ParamField>

<ParamField type="boolean">
  See the complete JSON schema below.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`, `"1:1"`.
</ParamField>

<ParamField type="array">
  Minimum items: `1`.
  Maximum items: `6`.

  <Expandable title="Nested fields">
    <ParamField type="string">
      Text instructions for the generation or edit.
      Maximum characters: `512`.
    </ParamField>

    <ParamField type="integer">
      Requested output duration in seconds.
      Minimum: `1`.
      Maximum: `15`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Format: `uri`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "if": {
      "properties": {
        "multi_shots": {
          "const": true
        }
      }
    },
    "else": {
      "required": [
        "prompt",
        "first_frame_url"
      ]
    },
    "then": {
      "required": [
        "multi_prompt",
        "first_frame_url"
      ]
    },
    "type": "object",
    "title": "Kling O3 Playground",
    "properties": {
      "mode": {
        "enum": [
          "std",
          "pro",
          "4k"
        ],
        "type": "string",
        "default": "pro"
      },
      "sound": {
        "enum": [
          "on",
          "off"
        ],
        "type": "string",
        "default": "off"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 3
      },
      "multi_shots": {
        "type": "boolean",
        "default": false
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "type": "string"
      },
      "multi_prompt": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "prompt": {
              "type": "string",
              "maxLength": 512
            },
            "duration": {
              "type": "integer",
              "maximum": 15,
              "minimum": 1
            }
          }
        },
        "maxItems": 6,
        "minItems": 1
      },
      "last_frame_url": {
        "type": "string",
        "title": "Last frame URL",
        "format": "uri"
      },
      "first_frame_url": {
        "type": "string",
        "title": "First frame URL",
        "format": "uri"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling O3 — Image reference API
Source: https://docs.higgsfield.ai/docs/models/kling-o3/image-reference

Image reference with Kling O3: request parameters, examples and response handling.

<div />

[← Kling O3](/docs/models/kling-o3)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/o3/image-reference`

**Endpoint ID:** `kling-video/o3/image-reference`

<a href="https://console.higgsfield.ai/models/kling-video%2Fo3%2Fimage-reference/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling O3 · Image reference</span></span>
  <span>↗</span>
</a>

## Usage notes

* Supply image\_urls for visual references. Reference images are optional in the schema.
* For a single shot, set multi\_shots to false and provide prompt. For multiple shots, set multi\_shots to true and provide 1–6 multi\_prompt objects, each containing prompt and a positive integer duration.
* Always include a non-empty top-level prompt, including when using multi\_prompt.
* Each shot prompt is limited to 512 characters. Custom-shot durations are summed for generation and billing; the top-level duration does not override that sum.
* Native audio uses sound: on or off and defaults to off.
* A multi\_prompt shot must last at least 1 second; zero-second shots are rejected even though the schema permits zero.
* When multi\_shots is true, multi\_prompt is required even with shot\_type set to intelligent.
* Keep the top-level prompt within 2,500 characters; longer prompts are truncated.
* elements contains Kling element IDs as decimal strings. Each ID must belong to the account making the request; arbitrary provider IDs are rejected.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/o3/image-reference \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic camera move around the subject in warm evening light.",
    "image_urls": [
      "https://example.com/reference-image.jpg"
    ],
    "multi_shots": false
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic camera move around the subject in warm evening '
                 'light.',
       'image_urls': ['https://example.com/reference-image.jpg'],
       'multi_shots': False}
  )
  result = higgsfield_client.subscribe(
      "kling-video/o3/image-reference",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/o3/image-reference", {
    input:
      {
        "prompt": "A slow cinematic camera move around the subject in warm evening light.",
        "image_urls": [
          "https://example.com/reference-image.jpg"
        ],
        "multi_shots": false
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Allowed values: `"std"`, `"pro"`, `"4k"`.
</ParamField>

<ParamField type="string">
  Enable sound for the output video.
  Allowed values: `"on"`, `"off"`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `3`.
  Maximum: `15`.
</ParamField>

<ParamField type="array">
  Each item: string.
</ParamField>

<ParamField type="string">
  Allowed values: `"customize"`, `"intelligent"`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="boolean">
  See the complete JSON schema below.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`, `"1:1"`.
</ParamField>

<ParamField type="array">
  Minimum items: `1`.
  Maximum items: `6`.

  <Expandable title="Nested fields">
    <ParamField type="string">
      Text instructions for the generation or edit.
      Maximum characters: `512`.
    </ParamField>

    <ParamField type="integer">
      Requested output duration in seconds.
      Minimum: `0`.
      Maximum: `15`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Format: `uri`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "if": {
      "properties": {
        "multi_shots": {
          "const": true
        }
      }
    },
    "else": {
      "required": [
        "prompt"
      ]
    },
    "then": {
      "required": [
        "multi_prompt"
      ]
    },
    "type": "object",
    "title": "Kling Omni Playground",
    "properties": {
      "mode": {
        "enum": [
          "std",
          "pro",
          "4k"
        ],
        "type": "string",
        "default": "std"
      },
      "sound": {
        "enum": [
          "on",
          "off"
        ],
        "type": "string",
        "default": "off"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 3
      },
      "elements": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "shot_type": {
        "enum": [
          "customize",
          "intelligent"
        ],
        "type": "string",
        "default": "customize"
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "title": "Image URL",
          "format": "uri"
        }
      },
      "multi_shots": {
        "type": "boolean",
        "default": false
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "type": "string"
      },
      "multi_prompt": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "prompt": {
              "type": "string",
              "maxLength": 512
            },
            "duration": {
              "type": "integer",
              "maximum": 15,
              "minimum": 0
            }
          }
        },
        "maxItems": 6,
        "minItems": 1
      },
      "last_frame_url": {
        "type": "string",
        "title": "Last frame URL",
        "format": "uri"
      },
      "first_frame_url": {
        "type": "string",
        "title": "First frame URL",
        "format": "uri"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling O3 — Video edit API
Source: https://docs.higgsfield.ai/docs/models/kling-o3/video-edit

Video edit with Kling O3: request parameters, examples and response handling.

<div />

[← Kling O3](/docs/models/kling-o3)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/o3/video-edit`

**Endpoint ID:** `kling-video/o3/video-edit`

<a href="https://console.higgsfield.ai/models/kling-video%2Fo3%2Fvideo-edit/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling O3 · Video edit</span></span>
  <span>↗</span>
</a>

## Usage notes

* Supply exactly one source video from 3 to 15.5 seconds long and no larger than 200 MB. Duration is derived from the video; do not send a separate duration field.
* You may also supply up to four image\_urls and up to four elements.
* Keep the top-level prompt within 2,500 characters; longer prompts are truncated.
* elements contains Kling element IDs as decimal strings. Each ID must belong to the account making the request; arbitrary provider IDs are rejected.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/o3/video-edit \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "Change the background to a sunlit garden while preserving the subject and motion.",
    "video_urls": [
      "https://example.com/source-video.mp4"
    ]
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'Change the background to a sunlit garden while preserving the '
                 'subject and motion.',
       'video_urls': ['https://example.com/source-video.mp4']}
  )
  result = higgsfield_client.subscribe(
      "kling-video/o3/video-edit",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/o3/video-edit", {
    input:
      {
        "prompt": "Change the background to a sunlit garden while preserving the subject and motion.",
        "video_urls": [
          "https://example.com/source-video.mp4"
        ]
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Allowed values: `"std"`, `"pro"`, `"4k"`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="array">
  Minimum items: `0`.
  Maximum items: `4`.
  Each item: string.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Minimum items: `0`.
  Maximum items: `4`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="array">
  Ordered public video reference URLs.
  Minimum items: `1`.
  Maximum items: `1`.
  Each item: string. Format: `uri`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling O3 Playground",
    "required": [
      "prompt",
      "video_urls"
    ],
    "properties": {
      "mode": {
        "enum": [
          "std",
          "pro",
          "4k"
        ],
        "type": "string",
        "default": "pro"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "elements": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "maxItems": 4,
        "minItems": 0
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "title": "Image URL",
          "format": "uri"
        },
        "maxItems": 4,
        "minItems": 0
      },
      "video_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "title": "Video URL",
          "format": "uri"
        },
        "maxItems": 1,
        "minItems": 1
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling O3 — Video reference API
Source: https://docs.higgsfield.ai/docs/models/kling-o3/video-reference

Video reference with Kling O3: request parameters, examples and response handling.

<div />

[← Kling O3](/docs/models/kling-o3)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/o3/video-reference`

**Endpoint ID:** `kling-video/o3/video-reference`

<a href="https://console.higgsfield.ai/models/kling-video%2Fo3%2Fvideo-reference/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling O3 · Video reference</span></span>
  <span>↗</span>
</a>

## Usage notes

* Supply exactly one video reference. duration controls the generated clip and accepts integer values from 3 to 10 seconds.
* You may also supply up to four image\_urls and up to four elements.
* Keep the top-level prompt within 2,500 characters; longer prompts are truncated.
* elements contains Kling element IDs as decimal strings. Each ID must belong to the account making the request; arbitrary provider IDs are rejected.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/o3/video-reference \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic camera move around the subject in warm evening light.",
    "video_urls": [
      "https://example.com/source-video.mp4"
    ]
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic camera move around the subject in warm evening '
                 'light.',
       'video_urls': ['https://example.com/source-video.mp4']}
  )
  result = higgsfield_client.subscribe(
      "kling-video/o3/video-reference",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/o3/video-reference", {
    input:
      {
        "prompt": "A slow cinematic camera move around the subject in warm evening light.",
        "video_urls": [
          "https://example.com/source-video.mp4"
        ]
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Allowed values: `"std"`, `"pro"`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `3`.
  Maximum: `10`.
</ParamField>

<ParamField type="array">
  Minimum items: `0`.
  Maximum items: `4`.
  Each item: string.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Minimum items: `0`.
  Maximum items: `4`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="array">
  Ordered public video reference URLs.
  Minimum items: `1`.
  Maximum items: `1`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`, `"1:1"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling O3 Playground",
    "required": [
      "prompt",
      "video_urls"
    ],
    "properties": {
      "mode": {
        "enum": [
          "std",
          "pro"
        ],
        "type": "string",
        "default": "pro"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 10,
        "minimum": 3
      },
      "elements": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "maxItems": 4,
        "minItems": 0
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "title": "Image URL",
          "format": "uri"
        },
        "maxItems": 4,
        "minItems": 0
      },
      "video_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "title": "Video URL",
          "format": "uri"
        },
        "maxItems": 1,
        "minItems": 1
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "type": "string"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling Omni API
Source: https://docs.higgsfield.ai/docs/models/kling-omni

Create and edit videos with image and video references.

<div />

Create and edit videos with image and video references.

## Workflows

| Workflow | Endpoint |
| - | - |
| [First last frame](/docs/models/kling-omni/first-last-frame) | `POST /kling-video/omni/first-last-frame` |
| [Image reference](/docs/models/kling-omni/image-reference) | `POST /kling-video/omni/image-reference` |
| [Video edit](/docs/models/kling-omni/video-edit) | `POST /kling-video/omni/video-edit` |
| [Video reference](/docs/models/kling-omni/video-reference) | `POST /kling-video/omni/video-reference` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Kling Omni — First last frame API
Source: https://docs.higgsfield.ai/docs/models/kling-omni/first-last-frame

First last frame with Kling Omni: request parameters, examples and response handling.

<div />

[← Kling Omni](/docs/models/kling-omni)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/omni/first-last-frame`

**Endpoint ID:** `kling-video/omni/first-last-frame`

<a href="https://console.higgsfield.ai/models/kling-video%2Fomni%2Ffirst-last-frame/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling Omni · First last frame</span></span>
  <span>↗</span>
</a>

## Usage notes

* first\_frame\_url supplies the starting frame; last\_frame\_url is optional. These names differ from the image\_url and last\_image\_url fields on Kling 3.0 image-to-video.
* Keep the top-level prompt within 2,500 characters; longer prompts are truncated.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/omni/first-last-frame \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic camera move around the subject in warm evening light.",
    "first_frame_url": "https://example.com/first-frame.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic camera move around the subject in warm evening '
                 'light.',
       'first_frame_url': 'https://example.com/first-frame.jpg'}
  )
  result = higgsfield_client.subscribe(
      "kling-video/omni/first-last-frame",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/omni/first-last-frame", {
    input:
      {
        "prompt": "A slow cinematic camera move around the subject in warm evening light.",
        "first_frame_url": "https://example.com/first-frame.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Allowed values: `"std"`, `"pro"`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Allowed values: `5`, `10`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`, `"1:1"`.
</ParamField>

<ParamField type="string">
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Format: `uri`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling Omni Playground",
    "required": [
      "prompt",
      "first_frame_url"
    ],
    "properties": {
      "mode": {
        "enum": [
          "std",
          "pro"
        ],
        "type": "string",
        "default": "pro"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "enum": [
          5,
          10
        ],
        "type": "integer",
        "title": "Duration",
        "default": 5
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "type": "string",
        "default": "16:9"
      },
      "last_frame_url": {
        "type": "string",
        "title": "Last frame URL",
        "format": "uri"
      },
      "first_frame_url": {
        "type": "string",
        "title": "First frame URL",
        "format": "uri"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling Omni — Image reference API
Source: https://docs.higgsfield.ai/docs/models/kling-omni/image-reference

Image reference with Kling Omni: request parameters, examples and response handling.

<div />

[← Kling Omni](/docs/models/kling-omni)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/omni/image-reference`

**Endpoint ID:** `kling-video/omni/image-reference`

<a href="https://console.higgsfield.ai/models/kling-video%2Fomni%2Fimage-reference/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling Omni · Image reference</span></span>
  <span>↗</span>
</a>

## Usage notes

* Supply image\_urls for visual references. Reference images are optional in the schema.
* Keep the top-level prompt within 2,500 characters; longer prompts are truncated.
* elements contains Kling element IDs as decimal strings. Each ID must belong to the account making the request; arbitrary provider IDs are rejected.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/omni/image-reference \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic camera move around the subject in warm evening light.",
    "image_urls": [
      "https://example.com/reference-image.jpg"
    ]
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic camera move around the subject in warm evening '
                 'light.',
       'image_urls': ['https://example.com/reference-image.jpg']}
  )
  result = higgsfield_client.subscribe(
      "kling-video/omni/image-reference",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/omni/image-reference", {
    input:
      {
        "prompt": "A slow cinematic camera move around the subject in warm evening light.",
        "image_urls": [
          "https://example.com/reference-image.jpg"
        ]
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Allowed values: `"std"`, `"pro"`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `3`.
  Maximum: `10`.
</ParamField>

<ParamField type="array">
  Each item: string.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`, `"1:1"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling Omni Playground",
    "required": [
      "prompt"
    ],
    "properties": {
      "mode": {
        "enum": [
          "std",
          "pro"
        ],
        "type": "string",
        "default": "pro"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 10,
        "minimum": 3
      },
      "elements": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "title": "Image URL",
          "format": "uri"
        }
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "type": "string",
        "default": "16:9"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling Omni — Video edit API
Source: https://docs.higgsfield.ai/docs/models/kling-omni/video-edit

Video edit with Kling Omni: request parameters, examples and response handling.

<div />

[← Kling Omni](/docs/models/kling-omni)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/omni/video-edit`

**Endpoint ID:** `kling-video/omni/video-edit`

<a href="https://console.higgsfield.ai/models/kling-video%2Fomni%2Fvideo-edit/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling Omni · Video edit</span></span>
  <span>↗</span>
</a>

## Usage notes

* Supply exactly one source video from 3 to 10 seconds long and no larger than 200 MB. Duration is derived from the video; do not send a separate duration field.
* You may also supply up to four image\_urls and up to four elements.
* Keep the top-level prompt within 2,500 characters; longer prompts are truncated.
* elements contains Kling element IDs as decimal strings. Each ID must belong to the account making the request; arbitrary provider IDs are rejected.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/omni/video-edit \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "Change the background to a sunlit garden while preserving the subject and motion.",
    "video_urls": [
      "https://example.com/source-video.mp4"
    ]
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'Change the background to a sunlit garden while preserving the '
                 'subject and motion.',
       'video_urls': ['https://example.com/source-video.mp4']}
  )
  result = higgsfield_client.subscribe(
      "kling-video/omni/video-edit",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/omni/video-edit", {
    input:
      {
        "prompt": "Change the background to a sunlit garden while preserving the subject and motion.",
        "video_urls": [
          "https://example.com/source-video.mp4"
        ]
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Allowed values: `"std"`, `"pro"`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="array">
  Minimum items: `0`.
  Maximum items: `4`.
  Each item: string.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Minimum items: `0`.
  Maximum items: `4`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="array">
  Ordered public video reference URLs.
  Minimum items: `1`.
  Maximum items: `1`.
  Each item: string. Format: `uri`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling Omni Playground",
    "required": [
      "prompt",
      "video_urls"
    ],
    "properties": {
      "mode": {
        "enum": [
          "std",
          "pro"
        ],
        "type": "string",
        "default": "pro"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "elements": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "maxItems": 4,
        "minItems": 0
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "title": "Image URL",
          "format": "uri"
        },
        "maxItems": 4,
        "minItems": 0
      },
      "video_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "title": "Video URL",
          "format": "uri"
        },
        "maxItems": 1,
        "minItems": 1
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Kling Omni — Video reference API
Source: https://docs.higgsfield.ai/docs/models/kling-omni/video-reference

Video reference with Kling Omni: request parameters, examples and response handling.

<div />

[← Kling Omni](/docs/models/kling-omni)

**Endpoint:** `POST https://api.higgsfield.ai/kling-video/omni/video-reference`

**Endpoint ID:** `kling-video/omni/video-reference`

<a href="https://console.higgsfield.ai/models/kling-video%2Fomni%2Fvideo-reference/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Kling Omni · Video reference</span></span>
  <span>↗</span>
</a>

## Usage notes

* Supply exactly one video reference. duration controls the generated clip and accepts integer values from 3 to 10 seconds.
* You may also supply up to four image\_urls and up to four elements.
* Keep the top-level prompt within 2,500 characters; longer prompts are truncated.
* elements contains Kling element IDs as decimal strings. Each ID must belong to the account making the request; arbitrary provider IDs are rejected.
* The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/kling-video/omni/video-reference \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A slow cinematic camera move around the subject in warm evening light.",
    "video_urls": [
      "https://example.com/source-video.mp4"
    ]
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A slow cinematic camera move around the subject in warm evening '
                 'light.',
       'video_urls': ['https://example.com/source-video.mp4']}
  )
  result = higgsfield_client.subscribe(
      "kling-video/omni/video-reference",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("kling-video/omni/video-reference", {
    input:
      {
        "prompt": "A slow cinematic camera move around the subject in warm evening light.",
        "video_urls": [
          "https://example.com/source-video.mp4"
        ]
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Allowed values: `"std"`, `"pro"`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `3`.
  Maximum: `10`.
</ParamField>

<ParamField type="array">
  Minimum items: `0`.
  Maximum items: `4`.
  Each item: string.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Minimum items: `0`.
  Maximum items: `4`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="array">
  Ordered public video reference URLs.
  Minimum items: `1`.
  Maximum items: `1`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`, `"1:1"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Kling Omni Playground",
    "required": [
      "prompt",
      "video_urls"
    ],
    "properties": {
      "mode": {
        "enum": [
          "std",
          "pro"
        ],
        "type": "string",
        "default": "pro"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "mode": {
          "enum": [
            "std",
            "pro"
          ],
          "type": "string",
          "default": "pro"
        },
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 10,
        "minimum": 3
      },
      "elements": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "maxItems": 4,
        "minItems": 0
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "title": "Image URL",
          "format": "uri"
        },
        "maxItems": 4,
        "minItems": 0
      },
      "video_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "title": "Video URL",
          "format": "uri"
        },
        "maxItems": 1,
        "minItems": 1
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "type": "string",
        "default": "16:9"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# LTX-2.5 API
Source: https://docs.higgsfield.ai/docs/models/ltx-2-5

Generate videos from text or images with Fast and Pro variants.

<div />

Generate videos from text or images with Fast and Pro variants.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to video fast](/docs/models/ltx-2-5/text-to-video-fast) | `POST /lightricks/ltx-2.5/text-to-video/fast` |
| [Text to video pro](/docs/models/ltx-2-5/text-to-video-pro) | `POST /lightricks/ltx-2.5/text-to-video/pro` |
| [Image to video fast](/docs/models/ltx-2-5/image-to-video-fast) | `POST /lightricks/ltx-2.5/image-to-video/fast` |
| [Image to video pro](/docs/models/ltx-2-5/image-to-video-pro) | `POST /lightricks/ltx-2.5/image-to-video/pro` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# LTX-2.5 — Image to video fast API
Source: https://docs.higgsfield.ai/docs/models/ltx-2-5/image-to-video-fast

Image to video fast with LTX-2.5: request parameters, examples and response handling.

<div />

[← LTX-2.5](/docs/models/ltx-2-5)

**Endpoint:** `POST https://api.higgsfield.ai/lightricks/ltx-2.5/image-to-video/fast`

**Endpoint ID:** `lightricks/ltx-2.5/image-to-video/fast`

<a href="https://console.higgsfield.ai/models/lightricks%2Fltx-2.5%2Fimage-to-video%2Ffast/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>LTX-2.5 · Image to video fast</span></span>
  <span>↗</span>
</a>

## Usage notes

* duration is marked required in the schema and has default 6; the API applies this top-level default before validation. The example includes it explicitly.
* Fast supports 720p, 1080p, 2k or 4k and 24, 25, 48 or 50 fps.
* image\_url is the required first frame; end\_image\_url is an optional last frame. aspect\_ratio explicitly controls output dimensions.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/lightricks/ltx-2.5/image-to-video/fast \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
    "duration": 6,
    "image_url": "https://example.com/input.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.',
       'duration': 6,
       'image_url': 'https://example.com/input.jpg'}
  )
  result = higgsfield_client.subscribe(
      "lightricks/ltx-2.5/image-to-video/fast",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("lightricks/ltx-2.5/image-to-video/fast", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
        "duration": 6,
        "image_url": "https://example.com/input.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Allowed values: `24`, `25`, `48`, `50`.
</ParamField>

<ParamField type="string">
  Write your prompt here
  Minimum characters: `2`.
  Maximum characters: `5000`.
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Allowed values: `6`, `8`, `10`.
  The server supplies this default when the field is omitted.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`, `"2k"`, `"4k"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`.
</ParamField>

<ParamField type="string">
  Format: `uri`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<ParamField type="string">
  Allowed values: `"dolly_in"`, `"dolly_out"`, `"dolly_left"`, `"dolly_right"`, `"jib_up"`, `"jib_down"`, `"static"`, `"focus_shift"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "LTX-2.5 Fast Image to Video Playground",
    "required": [
      "prompt",
      "duration",
      "image_url"
    ],
    "properties": {
      "fps": {
        "enum": [
          24,
          25,
          48,
          50
        ],
        "type": "integer",
        "title": "Frames per second",
        "default": 25
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "maxLength": 5000,
        "minLength": 2,
        "description": "Write your prompt here"
      },
      "duration": {
        "enum": [
          6,
          8,
          10
        ],
        "type": "integer",
        "title": "Duration",
        "default": 6
      },
      "image_url": {
        "type": "string",
        "title": "First frame",
        "format": "uri"
      },
      "resolution": {
        "enum": [
          "720p",
          "1080p",
          "2k",
          "4k"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "720p"
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16"
        ],
        "type": "string",
        "title": "Aspect ratio",
        "default": "16:9"
      },
      "end_image_url": {
        "type": "string",
        "title": "Last frame",
        "format": "uri"
      },
      "generate_audio": {
        "type": "boolean",
        "title": "Generate audio",
        "default": true
      },
      "camera_movement": {
        "enum": [
          "dolly_in",
          "dolly_out",
          "dolly_left",
          "dolly_right",
          "jib_up",
          "jib_down",
          "static",
          "focus_shift"
        ],
        "type": "string",
        "title": "Camera movement"
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# LTX-2.5 — Image to video pro API
Source: https://docs.higgsfield.ai/docs/models/ltx-2-5/image-to-video-pro

Image to video pro with LTX-2.5: request parameters, examples and response handling.

<div />

[← LTX-2.5](/docs/models/ltx-2-5)

**Endpoint:** `POST https://api.higgsfield.ai/lightricks/ltx-2.5/image-to-video/pro`

**Endpoint ID:** `lightricks/ltx-2.5/image-to-video/pro`

<a href="https://console.higgsfield.ai/models/lightricks%2Fltx-2.5%2Fimage-to-video%2Fpro/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>LTX-2.5 · Image to video pro</span></span>
  <span>↗</span>
</a>

## Usage notes

* duration is marked required in the schema and has default 6; the API applies this top-level default before validation. The example includes it explicitly.
* Pro supports 720p or 1080p and 24, 25 or 50 fps. Use the Fast endpoint for 2k, 4k or 48 fps.
* image\_url is the required first frame; end\_image\_url is an optional last frame. aspect\_ratio explicitly controls output dimensions.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/lightricks/ltx-2.5/image-to-video/pro \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
    "duration": 6,
    "image_url": "https://example.com/input.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.',
       'duration': 6,
       'image_url': 'https://example.com/input.jpg'}
  )
  result = higgsfield_client.subscribe(
      "lightricks/ltx-2.5/image-to-video/pro",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("lightricks/ltx-2.5/image-to-video/pro", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
        "duration": 6,
        "image_url": "https://example.com/input.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Allowed values: `24`, `25`, `50`.
</ParamField>

<ParamField type="string">
  Write your prompt here
  Minimum characters: `2`.
  Maximum characters: `5000`.
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Allowed values: `6`, `8`, `10`.
  The server supplies this default when the field is omitted.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`.
</ParamField>

<ParamField type="string">
  Format: `uri`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<ParamField type="string">
  Allowed values: `"dolly_in"`, `"dolly_out"`, `"dolly_left"`, `"dolly_right"`, `"jib_up"`, `"jib_down"`, `"static"`, `"focus_shift"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "LTX-2.5 Pro Image to Video Playground",
    "required": [
      "prompt",
      "duration",
      "image_url"
    ],
    "properties": {
      "fps": {
        "enum": [
          24,
          25,
          50
        ],
        "type": "integer",
        "title": "Frames per second",
        "default": 25
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "maxLength": 5000,
        "minLength": 2,
        "description": "Write your prompt here"
      },
      "duration": {
        "enum": [
          6,
          8,
          10
        ],
        "type": "integer",
        "title": "Duration",
        "default": 6
      },
      "image_url": {
        "type": "string",
        "title": "First frame",
        "format": "uri"
      },
      "resolution": {
        "enum": [
          "720p",
          "1080p"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "720p"
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16"
        ],
        "type": "string",
        "title": "Aspect ratio",
        "default": "16:9"
      },
      "end_image_url": {
        "type": "string",
        "title": "Last frame",
        "format": "uri"
      },
      "generate_audio": {
        "type": "boolean",
        "title": "Generate audio",
        "default": true
      },
      "camera_movement": {
        "enum": [
          "dolly_in",
          "dolly_out",
          "dolly_left",
          "dolly_right",
          "jib_up",
          "jib_down",
          "static",
          "focus_shift"
        ],
        "type": "string",
        "title": "Camera movement"
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# LTX-2.5 — Text to video fast API
Source: https://docs.higgsfield.ai/docs/models/ltx-2-5/text-to-video-fast

Text to video fast with LTX-2.5: request parameters, examples and response handling.

<div />

[← LTX-2.5](/docs/models/ltx-2-5)

**Endpoint:** `POST https://api.higgsfield.ai/lightricks/ltx-2.5/text-to-video/fast`

**Endpoint ID:** `lightricks/ltx-2.5/text-to-video/fast`

<a href="https://console.higgsfield.ai/models/lightricks%2Fltx-2.5%2Ftext-to-video%2Ffast/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>LTX-2.5 · Text to video fast</span></span>
  <span>↗</span>
</a>

## Usage notes

* duration is marked required in the schema and has default 6; the API applies this top-level default before validation. The example includes it explicitly.
* Fast supports 720p, 1080p, 2k or 4k and 24, 25, 48 or 50 fps.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/lightricks/ltx-2.5/text-to-video/fast \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
    "duration": 6
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.',
       'duration': 6}
  )
  result = higgsfield_client.subscribe(
      "lightricks/ltx-2.5/text-to-video/fast",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("lightricks/ltx-2.5/text-to-video/fast", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
        "duration": 6
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Allowed values: `24`, `25`, `48`, `50`.
</ParamField>

<ParamField type="string">
  Write your prompt here
  Minimum characters: `2`.
  Maximum characters: `5000`.
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Allowed values: `6`, `8`, `10`.
  The server supplies this default when the field is omitted.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`, `"2k"`, `"4k"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<ParamField type="string">
  Allowed values: `"dolly_in"`, `"dolly_out"`, `"dolly_left"`, `"dolly_right"`, `"jib_up"`, `"jib_down"`, `"static"`, `"focus_shift"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "LTX-2.5 Fast Text to Video Playground",
    "required": [
      "prompt",
      "duration"
    ],
    "properties": {
      "fps": {
        "enum": [
          24,
          25,
          48,
          50
        ],
        "type": "integer",
        "title": "Frames per second",
        "default": 25
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "maxLength": 5000,
        "minLength": 2,
        "description": "Write your prompt here"
      },
      "duration": {
        "enum": [
          6,
          8,
          10
        ],
        "type": "integer",
        "title": "Duration",
        "default": 6
      },
      "resolution": {
        "enum": [
          "720p",
          "1080p",
          "2k",
          "4k"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "720p"
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16"
        ],
        "type": "string",
        "title": "Aspect ratio",
        "default": "16:9"
      },
      "generate_audio": {
        "type": "boolean",
        "title": "Generate audio",
        "default": true
      },
      "camera_movement": {
        "enum": [
          "dolly_in",
          "dolly_out",
          "dolly_left",
          "dolly_right",
          "jib_up",
          "jib_down",
          "static",
          "focus_shift"
        ],
        "type": "string",
        "title": "Camera movement"
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# LTX-2.5 — Text to video pro API
Source: https://docs.higgsfield.ai/docs/models/ltx-2-5/text-to-video-pro

Text to video pro with LTX-2.5: request parameters, examples and response handling.

<div />

[← LTX-2.5](/docs/models/ltx-2-5)

**Endpoint:** `POST https://api.higgsfield.ai/lightricks/ltx-2.5/text-to-video/pro`

**Endpoint ID:** `lightricks/ltx-2.5/text-to-video/pro`

<a href="https://console.higgsfield.ai/models/lightricks%2Fltx-2.5%2Ftext-to-video%2Fpro/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>LTX-2.5 · Text to video pro</span></span>
  <span>↗</span>
</a>

## Usage notes

* duration is marked required in the schema and has default 6; the API applies this top-level default before validation. The example includes it explicitly.
* Pro supports 720p or 1080p and 24, 25 or 50 fps. Use the Fast endpoint for 2k, 4k or 48 fps.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/lightricks/ltx-2.5/text-to-video/pro \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
    "duration": 6
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.',
       'duration': 6}
  )
  result = higgsfield_client.subscribe(
      "lightricks/ltx-2.5/text-to-video/pro",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("lightricks/ltx-2.5/text-to-video/pro", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
        "duration": 6
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Allowed values: `24`, `25`, `50`.
</ParamField>

<ParamField type="string">
  Write your prompt here
  Minimum characters: `2`.
  Maximum characters: `5000`.
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Allowed values: `6`, `8`, `10`.
  The server supplies this default when the field is omitted.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<ParamField type="string">
  Allowed values: `"dolly_in"`, `"dolly_out"`, `"dolly_left"`, `"dolly_right"`, `"jib_up"`, `"jib_down"`, `"static"`, `"focus_shift"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "LTX-2.5 Pro Text to Video Playground",
    "required": [
      "prompt",
      "duration"
    ],
    "properties": {
      "fps": {
        "enum": [
          24,
          25,
          50
        ],
        "type": "integer",
        "title": "Frames per second",
        "default": 25
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "maxLength": 5000,
        "minLength": 2,
        "description": "Write your prompt here"
      },
      "duration": {
        "enum": [
          6,
          8,
          10
        ],
        "type": "integer",
        "title": "Duration",
        "default": 6
      },
      "resolution": {
        "enum": [
          "720p",
          "1080p"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "720p"
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16"
        ],
        "type": "string",
        "title": "Aspect ratio",
        "default": "16:9"
      },
      "generate_audio": {
        "type": "boolean",
        "title": "Generate audio",
        "default": true
      },
      "camera_movement": {
        "enum": [
          "dolly_in",
          "dolly_out",
          "dolly_left",
          "dolly_right",
          "jib_up",
          "jib_down",
          "static",
          "focus_shift"
        ],
        "type": "string",
        "title": "Camera movement"
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Marketing Studio Image API
Source: https://docs.higgsfield.ai/docs/models/marketing-studio-image

Generate and edit campaign images, with optional preset-based prompt enhancement.

<div />

Generate and edit campaign images, with optional preset-based prompt enhancement.

## Workflows

| Workflow | Endpoint |
| - | - |
| [2.0 Alpha](/docs/models/marketing-studio-image/generate-and-edit) | `POST /marketing-studio/image` |
| [2.5 Flare](/docs/models/marketing-studio-image/flare) | `POST /marketing-studio/image/flare` |
| [2.5 Sunburst](/docs/models/marketing-studio-image/sunburst) | `POST /marketing-studio/image/sunburst` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Marketing Studio Image — 2.5 Flare API
Source: https://docs.higgsfield.ai/docs/models/marketing-studio-image/flare

2.5 Flare with Marketing Studio Image: request parameters, examples and response handling.

<div />

[← Marketing Studio Image](/docs/models/marketing-studio-image)

**Endpoint:** `POST https://api.higgsfield.ai/marketing-studio/image/flare`

**Endpoint ID:** `marketing-studio/image/flare`

<a href="https://console.higgsfield.ai/models/marketing-studio%2Fimage%2Fflare/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Marketing Studio Image · 2.5 Flare</span></span>
  <span>↗</span>
</a>

## Usage notes

* Omit image\_urls for text-to-image; provide up to 16 URLs for editing when enhance\_prompt=false.
* enhance\_prompt=true requires an existing preset\_id and 1–2 image URLs: product first, optional person/model reference second. Discover presets with GET /marketing-studio/image/presets.
* Reference images must be valid JPEG, PNG, or WebP. Oversized supported images are normalized before rendering.
* With enhancement enabled, aspect\_ratio=auto uses the preset ratio. With enhancement disabled, current production mappings use square output for auto.
* The 1k/2k/4k values are resolution tiers; exact pixel dimensions depend on the aspect ratio.
* quality accepts low, medium, high, xhigh, max and remains selectable with enhancement enabled.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/marketing-studio/image/flare \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
    "resolution": "2k",
    "aspect_ratio": "1:1",
    "quality": "high",
    "enhance_prompt": false
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A ceramic vase on a wooden table beside a sunlit window, soft '
                 'natural shadows, editorial photograph.',
       'resolution': '2k',
       'aspect_ratio': '1:1',
       'quality': 'high',
       'enhance_prompt': False}
  )
  result = higgsfield_client.subscribe(
      "marketing-studio/image/flare",
      arguments=arguments,
  )
  print(result["images"][0]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("marketing-studio/image/flare", {
    input:
      {
        "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
        "resolution": "2k",
        "aspect_ratio": "1:1",
        "quality": "high",
        "enhance_prompt": false
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.images?.[0]?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
  Maximum characters: `5000`.
</ParamField>

<ParamField type="string">
  Allowed values: `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`.
</ParamField>

<ParamField type="string">
  Identifier of a Marketing Studio image preset.
  Format: `uuid`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Minimum items: `0`.
  Maximum items: `16`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Allowed values: `"auto"`, `"low"`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"1k"`, `"2k"`, `"4k"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"auto"`, `"1:1"`, `"3:2"`, `"2:3"`, `"4:3"`, `"3:4"`, `"16:9"`, `"9:16"`, `"21:9"`.
</ParamField>

<ParamField type="boolean">
  Enable prompt enhancement for this workflow.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "allOf": [
      {
        "if": {
          "required": [
            "enhance_prompt"
          ],
          "properties": {
            "enhance_prompt": {
              "const": true
            }
          }
        },
        "then": {
          "required": [
            "preset_id",
            "image_urls"
          ],
          "properties": {
            "image_urls": {
              "maxItems": 2,
              "minItems": 1
            }
          }
        }
      }
    ],
    "title": "Marketing Studio Image 2.5 Flare",
    "required": [
      "prompt"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "maxLength": 5000,
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "quality": {
        "enum": [
          "low",
          "medium",
          "high",
          "xhigh",
          "max"
        ],
        "type": "string",
        "title": "Quality",
        "default": "high"
      },
      "preset_id": {
        "type": "string",
        "title": "Preset ID",
        "format": "uuid"
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "title": "Image URLs",
        "maxItems": 16,
        "minItems": 0
      },
      "moderation": {
        "enum": [
          "auto",
          "low"
        ],
        "type": "string",
        "default": "auto"
      },
      "resolution": {
        "enum": [
          "1k",
          "2k",
          "4k"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "2k"
      },
      "aspect_ratio": {
        "enum": [
          "auto",
          "1:1",
          "3:2",
          "2:3",
          "4:3",
          "3:4",
          "16:9",
          "9:16",
          "21:9"
        ],
        "type": "string",
        "title": "Aspect Ratio",
        "default": "auto"
      },
      "enhance_prompt": {
        "type": "boolean",
        "title": "Enhance prompt",
        "default": false
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "images": [
    {
      "url": "https://example.com/output.png"
    }
  ]
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Marketing Studio Image — 2.0 Alpha API
Source: https://docs.higgsfield.ai/docs/models/marketing-studio-image/generate-and-edit

2.0 Alpha with Marketing Studio Image: request parameters, examples and response handling.

<div />

[← Marketing Studio Image](/docs/models/marketing-studio-image)

**Endpoint:** `POST https://api.higgsfield.ai/marketing-studio/image`

**Endpoint ID:** `marketing-studio/image`

<a href="https://console.higgsfield.ai/models/marketing-studio%2Fimage/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Marketing Studio Image · 2.0 Alpha</span></span>
  <span>↗</span>
</a>

## Usage notes

* Omit image\_urls for text-to-image; provide up to 16 URLs for editing when enhance\_prompt=false.
* enhance\_prompt=true requires an existing preset\_id and 1–2 image URLs: product first, optional person/model reference second. Discover presets with GET /marketing-studio/image/presets.
* Reference images must be valid JPEG, PNG, or WebP. Oversized supported images are normalized before rendering.
* With enhancement enabled, aspect\_ratio=auto uses the preset ratio. With enhancement disabled, current production mappings use square output for auto.
* The 1k/2k/4k values are resolution tiers; exact pixel dimensions depend on the aspect ratio.
* With enhance\_prompt=true, quality must be high. This endpoint accepts low, medium, or high for unenhanced requests.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/marketing-studio/image \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
    "resolution": "2k",
    "aspect_ratio": "1:1",
    "quality": "high",
    "enhance_prompt": false
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A ceramic vase on a wooden table beside a sunlit window, soft '
                 'natural shadows, editorial photograph.',
       'resolution': '2k',
       'aspect_ratio': '1:1',
       'quality': 'high',
       'enhance_prompt': False}
  )
  result = higgsfield_client.subscribe(
      "marketing-studio/image",
      arguments=arguments,
  )
  print(result["images"][0]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("marketing-studio/image", {
    input:
      {
        "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
        "resolution": "2k",
        "aspect_ratio": "1:1",
        "quality": "high",
        "enhance_prompt": false
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.images?.[0]?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
  Maximum characters: `5000`.
</ParamField>

<ParamField type="string">
  Allowed values: `"low"`, `"medium"`, `"high"`.
</ParamField>

<ParamField type="string">
  Identifier of a Marketing Studio image preset.
  Format: `uuid`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Minimum items: `0`.
  Maximum items: `16`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Allowed values: `"auto"`, `"low"`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"1k"`, `"2k"`, `"4k"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"auto"`, `"1:1"`, `"3:2"`, `"2:3"`, `"4:3"`, `"3:4"`, `"16:9"`, `"9:16"`, `"21:9"`.
</ParamField>

<ParamField type="boolean">
  Enable prompt enhancement for this workflow.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "allOf": [
      {
        "if": {
          "required": [
            "enhance_prompt"
          ],
          "properties": {
            "enhance_prompt": {
              "const": true
            }
          }
        },
        "then": {
          "required": [
            "preset_id",
            "image_urls"
          ],
          "properties": {
            "quality": {
              "const": "high"
            },
            "image_urls": {
              "maxItems": 2,
              "minItems": 1
            }
          }
        }
      }
    ],
    "title": "Marketing Studio Image 2.0 Alpha",
    "required": [
      "prompt"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "maxLength": 5000,
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "quality": {
        "enum": [
          "low",
          "medium",
          "high"
        ],
        "type": "string",
        "default": "high"
      },
      "preset_id": {
        "type": "string",
        "title": "Preset ID",
        "format": "uuid"
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "title": "Image URLs",
        "maxItems": 16,
        "minItems": 0
      },
      "moderation": {
        "enum": [
          "auto",
          "low"
        ],
        "type": "string",
        "default": "auto"
      },
      "resolution": {
        "enum": [
          "1k",
          "2k",
          "4k"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "2k"
      },
      "aspect_ratio": {
        "enum": [
          "auto",
          "1:1",
          "3:2",
          "2:3",
          "4:3",
          "3:4",
          "16:9",
          "9:16",
          "21:9"
        ],
        "type": "string",
        "title": "Aspect Ratio",
        "default": "auto"
      },
      "enhance_prompt": {
        "type": "boolean",
        "title": "Enhance prompt",
        "default": false
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## List Marketing Studio presets

`GET https://api.higgsfield.ai/marketing-studio/image/presets`

Use this authenticated endpoint to retrieve valid `preset_id` values for enhanced requests.

| Query parameter | Type | Default | Description |
| - | - | - | - |
| `search` | string | — | Search preset or group names. Accepts 1–100 characters. |
| `size` | integer | `50` | Results per page. Accepts 1–100. |
| `cursor` | integer | `0` | Zero-based pagination offset; must be nonnegative. |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request GET \
  --url "https://api.higgsfield.ai/marketing-studio/image/presets?size=50&cursor=0" \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "total": 120,
  "cursor": 50,
  "items": [
    {
      "id": "<preset-uuid>",
      "type": "ads",
      "name": "Editorial product portrait",
      "cover_image": null,
      "metadata": {
        "aspect_ratio": "3:4",
        "group_name": "Editorial"
      },
      "format_slugs": []
    }
  ]
}
```

The response `cursor` is `null` when there are no more results.

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "images": [
    {
      "url": "https://example.com/output.png"
    }
  ]
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Marketing Studio Image — 2.5 Sunburst API
Source: https://docs.higgsfield.ai/docs/models/marketing-studio-image/sunburst

2.5 Sunburst with Marketing Studio Image: request parameters, examples and response handling.

<div />

[← Marketing Studio Image](/docs/models/marketing-studio-image)

**Endpoint:** `POST https://api.higgsfield.ai/marketing-studio/image/sunburst`

**Endpoint ID:** `marketing-studio/image/sunburst`

<a href="https://console.higgsfield.ai/models/marketing-studio%2Fimage%2Fsunburst/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Marketing Studio Image · 2.5 Sunburst</span></span>
  <span>↗</span>
</a>

## Usage notes

* Omit image\_urls for text-to-image; provide up to 16 URLs for editing when enhance\_prompt=false.
* enhance\_prompt=true requires an existing preset\_id and 1–2 image URLs: product first, optional person/model reference second. Discover presets with GET /marketing-studio/image/presets.
* Reference images must be valid JPEG, PNG, or WebP. Oversized supported images are normalized before rendering.
* With enhancement enabled, aspect\_ratio=auto uses the preset ratio. With enhancement disabled, current production mappings use square output for auto.
* The 1k/2k/4k values are resolution tiers; exact pixel dimensions depend on the aspect ratio.
* quality accepts low, medium, high, xhigh, max and remains selectable with enhancement enabled.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/marketing-studio/image/sunburst \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
    "resolution": "2k",
    "aspect_ratio": "1:1",
    "quality": "high",
    "enhance_prompt": false
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A ceramic vase on a wooden table beside a sunlit window, soft '
                 'natural shadows, editorial photograph.',
       'resolution': '2k',
       'aspect_ratio': '1:1',
       'quality': 'high',
       'enhance_prompt': False}
  )
  result = higgsfield_client.subscribe(
      "marketing-studio/image/sunburst",
      arguments=arguments,
  )
  print(result["images"][0]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("marketing-studio/image/sunburst", {
    input:
      {
        "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
        "resolution": "2k",
        "aspect_ratio": "1:1",
        "quality": "high",
        "enhance_prompt": false
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.images?.[0]?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
  Maximum characters: `5000`.
</ParamField>

<ParamField type="string">
  Allowed values: `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`.
</ParamField>

<ParamField type="string">
  Identifier of a Marketing Studio image preset.
  Format: `uuid`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Minimum items: `0`.
  Maximum items: `16`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Allowed values: `"auto"`, `"low"`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"1k"`, `"2k"`, `"4k"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"auto"`, `"1:1"`, `"3:2"`, `"2:3"`, `"4:3"`, `"3:4"`, `"16:9"`, `"9:16"`, `"21:9"`.
</ParamField>

<ParamField type="boolean">
  Enable prompt enhancement for this workflow.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "allOf": [
      {
        "if": {
          "required": [
            "enhance_prompt"
          ],
          "properties": {
            "enhance_prompt": {
              "const": true
            }
          }
        },
        "then": {
          "required": [
            "preset_id",
            "image_urls"
          ],
          "properties": {
            "image_urls": {
              "maxItems": 2,
              "minItems": 1
            }
          }
        }
      }
    ],
    "title": "Marketing Studio Image 2.5 Sunburst",
    "required": [
      "prompt"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "maxLength": 5000,
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "quality": {
        "enum": [
          "low",
          "medium",
          "high",
          "xhigh",
          "max"
        ],
        "type": "string",
        "title": "Quality",
        "default": "high"
      },
      "preset_id": {
        "type": "string",
        "title": "Preset ID",
        "format": "uuid"
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "title": "Image URLs",
        "maxItems": 16,
        "minItems": 0
      },
      "moderation": {
        "enum": [
          "auto",
          "low"
        ],
        "type": "string",
        "default": "auto"
      },
      "resolution": {
        "enum": [
          "1k",
          "2k",
          "4k"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "2k"
      },
      "aspect_ratio": {
        "enum": [
          "auto",
          "1:1",
          "3:2",
          "2:3",
          "4:3",
          "3:4",
          "16:9",
          "9:16",
          "21:9"
        ],
        "type": "string",
        "title": "Aspect Ratio",
        "default": "auto"
      },
      "enhance_prompt": {
        "type": "boolean",
        "title": "Enhance prompt",
        "default": false
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "images": [
    {
      "url": "https://example.com/output.png"
    }
  ]
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# MiniMax H3 API
Source: https://docs.higgsfield.ai/docs/models/minimax-h3

Generate videos from text, frames or multimodal references.

<div />

Generate videos from text, frames or multimodal references.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to video](/docs/models/minimax-h3/text-to-video) | `POST /minimax/h3/text-to-video` |
| [Image to video](/docs/models/minimax-h3/image-to-video) | `POST /minimax/h3/image-to-video` |
| [Reference to video](/docs/models/minimax-h3/reference-to-video) | `POST /minimax/h3/reference-to-video` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# MiniMax H3 — Image to video API
Source: https://docs.higgsfield.ai/docs/models/minimax-h3/image-to-video

Image to video with MiniMax H3: request parameters, examples and response handling.

<div />

[← MiniMax H3](/docs/models/minimax-h3)

**Endpoint:** `POST https://api.higgsfield.ai/minimax/h3/image-to-video`

**Endpoint ID:** `minimax/h3/image-to-video`

<a href="https://console.higgsfield.ai/models/minimax%2Fh3%2Fimage-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>MiniMax H3 · Image to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Resolution is fixed to the case-sensitive schema value "2K". The prompt must contain non-whitespace text; the current provider serializer uses only its first 7,000 characters.
* The output aspect ratio follows the input keyframe even when aspect\_ratio is supplied. end\_image\_url is an optional last frame.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/minimax/h3/image-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
    "image_url": "https://example.com/input.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.',
       'image_url': 'https://example.com/input.jpg'}
  )
  result = higgsfield_client.subscribe(
      "minimax/h3/image-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("minimax/h3/image-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
        "image_url": "https://example.com/input.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `5`.
  Maximum: `15`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"2K"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"auto"`, `"adaptive"`, `"21:9"`, `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`.
</ParamField>

<ParamField type="string">
  Format: `uri`.
</ParamField>

<ParamField type="boolean">
  See the complete JSON schema below.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "MiniMax H3 Image to Video Playground",
    "required": [
      "prompt",
      "image_url"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 5
      },
      "image_url": {
        "type": "string",
        "title": "First frame URL",
        "format": "uri"
      },
      "resolution": {
        "enum": [
          "2K"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "2K"
      },
      "aspect_ratio": {
        "enum": [
          "auto",
          "adaptive",
          "21:9",
          "16:9",
          "4:3",
          "1:1",
          "3:4",
          "9:16"
        ],
        "type": "string",
        "title": "Aspect ratio",
        "default": "auto"
      },
      "end_image_url": {
        "type": "string",
        "title": "Last frame URL",
        "format": "uri"
      },
      "aigc_watermark": {
        "type": "boolean",
        "title": "AIGC watermark",
        "default": false
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# MiniMax H3 — Reference to video API
Source: https://docs.higgsfield.ai/docs/models/minimax-h3/reference-to-video

Reference to video with MiniMax H3: request parameters, examples and response handling.

<div />

[← MiniMax H3](/docs/models/minimax-h3)

**Endpoint:** `POST https://api.higgsfield.ai/minimax/h3/reference-to-video`

**Endpoint ID:** `minimax/h3/reference-to-video`

<a href="https://console.higgsfield.ai/models/minimax%2Fh3%2Freference-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>MiniMax H3 · Reference to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Resolution is fixed to the case-sensitive schema value "2K". The prompt must contain non-whitespace text; the current provider serializer uses only its first 7,000 characters.
* Provide at least one image or video reference. Audio references require an image or video reference and cannot be used alone.
* Reference media may be cropped, resized, transcoded and trimmed. Video duration and audio duration are each normalized to fit within the provider's 15-second total budget.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/minimax/h3/reference-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
    "image_urls": [
      "https://example.com/input.jpg"
    ]
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.',
       'image_urls': ['https://example.com/input.jpg']}
  )
  result = higgsfield_client.subscribe(
      "minimax/h3/reference-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("minimax/h3/reference-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
        "image_urls": [
          "https://example.com/input.jpg"
        ]
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `5`.
  Maximum: `15`.
</ParamField>

<ParamField type="array">
  Ordered public audio reference URLs.
  Minimum items: `0`.
  Maximum items: `3`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Minimum items: `1`.
  Maximum items: `9`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"2K"`.
</ParamField>

<ParamField type="array">
  Ordered public video reference URLs.
  Minimum items: `1`.
  Maximum items: `3`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"auto"`, `"adaptive"`, `"21:9"`, `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`.
</ParamField>

<ParamField type="boolean">
  See the complete JSON schema below.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "if": {
      "required": [
        "image_urls"
      ]
    },
    "else": {
      "required": [
        "video_urls"
      ]
    },
    "type": "object",
    "title": "MiniMax H3 Reference to Video Playground",
    "required": [
      "prompt"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 5
      },
      "audio_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "title": "Reference audio URLs",
        "maxItems": 3,
        "minItems": 0
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "title": "Reference image URLs",
        "maxItems": 9,
        "minItems": 1
      },
      "resolution": {
        "enum": [
          "2K"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "2K"
      },
      "video_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "title": "Reference video URLs",
        "maxItems": 3,
        "minItems": 1
      },
      "aspect_ratio": {
        "enum": [
          "auto",
          "adaptive",
          "21:9",
          "16:9",
          "4:3",
          "1:1",
          "3:4",
          "9:16"
        ],
        "type": "string",
        "title": "Aspect ratio",
        "default": "auto"
      },
      "aigc_watermark": {
        "type": "boolean",
        "title": "AIGC watermark",
        "default": false
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# MiniMax H3 — Text to video API
Source: https://docs.higgsfield.ai/docs/models/minimax-h3/text-to-video

Text to video with MiniMax H3: request parameters, examples and response handling.

<div />

[← MiniMax H3](/docs/models/minimax-h3)

**Endpoint:** `POST https://api.higgsfield.ai/minimax/h3/text-to-video`

**Endpoint ID:** `minimax/h3/text-to-video`

<a href="https://console.higgsfield.ai/models/minimax%2Fh3%2Ftext-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>MiniMax H3 · Text to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Resolution is fixed to the case-sensitive schema value "2K". The prompt must contain non-whitespace text; the current provider serializer uses only its first 7,000 characters.
* For text-only requests, aspect\_ratio="auto" or "adaptive" resolves to 16:9.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/minimax/h3/text-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.'}
  )
  result = higgsfield_client.subscribe(
      "minimax/h3/text-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("minimax/h3/text-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `5`.
  Maximum: `15`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"2K"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"auto"`, `"adaptive"`, `"21:9"`, `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`.
</ParamField>

<ParamField type="boolean">
  See the complete JSON schema below.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "MiniMax H3 Text to Video Playground",
    "required": [
      "prompt"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 5
      },
      "resolution": {
        "enum": [
          "2K"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "2K"
      },
      "aspect_ratio": {
        "enum": [
          "auto",
          "adaptive",
          "21:9",
          "16:9",
          "4:3",
          "1:1",
          "3:4",
          "9:16"
        ],
        "type": "string",
        "title": "Aspect ratio",
        "default": "auto"
      },
      "aigc_watermark": {
        "type": "boolean",
        "title": "AIGC watermark",
        "default": false
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# PixVerse V6 API
Source: https://docs.higgsfield.ai/docs/models/pixverse-v6

Generate videos from text or images with optional sound.

<div />

Generate videos from text or images with optional sound.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to video](/docs/models/pixverse-v6/text-to-video) | `POST /pixverse/v6/text-to-video` |
| [Image to video](/docs/models/pixverse-v6/image-to-video) | `POST /pixverse/v6/image-to-video` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# PixVerse V6 — Image to video API
Source: https://docs.higgsfield.ai/docs/models/pixverse-v6/image-to-video

Image to video with PixVerse V6: request parameters, examples and response handling.

<div />

[← PixVerse V6](/docs/models/pixverse-v6)

**Endpoint:** `POST https://api.higgsfield.ai/pixverse/v6/image-to-video`

**Endpoint ID:** `pixverse/v6/image-to-video`

<a href="https://console.higgsfield.ai/models/pixverse%2Fv6%2Fimage-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>PixVerse V6 · Image to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* duration is a number from 1 to 15, so the schema allows fractional values. If negative\_prompt is supplied, it must contain 1–2,048 characters.
* Use image\_url for the first frame and optional end\_image\_url for the last frame. This endpoint has no aspect\_ratio parameter; framing comes from the input image.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/pixverse/v6/image-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
    "image_url": "https://example.com/input.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.',
       'image_url': 'https://example.com/input.jpg'}
  )
  result = higgsfield_client.subscribe(
      "pixverse/v6/image-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("pixverse/v6/image-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
        "image_url": "https://example.com/input.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `0`.
  Maximum: `2147483647`.
</ParamField>

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
  Maximum characters: `5000`.
</ParamField>

<ParamField type="number">
  Requested output duration in seconds.
  Minimum: `1`.
  Maximum: `15`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"360p"`, `"540p"`, `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="string">
  Format: `uri`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<ParamField type="string">
  Content or visual features to avoid.
  Minimum characters: `1`.
  Maximum characters: `2048`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "PixVerse V6 Image to Video Playground",
    "required": [
      "prompt",
      "image_url"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "title": "Seed",
        "maximum": 2147483647,
        "minimum": 0
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "maxLength": 5000,
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "number",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 1
      },
      "image_url": {
        "type": "string",
        "title": "First frame",
        "format": "uri"
      },
      "resolution": {
        "enum": [
          "360p",
          "540p",
          "720p",
          "1080p"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "720p"
      },
      "end_image_url": {
        "type": "string",
        "title": "Last frame",
        "format": "uri"
      },
      "generate_audio": {
        "type": "boolean",
        "title": "Generate audio",
        "default": true
      },
      "negative_prompt": {
        "type": "string",
        "title": "Negative prompt",
        "maxLength": 2048,
        "minLength": 1
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# PixVerse V6 — Text to video API
Source: https://docs.higgsfield.ai/docs/models/pixverse-v6/text-to-video

Text to video with PixVerse V6: request parameters, examples and response handling.

<div />

[← PixVerse V6](/docs/models/pixverse-v6)

**Endpoint:** `POST https://api.higgsfield.ai/pixverse/v6/text-to-video`

**Endpoint ID:** `pixverse/v6/text-to-video`

<a href="https://console.higgsfield.ai/models/pixverse%2Fv6%2Ftext-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>PixVerse V6 · Text to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* duration is a number from 1 to 15, so the schema allows fractional values. If negative\_prompt is supplied, it must contain 1–2,048 characters.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/pixverse/v6/text-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.'}
  )
  result = higgsfield_client.subscribe(
      "pixverse/v6/text-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("pixverse/v6/text-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `0`.
  Maximum: `2147483647`.
</ParamField>

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
  Maximum characters: `5000`.
</ParamField>

<ParamField type="number">
  Requested output duration in seconds.
  Minimum: `1`.
  Maximum: `15`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"360p"`, `"540p"`, `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<ParamField type="string">
  Content or visual features to avoid.
  Minimum characters: `1`.
  Maximum characters: `2048`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "PixVerse V6 Text to Video Playground",
    "required": [
      "prompt"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "title": "Seed",
        "maximum": 2147483647,
        "minimum": 0
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "maxLength": 5000,
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "number",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 1
      },
      "resolution": {
        "enum": [
          "360p",
          "540p",
          "720p",
          "1080p"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "720p"
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "4:3",
          "1:1",
          "3:4",
          "9:16"
        ],
        "type": "string",
        "title": "Aspect ratio",
        "default": "16:9"
      },
      "generate_audio": {
        "type": "boolean",
        "title": "Generate audio",
        "default": true
      },
      "negative_prompt": {
        "type": "string",
        "title": "Negative prompt",
        "maxLength": 2048,
        "minLength": 1
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Qwen Image 3 API
Source: https://docs.higgsfield.ai/docs/models/qwen-image-3

Generate images or edit one to three reference images with optional prompt reasoning.

<div />

Generate images or edit one to three reference images with optional prompt reasoning.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to image](/docs/models/qwen-image-3/text-to-image) | `POST /alibaba/qwen-image-3/text-to-image` |
| [Edit images](/docs/models/qwen-image-3/edit) | `POST /alibaba/qwen-image-3/edit` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Qwen Image 3 — Edit images API
Source: https://docs.higgsfield.ai/docs/models/qwen-image-3/edit

Edit images with Qwen Image 3: request parameters, examples and response handling.

<div />

[← Qwen Image 3](/docs/models/qwen-image-3)

**Endpoint:** `POST https://api.higgsfield.ai/alibaba/qwen-image-3/edit`

**Endpoint ID:** `alibaba/qwen-image-3/edit`

<a href="https://console.higgsfield.ai/models/alibaba%2Fqwen-image-3%2Fedit/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Qwen Image 3 · Edit images</span></span>
  <span>↗</span>
</a>

## Usage notes

* Provide 1–3 ordered reference image URLs. The list is required and cannot be empty.
* enable\_thinking defaults to true and requires prompt\_extend=true. Set both to false to disable enhancement.
* prompt\_extend\_mode accepts only direct; agent enhancement is unavailable on editing requests.
* prompt must contain non-whitespace text. The 2k square output tier maps to 1536 by 1536 pixels.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/alibaba/qwen-image-3/edit \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "Change the vase to matte blue while keeping the composition.",
    "image_urls": [
      "https://example.com/input-image.jpg"
    ],
    "resolution": "1k",
    "aspect_ratio": "1:1"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'Change the vase to matte blue while keeping the composition.',
       'image_urls': ['https://example.com/input-image.jpg'],
       'resolution': '1k',
       'aspect_ratio': '1:1'}
  )
  result = higgsfield_client.subscribe(
      "alibaba/qwen-image-3/edit",
      arguments=arguments,
  )
  print(result["images"][0]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("alibaba/qwen-image-3/edit", {
    input:
      {
        "prompt": "Change the vase to matte blue while keeping the composition.",
        "image_urls": [
          "https://example.com/input-image.jpg"
        ],
        "resolution": "1k",
        "aspect_ratio": "1:1"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.images?.[0]?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Optional random seed for similar, reproducible results.
  Minimum: `0`.
  Maximum: `2147483647`.
</ParamField>

<ParamField type="string">
  Positive prompt or editing instruction in Chinese or English. Alibaba recommends at most 4,500 tokens.
  Minimum characters: `1`.
</ParamField>

<ParamField type="array">
  One to three ordered public image URLs used as editing references.
  Minimum items: `1`.
  Maximum items: `3`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier. Both tiers produce PNG images.
  Allowed values: `"1k"`, `"2k"`.
</ParamField>

<ParamField type="string">
  Output aspect ratio. Exact provider-recommended dimensions are selected automatically.
  Allowed values: `"1:1"`, `"2:3"`, `"3:2"`, `"3:4"`, `"4:3"`, `"7:9"`, `"9:7"`, `"9:16"`, `"16:9"`, `"21:9"`.
</ParamField>

<ParamField type="boolean">
  Improve the prompt before generation. Required when thinking mode is enabled.
</ParamField>

<ParamField type="boolean">
  Use model reasoning to improve image quality. Requires prompt enhancement.
</ParamField>

<ParamField type="string">
  Content, styles, or artifacts to avoid in the output.
</ParamField>

<ParamField type="string">
  Direct enhancement is available for every request; agent enhancement is text-to-image only.
  Allowed values: `"direct"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "allOf": [
      {
        "if": {
          "required": [
            "enable_thinking"
          ],
          "properties": {
            "enable_thinking": {
              "const": true
            }
          }
        },
        "then": {
          "required": [
            "prompt_extend"
          ],
          "properties": {
            "prompt_extend": {
              "const": true
            }
          }
        }
      }
    ],
    "title": "Qwen Image 3 Edit",
    "required": [
      "prompt",
      "image_urls"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "maximum": 2147483647,
        "minimum": 0,
        "description": "Optional random seed for similar, reproducible results."
      },
      "prompt": {
        "type": "string",
        "minLength": 1,
        "description": "Positive prompt or editing instruction in Chinese or English. Alibaba recommends at most 4,500 tokens."
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "maxItems": 3,
        "minItems": 1,
        "description": "One to three ordered public image URLs used as editing references."
      },
      "resolution": {
        "enum": [
          "1k",
          "2k"
        ],
        "type": "string",
        "default": "1k",
        "description": "Output resolution tier. Both tiers produce PNG images."
      },
      "aspect_ratio": {
        "enum": [
          "1:1",
          "2:3",
          "3:2",
          "3:4",
          "4:3",
          "7:9",
          "9:7",
          "9:16",
          "16:9",
          "21:9"
        ],
        "type": "string",
        "default": "1:1",
        "description": "Output aspect ratio. Exact provider-recommended dimensions are selected automatically."
      },
      "prompt_extend": {
        "type": "boolean",
        "default": true,
        "description": "Improve the prompt before generation. Required when thinking mode is enabled."
      },
      "enable_thinking": {
        "type": "boolean",
        "default": true,
        "description": "Use model reasoning to improve image quality. Requires prompt enhancement."
      },
      "negative_prompt": {
        "type": "string",
        "description": "Content, styles, or artifacts to avoid in the output."
      },
      "prompt_extend_mode": {
        "enum": [
          "direct"
        ],
        "type": "string",
        "default": "direct",
        "description": "Direct enhancement is available for every request; agent enhancement is text-to-image only."
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "images": [
    {
      "url": "https://example.com/output.png"
    }
  ]
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Qwen Image 3 — Text to image API
Source: https://docs.higgsfield.ai/docs/models/qwen-image-3/text-to-image

Text to image with Qwen Image 3: request parameters, examples and response handling.

<div />

[← Qwen Image 3](/docs/models/qwen-image-3)

**Endpoint:** `POST https://api.higgsfield.ai/alibaba/qwen-image-3/text-to-image`

**Endpoint ID:** `alibaba/qwen-image-3/text-to-image`

<a href="https://console.higgsfield.ai/models/alibaba%2Fqwen-image-3%2Ftext-to-image/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Qwen Image 3 · Text to image</span></span>
  <span>↗</span>
</a>

## Usage notes

* prompt must contain non-whitespace text. The schema imposes no character maximum; its 4,500-token guidance is advisory.
* enable\_thinking defaults to true and requires prompt\_extend=true. Set both to false to disable enhancement.
* prompt\_extend\_mode supports direct or agent. No reference images are accepted by this endpoint.
* resolution is a tier; 2k square maps to 1536 by 1536 pixels, not 2048 by 2048.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/alibaba/qwen-image-3/text-to-image \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
    "resolution": "1k",
    "aspect_ratio": "1:1"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A ceramic vase on a wooden table beside a sunlit window, soft '
                 'natural shadows, editorial photograph.',
       'resolution': '1k',
       'aspect_ratio': '1:1'}
  )
  result = higgsfield_client.subscribe(
      "alibaba/qwen-image-3/text-to-image",
      arguments=arguments,
  )
  print(result["images"][0]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("alibaba/qwen-image-3/text-to-image", {
    input:
      {
        "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
        "resolution": "1k",
        "aspect_ratio": "1:1"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.images?.[0]?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Optional random seed for similar, reproducible results.
  Minimum: `0`.
  Maximum: `2147483647`.
</ParamField>

<ParamField type="string">
  Positive prompt or editing instruction in Chinese or English. Alibaba recommends at most 4,500 tokens.
  Minimum characters: `1`.
</ParamField>

<ParamField type="string">
  Output resolution tier. Both tiers produce PNG images.
  Allowed values: `"1k"`, `"2k"`.
</ParamField>

<ParamField type="string">
  Output aspect ratio. Exact provider-recommended dimensions are selected automatically.
  Allowed values: `"1:1"`, `"2:3"`, `"3:2"`, `"3:4"`, `"4:3"`, `"7:9"`, `"9:7"`, `"9:16"`, `"16:9"`, `"21:9"`.
</ParamField>

<ParamField type="boolean">
  Improve the prompt before generation. Required when thinking mode is enabled.
</ParamField>

<ParamField type="boolean">
  Use model reasoning to improve image quality. Requires prompt enhancement.
</ParamField>

<ParamField type="string">
  Content, styles, or artifacts to avoid in the output.
</ParamField>

<ParamField type="string">
  Direct enhancement is available for every request; agent enhancement is text-to-image only.
  Allowed values: `"direct"`, `"agent"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "allOf": [
      {
        "if": {
          "required": [
            "enable_thinking"
          ],
          "properties": {
            "enable_thinking": {
              "const": true
            }
          }
        },
        "then": {
          "required": [
            "prompt_extend"
          ],
          "properties": {
            "prompt_extend": {
              "const": true
            }
          }
        }
      }
    ],
    "title": "Qwen Image 3 Text to Image",
    "required": [
      "prompt"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "maximum": 2147483647,
        "minimum": 0,
        "description": "Optional random seed for similar, reproducible results."
      },
      "prompt": {
        "type": "string",
        "minLength": 1,
        "description": "Positive prompt or editing instruction in Chinese or English. Alibaba recommends at most 4,500 tokens."
      },
      "resolution": {
        "enum": [
          "1k",
          "2k"
        ],
        "type": "string",
        "default": "1k",
        "description": "Output resolution tier. Both tiers produce PNG images."
      },
      "aspect_ratio": {
        "enum": [
          "1:1",
          "2:3",
          "3:2",
          "3:4",
          "4:3",
          "7:9",
          "9:7",
          "9:16",
          "16:9",
          "21:9"
        ],
        "type": "string",
        "default": "1:1",
        "description": "Output aspect ratio. Exact provider-recommended dimensions are selected automatically."
      },
      "prompt_extend": {
        "type": "boolean",
        "default": true,
        "description": "Improve the prompt before generation. Required when thinking mode is enabled."
      },
      "enable_thinking": {
        "type": "boolean",
        "default": true,
        "description": "Use model reasoning to improve image quality. Requires prompt enhancement."
      },
      "negative_prompt": {
        "type": "string",
        "description": "Content, styles, or artifacts to avoid in the output."
      },
      "prompt_extend_mode": {
        "enum": [
          "direct",
          "agent"
        ],
        "type": "string",
        "default": "direct",
        "description": "Direct enhancement is available for every request; agent enhancement is text-to-image only."
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "images": [
    {
      "url": "https://example.com/output.png"
    }
  ]
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Recraft V4.1 API
Source: https://docs.higgsfield.ai/docs/models/recraft-v4-1

Generate 1K images with RGB palette and background controls.

<div />

Generate 1K images with RGB palette and background controls.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to image](/docs/models/recraft-v4-1/text-to-image) | `POST /recraft/v4.1/text-to-image` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Recraft V4.1 Pro API
Source: https://docs.higgsfield.ai/docs/models/recraft-v4-1-pro

Generate 2K images with RGB palette and background controls.

<div />

Generate 2K images with RGB palette and background controls.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to image](/docs/models/recraft-v4-1-pro/generate) | `POST /recraft/v4.1/pro/text-to-image` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Recraft V4.1 Pro — Text to image API
Source: https://docs.higgsfield.ai/docs/models/recraft-v4-1-pro/generate

Text to image with Recraft V4.1 Pro: request parameters, examples and response handling.

<div />

[← Recraft V4.1 Pro](/docs/models/recraft-v4-1-pro)

**Endpoint:** `POST https://api.higgsfield.ai/recraft/v4.1/pro/text-to-image`

**Endpoint ID:** `recraft/v4.1/pro/text-to-image`

<a href="https://console.higgsfield.ai/models/recraft%2Fv4.1%2Fpro%2Ftext-to-image/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Recraft V4.1 Pro · Text to image</span></span>
  <span>↗</span>
</a>

## Usage notes

* This variant accepts only resolution=2k; use the separate standard/Pro endpoint for the other resolution tier.
* colors is an array of objects shaped as \{"rgb": \[R, G, B]}; background\_color is one such object. Every RGB value is an integer 0–255, with exactly three entries.
* output\_format is jpg, png, or webp; default is jpg. No reference-image input is declared.
* prompt must contain 1–10000 characters. Fourteen aspect-ratio values are listed in the schema, including 6:10, 14:10, and 10:14.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/recraft/v4.1/pro/text-to-image \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
    "resolution": "2k",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "colors": [
      {
        "rgb": [
          40,
          90,
          150
        ]
      }
    ],
    "background_color": {
      "rgb": [
        245,
        242,
        235
      ]
    }
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A ceramic vase on a wooden table beside a sunlit window, soft '
                 'natural shadows, editorial photograph.',
       'resolution': '2k',
       'aspect_ratio': '1:1',
       'output_format': 'png',
       'colors': [{'rgb': [40, 90, 150]}],
       'background_color': {'rgb': [245, 242, 235]}}
  )
  result = higgsfield_client.subscribe(
      "recraft/v4.1/pro/text-to-image",
      arguments=arguments,
  )
  print(result["images"][0]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("recraft/v4.1/pro/text-to-image", {
    input:
      {
        "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
        "resolution": "2k",
        "aspect_ratio": "1:1",
        "output_format": "png",
        "colors": [
          {
            "rgb": [
              40,
              90,
              150
            ]
          }
        ],
        "background_color": {
          "rgb": [
            245,
            242,
            235
          ]
        }
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.images?.[0]?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="array">
  Preferred RGB palette for the generated image.

  <Expandable title="Nested fields">
    <ParamField type="array">
      Minimum items: `3`.
      Maximum items: `3`.
      Each item: integer. Minimum: `0`. Maximum: `255`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
  Maximum characters: `10000`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"2k"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"1:1"`, `"2:1"`, `"1:2"`, `"3:2"`, `"2:3"`, `"4:3"`, `"3:4"`, `"5:4"`, `"4:5"`, `"6:10"`, `"14:10"`, `"10:14"`, `"16:9"`, `"9:16"`.
</ParamField>

<ParamField type="string">
  Output file format.
  Allowed values: `"jpg"`, `"png"`, `"webp"`.
</ParamField>

<ParamField type="object">
  Preferred RGB background color.

  <Expandable title="Nested fields">
    <ParamField type="array">
      Minimum items: `3`.
      Maximum items: `3`.
      Each item: integer. Minimum: `0`. Maximum: `255`.
    </ParamField>
  </Expandable>
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Recraft V4.1 Pro Playground",
    "required": [
      "prompt"
    ],
    "properties": {
      "colors": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "rgb"
          ],
          "properties": {
            "rgb": {
              "type": "array",
              "items": {
                "type": "integer",
                "maximum": 255,
                "minimum": 0
              },
              "maxItems": 3,
              "minItems": 3
            }
          }
        },
        "title": "Colors"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "maxLength": 10000,
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "resolution": {
        "enum": [
          "2k"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "2k"
      },
      "aspect_ratio": {
        "enum": [
          "1:1",
          "2:1",
          "1:2",
          "3:2",
          "2:3",
          "4:3",
          "3:4",
          "5:4",
          "4:5",
          "6:10",
          "14:10",
          "10:14",
          "16:9",
          "9:16"
        ],
        "type": "string",
        "title": "Aspect ratio",
        "default": "1:1"
      },
      "output_format": {
        "enum": [
          "jpg",
          "png",
          "webp"
        ],
        "type": "string",
        "title": "Output format",
        "default": "jpg"
      },
      "background_color": {
        "type": "object",
        "title": "Background color",
        "required": [
          "rgb"
        ],
        "properties": {
          "rgb": {
            "type": "array",
            "items": {
              "type": "integer",
              "maximum": 255,
              "minimum": 0
            },
            "maxItems": 3,
            "minItems": 3
          }
        }
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "images": [
    {
      "url": "https://example.com/output.png"
    }
  ]
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Recraft V4.1 Utility API
Source: https://docs.higgsfield.ai/docs/models/recraft-v4-1-utility

Generate 1K images with RGB palette and background controls.

<div />

Generate 1K images with RGB palette and background controls.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to image](/docs/models/recraft-v4-1-utility/text-to-image) | `POST /recraft/v4.1/utility/text-to-image` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Recraft V4.1 Utility Pro API
Source: https://docs.higgsfield.ai/docs/models/recraft-v4-1-utility-pro

Generate 2K images with RGB palette and background controls.

<div />

Generate 2K images with RGB palette and background controls.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to image](/docs/models/recraft-v4-1-utility-pro/text-to-image) | `POST /recraft/v4.1/utility/pro/text-to-image` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Recraft V4.1 Utility Pro — Text to image API
Source: https://docs.higgsfield.ai/docs/models/recraft-v4-1-utility-pro/text-to-image

Text to image with Recraft V4.1 Utility Pro: request parameters, examples and response handling.

<div />

[← Recraft V4.1 Utility Pro](/docs/models/recraft-v4-1-utility-pro)

**Endpoint:** `POST https://api.higgsfield.ai/recraft/v4.1/utility/pro/text-to-image`

**Endpoint ID:** `recraft/v4.1/utility/pro/text-to-image`

<a href="https://console.higgsfield.ai/models/recraft%2Fv4.1%2Futility%2Fpro%2Ftext-to-image/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Recraft V4.1 Utility Pro · Text to image</span></span>
  <span>↗</span>
</a>

## Usage notes

* This variant accepts only resolution=2k; use the separate standard/Pro endpoint for the other resolution tier.
* colors is an array of objects shaped as \{"rgb": \[R, G, B]}; background\_color is one such object. Every RGB value is an integer 0–255, with exactly three entries.
* output\_format is jpg, png, or webp; default is jpg. No reference-image input is declared.
* prompt must contain 1–10000 characters. Fourteen aspect-ratio values are listed in the schema, including 6:10, 14:10, and 10:14.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/recraft/v4.1/utility/pro/text-to-image \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
    "resolution": "2k",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "colors": [
      {
        "rgb": [
          40,
          90,
          150
        ]
      }
    ],
    "background_color": {
      "rgb": [
        245,
        242,
        235
      ]
    }
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A ceramic vase on a wooden table beside a sunlit window, soft '
                 'natural shadows, editorial photograph.',
       'resolution': '2k',
       'aspect_ratio': '1:1',
       'output_format': 'png',
       'colors': [{'rgb': [40, 90, 150]}],
       'background_color': {'rgb': [245, 242, 235]}}
  )
  result = higgsfield_client.subscribe(
      "recraft/v4.1/utility/pro/text-to-image",
      arguments=arguments,
  )
  print(result["images"][0]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("recraft/v4.1/utility/pro/text-to-image", {
    input:
      {
        "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
        "resolution": "2k",
        "aspect_ratio": "1:1",
        "output_format": "png",
        "colors": [
          {
            "rgb": [
              40,
              90,
              150
            ]
          }
        ],
        "background_color": {
          "rgb": [
            245,
            242,
            235
          ]
        }
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.images?.[0]?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="array">
  Preferred RGB palette for the generated image.

  <Expandable title="Nested fields">
    <ParamField type="array">
      Minimum items: `3`.
      Maximum items: `3`.
      Each item: integer. Minimum: `0`. Maximum: `255`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
  Maximum characters: `10000`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"2k"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"1:1"`, `"2:1"`, `"1:2"`, `"3:2"`, `"2:3"`, `"4:3"`, `"3:4"`, `"5:4"`, `"4:5"`, `"6:10"`, `"14:10"`, `"10:14"`, `"16:9"`, `"9:16"`.
</ParamField>

<ParamField type="string">
  Output file format.
  Allowed values: `"jpg"`, `"png"`, `"webp"`.
</ParamField>

<ParamField type="object">
  Preferred RGB background color.

  <Expandable title="Nested fields">
    <ParamField type="array">
      Minimum items: `3`.
      Maximum items: `3`.
      Each item: integer. Minimum: `0`. Maximum: `255`.
    </ParamField>
  </Expandable>
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Recraft V4.1 Utility Pro Playground",
    "required": [
      "prompt"
    ],
    "properties": {
      "colors": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "rgb"
          ],
          "properties": {
            "rgb": {
              "type": "array",
              "items": {
                "type": "integer",
                "maximum": 255,
                "minimum": 0
              },
              "maxItems": 3,
              "minItems": 3
            }
          }
        },
        "title": "Colors"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "maxLength": 10000,
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "resolution": {
        "enum": [
          "2k"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "2k"
      },
      "aspect_ratio": {
        "enum": [
          "1:1",
          "2:1",
          "1:2",
          "3:2",
          "2:3",
          "4:3",
          "3:4",
          "5:4",
          "4:5",
          "6:10",
          "14:10",
          "10:14",
          "16:9",
          "9:16"
        ],
        "type": "string",
        "title": "Aspect ratio",
        "default": "1:1"
      },
      "output_format": {
        "enum": [
          "jpg",
          "png",
          "webp"
        ],
        "type": "string",
        "title": "Output format",
        "default": "jpg"
      },
      "background_color": {
        "type": "object",
        "title": "Background color",
        "required": [
          "rgb"
        ],
        "properties": {
          "rgb": {
            "type": "array",
            "items": {
              "type": "integer",
              "maximum": 255,
              "minimum": 0
            },
            "maxItems": 3,
            "minItems": 3
          }
        }
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "images": [
    {
      "url": "https://example.com/output.png"
    }
  ]
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Recraft V4.1 Utility — Text to image API
Source: https://docs.higgsfield.ai/docs/models/recraft-v4-1-utility/text-to-image

Text to image with Recraft V4.1 Utility: request parameters, examples and response handling.

<div />

[← Recraft V4.1 Utility](/docs/models/recraft-v4-1-utility)

**Endpoint:** `POST https://api.higgsfield.ai/recraft/v4.1/utility/text-to-image`

**Endpoint ID:** `recraft/v4.1/utility/text-to-image`

<a href="https://console.higgsfield.ai/models/recraft%2Fv4.1%2Futility%2Ftext-to-image/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Recraft V4.1 Utility · Text to image</span></span>
  <span>↗</span>
</a>

## Usage notes

* This variant accepts only resolution=1k; use the separate standard/Pro endpoint for the other resolution tier.
* colors is an array of objects shaped as \{"rgb": \[R, G, B]}; background\_color is one such object. Every RGB value is an integer 0–255, with exactly three entries.
* output\_format is jpg, png, or webp; default is jpg. No reference-image input is declared.
* prompt must contain 1–10000 characters. Fourteen aspect-ratio values are listed in the schema, including 6:10, 14:10, and 10:14.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/recraft/v4.1/utility/text-to-image \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
    "resolution": "1k",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "colors": [
      {
        "rgb": [
          40,
          90,
          150
        ]
      }
    ],
    "background_color": {
      "rgb": [
        245,
        242,
        235
      ]
    }
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A ceramic vase on a wooden table beside a sunlit window, soft '
                 'natural shadows, editorial photograph.',
       'resolution': '1k',
       'aspect_ratio': '1:1',
       'output_format': 'png',
       'colors': [{'rgb': [40, 90, 150]}],
       'background_color': {'rgb': [245, 242, 235]}}
  )
  result = higgsfield_client.subscribe(
      "recraft/v4.1/utility/text-to-image",
      arguments=arguments,
  )
  print(result["images"][0]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("recraft/v4.1/utility/text-to-image", {
    input:
      {
        "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
        "resolution": "1k",
        "aspect_ratio": "1:1",
        "output_format": "png",
        "colors": [
          {
            "rgb": [
              40,
              90,
              150
            ]
          }
        ],
        "background_color": {
          "rgb": [
            245,
            242,
            235
          ]
        }
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.images?.[0]?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="array">
  Preferred RGB palette for the generated image.

  <Expandable title="Nested fields">
    <ParamField type="array">
      Minimum items: `3`.
      Maximum items: `3`.
      Each item: integer. Minimum: `0`. Maximum: `255`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
  Maximum characters: `10000`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"1k"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"1:1"`, `"2:1"`, `"1:2"`, `"3:2"`, `"2:3"`, `"4:3"`, `"3:4"`, `"5:4"`, `"4:5"`, `"6:10"`, `"14:10"`, `"10:14"`, `"16:9"`, `"9:16"`.
</ParamField>

<ParamField type="string">
  Output file format.
  Allowed values: `"jpg"`, `"png"`, `"webp"`.
</ParamField>

<ParamField type="object">
  Preferred RGB background color.

  <Expandable title="Nested fields">
    <ParamField type="array">
      Minimum items: `3`.
      Maximum items: `3`.
      Each item: integer. Minimum: `0`. Maximum: `255`.
    </ParamField>
  </Expandable>
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Recraft V4.1 Utility Playground",
    "required": [
      "prompt"
    ],
    "properties": {
      "colors": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "rgb"
          ],
          "properties": {
            "rgb": {
              "type": "array",
              "items": {
                "type": "integer",
                "maximum": 255,
                "minimum": 0
              },
              "maxItems": 3,
              "minItems": 3
            }
          }
        },
        "title": "Colors"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "maxLength": 10000,
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "resolution": {
        "enum": [
          "1k"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "1k"
      },
      "aspect_ratio": {
        "enum": [
          "1:1",
          "2:1",
          "1:2",
          "3:2",
          "2:3",
          "4:3",
          "3:4",
          "5:4",
          "4:5",
          "6:10",
          "14:10",
          "10:14",
          "16:9",
          "9:16"
        ],
        "type": "string",
        "title": "Aspect ratio",
        "default": "1:1"
      },
      "output_format": {
        "enum": [
          "jpg",
          "png",
          "webp"
        ],
        "type": "string",
        "title": "Output format",
        "default": "jpg"
      },
      "background_color": {
        "type": "object",
        "title": "Background color",
        "required": [
          "rgb"
        ],
        "properties": {
          "rgb": {
            "type": "array",
            "items": {
              "type": "integer",
              "maximum": 255,
              "minimum": 0
            },
            "maxItems": 3,
            "minItems": 3
          }
        }
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "images": [
    {
      "url": "https://example.com/output.png"
    }
  ]
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Recraft V4.1 — Text to image API
Source: https://docs.higgsfield.ai/docs/models/recraft-v4-1/text-to-image

Text to image with Recraft V4.1: request parameters, examples and response handling.

<div />

[← Recraft V4.1](/docs/models/recraft-v4-1)

**Endpoint:** `POST https://api.higgsfield.ai/recraft/v4.1/text-to-image`

**Endpoint ID:** `recraft/v4.1/text-to-image`

<a href="https://console.higgsfield.ai/models/recraft%2Fv4.1%2Ftext-to-image/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Recraft V4.1 · Text to image</span></span>
  <span>↗</span>
</a>

## Usage notes

* This variant accepts only resolution=1k; use the separate standard/Pro endpoint for the other resolution tier.
* colors is an array of objects shaped as \{"rgb": \[R, G, B]}; background\_color is one such object. Every RGB value is an integer 0–255, with exactly three entries.
* output\_format is jpg, png, or webp; default is jpg. No reference-image input is declared.
* prompt must contain 1–10000 characters. Fourteen aspect-ratio values are listed in the schema, including 6:10, 14:10, and 10:14.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/recraft/v4.1/text-to-image \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
    "resolution": "1k",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "colors": [
      {
        "rgb": [
          40,
          90,
          150
        ]
      }
    ],
    "background_color": {
      "rgb": [
        245,
        242,
        235
      ]
    }
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A ceramic vase on a wooden table beside a sunlit window, soft '
                 'natural shadows, editorial photograph.',
       'resolution': '1k',
       'aspect_ratio': '1:1',
       'output_format': 'png',
       'colors': [{'rgb': [40, 90, 150]}],
       'background_color': {'rgb': [245, 242, 235]}}
  )
  result = higgsfield_client.subscribe(
      "recraft/v4.1/text-to-image",
      arguments=arguments,
  )
  print(result["images"][0]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("recraft/v4.1/text-to-image", {
    input:
      {
        "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
        "resolution": "1k",
        "aspect_ratio": "1:1",
        "output_format": "png",
        "colors": [
          {
            "rgb": [
              40,
              90,
              150
            ]
          }
        ],
        "background_color": {
          "rgb": [
            245,
            242,
            235
          ]
        }
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.images?.[0]?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="array">
  Preferred RGB palette for the generated image.

  <Expandable title="Nested fields">
    <ParamField type="array">
      Minimum items: `3`.
      Maximum items: `3`.
      Each item: integer. Minimum: `0`. Maximum: `255`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
  Maximum characters: `10000`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"1k"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"1:1"`, `"2:1"`, `"1:2"`, `"3:2"`, `"2:3"`, `"4:3"`, `"3:4"`, `"5:4"`, `"4:5"`, `"6:10"`, `"14:10"`, `"10:14"`, `"16:9"`, `"9:16"`.
</ParamField>

<ParamField type="string">
  Output file format.
  Allowed values: `"jpg"`, `"png"`, `"webp"`.
</ParamField>

<ParamField type="object">
  Preferred RGB background color.

  <Expandable title="Nested fields">
    <ParamField type="array">
      Minimum items: `3`.
      Maximum items: `3`.
      Each item: integer. Minimum: `0`. Maximum: `255`.
    </ParamField>
  </Expandable>
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Recraft V4.1 Playground",
    "required": [
      "prompt"
    ],
    "properties": {
      "colors": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "rgb"
          ],
          "properties": {
            "rgb": {
              "type": "array",
              "items": {
                "type": "integer",
                "maximum": 255,
                "minimum": 0
              },
              "maxItems": 3,
              "minItems": 3
            }
          }
        },
        "title": "Colors"
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "maxLength": 10000,
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "resolution": {
        "enum": [
          "1k"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "1k"
      },
      "aspect_ratio": {
        "enum": [
          "1:1",
          "2:1",
          "1:2",
          "3:2",
          "2:3",
          "4:3",
          "3:4",
          "5:4",
          "4:5",
          "6:10",
          "14:10",
          "10:14",
          "16:9",
          "9:16"
        ],
        "type": "string",
        "title": "Aspect ratio",
        "default": "1:1"
      },
      "output_format": {
        "enum": [
          "jpg",
          "png",
          "webp"
        ],
        "type": "string",
        "title": "Output format",
        "default": "jpg"
      },
      "background_color": {
        "type": "object",
        "title": "Background color",
        "required": [
          "rgb"
        ],
        "properties": {
          "rgb": {
            "type": "array",
            "items": {
              "type": "integer",
              "maximum": 255,
              "minimum": 0
            },
            "maxItems": 3,
            "minItems": 3
          }
        }
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "images": [
    {
      "url": "https://example.com/output.png"
    }
  ]
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Seedance 2.0 API
Source: https://docs.higgsfield.ai/docs/models/seedance-2

Generate videos from text, frames or image, video and audio references.

<div />

Generate videos from text, frames or image, video and audio references.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to video](/docs/models/seedance-2/text-to-video) | `POST /bytedance/seedance-2.0/text-to-video` |
| [Image to video](/docs/models/seedance-2/image-to-video) | `POST /bytedance/seedance-2.0/image-to-video` |
| [Reference to video](/docs/models/seedance-2/reference-to-video) | `POST /bytedance/seedance-2.0/reference-to-video` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Seedance 2.5 API
Source: https://docs.higgsfield.ai/docs/models/seedance-2-5

Generate, edit and extend videos using text and multimodal references.

<div />

Generate, edit and extend videos using text and multimodal references.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to video](/docs/models/seedance-2-5/text-to-video) | `POST /bytedance/seedance-2.5/text-to-video` |
| [Image to video](/docs/models/seedance-2-5/image-to-video) | `POST /bytedance/seedance-2.5/image-to-video` |
| [Reference to video](/docs/models/seedance-2-5/reference-to-video) | `POST /bytedance/seedance-2.5/reference-to-video` |
| [Video edit](/docs/models/seedance-2-5/video-edit) | `POST /bytedance/seedance-2.5/video-edit` |
| [Video extend](/docs/models/seedance-2-5/video-extend) | `POST /bytedance/seedance-2.5/video-extend` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Seedance 2.5 — Image to video API
Source: https://docs.higgsfield.ai/docs/models/seedance-2-5/image-to-video

Image to video with Seedance 2.5: request parameters, examples and response handling.

<div />

[← Seedance 2.5](/docs/models/seedance-2-5)

**Endpoint:** `POST https://api.higgsfield.ai/bytedance/seedance-2.5/image-to-video`

**Endpoint ID:** `bytedance/seedance-2.5/image-to-video`

<a href="https://console.higgsfield.ai/models/bytedance%2Fseedance-2.5%2Fimage-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Seedance 2.5 · Image to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Use publicly accessible media URLs; asset:// references are rejected for these endpoints.
* The prompt is optional. Output framing follows image\_url; end\_image\_url is the optional last frame.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/bytedance/seedance-2.5/image-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "image_url": "https://example.com/input.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'image_url': 'https://example.com/input.jpg'}
  )
  result = higgsfield_client.subscribe(
      "bytedance/seedance-2.5/image-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("bytedance/seedance-2.5/image-to-video", {
    input:
      {
        "image_url": "https://example.com/input.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `4`.
  Maximum: `30`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"480p"`, `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="string">
  Allowed values: `"standard"`, `"high"`.
</ParamField>

<ParamField type="string">
  Format: `uri`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "required": [
      "image_url"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "default": 5,
        "maximum": 30,
        "minimum": 4
      },
      "image_url": {
        "type": "string",
        "format": "uri"
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p"
        ],
        "type": "string",
        "default": "720p"
      },
      "bitrate_mode": {
        "enum": [
          "standard",
          "high"
        ],
        "type": "string",
        "default": "high"
      },
      "end_image_url": {
        "type": "string",
        "format": "uri"
      },
      "generate_audio": {
        "type": "boolean",
        "default": true
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Seedance 2.5 — Reference to video API
Source: https://docs.higgsfield.ai/docs/models/seedance-2-5/reference-to-video

Reference to video with Seedance 2.5: request parameters, examples and response handling.

<div />

[← Seedance 2.5](/docs/models/seedance-2-5)

**Endpoint:** `POST https://api.higgsfield.ai/bytedance/seedance-2.5/reference-to-video`

**Endpoint ID:** `bytedance/seedance-2.5/reference-to-video`

<a href="https://console.higgsfield.ai/models/bytedance%2Fseedance-2.5%2Freference-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Seedance 2.5 · Reference to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Use publicly accessible media URLs; asset:// references are rejected for these endpoints.
* Provide at least one nonempty reference array: image\_urls, video\_urls or audio\_urls. Audio-only references are supported by this schema and preprocessing path.
* Reference media are limited to 30 images, 10 videos and 10 audio files, with at most 50 items total. Video duration and audio duration are normalized separately to at most 30 seconds total per media type.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/bytedance/seedance-2.5/reference-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "image_urls": [
      "https://example.com/input.jpg"
    ]
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'image_urls': ['https://example.com/input.jpg']}
  )
  result = higgsfield_client.subscribe(
      "bytedance/seedance-2.5/reference-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("bytedance/seedance-2.5/reference-to-video", {
    input:
      {
        "image_urls": [
          "https://example.com/input.jpg"
        ]
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `4`.
  Maximum: `30`.
</ParamField>

<ParamField type="array">
  Ordered public audio reference URLs.
  Minimum items: `1`.
  Maximum items: `10`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Minimum items: `1`.
  Maximum items: `30`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"480p"`, `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="array">
  Ordered public video reference URLs.
  Minimum items: `1`.
  Maximum items: `10`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"21:9"`.
</ParamField>

<ParamField type="string">
  Allowed values: `"standard"`, `"high"`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "if": {
      "required": [
        "image_urls"
      ]
    },
    "else": {
      "if": {
        "required": [
          "video_urls"
        ]
      },
      "else": {
        "required": [
          "audio_urls"
        ]
      }
    },
    "type": "object",
    "required": [],
    "properties": {
      "prompt": {
        "type": "string",
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "default": 5,
        "maximum": 30,
        "minimum": 4
      },
      "audio_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "maxItems": 10,
        "minItems": 1
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "maxItems": 30,
        "minItems": 1
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p"
        ],
        "type": "string",
        "default": "720p"
      },
      "video_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "maxItems": 10,
        "minItems": 1
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "4:3",
          "1:1",
          "3:4",
          "9:16",
          "21:9"
        ],
        "type": "string",
        "default": "16:9"
      },
      "bitrate_mode": {
        "enum": [
          "standard",
          "high"
        ],
        "type": "string",
        "default": "high"
      },
      "generate_audio": {
        "type": "boolean",
        "default": true
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Seedance 2.5 — Text to video API
Source: https://docs.higgsfield.ai/docs/models/seedance-2-5/text-to-video

Text to video with Seedance 2.5: request parameters, examples and response handling.

<div />

[← Seedance 2.5](/docs/models/seedance-2-5)

**Endpoint:** `POST https://api.higgsfield.ai/bytedance/seedance-2.5/text-to-video`

**Endpoint ID:** `bytedance/seedance-2.5/text-to-video`

<a href="https://console.higgsfield.ai/models/bytedance%2Fseedance-2.5%2Ftext-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Seedance 2.5 · Text to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Use publicly accessible media URLs; asset:// references are rejected for these endpoints.
* Provide a nonblank prompt. This endpoint does not use media inputs; use the image-to-video or reference-to-video endpoint instead.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/bytedance/seedance-2.5/text-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.'}
  )
  result = higgsfield_client.subscribe(
      "bytedance/seedance-2.5/text-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("bytedance/seedance-2.5/text-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `4`.
  Maximum: `30`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"480p"`, `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"21:9"`.
</ParamField>

<ParamField type="string">
  Allowed values: `"standard"`, `"high"`.
</ParamField>

<ParamField type="string">
  Output file format.
  Allowed values: `"mp4"`, `"mov"`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "required": [
      "prompt"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "default": 5,
        "maximum": 30,
        "minimum": 4
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p"
        ],
        "type": "string",
        "default": "720p"
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "4:3",
          "1:1",
          "3:4",
          "9:16",
          "21:9"
        ],
        "type": "string",
        "default": "16:9"
      },
      "bitrate_mode": {
        "enum": [
          "standard",
          "high"
        ],
        "type": "string",
        "default": "high"
      },
      "output_format": {
        "enum": [
          "mp4",
          "mov"
        ],
        "type": "string",
        "default": "mp4"
      },
      "generate_audio": {
        "type": "boolean",
        "default": true
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Seedance 2.5 — Video edit API
Source: https://docs.higgsfield.ai/docs/models/seedance-2-5/video-edit

Video edit with Seedance 2.5: request parameters, examples and response handling.

<div />

[← Seedance 2.5](/docs/models/seedance-2-5)

**Endpoint:** `POST https://api.higgsfield.ai/bytedance/seedance-2.5/video-edit`

**Endpoint ID:** `bytedance/seedance-2.5/video-edit`

<a href="https://console.higgsfield.ai/models/bytedance%2Fseedance-2.5%2Fvideo-edit/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Seedance 2.5 · Video edit</span></span>
  <span>↗</span>
</a>

## Usage notes

* Use publicly accessible media URLs; asset:// references are rejected for these endpoints.
* The source video\_url counts toward the 10-video limit, so include at most 9 additional video\_urls. At most 50 media items are accepted across the source video and all reference arrays.
* Videos and audio may be trimmed or padded during preprocessing to fit their respective 30-second total budgets. Output framing follows the source video.
* Do not send duration: this endpoint derives output duration from the processed source video. The main video is normalized to at least 4 seconds.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/bytedance/seedance-2.5/video-edit \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
    "video_url": "https://example.com/input.mp4"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.',
       'video_url': 'https://example.com/input.mp4'}
  )
  result = higgsfield_client.subscribe(
      "bytedance/seedance-2.5/video-edit",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("bytedance/seedance-2.5/video-edit", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
        "video_url": "https://example.com/input.mp4"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
</ParamField>

<ParamField type="string">
  Public URL of the source video.
  Format: `uri`.
</ParamField>

<ParamField type="array">
  Ordered public audio reference URLs.
  Minimum items: `1`.
  Maximum items: `10`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Minimum items: `1`.
  Maximum items: `30`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"480p"`, `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="array">
  Ordered public video reference URLs.
  Minimum items: `1`.
  Maximum items: `10`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Allowed values: `"standard"`, `"high"`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "required": [
      "prompt",
      "video_url"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "video_url": {
        "type": "string",
        "format": "uri"
      },
      "audio_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "maxItems": 10,
        "minItems": 1
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "maxItems": 30,
        "minItems": 1
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p"
        ],
        "type": "string",
        "default": "720p"
      },
      "video_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "maxItems": 10,
        "minItems": 1
      },
      "bitrate_mode": {
        "enum": [
          "standard",
          "high"
        ],
        "type": "string",
        "default": "high"
      },
      "generate_audio": {
        "type": "boolean",
        "default": true
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Seedance 2.5 — Video extend API
Source: https://docs.higgsfield.ai/docs/models/seedance-2-5/video-extend

Video extend with Seedance 2.5: request parameters, examples and response handling.

<div />

[← Seedance 2.5](/docs/models/seedance-2-5)

**Endpoint:** `POST https://api.higgsfield.ai/bytedance/seedance-2.5/video-extend`

**Endpoint ID:** `bytedance/seedance-2.5/video-extend`

<a href="https://console.higgsfield.ai/models/bytedance%2Fseedance-2.5%2Fvideo-extend/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Seedance 2.5 · Video extend</span></span>
  <span>↗</span>
</a>

## Usage notes

* Use publicly accessible media URLs; asset:// references are rejected for these endpoints.
* The source video\_url counts toward the 10-video limit, so include at most 9 additional video\_urls. At most 50 media items are accepted across the source video and all reference arrays.
* Videos and audio may be trimmed or padded during preprocessing to fit their respective 30-second total budgets. Output framing follows the source video.
* duration is an integer from 4 to 30 seconds, with default 5.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/bytedance/seedance-2.5/video-extend \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
    "video_url": "https://example.com/input.mp4"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.',
       'video_url': 'https://example.com/input.mp4'}
  )
  result = higgsfield_client.subscribe(
      "bytedance/seedance-2.5/video-extend",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("bytedance/seedance-2.5/video-extend", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
        "video_url": "https://example.com/input.mp4"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `4`.
  Maximum: `30`.
</ParamField>

<ParamField type="string">
  Public URL of the source video.
  Format: `uri`.
</ParamField>

<ParamField type="array">
  Ordered public audio reference URLs.
  Minimum items: `1`.
  Maximum items: `10`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Minimum items: `1`.
  Maximum items: `30`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"480p"`, `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="array">
  Ordered public video reference URLs.
  Minimum items: `1`.
  Maximum items: `10`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Allowed values: `"standard"`, `"high"`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "required": [
      "prompt",
      "video_url"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "default": 5,
        "maximum": 30,
        "minimum": 4
      },
      "video_url": {
        "type": "string",
        "format": "uri"
      },
      "audio_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "maxItems": 10,
        "minItems": 1
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "maxItems": 30,
        "minItems": 1
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p"
        ],
        "type": "string",
        "default": "720p"
      },
      "video_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "maxItems": 10,
        "minItems": 1
      },
      "bitrate_mode": {
        "enum": [
          "standard",
          "high"
        ],
        "type": "string",
        "default": "high"
      },
      "generate_audio": {
        "type": "boolean",
        "default": true
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Seedance 2.0 — Image to video API
Source: https://docs.higgsfield.ai/docs/models/seedance-2/image-to-video

Image to video with Seedance 2.0: request parameters, examples and response handling.

<div />

[← Seedance 2.0](/docs/models/seedance-2)

**Endpoint:** `POST https://api.higgsfield.ai/bytedance/seedance-2.0/image-to-video`

**Endpoint ID:** `bytedance/seedance-2.0/image-to-video`

<a href="https://console.higgsfield.ai/models/bytedance%2Fseedance-2.0%2Fimage-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Seedance 2.0 · Image to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Use publicly accessible media URLs; asset:// references are rejected for these endpoints.
* The prompt is optional. Output framing follows image\_url; end\_image\_url is the optional last frame.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/bytedance/seedance-2.0/image-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "image_url": "https://example.com/input.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'image_url': 'https://example.com/input.jpg'}
  )
  result = higgsfield_client.subscribe(
      "bytedance/seedance-2.0/image-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("bytedance/seedance-2.0/image-to-video", {
    input:
      {
        "image_url": "https://example.com/input.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `4`.
  Maximum: `15`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"480p"`, `"720p"`, `"1080p"`, `"4k"`.
</ParamField>

<ParamField type="string">
  Format: `uri`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "required": [
      "image_url"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "default": 5,
        "maximum": 15,
        "minimum": 4
      },
      "image_url": {
        "type": "string",
        "format": "uri"
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p",
          "4k"
        ],
        "type": "string",
        "default": "720p"
      },
      "end_image_url": {
        "type": "string",
        "format": "uri"
      },
      "generate_audio": {
        "type": "boolean",
        "default": true
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Seedance 2.0 — Reference to video API
Source: https://docs.higgsfield.ai/docs/models/seedance-2/reference-to-video

Reference to video with Seedance 2.0: request parameters, examples and response handling.

<div />

[← Seedance 2.0](/docs/models/seedance-2)

**Endpoint:** `POST https://api.higgsfield.ai/bytedance/seedance-2.0/reference-to-video`

**Endpoint ID:** `bytedance/seedance-2.0/reference-to-video`

<a href="https://console.higgsfield.ai/models/bytedance%2Fseedance-2.0%2Freference-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Seedance 2.0 · Reference to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Use publicly accessible media URLs; asset:// references are rejected for these endpoints.
* Provide a nonempty image\_urls or video\_urls array. Audio alone does not satisfy the reference requirement. Do not mix reference arrays with image\_url, end\_image\_url or video\_url.
* Reference videos may be resized, transcoded and trimmed to 15 seconds each. Reference audio is normalized to 2–15 seconds per file and at most 15 seconds total.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/bytedance/seedance-2.0/reference-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "image_urls": [
      "https://example.com/input.jpg"
    ]
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'image_urls': ['https://example.com/input.jpg']}
  )
  result = higgsfield_client.subscribe(
      "bytedance/seedance-2.0/reference-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("bytedance/seedance-2.0/reference-to-video", {
    input:
      {
        "image_urls": [
          "https://example.com/input.jpg"
        ]
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `4`.
  Maximum: `15`.
</ParamField>

<ParamField type="array">
  Ordered public audio reference URLs.
  Minimum items: `1`.
  Maximum items: `3`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Minimum items: `1`.
  Maximum items: `9`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"480p"`, `"720p"`, `"1080p"`, `"4k"`.
</ParamField>

<ParamField type="array">
  Ordered public video reference URLs.
  Minimum items: `1`.
  Maximum items: `3`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"21:9"`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "if": {
      "required": [
        "image_urls"
      ]
    },
    "else": {
      "required": [
        "video_urls"
      ]
    },
    "type": "object",
    "required": [],
    "properties": {
      "prompt": {
        "type": "string",
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "default": 5,
        "maximum": 15,
        "minimum": 4
      },
      "audio_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "maxItems": 3,
        "minItems": 1
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "maxItems": 9,
        "minItems": 1
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p",
          "4k"
        ],
        "type": "string",
        "default": "720p"
      },
      "video_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "maxItems": 3,
        "minItems": 1
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "4:3",
          "1:1",
          "3:4",
          "9:16",
          "21:9"
        ],
        "type": "string",
        "default": "16:9"
      },
      "generate_audio": {
        "type": "boolean",
        "default": true
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Seedance 2.0 — Text to video API
Source: https://docs.higgsfield.ai/docs/models/seedance-2/text-to-video

Text to video with Seedance 2.0: request parameters, examples and response handling.

<div />

[← Seedance 2.0](/docs/models/seedance-2)

**Endpoint:** `POST https://api.higgsfield.ai/bytedance/seedance-2.0/text-to-video`

**Endpoint ID:** `bytedance/seedance-2.0/text-to-video`

<a href="https://console.higgsfield.ai/models/bytedance%2Fseedance-2.0%2Ftext-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Seedance 2.0 · Text to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Use publicly accessible media URLs; asset:// references are rejected for these endpoints.
* Provide a nonblank prompt. This endpoint does not use media inputs; use the image-to-video or reference-to-video endpoint instead.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/bytedance/seedance-2.0/text-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.'}
  )
  result = higgsfield_client.subscribe(
      "bytedance/seedance-2.0/text-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("bytedance/seedance-2.0/text-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
  Minimum characters: `1`.
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `4`.
  Maximum: `15`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"480p"`, `"720p"`, `"1080p"`, `"4k"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"21:9"`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "required": [
      "prompt"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "minLength": 1,
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "default": 5,
        "maximum": 15,
        "minimum": 4
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p",
          "4k"
        ],
        "type": "string",
        "default": "720p"
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "4:3",
          "1:1",
          "3:4",
          "9:16",
          "21:9"
        ],
        "type": "string",
        "default": "16:9"
      },
      "generate_audio": {
        "type": "boolean",
        "default": true
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# SOUL V2 API
Source: https://docs.higgsfield.ai/docs/models/soul-2

Generate portraits, fashion and editorial images with SOUL styles.

<div />

Generate portraits, fashion and editorial images with SOUL styles.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to image](/docs/models/soul-2/generate) | `POST /higgsfield-ai/soul/v2/standard` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# SOUL V2 — Text to image API
Source: https://docs.higgsfield.ai/docs/models/soul-2/generate

Text to image with SOUL V2: request parameters, examples and response handling.

<div />

[← SOUL V2](/docs/models/soul-2)

**Endpoint:** `POST https://api.higgsfield.ai/higgsfield-ai/soul/v2/standard`

**Endpoint ID:** `higgsfield-ai/soul/v2/standard`

<a href="https://console.higgsfield.ai/models/higgsfield-ai%2Fsoul%2Fv2%2Fstandard/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>SOUL V2 · Text to image</span></span>
  <span>↗</span>
</a>

## Usage notes

* batch\_size is 1 or 4 only. A custom\_reference\_id must belong to the calling account and have completed training.
* aspect\_ratio defaults to 1:1 and enhance\_prompt defaults to false. seed defaults to a random integer from 1 to 1000000; explicit null is invalid.
* style\_id defaults to 3db34ab5-3439-4317-9e03-08dc30852e69. style\_strength is accepted by the request schema but currently has no effect on generation.
* Short prompts using the general style can be enhanced automatically even when enhance\_prompt=false.
* When using custom\_reference\_id, set custom\_reference\_strength to a value greater than 0 and no greater than 1. The schema accepts 0, but the current runtime fails to process it for a character reference.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/higgsfield-ai/soul/v2/standard \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
    "resolution": "720p",
    "aspect_ratio": "1:1",
    "enhance_prompt": true,
    "batch_size": 1
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A ceramic vase on a wooden table beside a sunlit window, soft '
                 'natural shadows, editorial photograph.',
       'resolution': '720p',
       'aspect_ratio': '1:1',
       'enhance_prompt': True,
       'batch_size': 1}
  )
  result = higgsfield_client.subscribe(
      "higgsfield-ai/soul/v2/standard",
      arguments=arguments,
  )
  print(result["images"][0]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("higgsfield-ai/soul/v2/standard", {
    input:
      {
        "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
        "resolution": "720p",
        "aspect_ratio": "1:1",
        "enhance_prompt": true,
        "batch_size": 1
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.images?.[0]?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Text instructions for the generation or edit.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"9:16"`, `"16:9"`, `"4:3"`, `"3:4"`, `"1:1"`, `"2:3"`, `"3:2"`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="boolean">
  Enable prompt enhancement for this workflow.
</ParamField>

<ParamField type="string | null">
  Identifier of a completed character reference owned by your account.
  Format: `uuid`.
  Omit this field to use the server default; `null` is accepted only when included in the field type.
</ParamField>

<ParamField type="number">
  Strength of the character reference. With custom\_reference\_id, use a value greater than 0; the current runtime cannot process 0 even though the schema accepts it.
  Minimum: `0`.
  Maximum: `1`.
</ParamField>

<ParamField type="string">
  Identifier of a style supported by this model.
  Format: `uuid`.
</ParamField>

<ParamField type="number">
  Accepted by the request schema, but currently has no effect on generation.
  Minimum: `0`.
  Maximum: `1`.
</ParamField>

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `1`.
  Maximum: `1000000`.
</ParamField>

<ParamField type="integer">
  Number of output images.
  Allowed values: `1`, `4`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "properties": {
      "prompt": {
        "title": "Prompt",
        "type": "string"
      },
      "aspect_ratio": {
        "default": "1:1",
        "enum": [
          "9:16",
          "16:9",
          "4:3",
          "3:4",
          "1:1",
          "2:3",
          "3:2"
        ],
        "title": "Aspect Ratio",
        "type": "string"
      },
      "resolution": {
        "default": "720p",
        "enum": [
          "720p",
          "1080p"
        ],
        "title": "Resolution",
        "type": "string"
      },
      "enhance_prompt": {
        "default": false,
        "title": "Enhance Prompt",
        "type": "boolean"
      },
      "custom_reference_id": {
        "anyOf": [
          {
            "format": "uuid",
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "title": "Custom Reference Id"
      },
      "custom_reference_strength": {
        "default": 1.0,
        "maximum": 1,
        "minimum": 0,
        "title": "Custom Reference Strength",
        "type": "number"
      },
      "style_id": {
        "default": "3db34ab5-3439-4317-9e03-08dc30852e69",
        "format": "uuid",
        "title": "Style Id",
        "type": "string"
      },
      "style_strength": {
        "default": 1.0,
        "maximum": 1,
        "minimum": 0,
        "title": "Style Strength",
        "type": "number"
      },
      "seed": {
        "maximum": 1000000,
        "minimum": 1,
        "title": "Seed",
        "type": "integer"
      },
      "batch_size": {
        "default": 1,
        "enum": [
          1,
          4
        ],
        "title": "Batch Size",
        "type": "integer"
      }
    },
    "required": [
      "prompt"
    ],
    "title": "SoulV2ParamsSchema",
    "type": "object"
  }
  ```
</Accordion>

## List SOUL styles

`GET https://api.higgsfield.ai/v1/text2image/soul-styles/v2`

Use this authenticated endpoint to retrieve available `style_id` values.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request GET \
  --url https://api.higgsfield.ai/v1/text2image/soul-styles/v2 \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "id": "<style-uuid>",
    "name": "Editorial",
    "description": "A polished editorial image style.",
    "preview_url": "https://cdn.example.com/soul-style-preview.jpg"
  }
]
```

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "images": [
    {
      "url": "https://example.com/output.png"
    }
  ]
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# SOUL Cinema API
Source: https://docs.higgsfield.ai/docs/models/soul-cinema

Generate cinema-inspired still images from text prompts.

<div />

Generate cinema-inspired still images from text prompts.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to image](/docs/models/soul-cinema/generate) | `POST /higgsfield-ai/soul/cinema` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# SOUL Cinema — Text to image API
Source: https://docs.higgsfield.ai/docs/models/soul-cinema/generate

Text to image with SOUL Cinema: request parameters, examples and response handling.

<div />

[← SOUL Cinema](/docs/models/soul-cinema)

**Endpoint:** `POST https://api.higgsfield.ai/higgsfield-ai/soul/cinema`

**Endpoint ID:** `higgsfield-ai/soul/cinema`

<a href="https://console.higgsfield.ai/models/higgsfield-ai%2Fsoul%2Fcinema/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>SOUL Cinema · Text to image</span></span>
  <span>↗</span>
</a>

## Usage notes

* batch\_size is 1 or 4 only. A custom\_reference\_id must belong to the calling account and have completed training.
* aspect\_ratio defaults to 1:1 and enhance\_prompt defaults to false. seed defaults to a random integer from 1 to 1000000; explicit null is invalid.
* Providing a custom\_reference\_id enables prompt enhancement for the character reference, even if enhance\_prompt is false.
* Cinema uses a fixed style; client-supplied style\_id is ignored.
* This model may be absent from model discovery; authorized requests can use the endpoint ID directly.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/higgsfield-ai/soul/cinema \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
    "resolution": "720p",
    "aspect_ratio": "1:1",
    "enhance_prompt": true,
    "batch_size": 1
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A ceramic vase on a wooden table beside a sunlit window, soft '
                 'natural shadows, editorial photograph.',
       'resolution': '720p',
       'aspect_ratio': '1:1',
       'enhance_prompt': True,
       'batch_size': 1}
  )
  result = higgsfield_client.subscribe(
      "higgsfield-ai/soul/cinema",
      arguments=arguments,
  )
  print(result["images"][0]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("higgsfield-ai/soul/cinema", {
    input:
      {
        "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
        "resolution": "720p",
        "aspect_ratio": "1:1",
        "enhance_prompt": true,
        "batch_size": 1
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.images?.[0]?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Text instructions for the generation or edit.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"9:16"`, `"16:9"`, `"4:3"`, `"3:4"`, `"1:1"`, `"2:3"`, `"3:2"`.
</ParamField>

<ParamField type="boolean">
  Enable prompt enhancement. Providing custom\_reference\_id enables enhancement even when this field is false.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="string | null">
  Identifier of a completed character reference owned by your account.
  Format: `uuid`.
  Omit this field to use the server default; `null` is accepted only when included in the field type.
</ParamField>

<ParamField type="number">
  Strength of the character reference.
  Minimum: `0`.
  Maximum: `1`.
</ParamField>

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `1`.
  Maximum: `1000000`.
</ParamField>

<ParamField type="integer">
  Number of output images.
  Allowed values: `1`, `4`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "properties": {
      "prompt": {
        "title": "Prompt",
        "type": "string"
      },
      "aspect_ratio": {
        "default": "1:1",
        "enum": [
          "9:16",
          "16:9",
          "4:3",
          "3:4",
          "1:1",
          "2:3",
          "3:2"
        ],
        "title": "Aspect Ratio",
        "type": "string"
      },
      "enhance_prompt": {
        "default": false,
        "title": "Enhance Prompt",
        "type": "boolean"
      },
      "resolution": {
        "default": "720p",
        "enum": [
          "720p",
          "1080p"
        ],
        "title": "Resolution",
        "type": "string"
      },
      "custom_reference_id": {
        "anyOf": [
          {
            "format": "uuid",
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "title": "Custom Reference Id"
      },
      "custom_reference_strength": {
        "default": 1.0,
        "maximum": 1,
        "minimum": 0,
        "title": "Custom Reference Strength",
        "type": "number"
      },
      "seed": {
        "maximum": 1000000,
        "minimum": 1,
        "title": "Seed",
        "type": "integer"
      },
      "batch_size": {
        "default": 1,
        "enum": [
          1,
          4
        ],
        "title": "Batch Size",
        "type": "integer"
      }
    },
    "required": [
      "prompt"
    ],
    "title": "SoulCinemaParamsSchema",
    "type": "object"
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "images": [
    {
      "url": "https://example.com/output.png"
    }
  ]
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Soul ID API
Source: https://docs.higgsfield.ai/docs/models/soul-id

Train a personal character from reference images for use with compatible SOUL workflows.

<div />

Train a personal character from reference images for use with compatible SOUL workflows.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Create character](/docs/models/soul-id/create-character) | `POST /v1/custom-references` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Soul ID — Create character API
Source: https://docs.higgsfield.ai/docs/models/soul-id/create-character

Create character with Soul ID: request parameters, examples and response handling.

<div />

[← Soul ID](/docs/models/soul-id)

**Endpoint:** `POST https://api.higgsfield.ai/v1/custom-references`

**Catalog ID:** `soul-id`

## Usage notes

* Soul ID trains a reusable character reference. This is not an image-generation endpoint; do not POST to /soul-id.
* Use POST /v1/custom-references with application/json. name has a maximum length of 100; input\_images must contain 1–100 \{"type":"image\_url","image\_url":"..."} objects.
* model\_version accepts v1, v2, cinema; its default is v1. Choose the matching generation family.
* The creation response returns id and status. Poll GET /v1/custom-references/\{id}; statuses are not\_ready, queued, in\_progress, completed, and failed.
* After completion, pass the returned id as custom\_reference\_id to the matching Soul generation endpoint. References are scoped to the account that created them.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  --url https://api.higgsfield.ai/v1/custom-references \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "My character",
  "model_version": "v2",
  "input_images": [
    {
      "type": "image_url",
      "image_url": "https://example.com/portrait-front.jpg"
    },
    {
      "type": "image_url",
      "image_url": "https://example.com/portrait-side.jpg"
    },
    {
      "type": "image_url",
      "image_url": "https://example.com/portrait-outdoors.jpg"
    }
  ]
}'
```

## Input schema

<ParamField type="string">
  Name of the character reference.
  Maximum characters: `100`.
</ParamField>

<ParamField type="string">
  SOUL family that will use this character reference.
  Allowed values: `"v1"`, `"v2"`, `"cinema"`.
</ParamField>

<ParamField type="array">
  Training images supplied as public URL objects.
  Minimum items: `1`.
  Maximum items: `100`.

  <Expandable title="Nested fields">
    <ParamField type="string">
      Must be `"image_url"`.
    </ParamField>

    <ParamField type="string">
      Public URL of the input image.
      Minimum characters: `1`.
      Maximum characters: `2083`.
      Format: `uri`.
    </ParamField>
  </Expandable>
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "$defs": {
      "ImageUrlInputImageSchema": {
        "properties": {
          "type": {
            "const": "image_url",
            "title": "Type",
            "type": "string"
          },
          "image_url": {
            "format": "uri",
            "maxLength": 2083,
            "minLength": 1,
            "title": "Image Url",
            "type": "string"
          }
        },
        "required": [
          "type",
          "image_url"
        ],
        "title": "ImageUrlInputImageSchema",
        "type": "object"
      },
      "SoulModelVersion": {
        "enum": [
          "v1",
          "v2",
          "cinema"
        ],
        "title": "SoulModelVersion",
        "type": "string"
      }
    },
    "properties": {
      "name": {
        "maxLength": 100,
        "title": "Name",
        "type": "string"
      },
      "model_version": {
        "$ref": "#/$defs/SoulModelVersion",
        "default": "v1"
      },
      "input_images": {
        "items": {
          "$ref": "#/$defs/ImageUrlInputImageSchema"
        },
        "maxItems": 100,
        "minItems": 1,
        "title": "Input Images",
        "type": "array"
      }
    },
    "required": [
      "name",
      "input_images"
    ],
    "title": "CreateCustomReferenceSchema",
    "type": "object"
  }
  ```
</Accordion>

## Response

The response is a character reference with `id`, `name`, `model_version`, `status`, `thumbnail_url`, `created_at`, `in_progress_at` and `fail_reason`.

Poll `GET https://api.higgsfield.ai/v1/custom-references/{id}` with the same API credentials. Training states are `not_ready`, `queued`, `in_progress`, `completed` and `failed`.

After `completed`, pass the reference `id` as `custom_reference_id` to the matching SOUL generation workflow. The reference must belong to your account. Training does not return `request_id` or generated `images`.


# SOUL API
Source: https://docs.higgsfield.ai/docs/models/soul-standard

Generate images with selectable styles and adjustable style strength.

<div />

Generate images with selectable styles and adjustable style strength.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to image](/docs/models/soul-standard/generate) | `POST /higgsfield-ai/soul/standard` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# SOUL — Text to image API
Source: https://docs.higgsfield.ai/docs/models/soul-standard/generate

Text to image with SOUL: request parameters, examples and response handling.

<div />

[← SOUL](/docs/models/soul-standard)

**Endpoint:** `POST https://api.higgsfield.ai/higgsfield-ai/soul/standard`

**Endpoint ID:** `higgsfield-ai/soul/standard`

<a href="https://console.higgsfield.ai/models/higgsfield-ai%2Fsoul%2Fstandard/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>SOUL · Text to image</span></span>
  <span>↗</span>
</a>

## Usage notes

* batch\_size is 1 or 4 only. A custom\_reference\_id must belong to the calling account and have completed training.
* aspect\_ratio defaults to 4:3; enhance\_prompt defaults to false; style\_id defaults to 464ea177-8d40-4940-8d9d-b438bab269c7.
* Optional image\_reference\_url guides prompt enhancement; it is distinct from custom\_reference\_id for a trained character.
* seed may be omitted or null; generation selects a random seed when it is absent.
* Short prompts using the general style can be enhanced automatically even when enhance\_prompt=false.
* custom\_reference\_strength=0 uses the selected style's default character strength; it does not disable the character reference.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/higgsfield-ai/soul/standard \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
    "resolution": "720p",
    "aspect_ratio": "1:1",
    "enhance_prompt": true,
    "batch_size": 1
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A ceramic vase on a wooden table beside a sunlit window, soft '
                 'natural shadows, editorial photograph.',
       'resolution': '720p',
       'aspect_ratio': '1:1',
       'enhance_prompt': True,
       'batch_size': 1}
  )
  result = higgsfield_client.subscribe(
      "higgsfield-ai/soul/standard",
      arguments=arguments,
  )
  print(result["images"][0]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("higgsfield-ai/soul/standard", {
    input:
      {
        "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
        "resolution": "720p",
        "aspect_ratio": "1:1",
        "enhance_prompt": true,
        "batch_size": 1
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.images?.[0]?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Text instructions for the generation or edit.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"9:16"`, `"16:9"`, `"4:3"`, `"3:4"`, `"1:1"`, `"2:3"`, `"3:2"`.
</ParamField>

<ParamField type="boolean">
  Enable prompt enhancement for this workflow.
</ParamField>

<ParamField type="string">
  Identifier of a style supported by this model.
  Format: `uuid`.
</ParamField>

<ParamField type="number">
  Strength of the selected style.
  Minimum: `0`.
  Maximum: `1`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="integer | null">
  Seed used to control generation randomness.
  Minimum: `1`.
  Maximum: `1000000`.
  Omit this field to use the server default; `null` is accepted only when included in the field type.
</ParamField>

<ParamField type="string | null">
  Identifier of a completed character reference owned by your account.
  Format: `uuid`.
  Omit this field to use the server default; `null` is accepted only when included in the field type.
</ParamField>

<ParamField type="number">
  Strength of the character reference. A value of 0 uses the selected style's default character strength.
  Minimum: `0`.
  Maximum: `1`.
</ParamField>

<ParamField type="string | null">
  Minimum characters: `1`.
  Maximum characters: `2083`.
  Format: `uri`.
  Omit this field to use the server default; `null` is accepted only when included in the field type.
</ParamField>

<ParamField type="integer">
  Number of output images.
  Allowed values: `1`, `4`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "properties": {
      "prompt": {
        "title": "Prompt",
        "type": "string"
      },
      "aspect_ratio": {
        "default": "4:3",
        "enum": [
          "9:16",
          "16:9",
          "4:3",
          "3:4",
          "1:1",
          "2:3",
          "3:2"
        ],
        "title": "Aspect Ratio",
        "type": "string"
      },
      "enhance_prompt": {
        "default": false,
        "title": "Enhance Prompt",
        "type": "boolean"
      },
      "style_id": {
        "default": "464ea177-8d40-4940-8d9d-b438bab269c7",
        "format": "uuid",
        "title": "Style Id",
        "type": "string"
      },
      "style_strength": {
        "default": 1.0,
        "maximum": 1,
        "minimum": 0,
        "title": "Style Strength",
        "type": "number"
      },
      "resolution": {
        "default": "720p",
        "enum": [
          "720p",
          "1080p"
        ],
        "title": "Resolution",
        "type": "string"
      },
      "seed": {
        "anyOf": [
          {
            "maximum": 1000000,
            "minimum": 1,
            "type": "integer"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "title": "Seed"
      },
      "custom_reference_id": {
        "anyOf": [
          {
            "format": "uuid",
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "title": "Custom Reference Id"
      },
      "custom_reference_strength": {
        "default": 1.0,
        "maximum": 1,
        "minimum": 0,
        "title": "Custom Reference Strength",
        "type": "number"
      },
      "image_reference_url": {
        "anyOf": [
          {
            "format": "uri",
            "maxLength": 2083,
            "minLength": 1,
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "title": "Image Reference Url"
      },
      "batch_size": {
        "default": 1,
        "enum": [
          1,
          4
        ],
        "title": "Batch Size",
        "type": "integer"
      }
    },
    "required": [
      "prompt"
    ],
    "title": "SoulParamsSchema",
    "type": "object"
  }
  ```
</Accordion>

## List SOUL styles

`GET https://api.higgsfield.ai/v1/text2image/soul-styles`

Use this authenticated endpoint to retrieve valid `style_id` values.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request GET \
  --url https://api.higgsfield.ai/v1/text2image/soul-styles \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "id": "<style-uuid>",
    "name": "Editorial",
    "description": "A polished editorial image style.",
    "preview_url": "https://cdn.example.com/soul-style-preview.jpg"
  }
]
```

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "images": [
    {
      "url": "https://example.com/output.png"
    }
  ]
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Video Generation API
Source: https://docs.higgsfield.ai/docs/models/video-generation

Explore video models and their API request schemas.

<div />

Choose from **22 model families** and **67 catalog entries**. Each workflow has its own parameters and examples.

## Models

<div>
  <a href="/docs/models/genjutsu">
    <span><span>Higgsfield</span><span>Video · 3 workflows</span></span>
    <span>Genjutsu</span>
    <span>Transfer motion, replace objects, or restyle a source video.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/seedance-2">
    <span><span>ByteDance</span><span>Video · 3 workflows</span></span>
    <span>Seedance 2.0</span>
    <span>Generate videos from text, frames or image, video and audio references.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/seedance-2-5">
    <span><span>ByteDance</span><span>Video · 5 workflows</span></span>
    <span>Seedance 2.5</span>
    <span>Generate, edit and extend videos using text and multimodal references.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/kling-2-5-turbo">
    <span><span>Kling</span><span>Video · 3 workflows</span></span>
    <span>Kling 2.5 Turbo</span>
    <span>Generate videos with Standard and Pro workflow variants.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/kling-2-6">
    <span><span>Kling</span><span>Video · 2 workflows</span></span>
    <span>Kling 2.6</span>
    <span>Generate videos from text or a starting image, with optional sound.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/kling-2-6-motion-control">
    <span><span>Kling</span><span>Video · 2 workflows</span></span>
    <span>Kling 2.6 Motion Control</span>
    <span>Apply motion from a source video to an image with Standard or Pro processing.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/kling-3">
    <span><span>Kling</span><span>Video · 8 workflows</span></span>
    <span>Kling 3.0</span>
    <span>Generate videos with Standard, Pro, 4K and Turbo workflow variants.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/kling-3-motion-control">
    <span><span>Kling</span><span>Video · 2 workflows</span></span>
    <span>Kling 3.0 Motion Control</span>
    <span>Apply motion from a source video to an image with Standard or Pro processing.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/kling-o3">
    <span><span>Kling</span><span>Video · 4 workflows</span></span>
    <span>Kling O3</span>
    <span>Create and edit videos with first/last frames, image references and video references.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/kling-omni">
    <span><span>Kling</span><span>Video · 4 workflows</span></span>
    <span>Kling Omni</span>
    <span>Create and edit videos with image and video references.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/happy-horse-1">
    <span><span>Alibaba</span><span>Video · 3 workflows</span></span>
    <span>Happy Horse 1.0</span>
    <span>Generate videos from text, a starting image or reference images.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/happy-horse-1-1">
    <span><span>Alibaba</span><span>Video · 3 workflows</span></span>
    <span>HappyHorse 1.1</span>
    <span>Generate videos from text, a starting image or reference images.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/wan-3">
    <span><span>Alibaba</span><span>Video · 3 workflows</span></span>
    <span>Wan 3.0</span>
    <span>Generate videos from text, frames or multimodal references.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/wan-3-prime">
    <span><span>Alibaba</span><span>Video · 3 workflows</span></span>
    <span>Wan 3.0 Prime</span>
    <span>Generate videos from text, frames or multimodal references with Wan 3.0 Prime.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/cinema-studio-4">
    <span><span>Higgsfield</span><span>Video · 1 workflow</span></span>
    <span>Cinema Studio 4.0</span>
    <span>Create video shots with camera and style controls and media references.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/ltx-2-5">
    <span><span>Lightricks</span><span>Video · 4 workflows</span></span>
    <span>LTX-2.5</span>
    <span>Generate videos from text or images with Fast and Pro variants.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/minimax-h3">
    <span><span>MiniMax</span><span>Video · 3 workflows</span></span>
    <span>MiniMax H3</span>
    <span>Generate videos from text, frames or multimodal references.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/hailuo-2-3">
    <span><span>MiniMax</span><span>Video · 2 workflows</span></span>
    <span>Hailuo 2.3</span>
    <span>Generate videos from text or an image with Hailuo 2.3 Standard.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/pixverse-v6">
    <span><span>PixVerse</span><span>Video · 2 workflows</span></span>
    <span>PixVerse V6</span>
    <span>Generate videos from text or images with optional sound.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/wan-2-6">
    <span><span>Alibaba</span><span>Video · 3 workflows</span></span>
    <span>Wan 2.6</span>
    <span>Generate videos from text, images or video references.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/wan-2-7">
    <span><span>Alibaba</span><span>Video · 3 workflows</span></span>
    <span>Wan 2.7</span>
    <span>Generate videos from text, frames or multimodal references.</span>
    <span>View API reference <span>→</span></span>
  </a>

  <a href="/docs/models/grok-video-1-5">
    <span><span>xAI</span><span>Video · 1 workflow</span></span>
    <span>Grok Imagine Video 1.5</span>
    <span>Generate videos from text, images or an audio reference.</span>
    <span>View API reference <span>→</span></span>
  </a>
</div>

## Quick start

1. Choose a model and the workflow that matches your inputs.
2. Submit its documented JSON body with your [API credentials](/docs/authentication).
3. Follow that workflow’s response instructions to retrieve the result.


# Wan 2.6 API
Source: https://docs.higgsfield.ai/docs/models/wan-2-6

Generate videos from text, images or video references.

<div />

Generate videos from text, images or video references.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to video](/docs/models/wan-2-6/text-to-video) | `POST /wan/v2.6/text-to-video` |
| [Image to video](/docs/models/wan-2-6/image-to-video) | `POST /wan/v2.6/image-to-video` |
| [Reference to video](/docs/models/wan-2-6/reference-to-video) | `POST /wan/v2.6/reference-to-video` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Wan 2.6 — Image to video API
Source: https://docs.higgsfield.ai/docs/models/wan-2-6/image-to-video

Image to video with Wan 2.6: request parameters, examples and response handling.

<div />

[← Wan 2.6](/docs/models/wan-2-6)

**Endpoint:** `POST https://api.higgsfield.ai/wan/v2.6/image-to-video`

**Endpoint ID:** `wan/v2.6/image-to-video`

<a href="https://console.higgsfield.ai/models/wan%2Fv2.6%2Fimage-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Wan 2.6 · Image to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Setting multi\_shots=true also enables prompt\_extend, even if prompt\_extend was false.
* Input images may be resized to fit a 1,440-pixel maximum dimension before generation. A last-frame input is unsupported.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/wan/v2.6/image-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
    "image_url": "https://example.com/input.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.',
       'image_url': 'https://example.com/input.jpg'}
  )
  result = higgsfield_client.subscribe(
      "wan/v2.6/image-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("wan/v2.6/image-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
        "image_url": "https://example.com/input.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `-1`.
  Maximum: `10000000`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Allowed values: `5`, `10`, `15`.
</ParamField>

<ParamField type="string">
  Public URL of the audio reference.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"480p"`, `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="boolean">
  See the complete JSON schema below.
</ParamField>

<ParamField type="boolean">
  Enable prompt expansion.
</ParamField>

<ParamField type="string">
  Content or visual features to avoid.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Wan 2.6 Playground",
    "required": [
      "prompt",
      "image_url"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "maximum": 10000000,
        "minimum": -1
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "enum": [
          5,
          10,
          15
        ],
        "type": "integer",
        "title": "Duration",
        "default": 5
      },
      "audio_url": {
        "type": "string",
        "title": "Audio URL",
        "format": "uri"
      },
      "image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p"
        ],
        "type": "string",
        "default": "720p"
      },
      "multi_shots": {
        "type": "boolean",
        "default": false
      },
      "prompt_extend": {
        "type": "boolean",
        "default": false
      },
      "negative_prompt": {
        "type": "string",
        "title": "Negative prompt",
        "default": ""
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Wan 2.6 — Reference to video API
Source: https://docs.higgsfield.ai/docs/models/wan-2-6/reference-to-video

Reference to video with Wan 2.6: request parameters, examples and response handling.

<div />

[← Wan 2.6](/docs/models/wan-2-6)

**Endpoint:** `POST https://api.higgsfield.ai/wan/v2.6/reference-to-video`

**Endpoint ID:** `wan/v2.6/reference-to-video`

<a href="https://console.higgsfield.ai/models/wan%2Fv2.6%2Freference-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Wan 2.6 · Reference to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Supply 1–3 reference videos. This endpoint supports only 5 or 10 seconds, unlike the text and image endpoints that also support 15 seconds.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/wan/v2.6/reference-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
    "video_urls": [
      "https://example.com/input.mp4"
    ]
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.',
       'video_urls': ['https://example.com/input.mp4']}
  )
  result = higgsfield_client.subscribe(
      "wan/v2.6/reference-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("wan/v2.6/reference-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
        "video_urls": [
          "https://example.com/input.mp4"
        ]
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Allowed values: `5`, `10`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="array">
  Ordered public video reference URLs.
  Minimum items: `1`.
  Maximum items: `3`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, `"3:4"`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Wan 2.6 Playground",
    "required": [
      "prompt",
      "video_urls"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "enum": [
          5,
          10
        ],
        "type": "integer",
        "title": "Duration",
        "default": 5
      },
      "resolution": {
        "enum": [
          "720p",
          "1080p"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "720p"
      },
      "video_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "title": "Video URL",
          "format": "uri"
        },
        "maxItems": 3,
        "minItems": 1
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16",
          "1:1",
          "4:3",
          "3:4"
        ],
        "type": "string",
        "default": "16:9"
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Wan 2.6 — Text to video API
Source: https://docs.higgsfield.ai/docs/models/wan-2-6/text-to-video

Text to video with Wan 2.6: request parameters, examples and response handling.

<div />

[← Wan 2.6](/docs/models/wan-2-6)

**Endpoint:** `POST https://api.higgsfield.ai/wan/v2.6/text-to-video`

**Endpoint ID:** `wan/v2.6/text-to-video`

<a href="https://console.higgsfield.ai/models/wan%2Fv2.6%2Ftext-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Wan 2.6 · Text to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Setting multi\_shots=true also enables prompt\_extend, even if prompt\_extend was false.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/wan/v2.6/text-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.'}
  )
  result = higgsfield_client.subscribe(
      "wan/v2.6/text-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("wan/v2.6/text-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `-1`.
  Maximum: `10000000`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Allowed values: `5`, `10`, `15`.
</ParamField>

<ParamField type="string">
  Public URL of the audio reference.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="boolean">
  See the complete JSON schema below.
</ParamField>

<ParamField type="boolean">
  Enable prompt expansion.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Wan 2.6 Playground",
    "required": [
      "prompt"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "maximum": 10000000,
        "minimum": -1
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "enum": [
          5,
          10,
          15
        ],
        "type": "integer",
        "title": "Duration",
        "default": 5
      },
      "audio_url": {
        "type": "string",
        "title": "Audio URL",
        "format": "uri"
      },
      "resolution": {
        "enum": [
          "720p",
          "1080p"
        ],
        "type": "string",
        "default": "720p"
      },
      "multi_shots": {
        "type": "boolean",
        "default": false
      },
      "prompt_extend": {
        "type": "boolean",
        "default": false
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Wan 2.7 API
Source: https://docs.higgsfield.ai/docs/models/wan-2-7

Generate videos from text, frames or multimodal references.

<div />

Generate videos from text, frames or multimodal references.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to video](/docs/models/wan-2-7/text-to-video) | `POST /wan/v2.7/text-to-video` |
| [Image to video](/docs/models/wan-2-7/image-to-video) | `POST /wan/v2.7/image-to-video` |
| [Reference to video](/docs/models/wan-2-7/reference-to-video) | `POST /wan/v2.7/reference-to-video` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Wan 2.7 — Image to video API
Source: https://docs.higgsfield.ai/docs/models/wan-2-7/image-to-video

Image to video with Wan 2.7: request parameters, examples and response handling.

<div />

[← Wan 2.7](/docs/models/wan-2-7)

**Endpoint:** `POST https://api.higgsfield.ai/wan/v2.7/image-to-video`

**Endpoint ID:** `wan/v2.7/image-to-video`

<a href="https://console.higgsfield.ai/models/wan%2Fv2.7%2Fimage-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Wan 2.7 · Image to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* The prompt is optional. end\_image\_url supplies a last frame, and audio\_url can supply driving audio.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/wan/v2.7/image-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "image_url": "https://example.com/input.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'image_url': 'https://example.com/input.jpg'}
  )
  result = higgsfield_client.subscribe(
      "wan/v2.7/image-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("wan/v2.7/image-to-video", {
    input:
      {
        "image_url": "https://example.com/input.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `1`.
  Maximum: `2147483646`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `2`.
  Maximum: `15`.
</ParamField>

<ParamField type="string">
  Public URL of the audio reference.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="string">
  Format: `uri`.
</ParamField>

<ParamField type="boolean">
  Enable prompt expansion.
</ParamField>

<ParamField type="string">
  Content or visual features to avoid.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Wan 2.6 Playground",
    "required": [
      "image_url"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "maximum": 2147483646,
        "minimum": 1
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 2
      },
      "audio_url": {
        "type": "string",
        "title": "Audio URL",
        "format": "uri"
      },
      "image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      },
      "resolution": {
        "enum": [
          "720p",
          "1080p"
        ],
        "type": "string",
        "default": "720p"
      },
      "end_image_url": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      },
      "prompt_extend": {
        "type": "boolean",
        "default": false
      },
      "negative_prompt": {
        "type": "string",
        "title": "Negative prompt",
        "default": ""
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Wan 2.7 — Reference to video API
Source: https://docs.higgsfield.ai/docs/models/wan-2-7/reference-to-video

Reference to video with Wan 2.7: request parameters, examples and response handling.

<div />

[← Wan 2.7](/docs/models/wan-2-7)

**Endpoint:** `POST https://api.higgsfield.ai/wan/v2.7/reference-to-video`

**Endpoint ID:** `wan/v2.7/reference-to-video`

<a href="https://console.higgsfield.ai/models/wan%2Fv2.7%2Freference-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Wan 2.7 · Reference to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Provide a nonempty image\_urls or video\_urls array. The combined number of image and video references must not exceed 5; this submission limit is not expressed in the stored JSON Schema.
* Reference generation is limited to 2–10 seconds and aspect ratios 16:9 or 9:16.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/wan/v2.7/reference-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
    "image_urls": [
      "https://example.com/input.jpg"
    ]
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.',
       'image_urls': ['https://example.com/input.jpg']}
  )
  result = higgsfield_client.subscribe(
      "wan/v2.7/reference-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("wan/v2.7/reference-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
        "image_urls": [
          "https://example.com/input.jpg"
        ]
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `1`.
  Maximum: `2147483646`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `2`.
  Maximum: `10`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="array">
  Ordered public video reference URLs.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`.
</ParamField>

<ParamField type="boolean">
  Enable prompt expansion.
</ParamField>

<ParamField type="string">
  Content or visual features to avoid.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "if": {
      "required": [
        "image_urls"
      ],
      "properties": {
        "image_urls": {
          "type": "array",
          "minItems": 1
        }
      }
    },
    "else": {
      "required": [
        "video_urls"
      ],
      "properties": {
        "video_urls": {
          "type": "array",
          "minItems": 1
        }
      }
    },
    "type": "object",
    "title": "Wan 2.7 References",
    "required": [
      "prompt"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "maximum": 2147483646,
        "minimum": 1
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 10,
        "minimum": 2
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "title": "Image",
          "format": "uri"
        }
      },
      "resolution": {
        "enum": [
          "720p",
          "1080p"
        ],
        "type": "string",
        "default": "720p"
      },
      "video_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "title": "Video",
          "format": "uri"
        }
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16"
        ],
        "type": "string",
        "title": "Aspect Ratio",
        "default": "16:9"
      },
      "prompt_extend": {
        "type": "boolean",
        "default": false
      },
      "negative_prompt": {
        "type": "string",
        "title": "Negative prompt",
        "default": ""
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Wan 2.7 — Text to video API
Source: https://docs.higgsfield.ai/docs/models/wan-2-7/text-to-video

Text to video with Wan 2.7: request parameters, examples and response handling.

<div />

[← Wan 2.7](/docs/models/wan-2-7)

**Endpoint:** `POST https://api.higgsfield.ai/wan/v2.7/text-to-video`

**Endpoint ID:** `wan/v2.7/text-to-video`

<a href="https://console.higgsfield.ai/models/wan%2Fv2.7%2Ftext-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Wan 2.7 · Text to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* The prompt must contain text. audio\_url can supply driving audio.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/wan/v2.7/text-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.'}
  )
  result = higgsfield_client.subscribe(
      "wan/v2.7/text-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("wan/v2.7/text-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `1`.
  Maximum: `2147483646`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  Requested output duration in seconds.
  Minimum: `2`.
  Maximum: `15`.
</ParamField>

<ParamField type="string">
  Public URL of the audio reference.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, `"3:4"`.
</ParamField>

<ParamField type="boolean">
  Enable prompt expansion.
</ParamField>

<ParamField type="string">
  Content or visual features to avoid.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Wan 2.6 Playground",
    "required": [
      "prompt"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "maximum": 2147483646,
        "minimum": 1
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration",
        "default": 5,
        "maximum": 15,
        "minimum": 2
      },
      "audio_url": {
        "type": "string",
        "title": "Audio URL",
        "format": "uri"
      },
      "resolution": {
        "enum": [
          "720p",
          "1080p"
        ],
        "type": "string",
        "default": "720p"
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "9:16",
          "1:1",
          "4:3",
          "3:4"
        ],
        "type": "string",
        "title": "Aspect Ratio",
        "default": "16:9"
      },
      "prompt_extend": {
        "type": "boolean",
        "default": false
      },
      "negative_prompt": {
        "type": "string",
        "title": "Negative prompt",
        "default": ""
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Wan 3.0 API
Source: https://docs.higgsfield.ai/docs/models/wan-3

Generate videos from text, frames or multimodal references.

<div />

Generate videos from text, frames or multimodal references.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to video](/docs/models/wan-3/text-to-video) | `POST /alibaba/wan-3.0/text-to-video` |
| [Image to video](/docs/models/wan-3/image-to-video) | `POST /alibaba/wan-3.0/image-to-video` |
| [Reference to video](/docs/models/wan-3/reference-to-video) | `POST /alibaba/wan-3.0/reference-to-video` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Wan 3.0 Prime API
Source: https://docs.higgsfield.ai/docs/models/wan-3-prime

Generate videos from text, frames or multimodal references with Wan 3.0 Prime.

<div />

Generate videos from text, frames or multimodal references with Wan 3.0 Prime.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Text to video](/docs/models/wan-3-prime/text-to-video) | `POST /alibaba/wan-3.0-prime/text-to-video` |
| [Image to video](/docs/models/wan-3-prime/image-to-video) | `POST /alibaba/wan-3.0-prime/image-to-video` |
| [Reference to video](/docs/models/wan-3-prime/reference-to-video) | `POST /alibaba/wan-3.0-prime/reference-to-video` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Wan 3.0 Prime — Image to video API
Source: https://docs.higgsfield.ai/docs/models/wan-3-prime/image-to-video

Image to video with Wan 3.0 Prime: request parameters, examples and response handling.

<div />

[← Wan 3.0 Prime](/docs/models/wan-3-prime)

**Endpoint:** `POST https://api.higgsfield.ai/alibaba/wan-3.0-prime/image-to-video`

**Endpoint ID:** `alibaba/wan-3.0-prime/image-to-video`

<a href="https://console.higgsfield.ai/models/alibaba%2Fwan-3.0-prime%2Fimage-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Wan 3.0 Prime · Image to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Use image\_url for the first frame and optional end\_image\_url for the last frame. Reference arrays belong to the reference-to-video endpoint.
* The schema accepts seed=0, but the current implementation only forwards a nonzero seed.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/alibaba/wan-3.0-prime/image-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
    "image_url": "https://example.com/input.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.',
       'image_url': 'https://example.com/input.jpg'}
  )
  result = higgsfield_client.subscribe(
      "alibaba/wan-3.0-prime/image-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("alibaba/wan-3.0-prime/image-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
        "image_url": "https://example.com/input.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `0`.
  Maximum: `2147483647`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  2-30 seconds.
  Minimum: `2`.
  Maximum: `30`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"480p"`, `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"adaptive"`.
</ParamField>

<ParamField type="string">
  Format: `uri`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<ParamField type="boolean">
  Enable model reasoning.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Wan 3.0 Prime Image to Video",
    "required": [
      "prompt",
      "image_url"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "title": "Seed",
        "maximum": 2147483647,
        "minimum": 0
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration (sec)",
        "default": 5,
        "maximum": 30,
        "minimum": 2,
        "description": "2-30 seconds."
      },
      "image_url": {
        "type": "string",
        "title": "First Frame",
        "format": "uri"
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "1080p"
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "4:3",
          "1:1",
          "3:4",
          "9:16",
          "adaptive"
        ],
        "type": "string",
        "title": "Aspect Ratio",
        "default": "adaptive"
      },
      "end_image_url": {
        "type": "string",
        "title": "Last Frame",
        "format": "uri"
      },
      "generate_audio": {
        "type": "boolean",
        "title": "Sound",
        "default": true
      },
      "enable_thinking": {
        "type": "boolean",
        "title": "Deep Thinking",
        "default": false
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Wan 3.0 Prime — Reference to video API
Source: https://docs.higgsfield.ai/docs/models/wan-3-prime/reference-to-video

Reference to video with Wan 3.0 Prime: request parameters, examples and response handling.

<div />

[← Wan 3.0 Prime](/docs/models/wan-3-prime)

**Endpoint:** `POST https://api.higgsfield.ai/alibaba/wan-3.0-prime/reference-to-video`

**Endpoint ID:** `alibaba/wan-3.0-prime/reference-to-video`

<a href="https://console.higgsfield.ai/models/alibaba%2Fwan-3.0-prime%2Freference-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Wan 3.0 Prime · Reference to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Reference media are optional in the stored schema: only prompt is required. The example includes an image to demonstrate reference mode.
* Send either file\_url or link\_url. A document or web-page reference automatically enables thinking; when both are sent, file\_url takes precedence.
* Reference video clips must be 1–30 seconds each and total at most 30 seconds. Reference audio must be WAV or MP3 and total at most 30 seconds, as specified in the production schema.
* The schema accepts seed=0, but the current implementation only forwards a nonzero seed.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/alibaba/wan-3.0-prime/reference-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
    "image_urls": [
      "https://example.com/input.jpg"
    ]
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.',
       'image_urls': ['https://example.com/input.jpg']}
  )
  result = higgsfield_client.subscribe(
      "alibaba/wan-3.0-prime/reference-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("alibaba/wan-3.0-prime/reference-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
        "image_urls": [
          "https://example.com/input.jpg"
        ]
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `0`.
  Maximum: `2147483647`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  2-30 seconds.
  Minimum: `2`.
  Maximum: `30`.
</ParamField>

<ParamField type="string">
  One document (docx/xlsx/pptx/pdf/md). Forces deep thinking.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  One public page. Forces deep thinking. Not combinable with file\_url.
  Format: `uri`.
</ParamField>

<ParamField type="array">
  Up to 5 files, 30s total. WAV or MP3.
  Maximum items: `5`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Maximum items: `10`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"480p"`, `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="array">
  Up to 5 clips, 30s total, each 1-30s.
  Maximum items: `5`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"adaptive"`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<ParamField type="boolean">
  Enable model reasoning.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Wan 3.0 Prime Reference to Video",
    "required": [
      "prompt"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "title": "Seed",
        "maximum": 2147483647,
        "minimum": 0
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration (sec)",
        "default": 5,
        "maximum": 30,
        "minimum": 2,
        "description": "2-30 seconds."
      },
      "file_url": {
        "type": "string",
        "title": "Reference Document",
        "format": "uri",
        "description": "One document (docx/xlsx/pptx/pdf/md). Forces deep thinking."
      },
      "link_url": {
        "type": "string",
        "title": "Reference Web Page",
        "format": "uri",
        "description": "One public page. Forces deep thinking. Not combinable with file_url."
      },
      "audio_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "title": "Reference Audio",
        "maxItems": 5,
        "description": "Up to 5 files, 30s total. WAV or MP3."
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "title": "Reference Images",
        "maxItems": 10
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "1080p"
      },
      "video_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "title": "Reference Videos",
        "maxItems": 5,
        "description": "Up to 5 clips, 30s total, each 1-30s."
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "4:3",
          "1:1",
          "3:4",
          "9:16",
          "adaptive"
        ],
        "type": "string",
        "title": "Aspect Ratio",
        "default": "adaptive"
      },
      "generate_audio": {
        "type": "boolean",
        "title": "Sound",
        "default": true
      },
      "enable_thinking": {
        "type": "boolean",
        "title": "Deep Thinking",
        "default": false
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Wan 3.0 Prime — Text to video API
Source: https://docs.higgsfield.ai/docs/models/wan-3-prime/text-to-video

Text to video with Wan 3.0 Prime: request parameters, examples and response handling.

<div />

[← Wan 3.0 Prime](/docs/models/wan-3-prime)

**Endpoint:** `POST https://api.higgsfield.ai/alibaba/wan-3.0-prime/text-to-video`

**Endpoint ID:** `alibaba/wan-3.0-prime/text-to-video`

<a href="https://console.higgsfield.ai/models/alibaba%2Fwan-3.0-prime%2Ftext-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Wan 3.0 Prime · Text to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* This endpoint generates from text; use the separate image or reference endpoint for media inputs.
* The schema accepts seed=0, but the current implementation only forwards a nonzero seed.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/alibaba/wan-3.0-prime/text-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.'}
  )
  result = higgsfield_client.subscribe(
      "alibaba/wan-3.0-prime/text-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("alibaba/wan-3.0-prime/text-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `0`.
  Maximum: `2147483647`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  2-30 seconds.
  Minimum: `2`.
  Maximum: `30`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"480p"`, `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"adaptive"`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<ParamField type="boolean">
  Enable model reasoning.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Wan 3.0 Prime Text to Video",
    "required": [
      "prompt"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "title": "Seed",
        "maximum": 2147483647,
        "minimum": 0
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration (sec)",
        "default": 5,
        "maximum": 30,
        "minimum": 2,
        "description": "2-30 seconds."
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "1080p"
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "4:3",
          "1:1",
          "3:4",
          "9:16",
          "adaptive"
        ],
        "type": "string",
        "title": "Aspect Ratio",
        "default": "adaptive"
      },
      "generate_audio": {
        "type": "boolean",
        "title": "Sound",
        "default": true
      },
      "enable_thinking": {
        "type": "boolean",
        "title": "Deep Thinking",
        "default": false
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Wan 3.0 — Image to video API
Source: https://docs.higgsfield.ai/docs/models/wan-3/image-to-video

Image to video with Wan 3.0: request parameters, examples and response handling.

<div />

[← Wan 3.0](/docs/models/wan-3)

**Endpoint:** `POST https://api.higgsfield.ai/alibaba/wan-3.0/image-to-video`

**Endpoint ID:** `alibaba/wan-3.0/image-to-video`

<a href="https://console.higgsfield.ai/models/alibaba%2Fwan-3.0%2Fimage-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Wan 3.0 · Image to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Use image\_url for the first frame and optional end\_image\_url for the last frame. Reference arrays belong to the reference-to-video endpoint.
* The schema accepts seed=0, but the current implementation only forwards a nonzero seed.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/alibaba/wan-3.0/image-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
    "image_url": "https://example.com/input.jpg"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.',
       'image_url': 'https://example.com/input.jpg'}
  )
  result = higgsfield_client.subscribe(
      "alibaba/wan-3.0/image-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("alibaba/wan-3.0/image-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
        "image_url": "https://example.com/input.jpg"
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `0`.
  Maximum: `2147483647`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  2-30 seconds.
  Minimum: `2`.
  Maximum: `30`.
</ParamField>

<ParamField type="string">
  Public URL of the input image.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"480p"`, `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"adaptive"`.
</ParamField>

<ParamField type="string">
  Format: `uri`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<ParamField type="boolean">
  Enable model reasoning.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Wan 3.0 Image to Video",
    "required": [
      "prompt",
      "image_url"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "title": "Seed",
        "maximum": 2147483647,
        "minimum": 0
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration (sec)",
        "default": 5,
        "maximum": 30,
        "minimum": 2,
        "description": "2-30 seconds."
      },
      "image_url": {
        "type": "string",
        "title": "First Frame",
        "format": "uri"
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "1080p"
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "4:3",
          "1:1",
          "3:4",
          "9:16",
          "adaptive"
        ],
        "type": "string",
        "title": "Aspect Ratio",
        "default": "adaptive"
      },
      "end_image_url": {
        "type": "string",
        "title": "Last Frame",
        "format": "uri"
      },
      "generate_audio": {
        "type": "boolean",
        "title": "Sound",
        "default": true
      },
      "enable_thinking": {
        "type": "boolean",
        "title": "Deep Thinking",
        "default": false
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Wan 3.0 — Reference to video API
Source: https://docs.higgsfield.ai/docs/models/wan-3/reference-to-video

Reference to video with Wan 3.0: request parameters, examples and response handling.

<div />

[← Wan 3.0](/docs/models/wan-3)

**Endpoint:** `POST https://api.higgsfield.ai/alibaba/wan-3.0/reference-to-video`

**Endpoint ID:** `alibaba/wan-3.0/reference-to-video`

<a href="https://console.higgsfield.ai/models/alibaba%2Fwan-3.0%2Freference-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Wan 3.0 · Reference to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* Reference media are optional in the stored schema: only prompt is required. The example includes an image to demonstrate reference mode.
* Send either file\_url or link\_url. A document or web-page reference automatically enables thinking; when both are sent, file\_url takes precedence.
* Reference video clips must be 1–30 seconds each and total at most 30 seconds. Reference audio must be WAV or MP3 and total at most 30 seconds, as specified in the production schema.
* The schema accepts seed=0, but the current implementation only forwards a nonzero seed.

## Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/alibaba/wan-3.0/reference-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
    "image_urls": [
      "https://example.com/input.jpg"
    ]
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.',
       'image_urls': ['https://example.com/input.jpg']}
  )
  result = higgsfield_client.subscribe(
      "alibaba/wan-3.0/reference-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("alibaba/wan-3.0/reference-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
        "image_urls": [
          "https://example.com/input.jpg"
        ]
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `0`.
  Maximum: `2147483647`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  2-30 seconds.
  Minimum: `2`.
  Maximum: `30`.
</ParamField>

<ParamField type="string">
  One document (docx/xlsx/pptx/pdf/md). Forces deep thinking.
  Format: `uri`.
</ParamField>

<ParamField type="string">
  One public page. Forces deep thinking. Not combinable with file\_url.
  Format: `uri`.
</ParamField>

<ParamField type="array">
  Up to 5 files, 30s total. WAV or MP3.
  Maximum items: `5`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="array">
  Ordered public image reference URLs.
  Maximum items: `10`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"480p"`, `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="array">
  Up to 5 clips, 30s total, each 1-30s.
  Maximum items: `5`.
  Each item: string. Format: `uri`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"adaptive"`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<ParamField type="boolean">
  Enable model reasoning.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Wan 3.0 Reference to Video",
    "required": [
      "prompt"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "title": "Seed",
        "maximum": 2147483647,
        "minimum": 0
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration (sec)",
        "default": 5,
        "maximum": 30,
        "minimum": 2,
        "description": "2-30 seconds."
      },
      "file_url": {
        "type": "string",
        "title": "Reference Document",
        "format": "uri",
        "description": "One document (docx/xlsx/pptx/pdf/md). Forces deep thinking."
      },
      "link_url": {
        "type": "string",
        "title": "Reference Web Page",
        "format": "uri",
        "description": "One public page. Forces deep thinking. Not combinable with file_url."
      },
      "audio_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "title": "Reference Audio",
        "maxItems": 5,
        "description": "Up to 5 files, 30s total. WAV or MP3."
      },
      "image_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "title": "Reference Images",
        "maxItems": 10
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "1080p"
      },
      "video_urls": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "title": "Reference Videos",
        "maxItems": 5,
        "description": "Up to 5 clips, 30s total, each 1-30s."
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "4:3",
          "1:1",
          "3:4",
          "9:16",
          "adaptive"
        ],
        "type": "string",
        "title": "Aspect Ratio",
        "default": "adaptive"
      },
      "generate_audio": {
        "type": "boolean",
        "title": "Sound",
        "default": true
      },
      "enable_thinking": {
        "type": "boolean",
        "title": "Deep Thinking",
        "default": false
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Wan 3.0 — Text to video API
Source: https://docs.higgsfield.ai/docs/models/wan-3/text-to-video

Text to video with Wan 3.0: request parameters, examples and response handling.

<div />

[← Wan 3.0](/docs/models/wan-3)

**Endpoint:** `POST https://api.higgsfield.ai/alibaba/wan-3.0/text-to-video`

**Endpoint ID:** `alibaba/wan-3.0/text-to-video`

<a href="https://console.higgsfield.ai/models/alibaba%2Fwan-3.0%2Ftext-to-video/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Wan 3.0 · Text to video</span></span>
  <span>↗</span>
</a>

## Usage notes

* This endpoint generates from text; use the separate image or reference endpoint for media inputs.
* The schema accepts seed=0, but the current implementation only forwards a nonzero seed.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/alibaba/wan-3.0/text-to-video \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
                 'movement.'}
  )
  result = higgsfield_client.subscribe(
      "alibaba/wan-3.0/text-to-video",
      arguments=arguments,
  )
  print(result["video"]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("alibaba/wan-3.0/text-to-video", {
    input:
      {
        "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.video?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Seed used to control generation randomness.
  Minimum: `0`.
  Maximum: `2147483647`.
</ParamField>

<ParamField type="string">
  Write your prompt here
</ParamField>

<ParamField type="integer">
  2-30 seconds.
  Minimum: `2`.
  Maximum: `30`.
</ParamField>

<ParamField type="string">
  Output resolution tier.
  Allowed values: `"480p"`, `"720p"`, `"1080p"`.
</ParamField>

<ParamField type="string">
  Output width-to-height ratio.
  Allowed values: `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"adaptive"`.
</ParamField>

<ParamField type="boolean">
  Generate audio with the video.
</ParamField>

<ParamField type="boolean">
  Enable model reasoning.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Wan 3.0 Text to Video",
    "required": [
      "prompt"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "title": "Seed",
        "maximum": 2147483647,
        "minimum": 0
      },
      "prompt": {
        "type": "string",
        "title": "Prompt",
        "description": "Write your prompt here"
      },
      "duration": {
        "type": "integer",
        "title": "Duration (sec)",
        "default": 5,
        "maximum": 30,
        "minimum": 2,
        "description": "2-30 seconds."
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p"
        ],
        "type": "string",
        "title": "Resolution",
        "default": "1080p"
      },
      "aspect_ratio": {
        "enum": [
          "16:9",
          "4:3",
          "1:1",
          "3:4",
          "9:16",
          "adaptive"
        ],
        "type": "string",
        "title": "Aspect Ratio",
        "default": "adaptive"
      },
      "generate_audio": {
        "type": "boolean",
        "title": "Sound",
        "default": true
      },
      "enable_thinking": {
        "type": "boolean",
        "title": "Deep Thinking",
        "default": false
      }
    }
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Z-Image Turbo API
Source: https://docs.higgsfield.ai/docs/models/z-image-turbo

Generate images at 1K or 2K with optional prompt enhancement.

<div />

Generate images at 1K or 2K with optional prompt enhancement.

## Workflows

| Workflow | Endpoint |
| - | - |
| [Generate](/docs/models/z-image-turbo/generate) | `POST /z-image/turbo` |

Open a workflow to see its complete input schema, required fields, supported values and request examples.


# Z-Image Turbo — Generate API
Source: https://docs.higgsfield.ai/docs/models/z-image-turbo/generate

Generate with Z-Image Turbo: request parameters, examples and response handling.

<div />

[← Z-Image Turbo](/docs/models/z-image-turbo)

**Endpoint:** `POST https://api.higgsfield.ai/z-image/turbo`

**Endpoint ID:** `z-image/turbo`

<a href="https://console.higgsfield.ai/models/z-image%2Fturbo/playground">
  <span>▶</span>
  <span><span>Open API Playground</span><span>Z-Image Turbo · Generate</span></span>
  <span>↗</span>
</a>

## Usage notes

* Text-to-image only. prompt must contain non-whitespace text and at most 800 characters.
* prompt\_extend defaults to false; enabling it uses the enhanced pricing tier.
* The schema accepts 1k and 2k tiers, ten aspect ratios, and an optional integer seed from 0 to 2147483647.

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://api.higgsfield.ai/z-image/turbo \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    --data '{
    "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
    "resolution": "1k",
    "aspect_ratio": "1:1",
    "prompt_extend": false
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import higgsfield_client

  arguments = (
      {'prompt': 'A ceramic vase on a wooden table beside a sunlit window, soft '
                 'natural shadows, editorial photograph.',
       'resolution': '1k',
       'aspect_ratio': '1:1',
       'prompt_extend': False}
  )
  result = higgsfield_client.subscribe(
      "z-image/turbo",
      arguments=arguments,
  )
  print(result["images"][0]["url"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { config, higgsfield } from "@higgsfield/client/v2";

  config({ credentials: process.env.HF_CREDENTIALS });

  const result = await higgsfield.subscribe("z-image/turbo", {
    input:
      {
        "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
        "resolution": "1k",
        "aspect_ratio": "1:1",
        "prompt_extend": false
      },
    withPolling: true,
  });

  if (result.status === "completed") {
    console.log(result.images?.[0]?.url);
  }
  ```
</CodeGroup>

## Input schema

<ParamField type="integer">
  Optional random seed for similar, reproducible results.
  Minimum: `0`.
  Maximum: `2147483647`.
</ParamField>

<ParamField type="string">
  Positive prompt describing the desired content, style, and composition.
  Minimum characters: `1`.
  Maximum characters: `800`.
</ParamField>

<ParamField type="string">
  Output resolution tier. Both tiers produce PNG images.
  Allowed values: `"1k"`, `"2k"`.
</ParamField>

<ParamField type="string">
  Output aspect ratio. Exact provider-recommended dimensions are selected automatically.
  Allowed values: `"1:1"`, `"2:3"`, `"3:2"`, `"3:4"`, `"4:3"`, `"7:9"`, `"9:7"`, `"9:16"`, `"16:9"`, `"21:9"`.
</ParamField>

<ParamField type="boolean">
  Rewrite and reason over the prompt before generation; this uses the enhanced price tier.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "title": "Z-Image Turbo",
    "required": [
      "prompt"
    ],
    "properties": {
      "seed": {
        "type": "integer",
        "maximum": 2147483647,
        "minimum": 0,
        "description": "Optional random seed for similar, reproducible results."
      },
      "prompt": {
        "type": "string",
        "maxLength": 800,
        "minLength": 1,
        "description": "Positive prompt describing the desired content, style, and composition."
      },
      "resolution": {
        "enum": [
          "1k",
          "2k"
        ],
        "type": "string",
        "default": "1k",
        "description": "Output resolution tier. Both tiers produce PNG images."
      },
      "aspect_ratio": {
        "enum": [
          "1:1",
          "2:3",
          "3:2",
          "3:4",
          "4:3",
          "7:9",
          "9:7",
          "9:16",
          "16:9",
          "21:9"
        ],
        "type": "string",
        "default": "1:1",
        "description": "Output aspect ratio. Exact provider-recommended dimensions are selected automatically."
      },
      "prompt_extend": {
        "type": "boolean",
        "default": false,
        "description": "Rewrite and reason over the prompt before generation; this uses the enhanced price tier."
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Response

Submission returns a request handle. Poll `status_url` until `status` is `completed`, or use [webhooks](/docs/how-to/webhooks).

```json Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
```

A completed response includes the following output fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "images": [
    {
      "url": "https://example.com/output.png"
    }
  ]
}
```

See [idempotent requests](/docs/concepts/idempotency), [polling](/docs/concepts/polling), [request errors](/docs/concepts/errors) and [authentication](/docs/authentication) for shared request handling.


# Organizations
Source: https://docs.higgsfield.ai/docs/organizations

Create an organization and collaborate with members in the Higgsfield API dashboard.

Organizations give your team a dedicated workspace in the Higgsfield API dashboard. Members keep their own sign-in and can switch between their personal account and any organization they belong to.

## Organization workspace

Use the account switcher in the dashboard to create an organization or move between existing organizations.

## Next step

<Card title="Managing members" icon="users" href="/docs/organizations/managing-members">
  Invite members and understand organization roles.
</Card>


# Managing members
Source: https://docs.higgsfield.ai/docs/organizations/managing-members

Invite members and manage access to your Higgsfield organization.

Organization administrators manage membership from the organization settings in the Higgsfield API dashboard.

## Open organization settings

1. Sign in to the [Higgsfield API dashboard](https://console.higgsfield.ai).
2. Select the organization from the account switcher.
3. Open **Organization settings**.

## Roles

| Role | Access |
| - | - |
| Admin | Manages organization settings and members. |
| Member | Uses the organization workspace without member-management access. |

## Enterprise SSO

Enterprise SSO lets organization members authenticate through your identity provider. SSO configuration is available to organization members with the **Manage SSO** permission.

### Supported identity providers

| Provider | Connection type |
| - | - |
| Okta | SAML |
| Microsoft | SAML |
| Custom provider | Custom SAML |

### Configure a SAML connection

1. Select your organization in the [Higgsfield API dashboard](https://console.higgsfield.ai).
2. Open **Enterprise SSO** and select **Create SAML Connection**.
3. Enter a connection name and the domains that should use SSO.
4. Select your identity provider.
5. Add the Higgsfield **ACS URL** and **Entity ID** to your identity provider.
6. Enter your identity provider metadata or its SSO URL, entity ID, and certificate.
7. Review the attribute mapping, save the connection, and activate it.

Authorized organization members can edit, activate, deactivate, or delete existing SAML connections.

<Note>
  SSO settings are scoped to the currently selected organization.
</Note>


# Quickstart
Source: https://docs.higgsfield.ai/docs/quickstart

Submit a generation request and retrieve its result.

This guide uses the REST API so you can see the complete request lifecycle. It takes about five minutes.

## Prerequisites

* A [Higgsfield Console](https://console.higgsfield.ai) account
* An API key ID and secret
* `curl` and `jq`

<Warning>
  API credentials grant access to your account and credits. Use them only in server-side code and never commit them to source control.
</Warning>

## 1. Configure credentials

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export HF_API_KEY_ID="your-api-key-id"
export HF_API_KEY_SECRET="your-api-key-secret"
export IDEMPOTENCY_KEY=$(uuidgen | tr '[:upper:]' '[:lower:]')
```

## 2. Submit a generation

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url https://api.higgsfield.ai/higgsfield-ai/soul/v2/standard \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --data '{
    "prompt": "A quiet alpine lake at sunrise, editorial photography"
  }')

echo "$RESPONSE" | jq
export REQUEST_ID=$(echo "$RESPONSE" | jq --raw-output '.request_id')
```

The initial response has the `queued` status:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "queued",
  "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
  "status_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status",
  "cancel_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel"
}
```

If submission times out before you receive this response, repeat it with the same `IDEMPOTENCY_KEY`. See [Idempotent requests](/docs/concepts/idempotency).

## 3. Check the result

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --silent --show-error --fail-with-body \
  --url "https://api.higgsfield.ai/requests/${REQUEST_ID}/status" \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" | jq
```

Repeat the status request until it reaches a terminal state. A completed image request returns:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
  "status_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status",
  "cancel_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel",
  "images": [
    {
      "url": "https://cdn.example.com/generated-image.jpg"
    }
  ]
}
```

The other terminal statuses are `failed`, `nsfw`, and `canceled`.

## Next steps

<CardGroup>
  <Card title="Use an SDK" icon="code" href="/docs/how-to/sdk">
    Submit and wait for results with Python or TypeScript.
  </Card>

  <Card title="Prepare for production" icon="server" href="/docs/concepts/polling">
    Add backoff, timeouts, terminal-state handling, and webhooks.
  </Card>
</CardGroup>