# Authentication
Source: https://novita.ai/docs/api-reference/basic-authentication



The `Novita AI` API uses API keys in the `request headers` to authenticate requests. You can view and manage your API keys in [settings page](https://novita.ai/settings/key-management?utm_source=getstarted).

```js theme={"system"}
{
    "Authorization": "Bearer {{API Key}}"
}
```


# API Error Codes
Source: https://novita.ai/docs/api-reference/basic-error-code



## Image / Video / Audio

<table>
  <thead>
    <tr>
      <th>Error Name</th>
      <th>Status Code</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>INVALID\_REQUEST\_BODY</td>
      <td>400</td>
      <td>Request parameter validation failed</td>
    </tr>

    <tr>
      <td>IMAGE\_FILE\_EXCEEDS\_MAX\_SIZE</td>
      <td>400</td>
      <td>Image size exceeds limit</td>
    </tr>

    <tr>
      <td>INVALID\_IMAGE\_FORMAT</td>
      <td>400</td>
      <td>Image format does not meet requirements</td>
    </tr>

    <tr>
      <td>IMAGE\_EXCEEDS\_MAX\_RESOLUTION</td>
      <td>400</td>
      <td>Image resolution exceeds limit</td>
    </tr>

    <tr>
      <td>INVALID\_IMAGE\_SIZE</td>
      <td>400</td>
      <td>Image width or height exceeds limit</td>
    </tr>

    <tr>
      <td>API\_NOT\_FOUND</td>
      <td>404</td>
      <td>API not found</td>
    </tr>

    <tr>
      <td>IMAGE\_NO\_FACE\_DETECTED</td>
      <td>400</td>
      <td>No face detected</td>
    </tr>

    <tr>
      <td>INVALID\_CUSTOM\_OUTPUT\_PATH</td>
      <td>400</td>
      <td>Invalid OSS path</td>
    </tr>

    <tr>
      <td>ILLEGAL\_PROMPT</td>
      <td>400</td>
      <td>Prompt contains inappropriate content</td>
    </tr>

    <tr>
      <td>ILLEGAL\_IMAGE\_CONTENT</td>
      <td>400</td>
      <td>Image contains inappropriate content</td>
    </tr>

    <tr>
      <td>INVALID\_AUDIO\_FILE</td>
      <td>400</td>
      <td>Invalid audio input</td>
    </tr>

    <tr>
      <td>BILLING\_FAILED</td>
      <td>500</td>
      <td>Billing service error</td>
    </tr>

    <tr>
      <td>BILLING\_AUTH\_FAILED</td>
      <td>403</td>
      <td>Billing service authentication failed</td>
    </tr>

    <tr>
      <td>BILLING\_BALANCE\_NOT\_ENOUGH</td>
      <td>400</td>
      <td>Insufficient balance</td>
    </tr>

    <tr>
      <td>MISSING\_API\_KEY</td>
      <td>400</td>
      <td>API Key not provided</td>
    </tr>

    <tr>
      <td>INVALID\_API\_KEY</td>
      <td>403</td>
      <td>API Key validation failed</td>
    </tr>

    <tr>
      <td>FEATURE\_NOT\_ALLOWED</td>
      <td>403</td>
      <td>No permission to upload model</td>
    </tr>

    <tr>
      <td>API\_NOT\_ALLOWED</td>
      <td>403</td>
      <td>No permission to use this API</td>
    </tr>

    <tr>
      <td>RATE\_LIMIT\_EXCEEDED</td>
      <td>429</td>
      <td>Rate limit exceeded</td>
    </tr>

    <tr>
      <td>NEED\_REAL\_NAME\_VERIFY</td>
      <td>403</td>
      <td>Enterprise verification not completed</td>
    </tr>

    <tr>
      <td>CREATE\_TASK\_FAILED</td>
      <td>500</td>
      <td>Failed to create task</td>
    </tr>

    <tr>
      <td>TASK\_NOT\_FOUND</td>
      <td>404</td>
      <td>Task not found</td>
    </tr>

    <tr>
      <td>GET\_RESULT\_FAILED</td>
      <td>500</td>
      <td>Failed to get task result</td>
    </tr>

    <tr>
      <td>TASK\_FAILED</td>
      <td>500</td>
      <td>Task execution failed</td>
    </tr>
  </tbody>
</table>

## LLM

<table>
  <thead>
    <tr>
      <th>Error Name</th>
      <th>Status Code</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>INVALID\_API\_KEY</td>
      <td>403</td>
      <td>API Key not provided</td>
    </tr>

    <tr>
      <td>MODEL\_NOT\_FOUND</td>
      <td>404</td>
      <td>Model not found</td>
    </tr>

    <tr>
      <td>FAILED\_TO\_AUTH</td>
      <td>401</td>
      <td>Authentication failed</td>
    </tr>

    <tr>
      <td>NOT\_ENOUGH\_BALANCE</td>
      <td>403</td>
      <td>Insufficient balance</td>
    </tr>

    <tr>
      <td>INVALID\_REQUEST\_BODY</td>
      <td>400</td>
      <td>Request body format error, see message for details</td>
    </tr>

    <tr>
      <td>RATE\_LIMIT\_EXCEEDED</td>
      <td>429</td>
      <td>Too many requests, please try again later</td>
    </tr>

    <tr>
      <td>TOKEN\_LIMIT\_EXCEEDED</td>
      <td>429</td>
      <td>Token limit exceeded, please try again later</td>
    </tr>

    <tr>
      <td>SERVICE\_NOT\_AVAILABLE</td>
      <td>503</td>
      <td>Service unavailable</td>
    </tr>

    <tr>
      <td>ACCESS\_DENY</td>
      <td>403</td>
      <td>Access denied</td>
    </tr>
  </tbody>
</table>

## GPU

<table>
  <thead>
    <tr>
      <th>Error Name</th>
      <th>Status Code</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>UNKNOWN</td>
      <td>500</td>
      <td>Unknown error</td>
    </tr>

    <tr>
      <td>GET\_TOKEN\_FAILED</td>
      <td>400</td>
      <td>Failed to obtain token</td>
    </tr>

    <tr>
      <td>FORBIDDEN</td>
      <td>403</td>
      <td>Access forbidden / No permission</td>
    </tr>

    <tr>
      <td>UNAUTHORIZED</td>
      <td>401</td>
      <td>Unauthorized</td>
    </tr>

    <tr>
      <td>USER\_ALREADY\_EXISTS</td>
      <td>400</td>
      <td>User already exists</td>
    </tr>

    <tr>
      <td>INVALID\_USER\_OR\_PASSWORD</td>
      <td>400</td>
      <td>Invalid username or password</td>
    </tr>

    <tr>
      <td>INVALID\_CODE</td>
      <td>400</td>
      <td>Invalid verification code</td>
    </tr>

    <tr>
      <td>USER\_NOT\_FOUND</td>
      <td>400</td>
      <td>User not found</td>
    </tr>

    <tr>
      <td>USER\_PHONE\_NOT\_CONSIST</td>
      <td>400</td>
      <td>User phone number mismatch</td>
    </tr>

    <tr>
      <td>SEND\_CODE\_TOO\_FAST</td>
      <td>429</td>
      <td>Verification code sent too frequently</td>
    </tr>

    <tr>
      <td>INVALID\_PUBLIC\_KEY</td>
      <td>400</td>
      <td>Invalid public key</td>
    </tr>

    <tr>
      <td>USER\_NOT\_ACTIVATED</td>
      <td>400</td>
      <td>User not activated</td>
    </tr>

    <tr>
      <td>USER\_ALREADY\_ACTIVATED</td>
      <td>400</td>
      <td>User already activated</td>
    </tr>

    <tr>
      <td>INVALID\_USER\_TOKEN</td>
      <td>400</td>
      <td>Invalid user token</td>
    </tr>

    <tr>
      <td>BANNED\_USER</td>
      <td>400</td>
      <td>Account has been banned</td>
    </tr>

    <tr>
      <td>RATE\_LIMIT\_EXCEEDED</td>
      <td>429</td>
      <td>Request rate limit exceeded</td>
    </tr>

    <tr>
      <td>RESOURCE\_NOT\_FOUND</td>
      <td>400</td>
      <td>Resource not found (e.g., container not found)</td>
    </tr>

    <tr>
      <td>CONFLICT</td>
      <td>400</td>
      <td>Conflict (e.g., container conflict)</td>
    </tr>

    <tr>
      <td>VALIDATOR\_PARAM</td>
      <td>400</td>
      <td>Parameter validation failed / Invalid parameter</td>
    </tr>

    <tr>
      <td>REQUEST</td>
      <td>400</td>
      <td>Request error</td>
    </tr>

    <tr>
      <td>OPERATION\_LIMIT</td>
      <td>400</td>
      <td>Operation limit reached</td>
    </tr>

    <tr>
      <td>INSUFFICIENT\_RESOURCE</td>
      <td>400</td>
      <td>Insufficient resources</td>
    </tr>

    <tr>
      <td>CLUSTER\_STATUS</td>
      <td>400</td>
      <td>Cluster status abnormal</td>
    </tr>

    <tr>
      <td>NODE\_STATUS</td>
      <td>400</td>
      <td>Node status abnormal</td>
    </tr>

    <tr>
      <td>DEPENDENT\_RESOURCE\_STATE</td>
      <td>400</td>
      <td>Dependent resource state abnormal</td>
    </tr>

    <tr>
      <td>PREPAID\_INSTANCE\_NOT\_SUPPORT\_RELEASE</td>
      <td>400</td>
      <td>Prepaid instance does not support release</td>
    </tr>

    <tr>
      <td>CREATING\_INSTANCE\_NOT\_SUPPORT\_RENEWAL</td>
      <td>400</td>
      <td>Instance in creation does not support renewal</td>
    </tr>

    <tr>
      <td>INSTANCE\_LOCAL\_STORAGE\_NOT\_FOUND</td>
      <td>400</td>
      <td>Instance local storage not found</td>
    </tr>

    <tr>
      <td>INVALID\_COMMAND\_PARAM</td>
      <td>400</td>
      <td>Invalid instance startup command parameter</td>
    </tr>

    <tr>
      <td>GPU\_SPEC\_USED</td>
      <td>400</td>
      <td>GPU specification already in use</td>
    </tr>

    <tr>
      <td>INCORRECT\_USER\_SYNCER\_REQUIRE\_PARAMS</td>
      <td>400</td>
      <td>Incorrect user syncer request parameters</td>
    </tr>

    <tr>
      <td>MIGRATE\_INSUFFICIENT\_RESOURCE</td>
      <td>400</td>
      <td>Insufficient resources for migration</td>
    </tr>

    <tr>
      <td>WALLET\_NOT\_FOUND</td>
      <td>500</td>
      <td>Wallet not found</td>
    </tr>

    <tr>
      <td>WALLET\_UNSUPPORT\_RECHARGE\_METHOD</td>
      <td>400</td>
      <td>Unsupported wallet recharge method</td>
    </tr>

    <tr>
      <td>BALANCE\_NOT\_ENOUGH</td>
      <td>400</td>
      <td>Insufficient balance</td>
    </tr>

    <tr>
      <td>UNSUPPORTED\_BILLING\_MODE</td>
      <td>400</td>
      <td>Unsupported billing mode</td>
    </tr>

    <tr>
      <td>EXPIRED\_OR\_BALANCE\_NOT\_ENOUGH</td>
      <td>400</td>
      <td>Expired or insufficient balance</td>
    </tr>

    <tr>
      <td>ORDER\_NOT\_FOUND</td>
      <td>400</td>
      <td>Order not found</td>
    </tr>

    <tr>
      <td>SAVING\_PLAN\_ALREADY\_EXISTS</td>
      <td>400</td>
      <td>Saving plan already exists</td>
    </tr>

    <tr>
      <td>CREATE\_INSTANCE\_LIMIT</td>
      <td>400</td>
      <td>Instance creation limit reached, please recharge or delete other instances</td>
    </tr>

    <tr>
      <td>NETWORK\_STORAGE\_TOO\_LARGE</td>
      <td>400</td>
      <td>Network storage size exceeds limit</td>
    </tr>

    <tr>
      <td>CUR\_CLUSTER\_NETWORK\_STORAGE\_NOT\_SUPPORT</td>
      <td>400</td>
      <td>Network storage not supported in current region</td>
    </tr>

    <tr>
      <td>NETWORK\_STORAGE\_IN\_USE</td>
      <td>400</td>
      <td>Network storage is in use</td>
    </tr>

    <tr>
      <td>NETWORK\_STORAGE\_UNAVAILABLE</td>
      <td>400</td>
      <td>Network storage unavailable</td>
    </tr>

    <tr>
      <td>NETWORK\_STORAGE\_NOT\_FOUND</td>
      <td>400</td>
      <td>Network storage not found</td>
    </tr>

    <tr>
      <td>IMAGE\_NOT\_FOUND</td>
      <td>400</td>
      <td>Image not found</td>
    </tr>

    <tr>
      <td>IMAGE\_AUTH\_IN\_USE</td>
      <td>400</td>
      <td>Image authentication in use</td>
    </tr>

    <tr>
      <td>NETWORK\_NOT\_FOUND</td>
      <td>400</td>
      <td>Instance network not found</td>
    </tr>

    <tr>
      <td>NETWORK\_IN\_USE</td>
      <td>400</td>
      <td>Instance network in use</td>
    </tr>

    <tr>
      <td>NETWORK\_MAX\_LIMIT</td>
      <td>400</td>
      <td>Instance network creation limit exceeded</td>
    </tr>

    <tr>
      <td>SEND\_MSG\_ERROR</td>
      <td>400</td>
      <td>Message sending error</td>
    </tr>

    <tr>
      <td>JOB\_NOT\_FOUND</td>
      <td>400</td>
      <td>Instance job not found</td>
    </tr>

    <tr>
      <td>SERVERLESS\_ENDPOINT\_NOT\_FOUND</td>
      <td>400</td>
      <td>Serverless endpoint not found</td>
    </tr>

    <tr>
      <td>SERVERLESS\_WORKER\_NOT\_FOUND</td>
      <td>400</td>
      <td>Serverless worker not found</td>
    </tr>

    <tr>
      <td>SERVERLESS\_PRODUCT\_NOT\_FOUND</td>
      <td>400</td>
      <td>Serverless product not found</td>
    </tr>

    <tr>
      <td>SERVERLESS\_APP\_NAME\_IS\_EXIST</td>
      <td>400</td>
      <td>Serverless application name already exists</td>
    </tr>

    <tr>
      <td>TEMPLATE\_IS\_PRIVATE</td>
      <td>400</td>
      <td>Template is private</td>
    </tr>

    <tr>
      <td>TEMPLATE\_NOT\_FOUND</td>
      <td>400</td>
      <td>Template not found</td>
    </tr>
  </tbody>
</table>

## Billing

<table>
  <thead>
    <tr>
      <th>Error Name</th>
      <th>Status Code</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>UNKNOWN</td>
      <td>500</td>
      <td>Unknown error, please contact us</td>
    </tr>

    <tr>
      <td>LIST\_BILL\_TOO\_FAST</td>
      <td>429</td>
      <td>Requests are too frequent, please try again later</td>
    </tr>

    <tr>
      <td>INVALID\_PRODUCT\_CATEGORY</td>
      <td>400</td>
      <td>Invalid productCategory parameter</td>
    </tr>

    <tr>
      <td>INVALID\_BILL\_CYCLE</td>
      <td>400</td>
      <td>Invalid cycle parameter</td>
    </tr>

    <tr>
      <td>LIST\_BILL\_ERROR</td>
      <td>500</td>
      <td>Query error, please contact us</td>
    </tr>
  </tbody>
</table>


# User Balance Info
Source: https://novita.ai/docs/api-reference/basic-get-user-balance

GET https://api.novita.ai/openapi/v1/billing/balance/detail

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Response

<ResponseField name="availableBalance" type="string">
  The user's credit balance, unit is 0.0001 USD.
</ResponseField>

<ResponseField name="cashBalance" type="string">
  The remaining balance of your top-up. The Unit is 0.0001 USD.
</ResponseField>

<ResponseField name="creditLimit" type="string">
  Your credit limit (i.e., the maximum amount you can owe), unit is 0.0001 USD.
</ResponseField>

<ResponseField name="outstandingInvoices" type="string">
  The amount you currently owe, unit is 0.0001 USD.
</ResponseField>


# Query Fixed-Term Billing
Source: https://novita.ai/docs/api-reference/basic-query-fixed-term-billing

GET https://api.novita.ai/openapi/v1/billing/bill/monthly/list

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<ParamField type="string">
  Product type. default: `summary`, Options:

  * `summary` (Summary bill)
  * `gpu` (GPU instance)
  * `local_storage` (Storage resources)
  * `image` (Image dedicated endpoint)
</ParamField>

<ParamField type="string">
  Product name. Supports fuzzy matching.
</ParamField>

<ParamField type="string">
  The start time of the bill to query, timestamp in seconds, default: 0.
</ParamField>

<ParamField type="string">
  The end time of the bill to query, timestamp in seconds, default: 0.
</ParamField>

<ParamField type="string">
  Specify the instance ID to query.
</ParamField>

## Response Parameters

<ResponseField name="bills" type="object[]">
  Billing information for fixed-term instances.

  <Expandable title="properties">
    <ResponseField name="userId" type="string">
      User ID to which the instance belongs.
    </ResponseField>

    <ResponseField name="startTime" type="string">
      The start time of the bill, timestamp in seconds.
    </ResponseField>

    <ResponseField name="endTime" type="string">
      The end time of the bill, timestamp in seconds.
    </ResponseField>

    <ResponseField name="memberId" type="string">
      Sub-user ID within the team.
    </ResponseField>

    <ResponseField name="productName" type="string">
      Product name.
    </ResponseField>

    <ResponseField name="productCategory" type="string">
      Product type.
    </ResponseField>

    <ResponseField name="ownerID" type="string">
      Instance ID.
    </ResponseField>

    <ResponseField name="tradeMode" type="string">
      Billing method. The value is `monthly`, indicating fixed-term.
    </ResponseField>

    <ResponseField name="tradeType" type="string">
      Type of fixed-term. Possible values:

      * `monthly_new_buy` (New purchase).
      * `monthly_re_buy` (Renewal).
      * `monthly_re_config` (Expansion).
    </ResponseField>

    <ResponseField name="basePrice" type="string">
      Monthly unit price.
    </ResponseField>

    <ResponseField name="billNum" type="string">
      Usage.
    </ResponseField>

    <ResponseField name="amount" type="string">
      Total price.
    </ResponseField>

    <ResponseField name="voucherAmount" type="string">
      Voucher deduction amount.
    </ResponseField>

    <ResponseField name="payAmount" type="string">
      Cash payment amount.
    </ResponseField>

    <ResponseField name="payAmountDisplay" type="string" />

    <ResponseField name="pricePrecision" type="string">
      Price Precision.
    </ResponseField>

    <ResponseField name="createTime" type="string">
      Bill creation time.
    </ResponseField>

    <ResponseField name="cycle" type="string">
      Billing Cycle.
    </ResponseField>

    <ResponseField name="storageDays" type="string">
      Storage service duration (days).
    </ResponseField>
  </Expandable>
</ResponseField>


# Query Monthly Bill
Source: https://novita.ai/docs/api-reference/basic-query-monthly-bill

GET https://api.novita.ai/openapi/v1/billing/monthly/bill

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Response Parameters

<ResponseField name="data" type="object[]">
  Monthly billing information.

  <Expandable title="properties">
    <ResponseField name="billId" type="string">
      Unique identifier for the bill.
    </ResponseField>

    <ResponseField name="userId" type="string">
      User ID to which the bill belongs.
    </ResponseField>

    <ResponseField name="billingMonth" type="string">
      The billing month in YYYY-MM format (e.g., "2025-11").
    </ResponseField>

    <ResponseField name="totalAmount" type="string">
      Total amount for the billing month, unit is 0.0001 USD.
    </ResponseField>

    <ResponseField name="originTotalAmount" type="string">
      Original total amount before any discounts or adjustments, unit is 0.0001 USD.
    </ResponseField>

    <ResponseField name="voucherPayAmount" type="string">
      Amount paid using vouchers, unit is 0.0001 USD.
    </ResponseField>

    <ResponseField name="cashPayAmount" type="string">
      Amount paid in cash, unit is 0.0001 USD.
    </ResponseField>

    <ResponseField name="debtAmount" type="string">
      Outstanding debt amount, unit is 0.0001 USD.
    </ResponseField>

    <ResponseField name="status" type="string">
      Bill status. Possible values:

      * `pending` (Upcoming)
      * `outed` (Payment Due)
      * `paid` (Paid)
      * `overdue` (Overdue)
    </ResponseField>

    <ResponseField name="invoiceUrl" type="string">
      URL to download the invoice. Empty string if invoice is not yet available.
    </ResponseField>

    <ResponseField name="startTime" type="string">
      Start time of the billing period, Unix timestamp in seconds.
    </ResponseField>

    <ResponseField name="endTime" type="string">
      End time of the billing period, Unix timestamp in seconds.
    </ResponseField>

    <ResponseField name="repaidAmount" type="string">
      Amount that has been paid, unit is 0.0001 USD.
    </ResponseField>
  </Expandable>
</ResponseField>


# Query Usage-based Billing
Source: https://novita.ai/docs/api-reference/basic-query-usage-based-billing

GET https://api.novita.ai/openapi/v1/billing/bill/list

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<ParamField type="string">
  Billing cycle granularity. Options: `Hour`, `Day`, `Week`, `Month`
</ParamField>

<ParamField type="string">
  Product type. Options:

  * `summary` (Summary bill)
  * `gpu` (GPU instance)
  * `llm` (llm api)
  * `serverless` (Serverless Endpoint)
  * `cloud_storage` (Storage resources)
  * `gen_api` (Image/Video/Audio generation)
</ParamField>

<ParamField type="string">
  Product name. Supports fuzzy matching.
</ParamField>

<ParamField type="string">
  Start time of the billing period to query, timestamp in seconds, default: 0.
</ParamField>

<ParamField type="string">
  End time of the billing period to query, timestamp in seconds, default: 0.
</ParamField>

<ParamField type="string">
  Specify instance ID to query.
</ParamField>

## Response Parameters

<ResponseField name="bills" type="object[]">
  Pay-as-you-go instance billing information.

  <Expandable title="properties">
    <ResponseField name="userId" type="string">
      User ID to which the instance belongs.
    </ResponseField>

    <ResponseField name="startTime" type="string">
      Start time of the bill. Format is Unix timestamp.
    </ResponseField>

    <ResponseField name="endTime" type="string">
      End time of the bill. Format is Unix timestamp.
    </ResponseField>

    <ResponseField name="billingMethod" type="string">
      Billing method of the instance. A value of 1 indicates pay-as-you-go.
    </ResponseField>

    <ResponseField name="productName" type="string">
      Product name.
    </ResponseField>

    <ResponseField name="category" type="string">
      Product category.
    </ResponseField>

    <ResponseField name="ownerID" type="string">
      Instance ID.
    </ResponseField>

    <ResponseField name="billNum0" type="string">
      * llm: input token
      * gpu: number of cards \* billing time
      * storage: storage size \* billing time
    </ResponseField>

    <ResponseField name="billNum1" type="string">
      * llm: output token
    </ResponseField>

    <ResponseField name="basePrice0" type="string">
      Original Price
    </ResponseField>

    <ResponseField name="basePrice1" type="string">
      No significance
    </ResponseField>

    <ResponseField name="discountPrice0" type="string">
      * llm: input token unit price
      * others: unit price
    </ResponseField>

    <ResponseField name="discountPrice1" type="string">
      * llm: output token unit price
    </ResponseField>

    <ResponseField name="amount" type="string">
      Total price.
    </ResponseField>

    <ResponseField name="voucherAmount" type="string">
      Voucher deduction amount.
    </ResponseField>

    <ResponseField name="payAmount" type="string">
      Cash payment amount.
    </ResponseField>

    <ResponseField name="payAmountDisplay" type="string" />

    <ResponseField name="pricePrecision" type="string">
      Price Precision.
    </ResponseField>

    <ResponseField name="productId" type="string">
      Product ID.
    </ResponseField>
  </Expandable>
</ResponseField>


# Break Job
Source: https://novita.ai/docs/api-reference/gpu-instance-break-job

POST https://api.novita.ai/gpu-instance/openapi/v1/job/break

## API Description

Forcefully interrupt a running job.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The job ID to be interrupted. String, length 0–255.
</ParamField>

## cURL Example

```bash theme={"system"}
curl --location --request POST 'https://api.novita.ai/gpu-instance/openapi/v1/job/break' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{API_KEY}}' \
--data-raw '{
  "jobId": "10wi9visv0rqt57w"
}'
```

## Response

<ResponseField name="jobId" type="string">
  The job ID.
</ResponseField>


# Convert Pay-As-You-Go Instance to Subscription
Source: https://novita.ai/docs/api-reference/gpu-instance-change-billing-instance

POST https://api.novita.ai/gpu-instance/openapi/v1/gpu/instance/transToMonthlyInstance

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The ID of the pay-as-you-go instance to be converted to a subscription instance.
</ParamField>

<ParamField type="integer">
  Subscription period after conversion, in months.
</ParamField>


# Create Container Registry Authentication
Source: https://novita.ai/docs/api-reference/gpu-instance-create-container-registry-auth

POST https://api.novita.ai/gpu-instance/openapi/v1/repository/auth/save

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="string" />

## Example

Request

```bash theme={"system"}
curl --request POST \
  --url 'https://api.novita.ai/gpu-instance/openapi/v1/repository/auth/save' \
  --header 'Authorization: Bearer {{API Key}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "<string>",
    "username": "<string>",
    "password": "<string>"
  }'
```

Response

```json theme={"system"}
{}
```


# Create CPU Instance
Source: https://novita.ai/docs/api-reference/gpu-instance-create-cpu-instance

POST https://api.novita.ai/gpu-instance/openapi/v1/gpu/instance/create

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  CPU instance name. String, length limit: 0-255 characters.
</ParamField>

<ParamField type="string">
  Product ID for deploying the instance. You can query this via the [List CPU Products API](/api-reference/gpu-instance-list-cpu-products). String, length limit: 1-255 characters.
</ParamField>

<ParamField type="string">
  Container image URL. String, length limit: 1-500 characters.
</ParamField>

<ParamField type="string">
  Image repository authentication. Format: username:password. Required for private images; not required for public images or platform images. String, length limit: 0-10239 characters.
</ParamField>

<ParamField type="string">
  Image repository authentication ID.
</ParamField>

<ParamField type="string">
  Ports exposed by the instance. String, e.g.: 80/http, 3306/tcp. Supported port range: 1-65535, except for 2222, 2223, 2224 which are reserved for internal use. Supported port types: tcp, http. The total number of ports used by ports + tools must not exceed 15.
</ParamField>

<ParamField type="object[]">
  Instance environment variables. Array, up to 100 environment variables.

  <Expandable title="properties">
    <ParamField type="string">
      Environment variable name. String, length limit: 0-511 characters.
    </ParamField>

    <ParamField type="string">
      Environment variable value. String, length limit: 0-4095 characters.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  Enable official image support tools. Array. Currently, some official images only include Jupyter. The total number of ports used by ports + tools must not exceed 15.

  <Expandable title="properties">
    <ParamField type="string">
      Tool name. Valid value: Jupyter.
    </ParamField>

    <ParamField type="string">
      Port used by the tool. Supported port range: 1-65535, except for 2222, 2223, 2224 which are reserved for internal use.
    </ParamField>

    <ParamField type="string">
      Port type used by the tool. Valid values: tcp, http.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Container startup command. This setting will override the Docker image's CMD. String, length limit: 0-2047 characters.
</ParamField>

<ParamField type="string">
  Container startup entrypoint. This setting will override the Docker image's ENTRYPOINT. String, length limit: 0-2047 characters.
</ParamField>

<ParamField type="string">
  Specify the cluster ID to create the instance in. If left empty, the instance will be created in a random cluster. String, length limit: 0-255 characters.
</ParamField>

<ParamField type="string">
  Mount point for local storage. Default: "/workspace". String, length limit: 1-4095 characters.
</ParamField>

<ParamField type="object[]">
  Cloud storage mount configuration. Array, up to 30 cloud storages can be mounted.

  <Expandable title="properties">
    <ParamField type="string">
      Cloud storage ID.
    </ParamField>

    <ParamField type="string">
      Mount point for cloud storage. Default: "/network". String, length limit: 1-4095 characters.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  VPC network ID. Leave empty if not using a VPC network.
</ParamField>

<ParamField type="string">
  Instance type. Valid values: cpu, gpu. Must be set to cpu.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Created instance ID.
</ResponseField>


# Create Image Prewarm Task
Source: https://novita.ai/docs/api-reference/gpu-instance-create-image-prewarm

POST https://api.novita.ai/gpu-instance/openapi/v1/image/prewarm

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Image address to prewarm.
</ParamField>

<ParamField type="string">
  Image registry authentication ID. Required only for private registries.
</ParamField>

<ParamField type="string">
  Cluster ID where the image should be prewarmed.
</ParamField>

<ParamField type="string[]">
  Product IDs to prewarm on. Leave empty to prewarm globally in the cluster.
</ParamField>

<ParamField type="string">
  Task note or description.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Created prewarm task ID.
</ResponseField>


# Create GPU Instance
Source: https://novita.ai/docs/api-reference/gpu-instance-create-instance

POST https://api.novita.ai/gpu-instance/openapi/v1/gpu/instance/create

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Instance name. String, length limit: 0-255 characters.
</ParamField>

<ParamField type="string">
  GPU product ID. String, length limit: 1-255 characters. You can query this via the [List GPU Products API](/api-reference/gpu-instance-list-products).
</ParamField>

<ParamField type="integer">
  Number of GPUs. Integer, valid range: \[1, 8].
</ParamField>

<ParamField type="integer">
  Root filesystem size. Integer, valid range: \[10, 6144]. If the minimum value is less than 10 GB, the system will default to 10 GB. The maximum value is dynamically limited by available storage resources and can be queried via the product list API.
</ParamField>

<ParamField type="string">
  Image URL. String, length limit: 1-500 characters.
</ParamField>

<ParamField type="string">
  Image authentication (username:password). String, length limit: 0-10239 characters.
</ParamField>

<ParamField type="string">
  Image repository authentication ID.
</ParamField>

<ParamField type="string">
  Instance open ports, e.g.: 80/http, 3306/tcp. Supported port range: \[1-65535], except for 2222, 2223, 2224 which are reserved for internal use. Supported port types: \[tcp, http]. The total number of ports used by ports + tools must not exceed 15.
</ParamField>

<ParamField type="object[]">
  Instance environment variables. Up to 100 environment variables can be created.

  <Expandable title="properties">
    <ParamField type="string">
      Environment variable name. String, length limit: 0-511 characters.
    </ParamField>

    <ParamField type="string">
      Environment variable value. String, length limit: 0-4095 characters.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  Enable official image support tools. Currently, some official images only include Jupyter. The total number of ports used by ports + tools must not exceed 15.

  <Expandable title="properties">
    <ParamField type="string">
      Tool name. Valid values: \[Jupyter].
    </ParamField>

    <ParamField type="string">
      Port used by the tool. Supported port range: \[1-65535], except for 2222, 2223, 2224 which are reserved for internal use.
    </ParamField>

    <ParamField type="string">
      Port type used by the tool. Supported types: \[tcp, http].
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Instance startup command. String, length limit: 0-2047 characters.
</ParamField>

<ParamField type="string">
  Instance startup entrypoint. This setting will override the Docker image's ENTRYPOINT. String, length limit: 0-2047 characters.
</ParamField>

<ParamField type="string">
  Specify the cluster ID to create the instance in. If left empty, the instance will be created in a random cluster.
</ParamField>

<ParamField type="object[]">
  Cloud storage mount configuration. Up to 30 cloud storages can be mounted.

  <Expandable title="properties">
    <ParamField type="string">
      Network storage ID.
    </ParamField>

    <ParamField type="string">
      Network storage mount path. Default: "/network". String, length limit: 1-4095 characters.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  VPC network ID. Leave empty if not using a VPC network.
</ParamField>

<ParamField type="string">
  Instance type. Valid values: \[gpu, cpu].
</ParamField>

<ParamField type="integer">
  Number of months for subscription instance. Set to 0 to create a pay-as-you-go instance. Integer, value must be greater than or equal to 0.
</ParamField>

<ParamField type="string">
  Instance billing mode. Valid values: `onDemand`, `monthly`, `spot`. <br />
  Default: `onDemand`.<br />
  Note: If month > 0 is set, `monthly` billing mode will be enforced.

  * `onDemand`: Pay-as-you-go billing
  * `monthly`: Monthly subscription billing
  * `spot`: Spot instance billing
</ParamField>

<ParamField type="boolean">
  Whether to automatically renew. Boolean, default value: false.<br />
  Note: This parameter is only effective when monthly billing is enabled.
</ParamField>

<ParamField type="integer">
  Number of months to automatically renew. Integer, valid range: \[1, 12].<br />
  Note: This parameter is only effective when monthly billing is enabled and auto renew is enabled.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Created instance ID.
</ResponseField>


# Create Network Storage
Source: https://novita.ai/docs/api-reference/gpu-instance-create-network-storage

POST https://api.novita.ai/gpu-instance/openapi/v1/networkstorage/create

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="integer" />

## Example

Request

```bash theme={"system"}
curl --request POST \
  --url 'https://api.novita.ai/gpu-instance/openapi/v1/networkstorage/create' \
  --header 'Authorization: Bearer {{API Key}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "clusterId": "string",
    "storageName": "string",
    "storageSize": 0
  }'
```

Response

```json theme={"system"}
"<string>"
```


# Create Template
Source: https://novita.ai/docs/api-reference/gpu-instance-create-template

POST https://api.novita.ai/gpu-instance/openapi/v1/template/create

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Template settings.

  <Expandable title="properties">
    <ParamField type="string">
      Template name. String, length limit: 1-255 characters.
    </ParamField>

    <ParamField type="string">
      Template README content (in Markdown format). String, length limit: 0-102400 characters.
    </ParamField>

    <ParamField type="string">
      Template type.<br />
      Enum: `instance`
    </ParamField>

    <ParamField type="string">
      Template channel.<br />
      Enum: `private`
    </ParamField>

    <ParamField type="string">
      Docker image address for instance startup. String, length limit: 1-500 characters.
    </ParamField>

    <ParamField type="string">
      Image repository authentication ID for private images. String, length limit: 0-255 characters.
    </ParamField>

    <ParamField type="string">
      Startup command for the instance. String, length limit: 0-2047 characters.
    </ParamField>

    <ParamField type="string">
      Instance startup entrypoint. This setting will override the Docker image's ENTRYPOINT. String, length limit: 0-2047 characters.
    </ParamField>

    <ParamField type="integer">
      Root filesystem storage (GB). Integer, value must be greater than 0.
    </ParamField>

    <ParamField type="object[]">
      Exposed port settings.

      <Expandable title="properties">
        <ParamField type="string">
          Exposed port types.<br />
          Enum: `http`, `tcp`
        </ParamField>

        <ParamField type="integer[]">
          Exposed ports (maximum of 10). Supported port range: 1-65535, except for 2222, 2223, 2224 which are reserved for internal use.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object[]">
      Environment variables injected into the instance. Up to 100 environment variable pairs can be created.

      <Expandable title="properties">
        <ParamField type="string">
          Environment variable key. String, length limit: 0-511 characters.
        </ParamField>

        <ParamField type="string">
          Environment variable value. String, length limit: 0-4095 characters.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Minimum supported CUDA version. String, length limit: 0-255 characters. Format example: 11.8, 12.4.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="templateId" type="string">
  ID of the created template.
</ResponseField>

## Example

Request

```bash theme={"system"}

curl --request POST \
  --url 'https://api.novita.ai/gpu-instance/openapi/v1/template/create' \
  --header 'Authorization: Bearer {{API Key}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "template": {
      "name": "test",
      "readme": "readme",
      "type": "instance",
      "channel": "private",
      "readme": "test create template",
      "image": "nginx",
      "imageAuth": "",
      "startCommand": "echo test",
      "entrypoint": "",
      "rootfsSize": 60,
      "ports": [
        {
          "type": "http",
          "ports": [80, 443]
        },
        {
          "type": "tcp",
          "ports": [90, 95]
        }
      ],
      "envs": [
        {
          "key": "test1",
          "value": "template1"
        },
        {
          "key": "test2",
          "value": "test2"
        }
      ],
      "minCudaVersion": "11.8"
    }
  }'
```

Response

```json theme={"system"}
{
  "templateId": "1"
}
```


# Create VPC Network
Source: https://novita.ai/docs/api-reference/gpu-instance-create-vpc

POST https://api.novita.ai/gpu-instance/openapi/v1/network/create

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Cluster ID. You can obtain this via the [List Clusters](/api-reference/gpu-instance-list-clusters) API. String, length limit: 1-255 characters.
</ParamField>

<ParamField type="string">
  Name of the VPC network. Customizable. String, length limit: 0-30 characters.
</ParamField>

## Response

<ResponseField name="network" type="object[]">
  VPC network information.

  <Expandable title="properties">
    <ResponseField name="Id" type="string">
      VPC network ID.
    </ResponseField>

    <ResponseField name="user" type="string">
      User account ID.
    </ResponseField>

    <ResponseField name="name" type="string">
      VPC network name.
    </ResponseField>

    <ResponseField name="state" type="object[]">
      VPC network status.

      <Expandable title="properties">
        <ResponseField name="state" type="string">
          VPC network status. Possible values:

          * creating: Being created.
          * ready: Successfully created.
        </ResponseField>

        <ResponseField name="error" type="string">
          Error message if VPC network creation fails or the network is unavailable.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="segment" type="string">
      VPC network segment.
    </ResponseField>

    <ResponseField name="clusterId" type="string">
      Cluster ID.
    </ResponseField>

    <ResponseField name="Addresses" type="object[]">
      Instance information under the VPC network.

      <Expandable title="properties">
        <ResponseField name="Id" type="string">
          Instance ID.
        </ResponseField>

        <ResponseField name="Ip" type="string">
          Instance IP address.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="createTime" type="string">
      VPC network creation time.
    </ResponseField>
  </Expandable>
</ResponseField>


# Delete Container Registry Auth
Source: https://novita.ai/docs/api-reference/gpu-instance-delete-container-registry-auth

POST https://api.novita.ai/gpu-instance/openapi/v1/repository/auth/delete

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string" />

## Example

Request

```bash theme={"system"}
curl --request POST \
  --url 'https://api.novita.ai/gpu-instance/openapi/v1/repository/auth/delete' \
  --header 'Authorization: Bearer {{API Key}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "<string>"
  }'
```

Response

```json theme={"system"}
{}
```


# Delete Image Prewarm Tasks
Source: https://novita.ai/docs/api-reference/gpu-instance-delete-image-prewarm

POST https://api.novita.ai/gpu-instance/openapi/v1/image/prewarm/delete

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string[]">
  IDs of prewarm tasks to delete.
</ParamField>


# Delete Instance
Source: https://novita.ai/docs/api-reference/gpu-instance-delete-instance

POST https://api.novita.ai/gpu-instance/openapi/v1/gpu/instance/delete

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  ID of the instance to be deleted.
</ParamField>


# Delete Network Storage
Source: https://novita.ai/docs/api-reference/gpu-instance-delete-network-storage

POST https://api.novita.ai/gpu-instance/openapi/v1/networkstorage/delete

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string" />

## Example

Request

```bash theme={"system"}
curl --request POST \
  --url 'https://api.novita.ai/gpu-instance/openapi/v1/networkstorage/delete' \
  --header 'Authorization: Bearer {{API Key}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "storageId": "string"
  }'

```

Response

```json theme={"system"}
{}
```


# Delete Template
Source: https://novita.ai/docs/api-reference/gpu-instance-delete-template

POST https://api.novita.ai/gpu-instance/openapi/v1/template/delete

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The ID of the template to be deleted.
</ParamField>

## Response

<ResponseField name="templateId" type="string">
  The ID of the deleted template.
</ResponseField>

## Example

Request

```bash theme={"system"}
curl --request POST \
  --url 'https://api.novita.ai/gpu-instance/openapi/v1/template/delete' \
  --header 'Authorization: Bearer {{API Key}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "templateId": "<string>"
  }'
```

Response

```json theme={"system"}
{
  "templateId": "<string>"
}
```


# Delete VPC Network
Source: https://novita.ai/docs/api-reference/gpu-instance-delete-vpc

POST https://api.novita.ai/gpu-instance/openapi/v1/network/delete

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Cluster ID. String, length limit: 1-255 characters. Please ensure there are no instances under this VPC network before deletion.
</ParamField>


# Edit Instance
Source: https://novita.ai/docs/api-reference/gpu-instance-edit-instance

POST https://api.novita.ai/gpu-instance/openapi/v1/gpu/instance/edit

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  ID of the instance to edit.
</ParamField>

<ParamField type="object[]">
  Ports to be exposed by the instance. The total number of ports used by ports + tools must not exceed 15.

  <Expandable title="properties">
    <ParamField type="integer">
      Port number. Supported port range: 1-65535, except for 2222, 2223, and 2224 which are reserved for internal use.
    </ParamField>

    <ParamField type="string">
      Protocol type. Supported values: `tcp`, `http`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="integer">
  Size to expand the root disk, in GB. Integer, value must be >= 0. Set to 0 if no expansion is needed.
</ParamField>


# Edit Network Storage
Source: https://novita.ai/docs/api-reference/gpu-instance-edit-network-storage

POST https://api.novita.ai/gpu-instance/openapi/v1/networkstorage/update

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The unique identifier for the storage.
</ParamField>

<ParamField type="string">
  The name of the storage.
</ParamField>

<ParamField type="string">
  The size of the storage in appropriate units.
</ParamField>

## Example

Request

```bash theme={"system"}
curl --request POST \
  --url 'https://api.novita.ai/gpu-instance/openapi/v1/networkstorage/update' \
  --header 'Authorization: Bearer {{API Key}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "storageId": "string",
    "storageName": "string",
    "storageSize": "string"
  }'
```

Response

```json theme={"system"}
{}
```


# Get Image Prewarm Quota
Source: https://novita.ai/docs/api-reference/gpu-instance-get-image-quota

GET https://api.novita.ai/gpu-instance/openapi/v1/image/prewarm/quota

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Response

<ResponseField name="total" type="integer">
  Number of created prewarm tasks.
</ResponseField>

<ResponseField name="limit" type="integer">
  Maximum number of prewarm tasks that can be created.
</ResponseField>

<ResponseField name="perImageSize" type="integer">
  Maximum image size per prewarm task (GB).
</ResponseField>


# Get Instance
Source: https://novita.ai/docs/api-reference/gpu-instance-get-instance

GET https://api.novita.ai/gpu-instance/openapi/v1/gpu/instance

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<ParamField type="string">
  ID of the instance being queried.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Instance ID.
</ResponseField>

<ResponseField name="name" type="string">
  Instance name.
</ResponseField>

<ResponseField name="clusterId" type="string">
  Cluster ID.
</ResponseField>

<ResponseField name="clusterName" type="string">
  Name of the cluster.
</ResponseField>

<ResponseField name="imageUrl" type="string">
  Container image URL.
</ResponseField>

<ResponseField name="imageAuthId" type="string">
  Image registry authentication information.
</ResponseField>

<ResponseField name="command" type="string">
  Container startup command.
</ResponseField>

<ResponseField name="entrypoint" type="string">
  Container startup entrypoint.
</ResponseField>

<ResponseField name="cpuNum" type="string">
  Number of CPU cores allocated to the instance.
</ResponseField>

<ResponseField name="memory" type="string">
  Memory size allocated to the instance, in GB.
</ResponseField>

<ResponseField name="gpuNum" type="string">
  Number of GPU cards allocated to the instance.
</ResponseField>

<ResponseField name="status" type="string">
  Instance status. Possible values:

  * `toCreate`: Pending creation
  * `creating`: Creating
  * `pulling`: Pulling image
  * `running`: Running
  * `toStart`: Pending start
  * `starting`: Starting
  * `toStop`: Pending stop
  * `stopping`: Stopping
  * `exited`: Stopped
  * `toRestart`: Pending restart
  * `restarting`: Restarting
  * `toRemove`: Pending deletion
  * `removing`: Deleting
  * `removed`: Deleted
  * `toReset`: Pending reset (upgrade)
  * `resetting`: Resetting
  * `migrating`: Migrating
  * `freezing`: Freezing
</ResponseField>

<ResponseField name="statusError" type="object">
  Error information when instance creation fails or the instance is unavailable.

  <Expandable title="properties">
    <ResponseField name="state" type="string">
      Abnormal instance status.
    </ResponseField>

    <ResponseField name="message" type="string">
      Error message.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="network" type="object">
  VPC network information for the instance.

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      VPC network ID.
    </ResponseField>

    <ResponseField name="ip" type="string">
      Instance IP address.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="portMappings" type="object[]">
  Instance port mapping information.

  <Expandable title="properties">
    <ResponseField name="port" type="integer">
      Port number.
    </ResponseField>

    <ResponseField name="endpoint" type="string">
      Endpoint.
    </ResponseField>

    <ResponseField name="type" type="string">
      Protocol type.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="volumeMounts" type="object[]">
  Storage configuration for the instance.

  <Expandable title="properties">
    <ResponseField name="type" type="string">
      Storage type. Possible values:

      * network: Cloud storage.
      * local: Local storage.
    </ResponseField>

    <ResponseField name="size" type="number">
      Storage capacity.
    </ResponseField>

    <ResponseField name="id" type="string">
      Cloud storage ID. Only present when the storage type is "network".
    </ResponseField>

    <ResponseField name="mountPath" type="string">
      Mount path for the storage.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="node" type="object[]">
  Node information.

  <Expandable title="properties">
    <ResponseField name="maxRootfsSize" type="number">
      Maximum available system disk size.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="jobs" type="object[]">
  Tasks currently running on the instance.

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Task ID.
    </ResponseField>

    <ResponseField name="type" type="string">
      Task type. Currently, only saveImage is supported, which indicates saving an image.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="envs" type="object[]">
  Instance environment variable information.

  <Expandable title="properties">
    <ResponseField name="key" type="string">
      Environment variable name.
    </ResponseField>

    <ResponseField name="value" type="string">
      Environment variable value.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="connectComponentSSH" type="object">
  Instance SSH connection information.

  <Expandable title="properties">
    <ResponseField name="sshCommand" type="string">
      Command for SSH remote login.
    </ResponseField>

    <ResponseField name="password" type="string">
      Password for SSH remote login.
    </ResponseField>

    <ResponseField name="isRunning" type="boolean">
      Whether SSH remote login is active.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="connectComponentWebTerminal" type="object">
  Instance WebSSH connection information.

  <Expandable title="properties">
    <ResponseField name="address" type="string">
      Address for web-based remote login.
    </ResponseField>

    <ResponseField name="username" type="string">
      Username for web-based remote login.
    </ResponseField>

    <ResponseField name="password" type="string">
      Password for web-based remote login.
    </ResponseField>

    <ResponseField name="isRunning" type="boolean">
      Whether web-based remote login is active.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="connectComponentJupyter" type="object">
  Jupyter connection information for the instance (if available).

  <Expandable title="properties">
    <ResponseField name="port" type="integer">
      Connection port.
    </ResponseField>

    <ResponseField name="address" type="string">
      Connection address.
    </ResponseField>

    <ResponseField name="isRunning" type="boolean">
      Whether Jupyter remote login is active.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="connectComponentLog" type="object">
  Instance log connection information (HTTP Stream).

  <Expandable title="properties">
    <ResponseField name="systemLogAddress" type="string">
      System log address.
    </ResponseField>

    <ResponseField name="instanceLogAddress" type="string">
      Instance log address.
    </ResponseField>

    <ResponseField name="isRunning" type="boolean">
      Whether log connection is active.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="kind" type="string">
  Instance type.
</ResponseField>

<ResponseField name="billingMode" type="string">
  Billing mode for the instance. Values:

  * onDemand: Pay-as-you-go billing.
  * monthly: Subscription (monthly or yearly) billing.
  * spot: Spot instance billing.
</ResponseField>

<ResponseField name="endTime" type="string">
  Expiration time for subscription instances. For pay-as-you-go instances, returns -1.
</ResponseField>

<ResponseField name="freeStorageSize" type="integer">
  Free system disk size (GB).
</ResponseField>

<ResponseField name="keepDataDay" type="integer">
  Number of days data is retained after the instance is shut down.
</ResponseField>


# Fetch Instance Monitor Metrics
Source: https://novita.ai/docs/api-reference/gpu-instance-get-metrics

GET https://api.novita.ai/openapi/v1/metrics/gpu/instance

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<Note>
  If the parameters endTime, startTime, or interval do not meet the requirements, default values will be used. There may be a delay of about one minute when retrieving real-time monitoring data.
</Note>

<ParamField type="string">
  Instance ID.
</ParamField>

<ParamField type="integer">
  End time for querying monitoring data. Value range: (0, current timestamp], default: current timestamp.
</ParamField>

<ParamField type="integer">
  Start time for querying monitoring data. Value range: (0, endTime - 60], default: current timestamp - 60.
</ParamField>

<ParamField type="integer">
  Time granularity for monitoring data, in seconds. Value must be greater than 15. Default: 15.
</ParamField>

## Response

<ResponseField name="cpuUtilization" type="array">
  CPU utilization data.

  <Expandable title="properties">
    <ResponseField name="timestamp" type="string">
      Timestamp.
    </ResponseField>

    <ResponseField name="value" type="number">
      CPU utilization.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="memUtilization" type="array">
  Memory utilization data.

  <Expandable title="properties">
    <ResponseField name="timestamp" type="string">
      Timestamp.
    </ResponseField>

    <ResponseField name="value" type="number">
      Memory utilization.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="rootDiskUtilization" type="array">
  Root disk utilization data.

  <Expandable title="properties">
    <ResponseField name="timestamp" type="string">
      Timestamp.
    </ResponseField>

    <ResponseField name="value" type="number">
      Root disk utilization.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="gpuUtilization" type="object">
  GPU utilization data.

  <Expandable title="properties">
    <ResponseField name="avg" type="array">
      Average utilization across all GPUs.

      <Expandable title="properties">
        <ResponseField name="timestamp" type="string">
          Timestamp.
        </ResponseField>

        <ResponseField name="value" type="number">
          Utilization.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="gpuIds" type="array">
      Utilization for each GPU.

      <Expandable title="properties">
        <ResponseField name="gpuId" type="string">
          GPU ID in use.
        </ResponseField>

        <ResponseField name="items" type="array">
          GPU utilization data.

          <Expandable title="properties">
            <ResponseField name="timestamp" type="string">
              Timestamp.
            </ResponseField>

            <ResponseField name="value" type="number">
              Utilization.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="gpuMemUtilization" type="object">
  GPU memory utilization data.

  <Expandable title="properties">
    <ResponseField name="avg" type="array">
      Average GPU memory utilization across all GPUs.

      <Expandable title="properties">
        <ResponseField name="timestamp" type="string">
          Timestamp.
        </ResponseField>

        <ResponseField name="value" type="number">
          Utilization.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="gpuIds" type="array">
      GPU memory utilization for each GPU.

      <Expandable title="properties">
        <ResponseField name="gpuId" type="string">
          GPU ID in use.
        </ResponseField>

        <ResponseField name="items" type="array">
          GPU memory utilization data.

          <Expandable title="properties">
            <ResponseField name="timestamp" type="string">
              Timestamp.
            </ResponseField>

            <ResponseField name="value" type="number">
              Utilization.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>


# Get Template
Source: https://novita.ai/docs/api-reference/gpu-instance-get-template

GET https://api.novita.ai/gpu-instance/openapi/v1/template

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<ParamField type="string">
  ID of the template being queried.
</ParamField>

## Response

<ResponseField name="template" type="object">
  Template settings.

  <Expandable title="properties">
    <ResponseField name="Id" type="string">
      Template ID.
    </ResponseField>

    <ResponseField name="name" type="string">
      Template name.
    </ResponseField>

    <ResponseField name="readme" type="string">
      Template README content (in Markdown format).
    </ResponseField>

    <ResponseField name="type" type="string">
      Template type.Enum: `instance`
    </ResponseField>

    <ResponseField name="channel" type="string">
      Template channel.Enum: `private`
    </ResponseField>

    <ResponseField name="image" type="string">
      Docker image address for instance startup.
    </ResponseField>

    <ResponseField name="imageAuth" type="string">
      Image repository authentication ID for private images.
    </ResponseField>

    <ResponseField name="startCommand" type="string">
      Startup command for the instance.
    </ResponseField>

    <ResponseField name="entrypoint" type="string">
      Instance startup entrypoint.
    </ResponseField>

    <ResponseField name="rootfsSize" type="integer">
      Rootfs storage (GB).
    </ResponseField>

    <ResponseField name="ports" type="object[]">
      Exposed ports settings.

      <Expandable title="properties">
        <ResponseField name="type" type="string">
          Exposed port types.Enum: `http, tcp`
        </ResponseField>

        <ResponseField name="ports" type="[integer]">
          Exposed ports (maximum 10).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="envs" type="object[]">
      Environment variables injected into instance.

      <Expandable title="properties">
        <ResponseField name="key" type="string">
          Environment variable key.
        </ResponseField>

        <ResponseField name="value" type="string">
          Environment variable value.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tools" type="object[]">
      Template built-in tools (only available for official templates).

      <Expandable title="properties">
        <ResponseField name="name" type="string">
          Tool name.
        </ResponseField>

        <ResponseField name="describe" type="string">
          Tool description.
        </ResponseField>

        <ResponseField name="port" type="integer">
          Tool port.
        </ResponseField>

        <ResponseField name="type" type="string">
          Tool protocol type. Enum: `http`, `tcp`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Template creation timestamp (Unix seconds).
    </ResponseField>

    <ResponseField name="recommendCards" type="object[]">
      Recommended GPU card specs (only available for official templates).

      <Expandable title="properties">
        <ResponseField name="gpuSpecId" type="string">
          GPU spec ID.
        </ResponseField>

        <ResponseField name="cardNum" type="string">
          Recommended card number.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="minCudaVersion" type="string">
      Minimum required CUDA version, e.g. 11.8, 12.4.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

Request

```bash theme={"system"}
curl --request GET \
  --url 'https://api.novita.ai/gpu-instance/openapi/v1/template' \
  --header 'Authorization: Bearer {{API Key}}'
```

Response

```json theme={"system"}
{
  "template": {
    "Id": "212",
    "name": "ubuntu",
    "readme": "readme",
    "type": "instance",
    "channel": "private",
    "image": "ubuntu:latest",
    "imageAuth": "",
    "startCommand": "",
    "entrypoint": "",
    "rootfsSize": 10,
    "ports": [
      {
        "type": "tcp",
        "ports": [8080, 8090]
      },
      {
        "type": "http",
        "ports": [6000, 60001]
      }
    ],
    "envs": [
      {
        "key": "testkey",
        "value": "123"
      }
    ],
    "tools": [
      {
        "name": "Jupyter",
        "describe": "Start Jupyter Notebook",
        "port": 8888,
        "type": "http"
      }
    ],
    "createdAt": "1713162260",
    "recommendCards": [
      {
        "gpuSpecId": "4090.18c.60g",
        "cardNum": "2"
      }
    ],
    "minCudaVersion": "11.8"
  }
}
```


# Get VPC Network
Source: https://novita.ai/docs/api-reference/gpu-instance-get-vpc

GET https://api.novita.ai/gpu-instance/openapi/v1/network

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<ParamField type="string">
  Cluster ID. String, length limit: 1-255 characters. Only one is supported.
</ParamField>

## Response

<ResponseField name="network" type="object[]">
  VPC network information.

  <Expandable title="properties">
    <ResponseField name="Id" type="string">
      VPC network ID.
    </ResponseField>

    <ResponseField name="user" type="string">
      User account ID.
    </ResponseField>

    <ResponseField name="name" type="string">
      VPC network name.
    </ResponseField>

    <ResponseField name="state" type="object[]">
      VPC network status.

      <Expandable title="properties">
        <ResponseField name="state" type="string">
          VPC network status. Possible values:

          * creating: Being created.
          * ready: Successfully created.
        </ResponseField>

        <ResponseField name="error" type="string">
          Error message if VPC network creation fails or the network is unavailable.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="segment" type="string">
      VPC network segment.
    </ResponseField>

    <ResponseField name="clusterId" type="string">
      Cluster ID.
    </ResponseField>

    <ResponseField name="Addresses" type="object[]">
      Instance information under the VPC network.

      <Expandable title="properties">
        <ResponseField name="Id" type="string">
          Instance ID.
        </ResponseField>

        <ResponseField name="Ip" type="string">
          Instance IP address.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="createTime" type="string">
      VPC network creation time. Format: Unix timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>


# List Clusters
Source: https://novita.ai/docs/api-reference/gpu-instance-list-clusters

GET https://api.novita.ai/gpu-instance/openapi/v1/clusters

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Response

<ResponseField name="data" type="object[]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Cluster ID.
    </ResponseField>

    <ResponseField name="name" type="string">
      Cluster name.
    </ResponseField>

    <ResponseField name="availableGpuType" type="[string]">
      Supported GPU types in the cluster.
    </ResponseField>

    <ResponseField name="supportNetworkStorage" type="boolean">
      Whether the cluster supports creating cloud storage.
    </ResponseField>

    <ResponseField name="supportInstanceNetwork" type="boolean">
      Whether the cluster supports creating VPC networks.
    </ResponseField>
  </Expandable>
</ResponseField>


# List Container Registry Auth
Source: https://novita.ai/docs/api-reference/gpu-instance-list-container-registry-auth

GET https://api.novita.ai/gpu-instance/openapi/v1/repository/auths

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Response

<ResponseField name="data" type="object[]">
  <Expandable title="properties">
    <ResponseField name="id" type="string" />

    <ResponseField name="name" type="string" />

    <ResponseField name="username" type="string" />

    <ResponseField name="password" type="string" />
  </Expandable>
</ResponseField>

## Example

Request

```bash theme={"system"}
curl --request GET \
  --url 'https://api.novita.ai/gpu-instance/openapi/v1/repository/auths' \
  --header 'Authorization: Bearer {{API Key}}'
```

Response

```json theme={"system"}
{
  "data": [
    {
      "id": "75irlsvvsehnqdajg2r481mjk54ecodc",
      "name": "test",
      "username": "uuuu",
      "password": "1111"
    },
    {
      "id": "eih4rdk77avum5lyau291w1i54zd897w",
      "name": "test",
      "username": "uuuu",
      "password": "1111"
    }
  ]
}
```


# List CPU Products
Source: https://novita.ai/docs/api-reference/gpu-instance-list-cpu-products

GET https://api.novita.ai/gpu-instance/openapi/v1/cpu/products

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<ParamField type="string">
  Filter by specified cluster ID. String, length limit: 0-255 characters.
</ParamField>

<ParamField type="string">
  Filter by product name (fuzzy match). String, length limit: 0-255 characters.
</ParamField>

## Response

<ResponseField name="id" type="string">
  CPU product ID.
</ResponseField>

<ResponseField name="name" type="string">
  CPU product name.
</ResponseField>

<ResponseField name="cpuNum" type="integer">
  Number of CPU cores.
</ResponseField>

<ResponseField name="memorySize" type="integer">
  Memory size (GB).
</ResponseField>

<ResponseField name="rootfsSize" type="integer">
  Root filesystem size (GB).
</ResponseField>

<ResponseField name="localVolumeSize" type="integer">
  Local disk size (GB).
</ResponseField>

<ResponseField name="availableDeploy" type="boolean">
  Whether this product can be used to create an instance. Values:

  * true: This product can be used to create an instance.
  * false: Insufficient resources, cannot create an instance.
</ResponseField>

<ResponseField name="price" type="integer">
  Unit price of the product.
</ResponseField>


# List Image Prewarm Tasks
Source: https://novita.ai/docs/api-reference/gpu-instance-list-image-prewarm

GET https://api.novita.ai/gpu-instance/openapi/v1/image/prewarm

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<ParamField type="integer">
  Page number. Default: 1.
</ParamField>

<ParamField type="integer">
  Page size. Default: 10.
</ParamField>

<ParamField type="string">
  Prewarm task state. Valid values: `Pending`, `Running`, `Succeeded`, `Failed`.
</ParamField>

<ParamField type="string">
  Cluster ID.
</ParamField>

<ParamField type="string">
  Image name or task note for fuzzy matching.
</ParamField>

## Response

<ResponseField name="data" type="object[]">
  List of prewarm tasks.

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Prewarm task ID.
    </ResponseField>

    <ResponseField name="imageName" type="string">
      Image name (the last segment of the image URL without the tag).
    </ResponseField>

    <ResponseField name="imageUrl" type="string">
      Image URL.
    </ResponseField>

    <ResponseField name="repositoryAuth" type="string">
      Image registry authentication ID.
    </ResponseField>

    <ResponseField name="clusterId" type="string">
      Cluster ID.
    </ResponseField>

    <ResponseField name="clusterName" type="string">
      Cluster name.
    </ResponseField>

    <ResponseField name="products" type="object[]">
      Products to prewarm.

      <Expandable title="properties">
        <ResponseField name="productId" type="string">
          Product ID.
        </ResponseField>

        <ResponseField name="productName" type="string">
          Product name.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="imageSize" type="string">
      Image size in bytes.
    </ResponseField>

    <ResponseField name="createTime" type="string">
      Task creation time (Unix timestamp in seconds).
    </ResponseField>

    <ResponseField name="state" type="string">
      Task state. Valid values: `Pending`, `Running`, `Succeeded`, `Failed`.
    </ResponseField>

    <ResponseField name="completeTime" type="string">
      Task completion time (Unix timestamp in seconds).
    </ResponseField>

    <ResponseField name="note" type="string">
      Task note.
    </ResponseField>

    <ResponseField name="reason" type="string[]">
      Reason messages.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of tasks.
</ResponseField>


# List Instances
Source: https://novita.ai/docs/api-reference/gpu-instance-list-instances

GET https://api.novita.ai/gpu-instance/openapi/v1/gpu/instances

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<ParamField type="integer">
  Maximum number of items returned per page. Integer, value >= 0.
</ParamField>

<ParamField type="integer">
  Page number to retrieve. Integer, value >= 0.
</ParamField>

<ParamField type="string">
  Instance name (supports fuzzy search). String, length limit: 0-255 characters.
</ParamField>

<ParamField type="string">
  Product name (supports fuzzy search). String, length limit: 0-255 characters.
</ParamField>

<ParamField type="string">
  Instance status. String, length limit: 0-63 characters. Possible values:

  * `toCreate`: Pending creation
  * `creating`: Creating
  * `pulling`: Pulling image
  * `running`: Running
  * `toStart`: Pending start
  * `starting`: Starting
  * `toStop`: Pending stop
  * `stopping`: Stopping
  * `exited`: Stopped
  * `toRestart`: Pending restart
  * `restarting`: Restarting
  * `toRemove`: Pending deletion
  * `removing`: Deleting
  * `removed`: Deleted
  * `toReset`: Pending reset (upgrade)
  * `resetting`: Resetting
  * `migrating`: Migrating
  * `freezing`: Freezing
</ParamField>

## Response

<ResponseField name="instances" type="object[]">
  Instance information.

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Instance ID.
    </ResponseField>

    <ResponseField name="name" type="string">
      Instance name.
    </ResponseField>

    <ResponseField name="clusterId" type="string">
      Cluster ID.
    </ResponseField>

    <ResponseField name="clusterName" type="string">
      Cluster name.
    </ResponseField>

    <ResponseField name="status" type="string">
      Instance status.
    </ResponseField>

    <ResponseField name="imageUrl" type="string">
      Container image URL.
    </ResponseField>

    <ResponseField name="imageAuthId" type="string">
      Image repository authentication information.
    </ResponseField>

    <ResponseField name="command" type="string">
      Container startup command.
    </ResponseField>

    <ResponseField name="entrypoint" type="string">
      Container startup entrypoint.
    </ResponseField>

    <ResponseField name="cpuNum" type="string">
      Number of CPU cores for the instance.
    </ResponseField>

    <ResponseField name="memory" type="string">
      Memory size of the instance (GB).
    </ResponseField>

    <ResponseField name="gpuNum" type="string">
      Number of GPUs for the instance.
    </ResponseField>

    <ResponseField name="portMappings" type="object[]">
      Instance port information.

      <Expandable title="properties">
        <ResponseField name="port" type="integer">
          Port value.
        </ResponseField>

        <ResponseField name="type" type="string">
          Port type.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="productId" type="string">
      Product ID used to deploy the instance.
    </ResponseField>

    <ResponseField name="productName" type="string">
      Product name used to deploy the instance.
    </ResponseField>

    <ResponseField name="rootfsSize" type="integer">
      Root filesystem size (GB).
    </ResponseField>

    <ResponseField name="volumeMounts" type="object[]">
      Instance storage configuration.

      <Expandable title="properties">
        <ResponseField name="type" type="string">
          Storage type. Values:

          * network: Cloud storage.
          * local: Local storage.
        </ResponseField>

        <ResponseField name="size" type="string">
          Storage capacity.
        </ResponseField>

        <ResponseField name="id" type="string">
          Cloud storage ID. Returned when type = network.
        </ResponseField>

        <ResponseField name="mountPath" type="string">
          Storage mount path.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="statusError" type="object">
      Error information when instance creation fails or the instance is unavailable.

      <Expandable title="properties">
        <ResponseField name="state" type="string">
          Abnormal instance status.
        </ResponseField>

        <ResponseField name="message" type="string">
          Error message.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="envs" type="object[]">
      Instance environment variable information.

      <Expandable title="properties">
        <ResponseField name="key" type="string">
          Environment variable name.
        </ResponseField>

        <ResponseField name="value" type="string">
          Environment variable value.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="kind" type="string">
      Instance type.
    </ResponseField>

    <ResponseField name="billingMode" type="string">
      Billing mode for the instance. Values:

      * onDemand: Pay-as-you-go billing.
      * monthly: Subscription (monthly or yearly) billing.
      * spot: Spot instance billing.
    </ResponseField>

    <ResponseField name="endTime" type="string">
      Expiration time for subscription instances. For pay-as-you-go instances, returns -1.
    </ResponseField>

    <ResponseField name="spotStatus" type="string">
      Spot instance status. Values:

      * `running`: Running
      * `notified`: Notified for reclaim
      * `reclaiming`: Being reclaimed
      * `terminated`: Terminated
    </ResponseField>

    <ResponseField name="spotReclaimTime" type="string">
      Spot instance reclaim time. Value "0" means reclaim has not started.
    </ResponseField>
  </Expandable>
</ResponseField>

<ParamField name="total" type="integer">
  Total number of results.
</ParamField>


# List Jobs
Source: https://novita.ai/docs/api-reference/gpu-instance-list-jobs

GET https://api.novita.ai/gpu-instance/openapi/v1/jobs

## API Description

Retrieve a paginated list of background jobs for GPU instances. You can filter by job ID, state, type, time range, and creators.

## Request Headers

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<ParamField type="integer">
  Maximum number of items returned per page. Integer, value >= 0.
</ParamField>

<ParamField type="integer">
  Page number to retrieve. Integer, value >= 0.
</ParamField>

<ParamField type="string">
  Filter by job ID. String, length 0–255.
</ParamField>

<ParamField type="string">
  Filter by job state. One of: `pulling` (preparing), `running`, `fail`, `success`, `break`.
</ParamField>

<ParamField type="string">
  Filter by job type. One of: `saveImage`, `instanceMigrate`, `autoInstanceMigrate`.
</ParamField>

<ParamField type="integer">
  Start of time range (Unix timestamp in seconds). Integer, value >= 0. Default: 0.
</ParamField>

<ParamField type="integer">
  End of time range (Unix timestamp in seconds). Integer, value >= 0. Default: 0.
</ParamField>

<ParamField type="string">
  Filter by creator user ID.
</ParamField>

## cURL Example

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/gpu-instance/openapi/v1/jobs?pageSize=5&pageNum=1&jobId=&type=&state=&startTime=&endTime=&creators=' \
--header 'Authorization: Bearer {{API_KEY}}'
```

## Response

<ResponseField name="jobs" type="object[]">
  Job list.

  <Expandable title="properties">
    <ResponseField name="Id" type="string">
      Job ID.
    </ResponseField>

    <ResponseField name="user" type="string">
      The user ID who initiated the job.
    </ResponseField>

    <ResponseField name="type" type="string">
      Job type. One of: `saveImage`, `instanceMigrate`, `autoInstanceMigrate`.
    </ResponseField>

    <ResponseField name="envs" type="object[]">
      Environment variables for the job.

      <Expandable title="properties">
        <ResponseField name="key" type="string">
          Environment variable name.
        </ResponseField>

        <ResponseField name="value" type="string">
          Environment variable value.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="state" type="object">
      Current job state information.

      <Expandable title="properties">
        <ResponseField name="state" type="string">
          Current job state. One of: `pulling`, `running`, `fail`, `success`, `break`.
        </ResponseField>

        <ResponseField name="error" type="string">
          Error code, if any.
        </ResponseField>

        <ResponseField name="errorMessage" type="string">
          Error message, if any.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="logAddress" type="string">
      Log URL for viewing job execution logs.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Job creation time (Unix timestamp in seconds).
    </ResponseField>

    <ResponseField name="instanceId" type="string">
      Associated instance ID when the job was executed.
    </ResponseField>
  </Expandable>
</ResponseField>

<ParamField name="total" type="integer">
  Total number of jobs matching the query.
</ParamField>


# List Network Storage
Source: https://novita.ai/docs/api-reference/gpu-instance-list-network-storage

GET https://api.novita.ai/gpu-instance/openapi/v1/networkstorages/list

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<ParamField type="integer" />

<ParamField type="integer" />

<ParamField type="string" />

<ParamField type="string" />

## Response

<ResponseField name="data" type="object[]">
  <Expandable title="properties">
    <ResponseField name="storageId" type="string" />

    <ResponseField name="storageName" type="string" />

    <ResponseField name="storageSize" type="integer" />

    <ResponseField name="clusterId" type="string" />

    <ResponseField name="clusterName" type="string" />

    <ResponseField name="price" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer" />

## Example

Request

```bash theme={"system"}
curl --request GET \
  --url 'https://api.novita.ai/gpu-instance/openapi/v1/networkstorages/list' \
  --header 'Authorization: Bearer {{API Key}}'
```

Response

```json theme={"system"}
{
  "data": [
    {
      "storageId": "d4e82677-3f80-4020-a731-d15b1c589aa8",
      "storageName": "123",
      "storageSize": 10,
      "clusterId": "5",
      "clusterName": "EU-01",
      "price": "100"
    },
    {
      "storageId": "082383c6-bc28-4bfa-a3b3-b6d6511bdf64",
      "storageName": "123",
      "storageSize": 10,
      "clusterId": "5",
      "clusterName": "EU-01",
      "price": "100"
    }
  ],
  "total": 2
}
```


# List GPU Products
Source: https://novita.ai/docs/api-reference/gpu-instance-list-products

GET https://api.novita.ai/gpu-instance/openapi/v1/products

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<ParamField type="string">
  Filter by specified cluster ID. String, length limit: 0-255 characters.
</ParamField>

<ParamField type="integer">
  Filter by number of GPUs. Integer, valid range: \[0, 8].
</ParamField>

<ParamField type="string">
  Filter by product name (fuzzy match). String, length limit: 0-255 characters.
</ParamField>

<ParamField type="integer">
  Filter by minimum CPU cores per GPU. Integer, value must be greater than or equal to 0.
</ParamField>

<ParamField type="integer">
  Filter by minimum memory per GPU (GB). Integer, value must be greater than or equal to 0.
</ParamField>

<ParamField type="integer">
  Filter by minimum root filesystem size per GPU (GB). Integer, value must be greater than or equal to 0.
</ParamField>

<ParamField type="string">
  Filter by billing method. Options:

  * `onDemand`: Pay-as-you-go instance (default)
  * `monthly`: Subscription instance (monthly or yearly)
  * `spot`: Spot instance billing
</ParamField>

## Response

<ResponseField name="data" type="object[]">
  GPU product information.

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Product ID.
    </ResponseField>

    <ResponseField name="name" type="string">
      Product name.
    </ResponseField>

    <ResponseField name="cpuPerGpu" type="integer">
      Number of CPU cores per GPU.
    </ResponseField>

    <ResponseField name="memoryPerGpu" type="integer">
      Memory size per GPU (GB).
    </ResponseField>

    <ResponseField name="diskPerGpu" type="integer">
      Disk size per GPU (GB).
    </ResponseField>

    <ResponseField name="availableDeploy" type="boolean">
      Whether this product can be used to create an instance. Values:

      * true: The product can be used to create an instance.
      * false: Insufficient resources, cannot create an instance.
    </ResponseField>

    <ResponseField name="minRootFS" type="integer">
      Minimum available root filesystem size (GB).
    </ResponseField>

    <ResponseField name="maxRootFS" type="integer">
      Maximum available root filesystem size (GB).
    </ResponseField>

    <ResponseField name="minLocalStorage" type="integer">
      Minimum available local storage size (GB).
    </ResponseField>

    <ResponseField name="maxLocalStorage" type="integer">
      Maximum available local storage size (GB).
    </ResponseField>

    <ResponseField name="regions" type="[string]">
      Available clusters. Indicates that this product is only available in the specified clusters. If the list is empty, the product is available in all clusters.
    </ResponseField>

    <ResponseField name="price" type="integer">
      Price for creating a pay-as-you-go instance with this product.
    </ResponseField>

    <ResponseField name="monthlyPrice" type="object[]">
      Price for creating a subscription (monthly or yearly) instance with this product.

      <Expandable title="properties">
        <ResponseField name="price" type="integer">
          Unit price for the subscription instance.
        </ResponseField>

        <ResponseField name="month" type="integer">
          Subscription duration, in months.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="billingMethods" type="string[]">
      The billing methods supported by this product. Valid values:

      * `onDemand`: Pay-as-you-go billing
      * `monthly`: Monthly subscription billing
      * `spot`: Spot instance billing
    </ResponseField>

    <ResponseField name="spotPrice" type="string">
      Spot billing instance price.
    </ResponseField>

    <ResponseField name="inventoryState" type="string">
      Product inventory status:

      * `none`: Out of stock
      * `low`: Low stock
      * `normal`: Normal stock
      * `high`: Sufficient stock
    </ResponseField>
  </Expandable>
</ResponseField>


# List Templates
Source: https://novita.ai/docs/api-reference/gpu-instance-list-templates

GET https://api.novita.ai/gpu-instance/openapi/v1/templates

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<ParamField type="integer">
  Page size. Integer, value >= 0.
</ParamField>

<ParamField type="integer">
  Page number. Integer, value >= 0.
</ParamField>

<ParamField type="string">
  Filter the templates by name (fuzzy match). String, length limit: 1-255 characters.
</ParamField>

<ParamField type="string">
  Filter the templates by type.
</ParamField>

<ParamField type="string">
  Filter the templates by channel.<br />
  Enum: `official`, `community`, `private`
</ParamField>

<ParamField type="boolean">
  Template visibility scope. Values: `true`, `false`.<br />
  Note:

  * Query official/community templates: set to `false`
  * Query private templates: set to `true`
</ParamField>

## Response

<ResponseField name="template" type="object[]">
  <Expandable title="properties">
    <ResponseField name="Id" type="string">
      Template ID.
    </ResponseField>

    <ResponseField name="name" type="string">
      Template name.
    </ResponseField>

    <ResponseField name="readme" type="string">
      Template README content (in Markdown format).
    </ResponseField>

    <ResponseField name="type" type="string">
      Template type.Enum: `instance`
    </ResponseField>

    <ResponseField name="channel" type="string">
      Template channel.Enum: `official`, `community`, `private`
    </ResponseField>

    <ResponseField name="image" type="string">
      Docker image address for instance startup.
    </ResponseField>

    <ResponseField name="imageAuth" type="string">
      Image repository authentication ID for private images.
    </ResponseField>

    <ResponseField name="startCommand" type="string">
      Startup command for the instance.
    </ResponseField>

    <ResponseField name="entrypoint" type="string">
      Instance startup entrypoint.
    </ResponseField>

    <ResponseField name="rootfsSize" type="integer">
      Rootfs storage (GB).
    </ResponseField>

    <ResponseField name="ports" type="object[]">
      Exposed ports settings.

      <Expandable title="properties">
        <ResponseField name="type" type="string">
          Exposed port types.Enum: `http, tcp`
        </ResponseField>

        <ResponseField name="ports" type="[integer]">
          Exposed ports (maximum 10).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="envs" type="object[]">
      Environment variables injected into instance.

      <Expandable title="properties">
        <ResponseField name="key" type="string">
          Environment variable key.
        </ResponseField>

        <ResponseField name="value" type="string">
          Environment variable value.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tools" type="object[]">
      Template built-in tools (only available for official templates).

      <Expandable title="properties">
        <ResponseField name="name" type="string">
          Tool name.
        </ResponseField>

        <ResponseField name="describe" type="string">
          Tool description.
        </ResponseField>

        <ResponseField name="port" type="integer">
          Tool port.
        </ResponseField>

        <ResponseField name="type" type="string">
          Tool protocol type. Enum: `http`, `tcp`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Template creation timestamp (Unix seconds).
    </ResponseField>

    <ResponseField name="recommendCards" type="object[]">
      Recommended GPU card specs (only available for official templates).

      <Expandable title="properties">
        <ResponseField name="gpuSpecId" type="string">
          GPU spec ID.
        </ResponseField>

        <ResponseField name="cardNum" type="string">
          Recommended card number.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="minCudaVersion" type="string">
      Minimum required CUDA version, e.g. 11.8, 12.4.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of templates.
</ResponseField>

## Example

Request

```bash theme={"system"}
curl --request GET \
  --url 'https://api.novita.ai/gpu-instance/openapi/v1/templates' \
  --header 'Authorization: Bearer {{API Key}}'
```

Response

````json theme={"system"}
{
  "template": [
    {
      "Id": "100",
      "name": "name",
      "readme": "```\nreadme\n```\n# uiohiu\n68686",
      "type": "instance",
      "channel": "official",
      "image": "image",
      "imageAuth": "",
      "startCommand": "startCommand",
      "entrypoint": "",
      "rootfsSize": 10,
      "ports": [
        {
          "type": "tcp",
          "ports": [8080, 8090]
        },
        {
          "type": "http",
          "ports": [6000, 60001]
        }
      ],
      "envs": [
        {
          "key": "testkey",
          "value": "123"
        }
      ],
      "tools": [
        {
          "name": "Jupyter",
          "describe": "Start Jupyter Notebook",
          "port": 8888,
          "type": "http"
        }
      ],
      "createdAt": "1711995567",
      "recommendCards": [
        {
          "gpuSpecId": "4090.18c.60g",
          "cardNum": "2"
        }
      ],
      "minCudaVersion": "11.8"
    }
  ],
  "total": 10
}
````


# List VPC Networks
Source: https://novita.ai/docs/api-reference/gpu-instance-list-vpc

GET https://api.novita.ai/gpu-instance/openapi/v1/networks

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<ParamField type="integer">
  Number of items per page. Integer, value must be greater than or equal to 0.
</ParamField>

<ParamField type="integer">
  Page number to retrieve. Integer, value must be greater than or equal to 0.
</ParamField>

<ParamField type="string">
  Custom network name (supports fuzzy search). String, length limit: 0-255 characters.
</ParamField>

<ParamField type="string">
  Creator user ID. String, length limit: 0-255 characters.
</ParamField>

## Response

<ResponseField name="network" type="object[]">
  VPC network information.

  <Expandable title="properties">
    <ResponseField name="Id" type="string">
      VPC network ID.
    </ResponseField>

    <ResponseField name="user" type="string">
      User account ID.
    </ResponseField>

    <ResponseField name="name" type="string">
      VPC network name.
    </ResponseField>

    <ResponseField name="state" type="object[]">
      VPC network status.

      <Expandable title="properties">
        <ResponseField name="state" type="string">
          VPC network status. Possible values:

          * creating: Being created.
          * ready: Successfully created.
        </ResponseField>

        <ResponseField name="error" type="string">
          Error message if VPC network creation fails or the network is unavailable.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="segment" type="string">
      VPC network segment.
    </ResponseField>

    <ResponseField name="clusterId" type="string">
      Cluster ID.
    </ResponseField>

    <ResponseField name="Addresses" type="object[]">
      Instance information under the VPC network.

      <Expandable title="properties">
        <ResponseField name="Id" type="string">
          Instance ID.
        </ResponseField>

        <ResponseField name="Ip" type="string">
          Instance IP address.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="createTime" type="string">
      VPC network creation time. Format: Unix timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="string">
  Total number of results.
</ResponseField>


# Migrate Instance
Source: https://novita.ai/docs/api-reference/gpu-instance-migrate-instance

POST https://api.novita.ai/gpu-instance/openapi/v1/gpu/instance/migrate

## API Description

When migrating an instance, any new data on the system disk and local disk will not be preserved.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The ID of the instance to be migrated.
</ParamField>


# Renew Subscription Instance
Source: https://novita.ai/docs/api-reference/gpu-instance-renewal-instance

POST https://api.novita.ai/gpu-instance/openapi/v1/gpu/instance/renewInstance

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The ID of the subscription instance to be renewed.
</ParamField>

<ParamField type="integer">
  Renewal period, in months.
</ParamField>


# Restart Instance
Source: https://novita.ai/docs/api-reference/gpu-instance-restart-instance

POST https://api.novita.ai/gpu-instance/openapi/v1/gpu/instance/restart

**This API is used to restart a specific GPU instance.**

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  ID of the instance to be restarted.
</ParamField>


# Save Instance Image
Source: https://novita.ai/docs/api-reference/gpu-instance-save-image

POST https://api.novita.ai/gpu-instance/openapi/v1/job/save/image

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Instance ID. String, length: 1-255 characters.
</ParamField>

<ParamField type="string">
  Target image address, including registry/repository:tag. String, length: 1-4095 characters.
</ParamField>

<ParamField type="string">
  Container registry authentication ID. Not required for public registries or platform-provided registries. Required for third-party private registries.
</ParamField>

## Response

<ResponseField name="jobId" type="string">
  Image save job ID. Use this ID to check status and logs in the Console under Job Management.
</ResponseField>


# Set Auto Renew
Source: https://novita.ai/docs/api-reference/gpu-instance-set-autorenew

POST https://api.novita.ai/gpu-instance/openapi/v1/gpu/instance/setAutoRenew

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string[]">
  Instance ID list.
</ParamField>

<ParamField type="boolean">
  Whether to enable automatic renewal.
</ParamField>

<ParamField type="integer">
  Automatic renewal period, in months.
</ParamField>


# Start Instance
Source: https://novita.ai/docs/api-reference/gpu-instance-start-instance

POST https://api.novita.ai/gpu-instance/openapi/v1/gpu/instance/start

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  ID of the instance to be started.
</ParamField>


# Stop Instance
Source: https://novita.ai/docs/api-reference/gpu-instance-stop-instance

POST https://api.novita.ai/gpu-instance/openapi/v1/gpu/instance/stop

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  ID of the instance to be stopped.
</ParamField>


# Update Image Prewarm Task
Source: https://novita.ai/docs/api-reference/gpu-instance-update-image-prewarm

POST https://api.novita.ai/gpu-instance/openapi/v1/image/prewarm/edit

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Prewarm task ID.
</ParamField>

<ParamField type="string">
  Task note.
</ParamField>


# Update VPC Network
Source: https://novita.ai/docs/api-reference/gpu-instance-update-vpc

POST https://api.novita.ai/gpu-instance/openapi/v1/network/update

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Cluster ID. String, length limit: 1-255 characters.
</ParamField>

<ParamField type="string">
  Custom network name. String, length limit: 1-30 characters.
</ParamField>


# Upgrade Instance
Source: https://novita.ai/docs/api-reference/gpu-instance-upgrade-instance

POST https://api.novita.ai/gpu-instance/openapi/v1/gpu/instance/upgrade

## API Description

When upgrading an instance, all parameters must be provided in full.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The ID of the instance to be upgraded.
</ParamField>

<ParamField type="string">
  Container image URL. String, length limit: 1-500 characters.
</ParamField>

<ParamField type="string">
  Image registry authentication ID.
</ParamField>

<ParamField type="object[]">
  Instance environment variables. Up to 100 environment variable pairs can be created.

  <Expandable title="properties">
    <ParamField type="string">
      Environment variable name. String, length limit: 0-511 characters.
    </ParamField>

    <ParamField type="string">
      Environment variable value. String, length limit: 0-4095 characters.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Container startup command. String, length limit: 0-2047 characters.
</ParamField>

<ParamField type="string">
  Container startup entrypoint. This setting will override the Docker image's ENTRYPOINT. String, length limit: 0-2047 characters.
</ParamField>

<ParamField type="boolean">
  Whether to retain data from the previous instance. Boolean, values: true or false.
</ParamField>

<ParamField type="object">
  Configure cloud storage (type: network). Each instance supports mounting up to 30 cloud storage volumes. To remove all cloud storage mounts, set volumeMounts to an empty array: \[].

  <Expandable title="properties">
    <ParamField type="object[]">
      Cloud storage mount information.

      <Expandable title="properties">
        <ParamField type="string">
          Storage type. Must be set to network.
        </ParamField>

        <ParamField type="string">
          Cloud storage ID.
        </ParamField>

        <ParamField type="string">
          Mount path for the cloud storage. Default: "/network". String, length limit: 1-4095 characters.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>


# Cleanup
Source: https://novita.ai/docs/api-reference/model-apis-cleanup

POST https://api.novita.ai/v3/cleanup

**Easily remove unwanted objects, defects, people, or text from your pictures in just seconds.**

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Optional extra parameters for the request.

  <Expandable title="properties">
    <ParamField type="string">
      The returned image type. Default is png.<br />
      Enum: `png, webp, jpeg`
    </ParamField>

    <ParamField type="object">
      Dedicated Endpoints settings, which only take effect for users who have already subscribed to the [Dedicated Endpoints Documentation](/guides/model-apis-dedicated-endpoints).

      <Expandable title="properties">
        <ParamField type="boolean">
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  The base64-encoded original image, with a maximum resolution of 16 megapixels and a maximum file size of 30 MB.
</ParamField>

<ParamField type="string">
  The base64-encoded mask image, with a maximum resolution of 16 megapixels and a maximum file size of 30 MB.
</ParamField>

## Response

<ResponseField name="image_file" type="string">
  The Base64-encoded content of the returned image.
</ResponseField>

<ResponseField name="image_type" type="string">
  The returned image type.<br />
  Enum: `png`, `webp`, `jpeg`
</ResponseField>

## Example

Cleanup allows you to easily remove unwanted objects, defects, people, or text from your pictures in just seconds.

**Try it in the [playground](https://novita.ai/playground#cleanup).**

`Request:`

```bash theme={"system"}
curl --location --request POST 'https://api.novita.ai/v3/cleanup' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"image_file":"{{Base64 encoded image}}",
"mask_file":"{{Base64 encoded image}}"
}'
```

`Response:`

```js theme={"system"}
{
    "image_file": "{{Base64 encoded image}}",
    "image_type": "png"
}
```

HTTP status codes in the 2xx range indicate that the request has been successfully accepted. A code of 400 means there is an error with the request parameters, while status codes in the 5xx range indicate internal server errors.

You can retrieve the image URL in the `image_file` field of the response in base64 format.

`Response:`

```js theme={"system"}
{
    "image_file": "{{Base64 encoded image}}",
    "image_type": "png"
}
```

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>


# LoRA for Style Training
Source: https://novita.ai/docs/api-reference/model-apis-create-style-training



**You can train a LoRA model to generate images that emulate a specific artistic style.**

## Create Style Training Task

`POST https://api.novita.ai/v3/training/style`

**Use this API to start a style training task.**

> This is an **asynchronous API**; only the **task\_id** is returned initially. Utilize this **task\_id** to query the **Task Result API** at [Get Style Training Result API](#get-style-training-result) to retrieve the results of the image generation.

### Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

### Request Body

<ParamField type="string">
  Task name for this model training.
</ParamField>

<ParamField type="string">
  Base models used for training.<br />
  Enum: `stable-diffusion-xl-base-1.0`, `dreamshaperXL09Alpha_alpha2Xl10_91562`, `protovisionXLHighFidelity3D_release0630Bakedvae_154359`, `v1-5-pruned-emaonly`, `epicrealism_naturalSin_121250`, `chilloutmix_NiPrunedFp32Fix`, `abyssorangemix3AOM3_aom3a3_10864`, `dreamshaper_8_93211`, `WFChild_v1.0`, `majichenmixrealistic_v10`, `realisticVisionV51_v51VAE_94301`, `sdxlUnstableDiffusers_v11_216694`, `realisticVisionV40_v40VAE_81510`, `epicrealismXL_v10_247189`, `somboy_v10_172675`, `yesmixXL_v10_283329`, `animagineXLV31_v31_325600`
</ParamField>

<ParamField type="integer">
  Width of training images, must be > 0
</ParamField>

<ParamField type="integer">
  Height of training images, must be > 0
</ParamField>

<ParamField type="object[]">
  Image asset IDs and their captions.

  <Expandable title="properties">
    <ParamField type="integer">
      Image asset ID; see <a href="#_1-upload-images-for-training">Upload Images For Training</a> for reference.
    </ParamField>

    <ParamField type="string">
      Image caption; refer to <a href="/guides/model-apis-training-guidance">Training Image Caption Guidance</a> for more information.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="integer">
      batch size of training, Range \[1, 4]
    </ParamField>

    <ParamField type="number(float)">
      This parameter controls the extent of model parameter updates during each iteration. A higher learning rate results in larger updates, potentially speeding up the learning process but risking overshooting the optimal solution. Conversely, a lower learning rate ensures smaller, more precise adjustments, which may lead to a more stable convergence at the cost of slower training.<br />
      Enum: `1e-4, 1e-5, 1e-6, 2e-4, 5e-5`
    </ParamField>

    <ParamField type="integer">
      This parameter specifies the maximum number of training steps to be executed before halting the training process. It sets a limit on the duration of training, ensuring that the model does not continue to train indefinitely. If the `max_train_steps` set to 2000 and images amount in parameter `image_dataset_items` is 10, the number of training steps per graph is 200. Minimum value is 1.
    </ParamField>

    <ParamField type="integer">
      A seed is a number from which Stable Diffusion generates noise, which, makes training deterministic. Using the same seed and set of parameters will produce identical LoRA each time, Minimum 1.
    </ParamField>

    <ParamField type="string">
      This parameter specifies the type of learning rate scheduler to be used during the training process. The scheduler dynamically adjusts the learning rate according to one of the specified strategies. `constant`: Maintains a fixed learning rate throughout training. `linear`: Gradually decreases the learning rate linearly from a higher to a lower value. `cosine`: Adjusts the learning rate following a cosine curve, decreasing it initially and then increasing towards the end. `cosine_with_restarts`: Similar to cosine, but resets the rate periodically to avoid local minima. `polynomial`: Decreases the learning rate according to a polynomial decay. `constant_with_warmup`: Starts with a lower learning rate and warms up to a constant rate after a specified number of steps.<br />
      Enum: `constant, linear, cosine, cosine_with_restarts, polynomial, constant_with_warmup`
    </ParamField>

    <ParamField type="integer">
      This parameter determines the number of initial training steps during which the learning rate increases gradually, effective only when the lr\_scheduler is set to one of the following modes: linear, cosine, cosine\_with\_restarts, polynomial, or constant\_with\_warmup. The warmup phase helps in stabilizing the training process before the main learning rate schedule begins. The minimum value for this parameter is 0, indicating no warmup, Minimum 0.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  Common parameters configured for training.

  <Expandable title="properties">
    <ParamField type="string">
      Type of components. When set to `face_crop_region`, args can be set to args: \[name: ratio, value: 1.0], ratio > 1 means more non-facial area will be included. When set to `resize`, args can be set to args: \[name: width, value: 512, name: height, value: 512], which mean all the images will be cropped to 512\*512. When set to `face_restore`, args can be set to args: \[name: method, value:gfpgan\_1.4], which mean face restore will be open.<br />
      Enum: `face_crop_region`, `resize`, `face_restore`
    </ParamField>

    <ParamField type="object[]">
      Component detail settings.

      <Expandable title="properties">
        <ParamField type="string">
          Name of argument.
        </ParamField>

        <ParamField type="string">
          Argument value.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="task_id" type="string">
  Utilize this `task_id` to query the Task Result API at <a href="#get-style-training-result">Get style training result</a>.
</ResponseField>

## Get style training result

`GET https://api.novita.ai/v3/training/style`

**Use this API to get the style training result, including the model.**

### Request Headers

<ParamField type="string">
  In Bearer \{\{API Key}} format.
</ParamField>

### Request Body

<ParamField type="string" />

### Response

<ResponseField name="task_id" type="string">
  The task id of training.
</ResponseField>

<ResponseField name="task_status" type="string">
  Represents the current status of a task, particularly useful for monitoring and managing the progress of training tasks. Each status indicates a specific phase in the task's lifecycle.<br />
  Enum: `UNKNOWN`, `QUEUING`, `TRAINING`, `SUCCESS`, `CANCELED`, `FAILED`
</ResponseField>

<ResponseField name="model_type" type="string">
  Model trained type.<br />
  Enum: `lora`
</ResponseField>

<ResponseField name="models" type="object[]">
  models info

  <Expandable title="properties">
    <ResponseField name="model_name" type="string">
      model file name.
    </ResponseField>

    <ResponseField name="model_status" type="string">
      model status.<br />
      Enum: `DEPLOYING`, `SERVING`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="extra" type="object">
  extra info

  <Expandable title="properties">
    <ResponseField name="eta_relative" type="number">
      Estimated time of arrival in seconds.
    </ResponseField>

    <ResponseField name="progress_percent" type="number">
      The progress percent with a range of 0 to 100.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<u>**In this document we will explain step by step how to use our API for LoRA model training.**</u>

Generally, model training involves following steps.

* Upload the images for model training.
* Set training parameters and start the training.
* Get the training results and generate images with the trained model.

### 1. Upload images for training

* Currently we only supports uploading images in `png` / `jpeg` / `webp` format.
* Each task supports uploading up to 50 images. In order to make the final effect good, the images uploaded should meet some basic conditions, such as: "portrait in the center", "no watermark", "clear picture", etc.

#### 1.1 Get image upload URL

* This interface returns the URL for single image to upload and can be called multiple times to upload images for training.

```bash theme={"system"}
curl --location --request POST 'https://api.novita.ai/v3/assets/training_dataset' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "file_extension": "png"
}'
```

`Response:`

```js theme={"system"}
{
    "assets_id": "34558688e2f42a0137ca2d5274a8cf43",
    "upload_url": "https://faas-training-dataset.s3.ap-southeast-1.amazonaws.com/test/******",
    "method": "PUT",
    "headers": {
        "Host": {
            "values": [
                "faas-training-dataset.s3.ap-southeast-1.amazonaws.com"
            ]
        }
    }
}
```

* `assets_id`: The unique identifier of the image, which will be used in the training task.
* `upload_url`: The URL for image upload.
* `method`: The HTTP method for image upload.

#### 1.2 Upload images

After obtaining the `upload_url` at step `Get image upload URL`, please refer to the following document to complete the image upload: [https://docs.aws.amazon.com/zh\_cn/AmazonS3/latest/userguide/PresignedUrlUploadObject.html.](https://docs.aws.amazon.com/zh_cn/AmazonS3/latest/userguide/PresignedUrlUploadObject.html)

`Put images:`

```bash theme={"system"}
curl -X PUT -T "{{filepath}}" "{{upload_url}}"
```

`or`

```
curl --location --request PUT '{{upload_url}}' \
--header 'Content-Type: image/png' \
--data '{{filepath}}'
```

### 2. Start training task and configure parameters

In this step, we will begin the model training process, which is expected to take approximately 10 minutes, depending on the actual server's availability.

There are four types of parameters for model traning: `Model info parameters`, `dataset parameters`, `components parameters`,`expert parameters`, you can set them according to our tables below.

Here are some tips to train a good model:

* At least 10 photos of faces that meet the requirements.
* For parameters `instance_prompt`, we suggests using "a close photo of ohwx \<man|\woman>"
* For parameters `base_model`, value `v1-5-pruned-emaonly` has better generalization ability and can be used in combination with various Base models, such as `dreamshaper 2.5D`, value `epic-realism` has a strong sense of reality.

| Type                  | Parameters                         | Description                                                                                                                                     |
| :-------------------- | :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
| Model info parameters | name                               | Name of your training model                                                                                                                     |
| Model info parameters | base\_model                        | base\_model type                                                                                                                                |
| Model info parameters | width                              | Target image width                                                                                                                              |
| Model info parameters | height                             | Target image height                                                                                                                             |
| dataset parameters    | image\_dataset\_items              | Array: consist of `imageUrl` and image `caption`                                                                                                |
| dataset parameters    | - image\_dataset\_items.assets\_id | images assets\_id, which can be found in step `Get image upload URL`                                                                            |
| components parameters | components                         | Array: consist of `name` and `args`, this is a common parameters configured for training.                                                       |
| components parameters | - components.name                  | Type of components, Enum: `face_crop_region`, `resize`, `face_restore`                                                                          |
| components parameters | - components.args                  | Detail values of components.name                                                                                                                |
| expert parameters     | expert\_setting                    | expert parameters.                                                                                                                              |
| expert parameters     | - instance\_prompt                 | Captions for all the training images, here is a guidance of how to make a effective prompt : [Click Here](/guides/model-apis-training-guidance) |
| expert parameters     | - batch\_size                      | batch size of training.                                                                                                                         |
| expert parameters     | - max\_train\_steps                | Max train steps, 500 is enought for lora model training.                                                                                        |
| expert parameters     | - ......                           | More expert parameters can be access at api reference.                                                                                          |

**Here is a example of how to start training:**

```bash theme={"system"}
curl --location --request POST 'https://api.novita.ai/v3/training/style' \
--header 'Accept: <Accept>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{API Key}}' \
--data-raw '{
    "name": "test_style_01",
    "base_model": "v1-5-pruned-emaonly",
    "width": 512,
    "height": 512,
    "image_dataset_items": [
        {
          "assets_id": "34558688e2f42a0137ca2d5274a8cf43"
        },
        {
          "assets_id": "1231231243f42a0137ca2d5274a8cf43"
        }
    ],
    "expert_setting": {
        "instance_prompt": "Xstyle, of a young woman, profile shot, from side,sitting, looking at viewer, smiling, head tilt, eyes open,long black hair, glowing skin,light smile,cinematic lighting,dark environment",
        "class_prompt": "person"
    },
    "components": [
        {
            "name": "face_crop_region",
            "args": [
                {
                    "name": "ratio",
                    "value": "1"
                }
            ]
        },
        {
          "name": "resize",
          "args": [
              {"name": "width", "value": "512"},
              {"name": "height", "value": "512"}
          ]
        },
        {
          "name": "face_restore",
            "args": [
                {"name": "method", "value": "gfpgan_1.4"},
                {"name": "upscale", "value": "1.0"}
            ]
        }
    ]
}'
```

Response:

```bash theme={"system"}
{
    "task_id": "d660cdd0-ab9b-4a55-8b78-4bc851051fb0"
}
```

The `task_id` is the unique identifier of the training task, which can be used to query the training status and results.

### 3. Get training status

#### 3.1 Get model training and deployment status

In this step, we will obtain the progress of model training and the status of model deployment after training

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/training/style?task_id=d660cdd0-ab9b-4a55-8b78-4bc851051fb0' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```bash theme={"system"}
{
    "task_id": "d660cdd0-ab9b-4a55-8b78-4bc851051fb0",
    "task_status": "SUCCESS",
    "model_type": "",
    "models": [
        {
            "model_name": "model_1698904832_F2BB461625.safetensors",
            "model_status": "DEPLOYING"
        }
    ]
}
```

* `task_status`: The status of the training task, Enum: `UNKNOWN`, `QUEUING`, `TRAINING`, `SUCCESS`, `CANCELED`, `FAILED`.
* `model_status`: The status of the model, Enum: `DEPLOYING`, `SERVING`.
* `model_name`: The name of the model, which can be used to generate images in next step.

When the `task_status` is `SUCCESS`, the `model_status` is `SERVING` we can starting to use the lora model.

#### 3.2 Start using the trained model

After model deployed successfully, we can download the model files or generate images directly.

##### 3.2.1 Use the generated models to create images

In order to use the trained lora models, We need to add `model_name` into the `request` of endpoint `/v3/async/txt2img` or `/v3/async/img2img`. **Currently trained lora model can not be used in /v3 endpoint.**

Below is a example of how to generate images with trained model:

Please set the **`Content-Type`** header to **`application/json`** in your HTTP request to indicate that you are sending JSON data. Currently, **only JSON format is supported**.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/txt2img' \
--header 'Authorization: Bearer {{API Key}};' \
--header 'Content-Type;' \
--data '{
  "extra": {
    "response_image_type": "jpeg"
  },
  "request": {
    "model_name": "realisticVisionV51_v51VAE_94301.safetensors",
    "prompt": "a young woman",
    "negative_prompt": "bottle, bad face",
    "sd_vae": "",
    "loras": [
      {
        "model_name": "model_1698904832_F2BB461625.safetensors",
        "strength": 0.7
      }
    ],
    "embeddings": [
      {
        "model_name": ""
      }
    ],
    "hires_fix": {
      "target_width": 1024,
      "target_height": 768,
      "strength": 0.5
    },
    "refiner": {
      "switch_at": null
    },
    "width": 512,
    "height": 384,
    "image_num": 2,
    "steps": 20,
    "seed": 123,
    "clip_skip": 1,
    "guidance_scale": 7.5,
    "sampler_name": "Euler a"
  }
}'
```

`Response:`

```bash theme={"system"}
{
    "code": 0,
    "msg": "",
    "data": {
        "task_id": "bec2bcfe-47c6-4536-af34-f26cfe6fd457"
    }
}
```

**Use `task_id` to get images**

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get images url in `imgs` of response.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/task-result?task_id=bec2bcfe-47c6-4536-af34-f26cfe6fd457' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
  "task": {
    "task_id": "bec2bcfe-47c6-4536-af34-f26cfe6fd457",
    "status": "TASK_STATUS_SUCCEED",
    "reason": ""
  },
  "images": [
    {
      "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/dev/replace_object_a910c8f7-76ce-40bd-b805-f00f3ddd7dc1_0.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20231019%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20231019T084537Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=b9ad40a5cb3aecf89602c15fe72d28be5d8a33e0bfe3656ce968295fde1aab31",
      "image_url_ttl": 3600,
      "image_type": "png"
    }
  ],
  "videos": [
    {
      "video_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/dev/replace_object_a910c8f7-76ce-40bd-b805-f00f3ddd7dc1_0.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20231019%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20231019T084537Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=b9ad40a5cb3aecf89602c15fe72d28be5d8a33e0bfe3656ce968295fde1aab31",
      "video_url_ttl": "3600",
      "video_type": "png"
    }
  ]
}
```

#### 3.3 List training tasks

In this step, we can obtain all the info of trained models.

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/training?pagination.limit=10&pagination.cursor=c_0' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "tasks": [
        {
          "task_name": "test_01",
            "task_id": "a0c4cc90-0296-4972-a1d8-e6e227daf094",
            "task_type": "style",
            "task_status": "SUCCESS",
            "created_at": 1699325415,
            "models": [
                {
                    "model_name": "model_1699325939_E83A88DAC5.safetensors",
                    "model_status": "SERVING"
                }
            ]
        },
        {
          "task_name": "test_02",
          "task_id": "51e9bf41-8f7a-464d-b5ad-2fa217a1ec93",
          "task_type": "style",
          "task_status": "SUCCESS",
          "created_at": 1699267268,
          "models": [
              {
                  "model_name": "model_1699267603_27F0D9C81C.safetensors",
                  "model_status": "SERVING"
              }
          ]
        },
        {
          "task_name": "test_03",
            "task_id": "7bd205ab-63e9-452b-9a66-39c597000eaa",
            "task_type": "style",
            "task_status": "FAILED",
            "created_at": 1699264338,
            "models": []
        }
    ],
    "pagination": {
        "next_cursor": "c_10"
    }
}
```

* `task_name` : The name of the training task.
* `task_id` : The unique identifier of the training task, which can be used to query the training status and results.
* `task_type` : The type of the training task.
* `task_status`: The status of the training task, Enum: `UNKNOWN`, `QUEUING`, `TRAINING`, `SUCCESS`, `CANCELED`, `FAILED`.
* `created_at`: The time when the training task was created.
* `model`: The trained model.
* `model_name`: The sd name of the model.
* `model_status`: The status of the model, Enum: `DEPLOYING`, `SERVING`.

### 4. Training playground

You can also use our training playground to train models in a user-friendly way at: [Click Here](https://huggingface.co/spaces/novita-ai/Face-Stylization-Playground)

#### 4.1 Input Novita AI API Key, images and select training type

<Frame>
  <img />
</Frame>

#### 4.2 Switch to the inferencing tab and add more detail

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

#### Review the training results

<Frame>
  <img />
</Frame>


# LoRA for Subject Training
Source: https://novita.ai/docs/api-reference/model-apis-create-subject-training



**You can train a LoRA model to generate images featuring a subject, such as yourself.**

## Create Subject Training Task

`POST https://api.novita.ai/v3/training/subject`

**Use this API to start a subject training task.**

> This is an **asynchronous API**; only the **task\_id** is returned initially. Utilize this **task\_id** to query the **Task Result API** at [Get Subject Training Result API](#get-subject-training-result) to retrieve the results of the image generation.

### Request Headers

<ParamField type="string">
  In Bearer \{\{API Key}} format.
</ParamField>

<ParamField type="string">
  Enum: `application/json`
</ParamField>

### Request Body

<ParamField type="string">
  Task name for this model training.
</ParamField>

<ParamField type="string">
  Base models used for training.<br />
  Enum: `stable-diffusion-xl-base-1.0`, `dreamshaperXL09Alpha_alpha2Xl10_91562`, `protovisionXLHighFidelity3D_release0630Bakedvae_154359`, `v1-5-pruned-emaonly`, `epicrealism_naturalSin_121250`, `chilloutmix_NiPrunedFp32Fix`, `abyssorangemix3AOM3_aom3a3_10864`, `dreamshaper_8_93211`, `WFChild_v1.0`, `majichenmixrealistic_v10`, `realisticVisionV51_v51VAE_94301`, `sdxlUnstableDiffusers_v11_216694`, `realisticVisionV40_v40VAE_81510`, `epicrealismXL_v10_247189`, `somboy_v10_172675`, `yesmixXL_v10_283329`, `animagineXLV31_v31_325600`
</ParamField>

<ParamField type="integer">
  Training image width. Minimum value is 1.
</ParamField>

<ParamField type="integer">
  Training image height. Minimum value is 1.
</ParamField>

<ParamField type="object[]">
  Image asset IDs and image captions.

  <Expandable title="properties">
    <ParamField type="string">
      Image asset ID. Refer to <a href="#_1-upload-images-for-training">Upload Images For Training</a> for more information.
    </ParamField>

    <ParamField type="string">
      Image caption. Refer to <a href="/guides/model-apis-training-guidance">Training Image Caption Guidance</a>. The length must be between 1 and 1024 characters, inclusive.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="integer">
      batch size of training, Range: \[1, 4]
    </ParamField>

    <ParamField type="number(float)">
      This parameter controls the extent of model parameter updates during each iteration. A higher learning rate results in larger updates, potentially speeding up the learning process but risking overshooting the optimal solution. Conversely, a lower learning rate ensures smaller, more precise adjustments, which may lead to a more stable convergence at the cost of slower training.<br />
      Enum: `1e-4`, `1e-5`, `1e-6`, `2e-4`, `5e-5`
    </ParamField>

    <ParamField type="integer">
      This parameter specifies the maximum number of training steps to be executed before halting the training process. It sets a limit on the duration of training, ensuring that the model does not continue to train indefinitely. If the `max_train_steps` set to 2000 and images amount in parameter `image_dataset_items` is 10, the number of training steps per graph is 200. Minimum value is 1.
    </ParamField>

    <ParamField type="integer">
      A seed is a number from which Stable Diffusion generates noise, which, makes training deterministic. Using the same seed and set of parameters will produce identical LoRA each time, Minimum 1.
    </ParamField>

    <ParamField type="string">
      This parameter specifies the type of learning rate scheduler to be used during the training process. The scheduler dynamically adjusts the learning rate according to one of the specified strategies.<br />
      Enum: `constant`, `linear`, `cosine`, `cosine_with_restarts`, `polynomial`, `constant_with_warmup`
    </ParamField>

    <ParamField type="integer">
      This parameter determines the number of initial training steps during which the learning rate increases gradually, effective only when the lr\_scheduler is set to one of the following modes: linear, cosine, cosine\_with\_restarts, polynomial, or constant\_with\_warmup. The warmup phase helps in stabilizing the training process before the main learning rate schedule begins. The minimum value for this parameter is 0, indicating no warmup, Minimum 0.
    </ParamField>

    <ParamField type="string">
      This parameter specifies a prompt that best describes the images associated with an instance. It is essential for accurately conveying the content or theme of the images, facilitating better context or guidance for operations such as classification, tagging, or generation.
    </ParamField>

    <ParamField type="string">
      This parameter is used to specify a prompt that focuses the training process on a specific subject, in this case, a `person`. It guides the model to tailor its learning and output generation towards this defined class, enhancing specificity and relevance in tasks such as image recognition or generation related to human features or activities.<br />
      Enum: `person`
    </ParamField>

    <ParamField type="boolean">
      This parameter enables the option to preserve prior knowledge or settings in a model. When set to true, it ensures that existing configurations or learned patterns are maintained during updates or further training, enhancing the model's stability and consistency over time.
    </ParamField>

    <ParamField type="number(float)">
      This parameter specifies the weight assigned to the prior loss in the model's loss function. It must be greater than 0 to have an effect. Setting this parameter helps control the influence of prior knowledge on the training process, balancing new data learning with the retention of previously learned information.
    </ParamField>

    <ParamField type="boolean">
      This parameter determines whether the text encoder component of the model should undergo training. Enabling this setting (true) allows the text encoder to adapt and improve its understanding of textual input based on the specific data and tasks at hand, potentially enhancing overall model performance.
    </ParamField>

    <ParamField type="integer">
      This parameter specifies the rank for the LoRA (Low-Rank Adaptation) modification. Valid values range from 4 to 128. Adjusting this parameter allows for tuning the complexity and capacity of the LoRA layers within the model, impacting both performance and computational efficiency. Range \[4 , 128].
    </ParamField>

    <ParamField type="integer">
      This parameter sets the scaling factor (alpha) for the Low-Rank Adaptation (LoRA) layers within the model. It accepts values ranging from 4 to 128. Adjusting lora\_alpha modifies the degree of adaptation applied to the pre-trained layers, influencing the learning capability and the granularity of the adjustments made during training. Range \[4 , 128].
    </ParamField>

    <ParamField type="integer">
      This parameter specifies the rank of the LoRA (Low-Rank Adaptation) modification applied specifically to the text encoder component of the model. Valid values range from 4 to 128. By setting this parameter, you can tune the complexity and impact of the LoRA adjustments on the text encoder, potentially enhancing its performance and adaptability to new textual data. Range \[4 , 128].
    </ParamField>

    <ParamField type="integer">
      This parameter defines the scaling factor (alpha) for Low-Rank Adaptation (LoRA) specifically applied to the text encoder component of the model. It accepts values ranging from 4 to 128. The lora\_text\_encoder\_alpha parameter adjusts the degree of adaptation applied, allowing for finer control over how the text encoder processes and learns from textual input, thereby impacting the overall effectiveness and efficiency of the model. Range \[4 , 128].
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  Common parameters configured for training.

  <Expandable title="properties">
    <ParamField type="string">
      Type of components.<br />
      Enum: `face_crop_region`, `resize`, `face_restore`
    </ParamField>

    <ParamField type="object[]">
      Component detail settings.

      <Expandable title="properties">
        <ParamField type="string">
          Name of argument.
        </ParamField>

        <ParamField type="string">
          Argument value.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="task_id" type="string">
  Utilize this `task_id` to query the Task Result API at <a href="#get-subject-training-result">Get subject training result</a>.
</ResponseField>

## Get subject training result

`GET https://api.novita.ai/v3/training/subject`

**Use this API to get the subject training result, including the model.**

### Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

### Request Body

<ParamField type="string" />

### Response

<ResponseField name="task_id" type="string">
  The task id of training.
</ResponseField>

<ResponseField name="task_status" type="string">
  Represents the current status of a task, particularly useful for monitoring and managing the progress of training tasks. Each status indicates a specific phase in the task's lifecycle.<br />
  Enum: `UNKNOWN`, `QUEUING`, `TRAINING`, `SUCCESS`, `CANCELED`, `FAILED`
</ResponseField>

<ResponseField name="model_type" type="string">
  Model trained type.<br />
  Enum: `lora`
</ResponseField>

<ResponseField name="models" type="object[]">
  models info

  <Expandable title="properties">
    <ResponseField name="model_name" type="string">
      model file name.
    </ResponseField>

    <ResponseField name="model_status" type="string">
      model status.<br />
      Enum: `DEPLOYING`, `SERVING`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="extra" type="object">
  extra info

  <Expandable title="properties">
    <ResponseField name="eta_relative" type="number">
      Estimated time of arrival in seconds.
    </ResponseField>

    <ResponseField name="progress_percent" type="number">
      The progress percent with a range of 0 to 100.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<u>**In this document we will explain step by step how to use our API for LoRA model training.**</u>

Generally, model training involves following steps.

* Upload the images for model training.
* Set training parameters and start the training.
* Get the training results and generate images with the trained model.

### 1. Upload images for training

* Currently we only supports uploading images in `png` / `jpeg` / `webp` format.
* Each task supports uploading up to 50 images. In order to make the final effect good, the images uploaded should meet some basic conditions, such as: "portrait in the center", "no watermark", "clear picture", etc.

#### 1.1 Get image upload URL

* This interface returns the URL for single image to upload and can be called multiple times to upload images for training.

```bash theme={"system"}
curl --location --request POST 'https://api.novita.ai/v3/assets/training_dataset' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "file_extension": "png"
}'
```

`Response:`

```js theme={"system"}
{
    "assets_id": "34558688e2f42a0137ca2d5274a8cf43",
    "upload_url": "https://faas-training-dataset.s3.ap-southeast-1.amazonaws.com/test/******",
    "method": "PUT",
    "headers": {
        "Host": {
            "values": [
                "faas-training-dataset.s3.ap-southeast-1.amazonaws.com"
            ]
        }
    }
}
```

* `assets_id`: The unique identifier of the image, which will be used in the training task.
* `upload_url`: The URL for image upload.
* `method`: The HTTP method for image upload.

#### 1.2 Upload images

After obtaining the `upload_url` at step `Get image upload URL`, please refer to the following document to complete the image upload: [https://docs.aws.amazon.com/zh\_cn/AmazonS3/latest/userguide/PresignedUrlUploadObject.html.](https://docs.aws.amazon.com/zh_cn/AmazonS3/latest/userguide/PresignedUrlUploadObject.html)

`Put images:`

```bash theme={"system"}
curl -X PUT -T "{{filepath}}" "{{upload_url}}"
```

`or`

```
curl --location --request PUT '{{upload_url}}' \
--header 'Content-Type: image/png' \
--data '{{filepath}}'
```

### 2. Start training task and configure parameters

In this step, we will begin the model training process, which is expected to take approximately 10 minutes, depending on the actual server's availability.

There are four types of parameters for model traning: `Model info parameters`, `dataset parameters`, `components parameters`,`expert parameters`, you can set them according to our tables below.

Here are some tips to train a good model:

* At least 10 photos of faces that meet the requirements.
* For parameters `instance_prompt`, we suggests using "a close photo of ohwx \<man|woman>"
* For parameters `base_model`, value `v1-5-pruned-emaonly` has better generalization ability and can be used in combination with various Base models, such as `dreamshaper 2.5D`, value `epic-realism` has a strong sense of reality.

| Type                  | Parameters                         | Description                                                                                                                                     |
| :-------------------- | :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
| Model info parameters | name                               | Name of your training model                                                                                                                     |
| Model info parameters | base\_model                        | base\_model type                                                                                                                                |
| Model info parameters | width                              | Target image width                                                                                                                              |
| Model info parameters | height                             | Target image height                                                                                                                             |
| dataset parameters    | image\_dataset\_items              | Array: consist of `imageUrl` and image `caption`                                                                                                |
| dataset parameters    | - image\_dataset\_items.assets\_id | images assets\_id, which can be found in step `Get image upload URL`                                                                            |
| components parameters | components                         | Array: consist of `name` and `args`, this is a common parameters configured for training.                                                       |
| components parameters | - components.name                  | Type of components, Enum: `face_crop_region`, `resize`, `face_restore`                                                                          |
| components parameters | - components.args                  | Detail values of components.name                                                                                                                |
| expert parameters     | expert\_setting                    | expert parameters.                                                                                                                              |
| expert parameters     | - instance\_prompt                 | Captions for all the training images, here is a guidance of how to make a effective prompt : [Click Here](/guides/model-apis-training-guidance) |
| expert parameters     | - batch\_size                      | batch size of training.                                                                                                                         |
| expert parameters     | - max\_train\_steps                | Max train steps, 500 is enought for lora model training.                                                                                        |
| expert parameters     | - ......                           | More expert parameters can be access at api reference.                                                                                          |

**Here is a example of how to start training:**

```bash theme={"system"}
curl --location --request POST 'https://api.novita.ai/v3/training/subject' \
--header 'Accept: <Accept>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{API Key}}' \
--data-raw '{
    "name": "test_subject_01",
    "base_model": "v1-5-pruned-emaonly",
    "width": 512,
    "height": 512,
    "image_dataset_items": [
        {
          "assets_id": "34558688e2f42a0137ca2d5274a8cf43"
        },
        {
          "assets_id": "1231231243f42a0137ca2d5274a8cf43"
        }
    ],
    "expert_setting": {
        "instance_prompt": "Xsubject, of a young woman, profile shot, from side,sitting, looking at viewer, smiling, head tilt, eyes open,long black hair, glowing skin,light smile,cinematic lighting,dark environment",
        "class_prompt": "person"
    },
    "components": [
        {
            "name": "face_crop_region",
            "args": [
                {
                    "name": "ratio",
                    "value": "1"
                }
            ]
        },
        {
          "name": "resize",
          "args": [
              {"name": "width", "value": "512"},
              {"name": "height", "value": "512"}
          ]
        },
        {
          "name": "face_restore",
            "args": [
                {"name": "method", "value": "gfpgan_1.4"},
                {"name": "upscale", "value": "1.0"}
            ]
        }
    ]
}'
```

Response:

```js theme={"system"}
{
    "task_id": "d660cdd0-ab9b-4a55-8b78-4bc851051fb0"
}
```

The `task_id` is the unique identifier of the training task, which can be used to query the training status and results.

### 3. Get training status

#### 3.1 Get model training and deployment status

In this step, we will obtain the progress of model training and the status of model deployment after training

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/training/subject?task_id=d660cdd0-ab9b-4a55-8b78-4bc851051fb0' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "task_id": "d660cdd0-ab9b-4a55-8b78-4bc851051fb0",
    "task_status": "SUCCESS",
    "model_type": "",
    "models": [
        {
          "model_name": "model_1698904832_F2BB461625.safetensors",
            "model_status": "DEPLOYING"
        }
    ]
}
```

* `task_status`: The status of the training task, Enum: `UNKNOWN`, `QUEUING`, `TRAINING`, `SUCCESS`, `CANCELED`, `FAILED`.
* `model_status`: The status of the model, Enum: `DEPLOYING`, `SERVING`.
* `model_name`: The name of the model, which can be used to generate images in next step.

When the `task_status` is `SUCCESS`, the `model_status` is `SERVING` we can starting to use the lora model.

#### 3.2 Start using the trained model

After model deployed successfully, we can download the model files or generate images directly.

##### 3.2.1 Use the generated models to create images

In order to use the trained lora models, We need to add `model_name` into the `request` of endpoint `/v3/async/txt2img` or `/v3/async/img2img`. **Currently trained lora model can not be used in /v3 endpoint.**

Below is a example of how to generate images with trained model:

Please set the **`Content-Type`** header to **`application/json`** in your HTTP request to indicate that you are sending JSON data. Currently, **only JSON format is supported**.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/txt2img' \
--header 'Authorization: Bearer {{API Key}};' \
--header 'Content-Type;' \
--data '{
  "extra": {
    "response_image_type": "jpeg"
  },
  "request": {
    "model_name": "realisticVisionV51_v51VAE_94301.safetensors",
    "prompt": "a young woman",
    "negative_prompt": "bottle, bad face",
    "sd_vae": "",
    "loras": [
      {
        "model_name": "model_1698904832_F2BB461625.safetensors",
        "strength": 0.7
      }
    ],
    "embeddings": [
      {
        "model_name": ""
      }
    ],
    "hires_fix": {
      "target_width": 1024,
      "target_height": 768,
      "strength": 0.5
    },
    "refiner": {
      "switch_at": null
    },
    "width": 512,
    "height": 384,
    "image_num": 2,
    "steps": 20,
    "seed": 123,
    "clip_skip": 1,
    "guidance_scale": 7.5,
    "sampler_name": "Euler a"
  }
}'
```

`Response:`

```js theme={"system"}
{
    "code": 0,
    "msg": "",
    "data": {
        "task_id": "bec2bcfe-47c6-4536-af34-f26cfe6fd457"
    }
}
```

**Use `task_id` to get images**

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get images url in `imgs` of response.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/task-result?task_id=bec2bcfe-47c6-4536-af34-f26cfe6fd457' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
  "task": {
    "task_id": "bec2bcfe-47c6-4536-af34-f26cfe6fd457",
    "status": "TASK_STATUS_SUCCEED",
    "reason": ""
  },
  "images": [
    {
      "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/dev/replace_object_a910c8f7-76ce-40bd-b805-f00f3ddd7dc1_0.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20231019%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20231019T084537Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=b9ad40a5cb3aecf89602c15fe72d28be5d8a33e0bfe3656ce968295fde1aab31",
      "image_url_ttl": 3600,
      "image_type": "png"
    }
  ],
  "videos": [
    {
      "video_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/dev/replace_object_a910c8f7-76ce-40bd-b805-f00f3ddd7dc1_0.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20231019%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20231019T084537Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=b9ad40a5cb3aecf89602c15fe72d28be5d8a33e0bfe3656ce968295fde1aab31",
      "video_url_ttl": "3600",
      "video_type": "png"
    }
  ]
}
```

#### 3.3 List training tasks

In this step, we can obtain all the info of trained models.

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/training?pagination.limit=10&pagination.cursor=c_0' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "tasks": [
        {
          "task_name": "test_01",
            "task_id": "a0c4cc90-0296-4972-a1d8-e6e227daf094",
            "task_type": "subject",
            "task_status": "SUCCESS",
            "created_at": 1699325415,
            "models": [
                {
                    "model_name": "model_1699325939_E83A88DAC5.safetensors",
                    "model_status": "SERVING"
                }
            ]
        },
        {
          "task_name": "test_02",
          "task_id": "51e9bf41-8f7a-464d-b5ad-2fa217a1ec93",
          "task_type": "subject",
          "task_status": "SUCCESS",
          "created_at": 1699267268,
          "models": [
              {
                  "model_name": "model_1699267603_27F0D9C81C.safetensors",
                  "model_status": "SERVING"
              }
          ]
        },
        {
          "task_name": "test_03",
            "task_id": "7bd205ab-63e9-452b-9a66-39c597000eaa",
            "task_type": "subject",
            "task_status": "FAILED",
            "created_at": 1699264338,
            "models": []
        }
    ],
    "pagination": {
        "next_cursor": "c_10"
    }
}
```

* `task_name` : The name of the training task.
* `task_id` : The unique identifier of the training task, which can be used to query the training status and results.
* `task_type` : The type of the training task.
* `task_status`: The status of the training task, Enum: `UNKNOWN`, `QUEUING`, `TRAINING`, `SUCCESS`, `CANCELED`, `FAILED`.
* `created_at`: The time when the training task was created.
* `model`: The trained model.
* `model_name`: The sd name of the model.
* `model_status`: The status of the model, Enum: `DEPLOYING`, `SERVING`.

### 4. Training playground

You can also use our training playground to train models in a user-friendly way at: [Click Here](https://huggingface.co/spaces/novita-ai/Face-Stylization-Playground)

#### 4.1 Input Novita AI API Key, images and select training type

<Frame>
  <img />
</Frame>

#### 4.2 Switch to the inferencing tab and add more detail

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

#### Review the training results

<Frame>
  <img />
</Frame>


# Fish Audio Text to Speech
Source: https://novita.ai/docs/api-reference/model-apis-fish-audio-text-to-speech

POST https://api.novita.ai/v4beta/txt2speech

<Note>
  For best results, upload reference audio using the [create model](/api-reference/model-apis-fish-audio-voice-cloning) before using this one. This improves speech quality and reduces latency.
</Note>

Fish Audio converts text into speech.

Audio formats supported:

* WAV / PCM
  * Sample Rate: 8kHz, 16kHz, 24kHz, 32kHz, 44.1kHz
  * Default Sample Rate: 44.1kHz
  * 16-bit, mono

* MP3
  * Sample Rate: 32kHz, 44.1kHz
  * Default Sample Rate: 44.1kHz
  * mono
  * Bitrate: 64kbps, 128kbps (default), 192kbps

* Opus
  * Sample Rate: 48kHz
  * Default Sample Rate: 48kHz
  * mono
  * Bitrate: -1000 (auto), 24kbps, 32kbps (default), 48kbps, 64kbps

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

<ParamField type="enum<string>">
  Specify which TTS model to use. Only supports model: `s1`.
</ParamField>

## Request Body

<ParamField type="string">
  Text to be converted to speech.
</ParamField>

<ParamField type="number">
  Controls randomness in the speech generation. Higher values (e.g., 1.0) make the output more random, while lower values (e.g., 0.1) make it more deterministic. We recommend `0.9` for `s1` model.

  Required range: `0 <= x <= 1`
</ParamField>

<ParamField type="number">
  Controls diversity via nucleus sampling. Lower values (e.g., 0.1) make the output more focused, while higher values (e.g., 1.0) allow more diversity. We recommend `0.9` for `s1` model.

  Required range: `0 <= x <= 1`
</ParamField>

<ParamField type="ReferenceAudio · object[] | null">
  References to be used for the speech, this requires MessagePack serialization, this will override reference\_voices and reference\_texts.

  <Expandable title="properties">
    <ParamField type="file">
      Reference audio file.
    </ParamField>

    <ParamField type="string">
      Reference text corresponding to the audio.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string | null">
  ID of the reference model to be used for the speech.
</ParamField>

<ParamField type="ProsodyControl · object">
  Prosody to be used for the speech.

  <Expandable title="properties">
    <ParamField type="number">
      Speech speed control.
    </ParamField>

    <ParamField type="number">
      Speech volume control.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="integer">
  Chunk length to be used for the speech.

  Required range: `100 <= x <= 300`
</ParamField>

<ParamField type="boolean">
  Whether to normalize the speech, this will reduce the latency but may reduce performance on numbers and dates.
</ParamField>

<ParamField type="enum<string>">
  Format to be used for the speech.

  Available options: `wav`, `pcm`, `mp3`, `opus`
</ParamField>

<ParamField type="integer | null">
  Sample rate to be used for the speech.
</ParamField>

<ParamField type="enum<integer>">
  MP3 Bitrate to be used for the speech.

  Available options: `64`, `128`, `192`
</ParamField>

<ParamField type="enum<integer>">
  Opus Bitrate to be used for the speech.

  Available options: `-1000`, `24`, `32`, `48`, `64`
</ParamField>

<ParamField type="enum<string>">
  Latency to be used for the speech, balanced will reduce the latency but may lead to performance degradation.

  Available options: `normal`, `balanced`
</ParamField>

## Response

The API will directly return the audio stream in the format specified by the `format` parameter (default: mp3).


# Fish Audio Voice Cloning
Source: https://novita.ai/docs/api-reference/model-apis-fish-audio-voice-cloning

POST https://api.novita.ai/v4beta/model

Fish Audio API for creating a voice model (voice cloning).

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="enum<string>">
  Model type, tts is for text to speech.

  Available options: `tts`

  Allowed value: `"tts"`
</ParamField>

<ParamField type="string">
  Model title or name.
</ParamField>

<ParamField type="enum<string>">
  Model train mode, for TTS model, fast means model instantly available after creation.

  Available options: `fast`

  Allowed value: `"fast"`
</ParamField>

<ParamField type="file[]">
  Upload voices files that will be used to tune the model.
</ParamField>

<ParamField type="enum<string>">
  Model visibility, public will be shown in the discovery page, unlist allows anyone with the link to access, private only be visible to the creator.

  Available options: `public`, `unlist`, `private`
</ParamField>

<ParamField type="string | null">
  Model description.
</ParamField>

<ParamField type="file | null">
  Model cover image, this is required if the model is public.
</ParamField>

<ParamField type="string[]">
  Texts corresponding to the voices, if unspecified, ASR will be performed on the voices.
</ParamField>

<ParamField type="string[]">
  Model tags.
</ParamField>

<ParamField type="boolean">
  Enhance audio quality.
</ParamField>

## Response

<ResponseField name="_id" type="string">
  Unique identifier for the created model.
</ResponseField>

<ResponseField name="type" type="enum<string>">
  Model type.

  Available options: `svc`, `tts`
</ResponseField>

<ResponseField name="title" type="string">
  Model title or name.
</ResponseField>

<ResponseField name="description" type="string">
  Model description.
</ResponseField>

<ResponseField name="cover_image" type="string">
  URL of the model cover image.
</ResponseField>

<ResponseField name="state" type="enum<string>">
  Current state of the model.

  Available options: `created`, `training`, `trained`, `failed`
</ResponseField>

<ResponseField name="tags" type="string[]">
  Model tags.
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  Timestamp when the model was created.
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  Timestamp when the model was last updated.
</ResponseField>

<ResponseField name="visibility" type="enum<string>">
  Model visibility setting.

  Available options: `public`, `unlist`, `private`
</ResponseField>

<ResponseField name="like_count" type="integer">
  Number of likes the model has received.
</ResponseField>

<ResponseField name="mark_count" type="integer">
  Number of marks/bookmarks the model has received.
</ResponseField>

<ResponseField name="shared_count" type="integer">
  Number of times the model has been shared.
</ResponseField>

<ResponseField name="task_count" type="integer">
  Number of tasks associated with the model.
</ResponseField>

<ResponseField name="author" type="AuthorEntity · object">
  Information about the model author.

  <Expandable title="properties">
    <ResponseField name="_id" type="string">
      Author's unique identifier.
    </ResponseField>

    <ResponseField name="nickname" type="string">
      Author's nickname.
    </ResponseField>

    <ResponseField name="avatar" type="string">
      URL of the author's avatar image.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="train_mode" type="enum<string>">
  Training mode used for the model.

  Available options: `fast`, `full`
</ResponseField>

<ResponseField name="samples" type="SampleEntity · object[]">
  Sample data associated with the model.

  <Expandable title="properties">
    <ResponseField name="title" type="string">
      Sample title.
    </ResponseField>

    <ResponseField name="text" type="string">
      Text content of the sample.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Task identifier for the sample.
    </ResponseField>

    <ResponseField name="audio" type="string">
      URL of the sample audio file.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="languages" type="string[]">
  Languages supported by the model.
</ResponseField>

<ResponseField name="lock_visibility" type="boolean">
  Whether the visibility setting is locked.
</ResponseField>

<ResponseField name="unliked" type="boolean">
  Whether the current user has unliked the model.
</ResponseField>

<ResponseField name="liked" type="boolean">
  Whether the current user has liked the model.
</ResponseField>

<ResponseField name="marked" type="boolean">
  Whether the current user has marked/bookmarked the model.
</ResponseField>


# FLUX.1 Kontext Dev
Source: https://novita.ai/docs/api-reference/model-apis-flux-1-kontext-dev

POST https://api.novita.ai/v3/async/flux-1-kontext-dev

FLUX.1 Kontext dev is a model with greatly improved prompt adherence and typography generation meet premium consistency for editing without compromise on speed.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The prompt to generate an image from.
</ParamField>

<ParamField type="string[]">
  The images to generate an image from. Limit to a maximum of 4 images.
</ParamField>

<ParamField type="boolean">
  Whether to enable fast mode, which will generate videos more quickly but may reduce quality and lower the price.

  Default: `false`.
</ParamField>

<ParamField type="string">
  The size of the generated media in pixels (width\*height). Range \[256 \~ 1536 per dimension].
</ParamField>

<ParamField type="integer">
  The number of inference steps to perform. Default is 28. Range \[1 \~ 50].
</ParamField>

<ParamField type="number">
  The guidance scale to use for the generation. Default is 2.5. Range \[1.0 \~ 20.0].
</ParamField>

<ParamField type="integer">
  The number of images to generate. Default is 1. Range \[1 \~ 4].
</ParamField>

<ParamField type="integer">
  The random seed to use for the generation. Default is -1. -1 means a random seed will be used. Range \[-1 \~ 2147483647].
</ParamField>

<ParamField type="string">
  The format of the output image. Default is jpeg.<br />
  Enum: `jpeg`, `png`, `webp`
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# FLUX.1 Kontext Max
Source: https://novita.ai/docs/api-reference/model-apis-flux-1-kontext-max

POST https://api.novita.ai/v3/async/flux-1-kontext-max

FLUX.1 Kontext \[max] is a model with greatly improved prompt adherence and typography generation meet premium consistency for editing without compromise on speed.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The prompt to generate an image from.
</ParamField>

<ParamField type="string[]">
  The images to generate an image from. Limit to a maximum of 4 images.
</ParamField>

<ParamField type="integer">
  The random seed to use for the generation. Range \[-1 \~ 2147483647].
</ParamField>

<ParamField type="number">
  The guidance scale to use for the generation. Default is 3.5. Range \[1.0 \~ 20.0].
</ParamField>

<ParamField type="string">
  The safety tolerance level for the generated image. 1 being the most strict and 5 being the most permissive. Default is 2.<br />
  Enum: `1`, `2`, `3`, `4`, `5`
</ParamField>

<ParamField type="string">
  The aspect ratio of the generated image.<br />
  Enum: `21:9`, `16:9`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `9:16`, `9:21`
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# FLUX.1 Kontext Pro
Source: https://novita.ai/docs/api-reference/model-apis-flux-1-kontext-pro

POST https://api.novita.ai/v3/async/flux-1-kontext-pro

FLUX.1 Kontext \[pro] is a model with greatly improved prompt adherence and typography generation meet premium consistency for editing without compromise on speed.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The prompt to generate an image from.
</ParamField>

<ParamField type="string[]">
  The images to generate an image from. Limit to a maximum of 4 images.
</ParamField>

<ParamField type="number">
  The guidance scale to use for the generation. Default is 3.5. Range \[1.0 \~ 20.0].
</ParamField>

<ParamField type="string">
  The aspect ratio of the generated image.<br />
  Enum: `21:9`, `16:9`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `9:16`, `9:21`
</ParamField>

<ParamField type="integer">
  The random seed to use for the generation. Default is -1. -1 means a random seed will be used. Range \[-1 \~ 2147483647].
</ParamField>

<ParamField type="string">
  Only supported in text-to-image. <br />
  The safety tolerance level for the generated image. 1 being the most strict and 5 being the most permissive. Default is 2.<br />
  Enum: `1`, `2`, `3`, `4`, `5`
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# FLUX.1 [schnell] Text to Image
Source: https://novita.ai/docs/api-reference/model-apis-flux-1-schnell

POST https://api.novita.ai/v3beta/flux-1-schnell

**Generate images from text prompts using FLUX.1 \[schnell].**

> **Pricing:** \$0.003 \* (Width \* Height \* Steps) / (1024\*1024\*4)

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The returned image type. Default is png.<br />
  Enum: `png` `webp` `jpeg`
</ParamField>

<ParamField type="string">
  Text input required to guide the image generation, divided by `,` . Range \[1, 1024].
</ParamField>

<ParamField type="integer">
  A seed is a number from which Stable Diffusion generates noise, which, makes generation deterministic. Using the same seed and set of parameters will produce identical image each time. Range \[0, 4294967295].
</ParamField>

<ParamField type="integer">
  The number of denoising steps. More steps usually can produce higher quality images, but take more time to generate, Range \[1, 100].
</ParamField>

<ParamField type="integer">
  Width of image. Range \[64, 2048].
</ParamField>

<ParamField type="integer">
  Height of image. Range \[64, 2048].
</ParamField>

<ParamField type="integer">
  Images numbers generated in one single generation. Range \[1, 8].
</ParamField>

## Response

<ResponseField name="task" type="object">
  Task information.

  <Expandable title="properties">
    <ResponseField name="task_id" type="string">
      Task ID.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="images" type="object[]">
  Contains information about images associated with image-type tasks. This parameter provides detailed data on each image processed or generated during the task, such as file paths, metadata, or any image-specific attributes. It is returned only for tasks that involve image operations, facilitating enhanced tracking and management of image data.

  <Expandable title="properties">
    <ResponseField name="image_url" type="string">
      Image URL.
    </ResponseField>

    <ResponseField name="image_url_ttl" type="integer">
      Image expiration time in seconds.
    </ResponseField>

    <ResponseField name="image_type" type="string">
      Image type.<br />
      Enum: `jpeg`, `png`, `webp`
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

request

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3beta/flux-1-schnell' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
  "prompt": "Extreme close-up of a single tiger eye, direct frontal view. Detailed iris and pupil. Sharp focus on eye texture and color. Natural lighting to capture authentic eye shine and depth. The word \"Novita AI\" is painted over it in big, white brush strokes with visible texture",
  "width": 512,
  "height": 512,
  "seed": 2024,
  "steps": 4,
  "image_num": 1
}'
```

response

```json theme={"system"}
{
  "images": [
    {
      "image_url": "https://model-api-output.5e61b0cbce9f453eb9db49fdd85c7cac.r2.cloudflarestorage.com/xxx",
      "image_url_ttl": 604800,
      "image_type": "png"
    }
  ],
  "task": {
    "task_id": "xxx"
  }
}
```


# Flux 2 Dev Image Gen
Source: https://novita.ai/docs/api-reference/model-apis-flux-2-dev

POST https://api.novita.ai/v3/async/flux-2-dev

FLUX.2 \[dev] from Black Forest Labs delivers fast, studio-quality text-to-image generation with enhanced realism, crisper text rendering, and native editing for rapid iteration. Ready-to-use REST inference API, best performance, no cold starts, affordable pricing.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="integer">
  Random seed for generation. -1 means use a random seed. Range: -1 to 2147483647

  Value range: \[-1, 2147483647]
</ParamField>

<ParamField type="string">
  Pixel size (width\*height) of the output media. Each dimension ranges from 256 to 1536 pixels
</ParamField>

<ParamField type="array">
  List of LoRAs to apply, up to 3 are supported

  Array length: 0 - 3
</ParamField>

<ParamField type="array">
  A list of input image URLs for editing. Up to 3 images are supported

  Array length: 1 - 3
</ParamField>

<ParamField type="string">
  A text prompt describing the expected editing effect for the image
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Flux 2 Flex Image Gen
Source: https://novita.ai/docs/api-reference/model-apis-flux-2-flex

POST https://api.novita.ai/v3/async/flux-2-flex

FLUX.2 \[flex] from Black Forest Labs delivers fast, flexible text-to-image generation with enhanced realism, sharper text rendering, and built-in editing for rapid iteration: a ready-to-use REST inference API, best performance, no cold starts, and affordable pricing.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="integer">
  Random seed for generation. -1 means use a random seed. Range: -1 to 2147483647

  Value range: \[-1, 2147483647]
</ParamField>

<ParamField type="string">
  Pixel size (width\*height) of the output media. Each dimension ranges from 256 to 1536 pixels
</ParamField>

<ParamField type="array">
  A list of input image URLs for editing. Up to 3 images are supported

  Array length: 1 - 3
</ParamField>

<ParamField type="string">
  A text prompt describing the expected editing effect for the image
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Flux 2 Pro Image Gen
Source: https://novita.ai/docs/api-reference/model-apis-flux-2-pro

POST https://api.novita.ai/v3/async/flux-2-pro

FLUX.2 \[pro] from Black Forest Labs delivers production-grade text-to-image generation with enhanced realism, sharper text rendering, and native editing for reliable, repeatable results. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="integer">
  Random seed for generation. -1 means use a random seed. Range: -1 to 2147483647

  Value range: \[-1, 2147483647]
</ParamField>

<ParamField type="string">
  Pixel size (width\*height) of the output media. Each dimension ranges from 256 to 1536 pixels
</ParamField>

<ParamField type="array">
  A list of input image URLs for editing. Up to 3 images are supported

  Array length: 1 - 3
</ParamField>

<ParamField type="string">
  A text prompt describing the expected editing effect for the image
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Get Model
Source: https://novita.ai/docs/api-reference/model-apis-get-model

GET https://api.novita.ai/v3/model

**This API endpoint is designed to retrieve information on both public and private models. It allows users to access details such as model specifications, status, and usage guidelines, ensuring comprehensive insights into the available modeling resources.**

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<ParamField type="string">
  Model types: `public` or `private`. If not set, the interface will query all types of models.
</ParamField>

<ParamField type="string">
  Source of the model.<br />
  Enum: `civitai`, `training`, `uploading`
</ParamField>

<ParamField type="string">
  Specifies the types of models to include in the query.<br />
  Enum: `checkpoint`, `lora`, `vae`, `controlnet`, `upscaler`, `textualinversion`
</ParamField>

<ParamField type="boolean">
  Whether the model is SDXL or not. Setting this parameter to `true` includes only SDXL models in the query results, which are typically large-scale, high-performance models designed for extensive data processing tasks. Conversely, setting it to `false` excludes these models from the results. If left unspecified, the filter will not discriminate based on the SDXL classification, including all model types in the search results.
</ParamField>

<ParamField type="string">
  Searches the content of sd\_name, name, and tags.
</ParamField>

<ParamField type="boolean">
  If set to true, it will filter out the checkpoints used for inpainting. The default is false.
</ParamField>

<ParamField type="string">
  Number of models to query per request, range (0, 100].
</ParamField>

<ParamField type="string">
  pagination.cursor is used to specify which record to start returning from. If it is empty, it means to get it from the beginning. Generally, the content of the next page is obtained by passing in the next\_cursor field value from the response packet.
</ParamField>

## Response

<ResponseField name="models" type="object[]">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">
      ID of the model.
    </ResponseField>

    <ResponseField name="name" type="string">
      Model name.
    </ResponseField>

    <ResponseField name="hash_sha256" type="string">
      Hash of the model file.
    </ResponseField>

    <ResponseField name="sd_name" type="string">
      Model file name.
    </ResponseField>

    <ResponseField name="type" type="object">
      <Expandable title="properties">
        <ResponseField name="name" type="string">
          Model type name.
        </ResponseField>

        <ResponseField name="display_name" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="categories" type="string[]">
      Model categories.
    </ResponseField>

    <ResponseField name="status" type="integer">
      Model status: 0 for unavailable, 1 for available.
    </ResponseField>

    <ResponseField name="download_url" type="string">
      Model download URL.
    </ResponseField>

    <ResponseField name="tags" type="string[]">
      Model tags, such as photorealistic, anatomical, base model, CGI, realistic, semi-realistic.
    </ResponseField>

    <ResponseField name="cover_url" type="string">
      Model cover image URL.
    </ResponseField>

    <ResponseField name="source" type="string">
      The source of the model, such as civitai, training, uploading.
    </ResponseField>

    <ResponseField name="base_model" type="string">
      Base model of the model, such as SD 1.5 or SDXL 1.0.
    </ResponseField>

    <ResponseField name="base_model_type" type="string">
      Base model type of the model, such as Inpainting or Standard.
    </ResponseField>

    <ResponseField name="download_url_ttl" type="integer">
      The expiration time of the download URL in seconds, default is 1 day.
    </ResponseField>

    <ResponseField name="sd_name_in_api" type="string">
      The name users can add in the interface.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="properties">
    <ResponseField name="next_cursor" type="string">
      Next request starting cursor.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

request

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/model?filter.visibility=public&pagination.limit=2&pagination.cursor=c_0' \
--header 'Authorization: Bearer {{API Key}}'
```

response

```json theme={"system"}
{
  "models": [
    {
      "id": 114600,
      "name": "V4.0-inpainting (VAE)",
      "hash_sha256": "1A805277C8",
      "sd_name": "realisticVisionV40_v40VAE-inpainting_81543.safetensors",
      "type": {
        "name": "checkpoint",
        "display_name": "Checkpoint"
      },
      "categories": [],
      "status": 1,
      "tags": [
        "photorealistic",
        "anatomical",
        "base model",
        "cgi",
        "realistic",
        "semi-realistic"
      ],
      "cover_url": "https://next-app-static.s3.amazonaws.com/images-prod/xG1nkqKTMzGDvpLrqFT7WA/f291a219-4a86-45ab-96eb-c53446b3e4df/width=450/1495044.jpeg",
      "base_model": "SD 1.5",
      "base_model_type": "Inpainting",
      "download_url_ttl": 2592000,
      "sd_name_in_api": "realisticVisionV40_v40VAE-inpainting_81543.safetensors",
      "is_sdxl": false
    },
    {
      "id": 55199,
      "name": "beta2",
      "hash_sha256": "BA43B0EFEE",
      "sd_name": "GoodHands-beta2_39807.safetensors",
      "type": {
        "name": "locon",
        "display_name": "locon"
      },
      "categories": [],
      "status": 1,
      "tags": ["photorealistic", "concept", "hands"],
      "cover_url": "https://next-app-static.s3.amazonaws.com/images-prod/xG1nkqKTMzGDvpLrqFT7WA/031a378c-3d66-45da-5d67-966c47cd4800/width=450/599083.jpeg",
      "base_model": "SD 1.5",
      "base_model_type": "Standard",
      "download_url_ttl": 2592000,
      "sd_name_in_api": "GoodHands-beta2_39807",
      "is_sdxl": false
    }
  ],
  "pagination": {
    "next_cursor": "c_WzgwNDY2NiwiNTUxOTkiXQ=="
  }
}
```


# Get Images URL
Source: https://novita.ai/docs/api-reference/model-apis-get-training-images-url

POST https://api.novita.ai/v3/assets/training_dataset

**This API provides an S3 pre-signed uploading URL for training images.**

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Enum: `png`, `webp`, `jpeg`
</ParamField>

## Response

<ResponseField name="assets_id" type="integer">
  The asset ID.
</ResponseField>

<ResponseField name="upload_url" type="string">
  The S3 pre-signed uploading URL.
</ResponseField>

<ResponseField name="method" type="string">
  The method for uploading.<br />
  Enum: `PUT`
</ResponseField>

<ResponseField name="headers" type="object">
  <Expandable title="properties">
    <ResponseField name="Host" type="object">
      <Expandable title="properties">
        <ResponseField name="values" type="string[]">
          The host value.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

request

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/assets/training_dataset' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
  "file_extension": "png"
}'
```

response

```json theme={"system"}
{
  "assets_id": 100024,
  "upload_url": "https://faas-training-dataset.s3.ap-southeast-1.amazonaws.com/test/743567e210ff505ce5502cfb46659c8e.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20231102%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20231102T060519Z&X-Amz-Expires=120&X-Amz-SignedHeaders=host&x-id=PutObject&X-Amz-Signature=781d2156b707b7cfa87d94fb2836838e114c3afe4588368b9503c618ac125a67",
  "method": "PUT",
  "headers": {
    "Host": {
      "values": ["faas-training-dataset.s3.ap-southeast-1.amazonaws.com"]
    }
  }
}
```


# GLM Audio to Text
Source: https://novita.ai/docs/api-reference/model-apis-glm-asr

POST https://api.novita.ai/v3/glm-asr

Use the GLM-ASR-2512 model to transcribe audio files into text, supporting multi-language transcription.

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The audio file URL or Base64 encoded string to be transcribed. Supported audio formats: .wav / .mp3. Limitations: file size ≤ 25 MB, audio duration ≤ 30 seconds
</ParamField>

<ParamField type="string">
  For long text scenarios, you can provide previous transcription results as context. Recommended to be less than 8000 characters.
</ParamField>

<ParamField type="array">
  Hotword list to improve recognition accuracy for domain-specific vocabulary. Format example: \["person name", "place name"]. Recommended not to exceed 100 items.

  Array length: 0 - 100
</ParamField>

## Response

<ResponseField name="text" type="string">
  The complete transcribed content of the audio
</ResponseField>


# GLM Text to Speech
Source: https://novita.ai/docs/api-reference/model-apis-glm-tts

POST https://api.novita.ai/v3/glm-tts

Convert text to natural speech using GLM-TTS, supporting multiple voices, emotion control, and tone adjustment.

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The text to convert to speech

  Length limit: 0 - 1024
</ParamField>

<ParamField type="number">
  Speech speed, default is 1.0, range \[0.5, 2]

  Value range: \[0.5, 2]
</ParamField>

<ParamField type="string">
  The voice to use for audio generation, supporting both system voices and cloned voices. System voices include: tongtong (Tongtong, default voice), chuichui (Chuichui), xiaochen (Xiaochen), jam (Dongdong Zoo jam voice), kazi (Dongdong Zoo kazi voice), douji (Dongdong Zoo douji voice), luodo (Dongdong Zoo luodo voice)
</ParamField>

<ParamField type="number">
  Volume, default is 1.0, range (0, 10]

  Value range: \[0, 10]
</ParamField>

<ParamField type="string">
  Audio output format, defaults to pcm format

  Optional values: `wav`, `pcm`
</ParamField>

<ParamField type="boolean">
  Controls whether to add watermark when generating AI audio. true: Enables explicit watermark and implicit digital watermark for AI-generated content by default, complying with policy requirements. false: Disables all watermarks, only effective for users who have completed watermark removal action.
</ParamField>

## Response

Request processed successfully, recommended sample rate is 24000

Format: `binary`


# GLM Voice Clone
Source: https://novita.ai/docs/api-reference/model-apis-glm-tts-voice-clone

POST https://api.novita.ai/v3/glm-tts-voice-clone

Using voice cloning technology to generate speech synthesis with specified voice timbre and text content based on sample audio.

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Text content of the sample audio, optional
</ParamField>

<ParamField type="string">
  Target text content for generating preview audio
</ParamField>

<ParamField type="string">
  URL of the sample audio. Size limit is 10MB, recommended audio duration is between 3 to 30 seconds.
</ParamField>

<ParamField type="string">
  Specify a unique voice name
</ParamField>

## Response

<ResponseField name="voice" type="string">
  Voice timbre
</ResponseField>

<ResponseField name="audio_url" type="string">
  URL of the generated preview audio file
</ResponseField>


# Hunyuan Image 3
Source: https://novita.ai/docs/api-reference/model-apis-hunyuan-image-3

POST https://api.novita.ai/v3/async/hunyuan-image-3

Hunyuan Image 3.0 is a state-of-the-art text-to-image generation model. By simply providing a written prompt, you can create high-quality images that capture the essence of your story, resonate emotionally, and elevate your creative output.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The positive prompt for the generation.
</ParamField>

<ParamField type="string">
  The size of the generated media in pixels (width\*height). Range \[256 \~ 1536 per dimension]. Default is `1024*1024`.
</ParamField>

<ParamField type="integer">
  The random seed to use for the generation. -1 means a random seed will be used. Range \[-1 \~ 2147483647]. Default is `-1`.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Hunyuan Video Fast
Source: https://novita.ai/docs/api-reference/model-apis-hunyuan-video-fast

POST https://api.novita.ai/v3/async/hunyuan-video-fast

Accelerated inference for HunyuanVideo with high resolution, a state-of-the-art text-to-video generation model capable of creating high-quality videos with realistic motion from text descriptions.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Name of the model checkpoint.

  Supports: `hunyuan-video-fast`.
</ParamField>

<ParamField type="integer">
  Width of the output video.

  Supports: `720`, `1280`.
</ParamField>

<ParamField type="integer">
  Height of the output video.

  Supports:

  * `720` for `width` of `1280`
  * `1280` for `width` of `720`
</ParamField>

<ParamField type="integer">
  A seed is a number generates noise, which, makes generation deterministic. Using the same seed and set of parameters will produce identical content each time.

  Range: `-1 <= x <= 9999999999`.
</ParamField>

<ParamField type="integer">
  The number of denoising steps. More steps usually produce higher quality content but take more time to generate.

  Range: `2 <= x <= 30`.
</ParamField>

<ParamField type="string">
  Prompt text required to guide the generation.

  Range: `1 <= x <= 2000`.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>

## Example

Here is an example of how to use the Hunyuan Video Fast API.

1. Generate a task\_id by sending a POST request to the Hunyuan Video Fast API.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/hunyuan-video-fast' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "model_name": "hunyuan-video-fast",
    "height": 720,
    "width": 1280,
    "seed": -1,
    "steps": 30,
    "prompt": "A close up view of a glass sphere that has a zen garden within it. There is a small dwarf in the sphere who is raking the zen garden and creating patterns in the sand.",
    "frames": 85
}'
```

`Response:`

```js theme={"system"}
{
    "task_id": "{Returned Task ID}"
}
```

2. Use `task_id` to get output videos.

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get videos url in `videos` of response.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id={Returned Task ID}' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "task": {
        "task_id": "{Returned Task ID}",
        "task_type": "HUNYUAN_VIDEO_FAST",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 100
    },
    "images": [],
    "videos": [
        {
            "video_url": "{The URL of the generated video}",
            "video_url_ttl": "3600",
            "video_type": "mp4"
        }
    ]
}
```

`Video files:`

<video />


# Image Eraser
Source: https://novita.ai/docs/api-reference/model-apis-image-eraser

POST https://api.novita.ai/v3/async/image-eraser

AI-powered image erasing service. Supports object removal from images via mask and text prompts. Offers high-quality image processing: out-of-the-box REST inference API, top performance, no cold start, affordable pricing.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Mask image indicating the area to be erased. Areas to erase should be white; areas to keep should be black.
</ParamField>

<ParamField type="string">
  The original image to be processed.
</ParamField>

<ParamField type="string">
  Text prompt specifying the object or region to remove from the image, e.g., 'dog' or 'hat'.
</ParamField>

<ParamField type="string">
  Output image format.

  Optional values: `jpeg`, `png`, `webp`
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Image Remove Background
Source: https://novita.ai/docs/api-reference/model-apis-image-remove-background

POST https://api.novita.ai/v3/async/image-remove-background

AI-powered image background removal service. Supports intelligent recognition and removal of image backgrounds, delivering high-quality image processing: out-of-the-box REST inference API, best performance, no cold starts, and affordable pricing.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  URL of the image whose background will be removed.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Image to Image
Source: https://novita.ai/docs/api-reference/model-apis-image-to-image

POST https://api.novita.ai/v3/async/img2img

**Generate images with Stable Diffusion Models from Image and Text Prompts.**

> This is an **asynchronous API**; only the **task\_id** is returned initially. Use this **task\_id** to query the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the results of the image generation.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Optional extra parameters for the request.

  <Expandable title="properties">
    <ParamField type="string">
      The returned image type. Default is png.<br />
      Enum: `png`, `webp`, `jpeg`
    </ParamField>

    <ParamField type="object">
      Webhook settings. More details can be found at [Webhook Documentation](/api-reference/model-apis-webhook).

      <Expandable title="properties">
        <ParamField type="string">
          The URL of the webhook endpoint. Novita AI will send the task generated outputs to your specified webhook endpoint.
        </ParamField>

        <ParamField type="object">
          By specifying Test Mode, a mock event will be sent to the webhook endpoint.

          <Expandable title="properties">
            <ParamField type="boolean">
              Set to true to enable Test Mode, or false to disable it. The default is false.
            </ParamField>

            <ParamField type="string">
              Control the data content of the mock event. When set to TASK\_STATUS\_SUCCEED, you'll receive a normal response; when set to TASK\_STATUS\_FAILED, you'll receive an error response.<br />
              Enum: `TASK_STATUS_SUCCEED`, `TASK_STATUS_FAILED`
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      Customer storage settings for saving the generated outputs. <br /> By default, the generated outputs will be saved to Novita AI Storage temporarily and privately.

      <Expandable title="properties">
        <ParamField type="object">
          AWS S3 Bucket settings.

          <Expandable title="properties">
            <ParamField type="string">
              AWS S3 regions, <a href="https://docs.aws.amazon.com/general/latest/gr/rande.html">more details</a>.
            </ParamField>

            <ParamField type="string">
              AWS S3 bucket name.
            </ParamField>

            <ParamField type="string">
              AWS S3 bucket path for saving generated outputs.
            </ParamField>

            <ParamField type="boolean">
              Set this option to True to save the generated outputs directly to the specified path without creating any additional directory hierarchy. <br /> If set to False, Novita AI will create an additional directory in the path to save the generated outputs. The default is False.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      Dedicated Endpoints settings, which only take effect for users who have already subscribed to the [Dedicated Endpoints Documentation](/guides/model-apis-dedicated-endpoints).

      <Expandable title="properties">
        <ParamField type="boolean">
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="boolean">
      When set to true, NSFW detection will be enabled, incurring an additional cost of \$0.0015 for each generated image.
    </ParamField>

    <ParamField type="integer">
      0: Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols.<br /> 1: Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols; Non-Explicit Nudity, Obstructed Intimate Parts, Kissing on the Lips.<br /> 2: Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols; Non-Explicit Nudity, Obstructed Intimate Parts, Kissing on the Lips; Female Swimwear or Underwear, Male Swimwear or Underwear.
      Enum: `0`, `1`, `2`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      This parameter specifies the name of the model checkpoint. Retrieve the corresponding sd\_name value by invoking the <a href="/api-reference/model-apis-get-model">Query Model</a> API with filter.types=checkpoint as the query parameter.
    </ParamField>

    <ParamField type="string">
      The base64 of original image, with a maximum resolution of 16 megapixels and a maximum file size of 10 Mb.
    </ParamField>

    <ParamField type="string">
      Text input required to guide the image generation, divided by `,` . Range \[1, 1024].
    </ParamField>

    <ParamField type="integer">
      Width of image. Range \[128, 2048].
    </ParamField>

    <ParamField type="integer">
      Height of image. Range \[128, 2048].
    </ParamField>

    <ParamField type="integer">
      Images numbers generated in one single generation. Range \[1, 8].
    </ParamField>

    <ParamField type="integer">
      The number of denoising steps. More steps usually can produce higher quality images, but take more time to generate, Range \[1, 100].
    </ParamField>

    <ParamField type="number">
      This setting says how close the Stable Diffusion will listen to your prompt, higer guidance forces the model to better follow the prompt, but result in lower quality output. Range \[1, 30].
    </ParamField>

    <ParamField type="string">
      This parameter determines the denoising algorithm employed during the sampling phase of Stable Diffusion. Each option represents a distinct method by which the model incrementally generates new images. These algorithms differ significantly in their processing speed, output quality, and the specific characteristics of the images they generate, allowing users to tailor the image generation process to meet precise requirements. Get reference at [A brief introduction to Sampler](/guides/model-apis-sampler).<br />
      Enum: `Euler a`, `Euler`, `LMS`, `Heun`, `DPM2`, `DPM2 a`, `DPM++ 2S a`, `DPM++ 2M`, `DPM++ SDE`, `DPM fast`, `DPM adaptive`, `LMS Karras`, `DPM2 Karras`, `DPM2 a Karras`, `DPM++ 2S a Karras`, `DPM++ 2M Karras`, `DPM++ SDE Karras`, `DDIM`, `PLMS`, `UniPC`
    </ParamField>

    <ParamField type="string">
      Text input that specifies what to exclude from the generated images, divided by `,` . Range \[1, 1024].
    </ParamField>

    <ParamField type="string">
      VAE (Variational Auto Encoder). sd\_vae can be accessed in the API /v3/models with query params type=vae, like sd\_name: customVAE.safetensors. Get reference at [A Brief Introduction to VAE](/guides/model-apis-vae).
    </ParamField>

    <ParamField type="object">
      The ControlNet configuration provides a greater degree of control over text-to-image generation by conditioning the model on additional inputs such as edge maps, depth maps, segmentation maps, and keypoints for pose detection.

      <Expandable title="properties">
        <ParamField type="object[]">
          <Expandable title="properties">
            <ParamField type="string">
              Preprocessor to use on the image passed to this unit before using it for conditioning. \*\*\*ControlNets for SD 1.5: control\_v11e\_sd15\_ip2p, control\_v11e\_sd15\_shuffle, control\_v11f1e\_sd15\_tile, control\_v11f1p\_sd15\_depth, control\_v11p\_sd15\_canny, control\_v11p\_sd15\_inpaint, control\_v11p\_sd15\_lineart, control\_v11p\_sd15\_mlsd, control\_v11p\_sd15\_normalbae, control\_v11p\_sd15\_openpose, control\_v11p\_sd15\_scribble, control\_v11p\_sd15\_seg, control\_v11p\_sd15\_softedge, control\_v11p\_sd15s2\_lineart\_anime, control\_v1p\_sd15\_brightness, control\_v1p\_sd15\_qrcode\_monster, control\_v1p\_sd15\_qrcode\_monster\_v2, \*\*\*ControlNets for SDXL: controlnet-canny-sdxl-1.0, controlnet-depth-sdxl-1.0, controlnet-openpose-sdxl-1.0, controlnet-softedge-sdxl-1.0
            </ParamField>

            <ParamField type="string">
              base64 of input controlNet image
            </ParamField>

            <ParamField type="number">
              The strength of this unit, defaults to 1. Range \[0, 1]; the larger the value, the more biased the effect is towards ControlNet.
            </ParamField>

            <ParamField type="string">
              Preprocessor to use on the image passed to this unit before using it for conditioning.<br />
              Enum: `scribble_hed`, `softedge_hed`, `scribble_hedsafe`, `softedge_hedsafe`, `depth_midas`, `mlsd`, `openpose`, `openpose_face`, `openpose_faceonly`, `openpose_full`, `openpose_hand`, `dwpose`, `scribble_pidinet`, `softedge_pidinet`, `scribble_pidsafe`, `softedge_pidsafe`, `normal_bae`, `lineart_coarse`, `lineart_realistic`, `lineart_anime`, `lineart`, `depth_zoe`, `shuffle`, `mediapipe_face`, `canny`, `depth`, `depth_leres`, `depth_leres++`
            </ParamField>

            <ParamField type="number">
              Ratio of generation where this unit starts to impact the process. Range \[0, 1].
            </ParamField>

            <ParamField type="number">
              Ratio of generation where this unit stops impacting the process. Range \[0, 1].
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="integer">
      A seed is a number from which Stable Diffusion generates noise, which, makes generation deterministic. Using the same seed and set of parameters will produce identical image each time, minimum -1. Defaults to -1.
    </ParamField>

    <ParamField type="object[]">
      LoRA is a fast and lightweight training method that inserts and trains a significantly smaller number of parameters instead of all the model parameters. Currently supports up to 5 LoRAs.

      <Expandable title="properties">
        <ParamField type="string">
          Name of lora, retrieve the corresponding sd\_name\_in\_api value by invoking the <a href="/api-reference/model-apis-get-model">Get Model API</a> endpoint with filter.types=lora as the query parameter.
        </ParamField>

        <ParamField type="number">
          The strength value of lora. The larger the value, the more biased the effect is towards lora, Range \[0, 1]
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object[]">
      Textual Inversion is a training method for personalizing models by learning new text embeddings from a few example images, currently supports up to 5 embeddings.

      <Expandable title="properties">
        <ParamField type="string">
          Name of textual Inversion model, you can call the <a href="/api-reference/model-apis-get-model">Get Model API</a> endpoint with parameter filter.types=textualinversion to retrieve the sd\_name\_in\_api field as the model\_name.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="integer">
      This parameter indicates the number of layers to stop from the bottom during optimization, so clip\_skip on 2 would mean, that in SD1.x model where the CLIP has 12 layers, you would stop at 10th layer, Range \[1, 12], get reference at [A brief introduction to Clip Skip](/guides/model-apis-clip-skip).
    </ParamField>

    <ParamField type="number(float)¦null">
      Conceptually, the `strength` indicates the degree to which the reference `image_base64` should be transformed. Must be between 0 and 1. `image_base64` will be used as a starting point, with increasing levels of noise added as the strength value increases. The number of denoising steps depends on the amount of noise initially added. When `strength` is 1, added noise will be maximum and the denoising process will run for the full number of iterations specified in `steps`. A value of 1, therefore, essentially ignores `image_base64`.
    </ParamField>

    <ParamField type="object[]">
      IP-Adapter is an image prompt adapter that can be plugged into diffusion models to enable image prompting without any changes to the underlying model. Furthermore, adapter can be reused with other models finetuned from the same base model and it can be combined with other adapters like ControlNet, currenlty supports up to 1 IP-Adapter.

      <Expandable title="properties">
        <ParamField type="string">
          IP-Adapter model name, if the base model of your checkpoint is SDXL, then you should select ip-adapter\_sdxl.bin. Alternatively, if the base model of your checkpoint is SD1.x, then you should select ip-adapter\_sd15.bin.<br />
          Enum: `ip-adapter_sd15.bin`, `ip-adapter_sdxl.bin`
        </ParamField>

        <ParamField type="string">
          The base64 decoded content for input image.
        </ParamField>

        <ParamField type="number(float)">
          Range \[0, 1], this value represents the strength of this unit. The larger the value, the more pronounced the effect of the IP-Adapter becomes.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>

## Example

### 1. Image to image request with normal parameter.

Please set the **`Content-Type`** header to **`application/json`** in your HTTP request to indicate that you are sending JSON data. Currently, **only JSON format is supported**.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/img2img' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "extra": {
        "response_image_type": "jpeg"
    },
    "request": {
        "model_name": "sd_xl_base_1.0.safetensors",
        "prompt": "a cute dog",
        "negative_prompt": "",
        "height": 512,
        "width": 384,
        "image_num": 1,
        "steps": 20,
        "seed": -1,
        "clip_skip": 1,
        "guidance_scale": 7.5,
        "sampler_name": "Euler a",
        "embeddings": [
            {
                "model_name": "pureerosface_v1_5162.pt"
            }
        ],
        "loras": [
            {
              "model_name": "add_detail_44319",
              "strength": 0.7
            },
            {
              "model_name": "more_details_59655",
              "strength": 0.7
            }
        ],
        "image_base64": "{{Base64 encode image}}"
    }
}'
```

`Response:`

```js theme={"system"}
{
    "code": 0,
    "msg": "",
    "data": {
        "task_id": "73fab7c0-e24f-4027-9df0-81ff8ce4bc1f"
    }
}
```

**Use `task_id` to get images**

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get images url in `imgs` of response.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id=73fab7c0-e24f-4027-9df0-81ff8ce4bc1f' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "extra": {
        "seed": "1434608307"
    },
    "task": {
        "task_id": "73fab7c0-e24f-4027-9df0-81ff8ce4bc1f",
        "task_type": "IMG_TO_IMG",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 0
    },
    "images": [
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/73fab7c0-e24f-4027-9df0-81ff8ce4bc1f/d54551765e41409fbc80f7c23dc89241.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240115%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240115T083555Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=92dca9221e620d708c29ec525ed50ceb984dda23d8b7a352b4a19be682c8906e",
            "image_url_ttl": "3600",
            "image_type": "jpeg"
        }
    ],
    "videos": []
}
```

### 2. Image to image request with controlNet.

Please set the **`Content-Type`** header to **`application/json`** in your HTTP request to indicate that you are sending JSON data. Currently, **only JSON format is supported**.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/img2img' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "extra": {
        "response_image_type": "jpeg"
    },
    "request": {
        "model_name": "realcartoon25D_v3_240762.safetensors",
        "prompt": "1girl",
        "negative_prompt": "bad quality, bad anatomy, worst quality, low quality, lowres, extra fingers, blur, blurry, ugly, wrong proportions, watermark, image artifacts, bad eyes, bad hands, bad arms",
        "height": 1024,
        "width": 1024,
        "image_num": 1,
        "steps": 20,
        "seed": -1,
        "clip_skip": 1,
        "guidance_scale": 7,
        "sampler_name": "Euler",
        "controlnet": {
            "units": [
                {
                    "model_name": "control_v11p_sd15_openpose",
                    "image_base64": "{{Base64 encode image}}",
                    "strength": 0.5,
                    "preprocessor": "openpose"
                }
            ]
        },
        "image_base64": "{{Base64 encode image}}"
    }
}'
```

`Response:`

```bash theme={"system"}
{
    "code": 0,
    "msg": "",
    "data": {
        "task_id": "5867de36-7b76-4dc7-876e-818e3ffe683e"
    }
}
```

**Use `task_id` to get images**

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get images url in `imgs` of response.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id=5867de36-7b76-4dc7-876e-818e3ffe683e' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "extra": {
        "seed": "632855931",
        "enable_nsfw_detection": false
    },
    "task": {
        "task_id": "5867de36-7b76-4dc7-876e-818e3ffe683e",
        "task_type": "IMG_TO_IMG",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 0
    },
    "images": [
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/5867de36-7b76-4dc7-876e-818e3ffe683e/6569906512e14c2da82d74e69882b3a4.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240307%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240307T064348Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=f506cd2dc7ed7526bfe1cf4074722a1178efe242db6ca56e1e7dbca9b67230d2",
            "image_url_ttl": "3600",
            "image_type": "jpeg",
            "nsfw_detection_result": null
        }
    ],
    "videos": []
}
```

### 3. Image to image request with Textual Inversion(embedding).

Please set the **`Content-Type`** header to **`application/json`** in your HTTP request to indicate that you are sending JSON data. Currently, **only JSON format is supported**.

`Request for textual inversion names:`

```
curl --location --request GET 'https://api.novita.ai/v3/model?filter.visibility=public&pagination.limit=100&pagination.cursor=c_0&filter.types=textualinversion&filter.source=civitai' \
--header 'Authorization: Bearer {{API Key}}' | jq '.models[].sd_name'
```

`Response:`

```txt theme={"system"}
"epiCPhotoGasm-colorfulPhoto-neg_108119.pt"
"epiCNegative_66017.pt"
"verybadimagenegative_v1.3_21434.pt"
"FastNegativeV2_65067.pt"
"AS-YoungV2.pt"
"AS-YoungV2-neg.pt"
"AS-YoungestV2.pt"
"AS-YoungerV2.pt"
"AS-MidAged.pt"
"AS-Elderly.pt"
"AS-Adult.pt"
"AS-Adult-neg.pt"
"Adult.pt"
"MidAged.pt"
"unaestheticXLv13_98060.safetensors"
"unaestheticXL_Sky3.1_134255.safetensors"
"EasyNegativeV2_75525.safetensors"
"BadDream_53202.pt"
"UnrealisticDream_53204.pt"
"negative_hand-neg_43127.pt"
"bad_prompt_version2-neg_42594.pt"
"Asian-Less-Toon_39763.pt"
"badhandv4_16755.pt"
"easynegative_8955.safetensors"
"aestheticc-65800_8615.pt"
"corneo_side_deepthroat_6490.pt"
"corneo_tentacle_sex.pt"
"By bad artist -neg_6310.pt"
"dpthrt_5441.pt"
"ng_deepnegative_v1_75t_5845.pt"
"pureerosface_v1_5162.pt"
```

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/img2img' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "extra": {
        "response_image_type": "jpeg"
    },
    "request": {
        "model_name": "realcartoon25D_v3_240762.safetensors",
        "prompt": "dark theme girl",
        "negative_prompt": "",
        "height": 1024,
        "width": 1024,
        "image_num": 1,
        "steps": 20,
        "seed": 123,
        "clip_skip": 1,
        "guidance_scale": 7.5,
        "sampler_name": "Euler a",
        "embeddings": [
            {
                "model_name": "badhandv4_16755.pt"
            },
            {
                "model_name": "BadDream_53202.pt"
            }
        ],
        "image_base64": "{{Base64 encode image}}"
    }
}'
```

`Response:`

```js theme={"system"}
{
    "code": 0,
    "msg": "",
    "data": {
        "task_id": "6411f576-1c62-48b4-a0d5-427488721159"
    }
}
```

**Use `task_id` to get images**

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get images url in `imgs` of response.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id=6411f576-1c62-48b4-a0d5-427488721159' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "extra": {
        "seed": "170871295",
        "enable_nsfw_detection": false
    },
    "task": {
        "task_id": "6411f576-1c62-48b4-a0d5-427488721159",
        "task_type": "IMG_TO_IMG",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 0
    },
    "images": [
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/6411f576-1c62-48b4-a0d5-427488721159/ede3a87d667e4371abc687b9ede03938.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240307%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240307T065015Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=228bb2254bf7de328814c89b200287ab903f7f5690033f810c745ae7be902b76",
            "image_url_ttl": "3600",
            "image_type": "jpeg",
            "nsfw_detection_result": null
        }
    ],
    "videos": []
}
```

### 4. Img2img request with nsfw\_detection.

When set `enable_nsfw_detection` true, NSFW detection will be enabled, incurring an additional cost of \$0.0015 for each generated image.

`nsfw_detection_level`, nsfw check level, ranging from 0 to 2, with higher levels indicating stricter NSFW detection criteria. The default value is 0. The following table lists the NSFW detection criteria for each level.

* 0: Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols.
* 1: Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols; Non-Explicit Nudity, Obstructed Intimate Parts, Kissing on the Lips.
* 2: Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols; Non-Explicit Nudity, Obstructed Intimate Parts, Kissing on the Lips; Female Swimwear or Underwear, Male Swimwear or Underwear.

Please set the **`Content-Type`** header to **`application/json`** in your HTTP request to indicate that you are sending JSON data. Currently, **only JSON format is supported**.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/img2img' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "extra": {
        "response_image_type": "jpeg",
        "enable_nsfw_detection": true,
        "nsfw_detection_level": 2
    },
    "request": {
        "model_name": "chilloutmix_NiPrunedFp32Fix.safetensors",
        "prompt": "a cute dog",
        "negative_prompt": "",
        "height": 512,
        "width": 384,
        "image_num": 1,
        "steps": 20,
        "seed": 123,
        "clip_skip": 1,
        "guidance_scale": 7.5,
        "sampler_name": "Euler a",
        "embeddings": [
            {
                "model_name": "pureerosface_v1_5162.pt"
            }
        ],
        "loras": [
            {
                "model_name": "MS_Real_AssSpread",
                "strength": 0.7
            },
            {
                "model_name": "MS_Real_Cameltoe_Lite",
                "strength": 0.9
            }
        ],
        "controlnet": {
            "units": [
                {
                    "model_name": "control_v11f1e_sd15_tile",
                    "image_base64": "{{Base64 encode image}}",
                    "strength": 1,
                    "preprocessor": "openpose"
                }
            ]
        },
        "image_base64": "{{Base64 encode image}}"
    }
}'
```

`Response:`

```js theme={"system"}
{
    "code": 0,
    "msg": "",
    "data": {
        "task_id": "741597cc-8e27-4932-9d75-34f07b96413e"
    }
}
```

**Use `task_id` to get images**

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get images url in `imgs` of response.

There are two results in reponse.

* `enable_nsfw_detection`, when return with `true` means NSFW detection is enabled.

* `nsfw_detection_result`, presenting an array of NSFW detection outcomes for each image. The order of elements in the nsfw\_detection\_result array corresponds one-to-one with the sequence of images in the `images` field in the response. The `valid` field denotes the success of the NSFW detection process, while the `confidence` field, ranging from 0 to 100, signifies the confidence level of the NSFW detection result. Higher confidence values, nearing 100, suggest a greater likelihood of the corresponding image containing NSFW content.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id=741597cc-8e27-4932-9d75-34f07b96413e' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "extra": {
        "seed": "3183986171",
        "enable_nsfw_detection": true
    },
    "task": {
        "task_id": "741597cc-8e27-4932-9d75-34f07b96413e",
        "task_type": "TXT_TO_IMG",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 0
    },
    "images": [
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/741597cc-8e27-4932-9d75-34f07b96413e/6e38c309732f4241b99f75e54ffdb54a.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240124%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240124T141031Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=9edf916b9f3148207953140d0ec545a468e50fc80e635d4a7fa182c67989ced8",
            "image_url_ttl": "3600",
            "image_type": "jpeg",
            "nsfw_detection_result": {
                "valid": true,
                "confidence": 0
            }
        },
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/741597cc-8e27-4932-9d75-34f07b96413e/b8346c9cbe494102be2a28f29c0005b1.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240124%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240124T141031Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=d81316dea2446aab04cd5e559504a2a8fa7245958d766afd8f372e7e8fb02fb9",
            "image_url_ttl": "3600",
            "image_type": "jpeg",
            "nsfw_detection_result": {
                "valid": true,
                "confidence": 0
            }
        },
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/741597cc-8e27-4932-9d75-34f07b96413e/f6e0f939a5e4466990595445a41e75ef.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240124%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240124T141031Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=6d719fe7e4e6cb0f93ec07616b20e968f659b12102e4b11c866016780eb2eb6c",
            "image_url_ttl": "3600",
            "image_type": "jpeg",
            "nsfw_detection_result": {
                "valid": true,
                "confidence": 0
            }
        },
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/741597cc-8e27-4932-9d75-34f07b96413e/ddbc7d39db1d4468bd3c9d92556b99ee.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240124%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240124T141031Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=259a5d358175132a2c0adfcd23142bb8227cd6e68052b99779686956c04a713a",
            "image_url_ttl": "3600",
            "image_type": "jpeg",
            "nsfw_detection_result": {
                "valid": true,
                "confidence": 0
            }
        }
    ],
    "videos": []
}
```


# Image to Image V2
Source: https://novita.ai/docs/api-reference/model-apis-image-to-image-v2-deprecated

POST https://api.novita.ai/v2/img2img

<Warning>
  **The Image-to-Image V2 API is deprecated and will be removed in the future. Please migrate to [Image-to-Image V3](/api-reference/model-apis-image-to-image).**
</Warning>

## POST Image to Image V2

This is the image-to-image endpoint. Only a `task_id` will be returned. You should use the `task_id` to call the `/v2/progress` API endpoint in order to retrieve the image generation results. The output is provided in the format of "image/png". We will gradually phase out the V2 endpoints, and it is recommended to use the V3 endpoints to generate images.

## Request Headers

<ParamField type="string" />

## Request Body

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      When set to true, NSFW detection will be enabled, incurring an additional cost of \$0.0015 for each generated image.
    </ParamField>

    <ParamField type="integer">
      \*\*\* 0 - Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols. \*\*\* 1 - Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols; Non-Explicit Nudity, Obstructed Intimate Parts, Kissing on the Lips. \*\*\* 2 - Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols; Non-Explicit Nudity, Obstructed Intimate Parts, Kissing on the Lips; Female Swimwear or Underwear, Male Swimwear or Underwear.<br />
      Enum: `0`, `1`, `2`
    </ParamField>

    <ParamField type="boolean¦null">
      You will receive empty preview images after setting enable\_progress\_info to false.
    </ParamField>

    <ParamField type="string">
      The format of returned images, default: `png`<br />
      Enum: `png`, `jpeg`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string¦null">
  Positive prompt words, separated by commas. If you want to use LoRA, you can call the `/v3/model` endpoint with the parameter filter.types=lora to retrieve the `sd_name_in_api` field as the `model_name`. Remember that the format for LoRA models is `<lora:$sd_name:$weight>`.
</ParamField>

<ParamField type="string¦null">
  Negative prompt words, separated by commas.
</ParamField>

<ParamField type="string¦null">
  This denoising process is called sampling because Stable Diffusion generates a new sample image at each step.<br />
  Enum: `DPM++ 2M Karras`, `DPM++ SDE Karras`, `DPM++ 2M SDE Exponential`, `DPM++ 2M SDE Karras`, `Euler a`, `Euler`, `LMS`, `Heun`, `DPM2`, `DPM2 a`, `DPM++ 2S a`, `DPM++ 2M`, `DPM++ SDE`, `DPM++ 2M SDE`, `DPM++ 2M SDE Heun`, `DPM++ 2M SDE Heun Karras`, `DPM++ 2M SDE Heun Exponential`, `DPM++ 3M SDE`, `DPM++ 3M SDE Karras`, `DPM++ 3M SDE Exponential`, `DPM fast`, `DPM adaptive`, `LMS Karras`, `DPM2 Karras`, `DPM2 a Karras`, `DPM++ 2S a Karras`, `Restart`, `DDIM`, `PLMS`, `UniPC`
</ParamField>

<ParamField type="integer¦null">
  Number of images generated in a single generation. Range: \[0, 8]
</ParamField>

<ParamField type="integer¦null">
  Number of generations. Range: \[0, 8]
</ParamField>

<ParamField type="integer¦null">
  Think of steps as iterations of the image creation process. Range: (0, 50]
</ParamField>

<ParamField type="number¦null">
  This setting indicates how closely Stable Diffusion will adhere to your prompt. Range: (0, 30]
</ParamField>

<ParamField type="integer¦null">
  A seed is a number from which Stable Diffusion generates noise.
</ParamField>

<ParamField type="integer">
  Height of the image. Range: (0, 2048]
</ParamField>

<ParamField type="integer">
  Width of the image. Range: (0, 2048]
</ParamField>

<ParamField type="string">
  Name of the stable diffusion model. You can call the `/v3/model` endpoint with the parameter filter.types=checkpoint to retrieve the `sd_name_in_api` field as the `model_name`.
</ParamField>

<ParamField type="string[]" />

<ParamField type="number¦null">
  Indicates how much to transform the reference init\_images. Must be between 0 and 1. init\_images will be used as a starting point, with more noise added as the strength increases. The number of denoising steps depends on the amount of noise initially added. When denoising\_strength is 1, added noise will be maximum, and the denoising process will run for the full number of iterations specified in steps. A value of 1, therefore, essentially ignores init\_images.
</ParamField>

<ParamField type="boolean¦null">
  Enable Stable Diffusion restore faces plugin.
</ParamField>

<ParamField type="string¦null">
  VAE(Variational Auto Encoder),sd\_vae can be access in api /v3/model with query params filter.types=vae to retrieve the `sd_name` field as the `sd_vae`.
</ParamField>

<ParamField type="integer¦null">
  This parameter indicates the number of layers to stop from the bottom during optimization, so clip\_skip on 2 would mean, that in SD1.x model where the CLIP has 12 layers, you would stop at 10th layer.
</ParamField>

<ParamField type="string">
  Base64 of png, mask of inpaintings.
</ParamField>

<ParamField type="integer">
  Sets the degree of blurring of the border of the filled area.
</ParamField>

<ParamField type="integer¦null">
  Resize mode, while, 0 represent Just resize, 1 represent Crop and resize, 2 represent Resize and fill, 3 represent Just resize(latent upscale)<br />
  Enum: `0`, `1`, `2`, `3`
</ParamField>

<ParamField type="integer¦null">
  Image cfg scale
</ParamField>

<ParamField type="integer¦null">
  How to redraw the filled areas. 0: fill,  Redraw based on the surrounding color 1: original,  Redraw based on the original image 2: latent noise,  Change back to noise and redraw 3: latent nothing, based on the color of the filled area<br />
  Enum: `0`, `1`, `2`, `3`
</ParamField>

<ParamField type="integer¦null">
  Specify whether to apply or protect the filled area. 0: Whole picture the entire illustration and change the filled parts. 1: Only masked Draws only the filled area and then restores the original image.<br />
  Enum: `0`, `1`
</ParamField>

<ParamField type="integer¦null">
  This settings controls how many additional pixels can be used as a reference point for only masked mode. You can increase the amount if you are having trouble with producing a proper image. This is a numerical value for how much margin to set when Only masked is selected. The downside of increasing this value is that it will decrease the quality of output. Guidance: [https://civitai.com/articles/161/basic-inpainting-guide](https://civitai.com/articles/161/basic-inpainting-guide)
</ParamField>

<ParamField type="integer">
  Specify whether to invert the mask. 0 - Inpaint Masked 1 - Inpaint Not Masked<br />
  Enum: `0`, `1`
</ParamField>

<ParamField type="number">
  Noise multiplier for img2img in settings. This scaling factor is applied to the random latent tensor for img2img. Lowering it reduces flickering.
</ParamField>

<ParamField type="integer">
  Image storage time (seconds). Range \[0, 604800]
</ParamField>

<ParamField type="object">
  Refiner infos to enhances the image details.

  <Expandable title="properties">
    <ParamField type="string">
      Refiner checkpoint name. Currently only `sd_xl_refiner_1.0.safetensors` supported.<br />
      Enum: `sd_xl_refiner_1.0.safetensors`
    </ParamField>

    <ParamField type="number">
      Weight of refiner. From 0 to 1
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]¦null">
  ControlNet.

  <Expandable title="properties">
    <ParamField type="string">
      Model to use on the image passed to this unit before using it for conditioning. \*\*\*Controlnets for SD 1.5: control\_v11e\_sd15\_ip2p, control\_v11e\_sd15\_shuffle, control\_v11f1e\_sd15\_tile, control\_v11f1p\_sd15\_depth, control\_v11p\_sd15\_canny, control\_v11p\_sd15\_inpaint, control\_v11p\_sd15\_lineart, control\_v11p\_sd15\_mlsd, control\_v11p\_sd15\_normalbae, control\_v11p\_sd15\_openpose, control\_v11p\_sd15\_scribble, control\_v11p\_sd15\_seg, control\_v11p\_sd15\_softedge, control\_v11p\_sd15s2\_lineart\_anime, ip-adapter-plus-face\_sd15, ip-adapter\_sd15\_plus, ip-adapter\_sd15; \*\*\*Controlnets for SDXL: t2i-adapter\_diffusers\_xl\_canny, t2i-adapter\_diffusers\_xl\_depth\_midas, t2i-adapter\_diffusers\_xl\_depth\_zoe, t2i-adapter\_diffusers\_xl\_lineart, t2i-adapter\_diffusers\_xl\_openpose, t2i-adapter\_diffusers\_xl\_sketch, t2i-adapter\_xl\_canny, t2i-adapter\_xl\_openpose, t2i-adapter\_xl\_sketch, ip-adapter\_xl
    </ParamField>

    <ParamField type="number¦null">
      weight of this unit. defaults to 1
    </ParamField>

    <ParamField type="string">
      base64 of input image
    </ParamField>

    <ParamField type="string">
      preprocessor to use on the image passed to this unit before using it for conditioning.<br />
      Enum: `none`, `canny`, `depth`, `depth_leres`, `depth_leres++`, `hed`, `hed_safe`, `mediapipe_face`, `mlsd`, `normal_map`, `openpose`, `openpose_hand`, `openpose_face`, `openpose_faceonly`, `openpose_full`, `clip_vision`, `color`, `pidinet`, `pidinet_safe`, `pidinet_sketch`, `pidinet_scribble`, `scribble_xdog`, `scribble_hed`, `segmentation`, `threshold`, `depth_zoe`, `normal_bae`, `oneformer_coco`, `oneformer_ade20k`, `lineart`, `lineart_coarse`, `lineart_anime`, `lineart_standard`, `shuffle`, `tile_resample`, `invert`, `lineart_anime_denoise`, `reference_only`, `reference_adain`, `reference_adain+attn`, `inpaint`, `inpaint_only`, `inpaint_only+lama`, `tile_colorfix`, `tile_colorfix+sharp`, `depth_anything`
    </ParamField>

    <ParamField type="integer¦null">
      0 for Balanced,1 for My prompt is more important 2 for ControlNet is more important<br />
      Enum: `0`, `1`, `2`
    </ParamField>

    <ParamField type="string¦null">
      Base64 of mask images, support jpg, jpeg and png format images. Only take effect when controlnet\_units.model set to control\_v11p\_sd15\_inpaint.
    </ParamField>

    <ParamField type="integer¦null">
      How to resize the input image so as to fit the output resolution of the generation.<br />
      Enum: `0`, `1`, `2`
    </ParamField>

    <ParamField type="integer¦null">
      Resolution of the preprocessor.
    </ParamField>

    <ParamField type="integer¦null">
      First parameter of the preprocessor, only takes effect when preprocessor accepts arguments.
    </ParamField>

    <ParamField type="integer¦null">
      Second parameter of the preprocessor, only takes effect when preprocessor accepts arguments.
    </ParamField>

    <ParamField type="number¦null">
      ratio of generation where this unit starts to have an effect.
    </ParamField>

    <ParamField type="number¦null">
      ratio of generation where this unit stops to have an effect.
    </ParamField>

    <ParamField type="boolean¦null">
      Enable pixel-perfect preprocessor, when set to false, it means not to resize images.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="code" type="integer" />

<ResponseField name="msg" type="string" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="task_id" type="string" />

    <ResponseField name="warn" type="string" />
  </Expandable>
</ResponseField>

## Example

request

```bash theme={"system"}
curl --location 'https://api.novita.ai/v2/img2img' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
  'extra': {
    'enable_nsfw_detection': false,
    'nsfw_detection_level': 0,
    'enable_progress_info': false
  },
  'prompt': 'Photographic of a woman sitting at a cafe. 35mm photograph, film, bokeh, professional, 4k, highly detailed',
  'negative_prompt': 'ng_deepnegative_v1_75t, badhandv4, (worst quality:2), (low quality:2), (normal quality:2), lowres, ((monochrome)), ((grayscale)), watermark',
  'sampler_name': 'Euler a',
  'batch_size': 1,
  'n_iter': 1,
  'steps': 20,
  'cfg_scale': 7,
  'seed': -1,
  'height': 1024,
  'width': 1024,
  'model_name': 'sd_xl_base_1.0.safetensors',
  'init_images': [
    '{{base64 encoded image}}'
  ],
  'denoising_strength': 0.5,
  'restore_faces': false,
  'sd_vae': 'sdxl_vae.safetensors',
  'clip_skip': 1,
  'mask': '',
  'mask_blur': null,
  'resize_mode': 0,
  'image_cfg_scale': null,
  'inpainting_fill': 0,
  'inpaint_full_res': 0,
  'inpaint_full_res_padding': null,
  'inpainting_mask_invert': 0,
  'initial_noise_multiplier': null,
  'img_expire_ttl': null,
  'sd_refiner': {
    'checkpoint': 'sd_xl_refiner_1.0.safetensors',
    'switch_at': 1
  },
  'controlnet_units': [
    {
      'model': 't2i-adapter_xl_sketch',
      'weight': 0.5,
      'input_image': '{{base64 encoded image}}',
      'module': 'none',
      'control_mode': 0,
      'mask': '',
      'resize_mode': 0,
      'processor_res': null,
      'threshold_a': null,
      'threshold_b': null,
      'guidance_start': null,
      'guidance_end': null,
      'pixel_perfect': false,
      'lowvram': true
    }
  ],
  'controlnet_no_detectmap': true
}'
```

response

```json theme={"system"}
{
  "code": 0,
  "msg": "",
  "data": {
    "task_id": "d4cf3973-8414-4a5e-aa6f-ef54caf73662"
  }
}
```


# Image to Prompt
Source: https://novita.ai/docs/api-reference/model-apis-image-to-prompt

POST https://api.novita.ai/v3/img2prompt

**This API extracts prompts from images.**

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The base64-encoded original image, with a maximum resolution of 2048 x 2048 pixels and a maximum file size of 30 MB.
</ParamField>

## Response

<ResponseField name="prompt" type="string">
  The prompt generated from the input image.
</ResponseField>

## Example

This API retrieves prompts from images.

Please set the **`Content-Type`** header to **`application/json`** in your HTTP request to indicate that you are sending JSON data. Currently, **only JSON format is supported**.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/img2prompt' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "image_file": "{{Base64 encoded image}}"
}'
```

HTTP status codes in the 2xx range indicate that the request has been successfully accepted. A status code of 400 means there is an error with the request parameters, while status codes in the 5xx range indicate internal server errors.

You can find the generated prompt in the `prompt` field of the response.

`Image`:

<Frame>
  <img />
</Frame>

`Response:`

```js theme={"system"}
{
    "prompt": "a man standing on a rock near the ocean, Alejandro Iñárritu, Nadav Kander, Ignacio Fernández Ríos, Ignacio Fernández Ríos, Ignacio Ríos, Navid Negahban, Reza Afshar, Steven Klein, Ignacio Fernández Ríos, Lorenzo Lanfranconi, Peter Palombi, Alberto Mielgo"
}
```


# Image Upscaling
Source: https://novita.ai/docs/api-reference/model-apis-image-upscaler

POST https://api.novita.ai/v3/async/image-upscaler

AI-powered image upscaling service that enhances low-resolution images to higher resolutions, providing high-quality image processing: out-of-the-box REST inference API, best performance, no cold start, and affordable pricing.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The URL of the original image to be upscaled.
</ParamField>

<ParamField type="string">
  Target resolution after upscaling.

  Optional values: `2k`, `4k`, `8k`
</ParamField>

<ParamField type="string">
  The output image format.

  Optional values: `jpeg`, `png`, `webp`
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Image to Video
Source: https://novita.ai/docs/api-reference/model-apis-img2video

POST https://api.novita.ai/v3/async/img2video

**This API seamlessly transforms an image into a cohesive video. It is designed to create smooth transitions and animations from static images, making it ideal for producing dynamic visual content for presentations, social media, and marketing campaigns.**

> This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Optional extra parameters for the request.

  <Expandable title="properties">
    <ParamField type="string">
      The returned video type. Default is mp4.Enum: `mp4, gif`
    </ParamField>

    <ParamField type="object">
      Webhook settings. More details can be found at [Webhook Documentation](/api-reference/model-apis-webhook).

      <Expandable title="properties">
        <ParamField type="string">
          The URL of the webhook endpoint. Novita AI will send the task generated outputs to your specified webhook endpoint.
        </ParamField>

        <ParamField type="object">
          By specifying Test Mode, a mock event will be sent to the webhook endpoint.

          <Expandable title="properties">
            <ParamField type="boolean">
              Set to true to enable Test Mode, or false to disable it. The default is false.
            </ParamField>

            <ParamField type="string">
              Control the data content of the mock event. When set to TASK\_STATUS\_SUCCEED, you'll receive a normal response; when set to TASK\_STATUS\_FAILED, you'll receive an error response.Enum: `TASK_STATUS_SUCCEED, TASK_STATUS_FAILED`
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      Dedicated Endpoints settings, which only take effect for users who have already subscribed to the [Dedicated Endpoints Documentation](/guides/model-apis-dedicated-endpoints).

      <Expandable title="properties">
        <ParamField type="boolean">
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Specifies the model to be used for processing. SVD (Singular Value Decomposition): Ideal for applications involving matrix factorization and dimensionality reduction. This model is well-suited for tasks such as signal processing, recommendation systems, and data compression, offering robust feature extraction and data simplification capabilities. SVD-XT: This model is an extended version of the standard SVD, optimized for handling larger datasets and more complex computations. It provides enhanced performance and accuracy in environments requiring intensive data processing.Enum: `SVD-XT, SVD`
</ParamField>

<ParamField type="string">
  The base64 of input image, with a maximum resolution of 2048 x 2048 and a maximum file size of 30 Mb.
</ParamField>

<ParamField type="integer">
  Total number of video frames. When the parameter model\_name=SVD\_XT, then frames\_num = 25; when the parameter model\_name=SVD, then frames\_num = 14.
</ParamField>

<ParamField type="integer">
  Frames per second; the larger the frame rate, the smoother the video. Currently, only the number 6 is supported.
</ParamField>

<ParamField type="string">
  The image file resize mode has two settings: When set to ORIGINAL\_RESOLUTION, it retains the original image size but ensures the resolution is below 576 x 1024. When set to CROP\_TO\_ASPECT\_RATIO, it maintains the original proportions of the image and crops it to fit within a 576 x 1024 resolution.Enum: `ORIGINAL_RESOLUTION, CROP_TO_ASPECT_RATIO`
</ParamField>

<ParamField type="integer">
  The number of denoising steps. More steps usually produce higher quality content, but take more time to generate. Range \[1, 50].
</ParamField>

<ParamField type="integer">
  A seed is a number from which Stable Diffusion generates noise, which, makes generation deterministic. Using the same seed and set of parameters will produce identical content each time, minimum -1. Defaults to -1.
</ParamField>

<ParamField type="integer">
  Identifies the specific motion bucket to be utilized during the img2video process. This parameter selects a predefined set of motion profiles, each corresponding to a unique identifier ranging from 1 to 255. Selecting an appropriate motion bucket can tailor the animation effects to better suit the specific characteristics or themes of the input images. Range \[1, 255].
</ParamField>

<ParamField type="number">
  The amount of noise added to the conditioning image. The higher the value, the less the video resembles the conditioning image. Increasing this value also enhances the motion in the generated video. Range \[0, 1].
</ParamField>

<ParamField type="boolean">
  Enables frame interpolation to standardize video output to 24 frames per second (fps). This feature smooths out motion by generating intermediate frames, enhancing the fluidity and continuity of the video sequence. This is particularly useful for converting lower frame rate footage to a more cinematic frame rate.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>

## Example

This API helps generate a video from an image. The returned video can be accessed via the API `/v3/async/task-result` using the `task_id`.

**Try it in [playground](https://novita.ai/playground#img2video).**

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/img2video' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "model_name": "SVD-XT",
    "image_file": "{{Base64 encoded image}}",
    "frames_num": 25,
    "frames_per_second": 6,
    "seed": 20231127,
    "image_file_resize_mode": "CROP_TO_ASPECT_RATIO",
    "steps": 20
}'
```

`Response:`

```js theme={"system"}
{
    "task_id": "fa20dff3-18cb-4417-a7f8-269456a35154"
}
```

**Use `task_id` to get videos**

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get the video URLs from the `videos` field in the response.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id=fa20dff3-18cb-4417-a7f8-269456a35154' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "task": {
        "task_id": "fa20dff3-18cb-4417-a7f8-269456a35154",
        "task_type": "IMG_TO_VIDEO",
        "status": "TASK_STATUS_SUCCEED",
        "reason": ""
    },
    "images": [],
    "videos": [
        {
            "video_url": "https://faas-output-video.s3.ap-southeast-1.amazonaws.com/test/fa20dff3-18cb-4417-a7f8-269456a35154/e40de30e115947a0be2dfc78925e587d.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20231127%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20231127T151757Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=14faf7df34c2c2ff68fed102095af593844db7c5c5cd2d80e80beec0613192c7",
            "video_url_ttl": "3600",
            "video_type": "mp4"
        }
    ]
}
```


# Inpainting
Source: https://novita.ai/docs/api-reference/model-apis-inpainting

POST https://api.novita.ai/v3/async/inpainting

**Inpainting is a conservation process in which damaged, deteriorated, or missing parts of an artwork are filled in to present a complete image.**

> This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the image generation results.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Optional extra parameters for the request.

  <Expandable title="properties">
    <ParamField type="string">
      The returned image type. Default is png.<br />
      Enum: `png`, `webp`, `jpeg`
    </ParamField>

    <ParamField type="object">
      Webhook settings. More details can be found at [Webhook Documentation](/api-reference/model-apis-webhook).

      <Expandable title="properties">
        <ParamField type="string">
          The URL of the webhook endpoint. Novita AI will send the task generated outputs to your specified webhook endpoint.
        </ParamField>

        <ParamField type="object">
          By specifying Test Mode, a mock event will be sent to the webhook endpoint.

          <Expandable title="properties">
            <ParamField type="boolean">
              Set to true to enable Test Mode, or false to disable it. The default is false.
            </ParamField>

            <ParamField type="string">
              Control the data content of the mock event. When set to TASK\_STATUS\_SUCCEED, you'll receive a normal response; when set to TASK\_STATUS\_FAILED, you'll receive an error response.<br />
              Enum: `TASK_STATUS_SUCCEED`, `TASK_STATUS_FAILED`
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      Customer storage settings for saving the generated outputs. <br /> By default, the generated outputs will be saved to Novita AI Storage temporarily and privately.

      <Expandable title="properties">
        <ParamField type="object">
          AWS S3 Bucket settings.

          <Expandable title="properties">
            <ParamField type="string">
              AWS S3 regions, <a href="https://docs.aws.amazon.com/general/latest/gr/rande.html">more details</a>.
            </ParamField>

            <ParamField type="string">
              AWS S3 bucket name.
            </ParamField>

            <ParamField type="string">
              AWS S3 bucket path for saving generated outputs.
            </ParamField>

            <ParamField type="boolean">
              Set this option to True to save the generated outputs directly to the specified path without creating any additional directory hierarchy. <br /> If set to False, Novita AI will create an additional directory in the path to save the generated outputs. The default is False.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      Dedicated Endpoints settings, which only take effect for users who have already subscribed to the [Dedicated Endpoints Documentation](/guides/model-apis-dedicated-endpoints).

      <Expandable title="properties">
        <ParamField type="boolean">
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="boolean">
      When set to true, NSFW detection will be enabled, incurring an additional cost of \$0.0015 for each generated image.
    </ParamField>

    <ParamField type="integer">
      0: Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols.<br /> 1: Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols; Non-Explicit Nudity, Obstructed Intimate Parts, Kissing on the Lips.<br /> 2: Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols; Non-Explicit Nudity, Obstructed Intimate Parts, Kissing on the Lips; Female Swimwear or Underwear, Male Swimwear or Underwear.<br />
      Enum: `0`, `1`, `2`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      This parameter specifies the name of the model checkpoint. Retrieve the corresponding sd\_name value by invoking the <a href="/api-reference/model-apis-get-model">Query Model</a> API with filter.types=checkpoint\&filter.is\_inpainting=true as the query parameter.
    </ParamField>

    <ParamField type="string">
      The base64 representation of the original image, with a maximum resolution of 16 megapixels and a maximum file size of 30 Mb.
    </ParamField>

    <ParamField type="string">
      The base64 representation of the mask image, with a maximum resolution of 16 megapixels and a maximum file size of 30 Mb. The mask image should have the same resolution as the original image.
    </ParamField>

    <ParamField type="string">
      Text input required to guide the image generation, divided by `,` . Range \[1, 1024].
    </ParamField>

    <ParamField type="integer">
      Images numbers generated in one single generation. Range \[1, 8].
    </ParamField>

    <ParamField type="integer">
      The number of denoising steps. More steps usually can produce higher quality images, but take more time to generate, Range \[1, 100].
    </ParamField>

    <ParamField type="number">
      This setting says how close the Stable Diffusion will listen to your prompt, higer guidance forces the model to better follow the prompt, but result in lower quality output. Range \[1, 30].
    </ParamField>

    <ParamField type="string">
      This parameter determines the denoising algorithm employed during the sampling phase of Stable Diffusion. Each option represents a distinct method by which the model incrementally generates new images. These algorithms differ significantly in their processing speed, output quality, and the specific characteristics of the images they generate, allowing users to tailor the image generation process to meet precise requirements. Get reference at [A brief introduction to Sampler](/guides/model-apis-sampler).<br />
      Enum: `Euler a`, `Euler`, `LMS`, `Heun`, `DPM2`, `DPM2 a`, `DPM++ 2S a`, `DPM++ 2M`, `DPM++ SDE`, `DPM fast`, `DPM adaptive`, `LMS Karras`, `DPM2 Karras`, `DPM2 a Karras`, `DPM++ 2S a Karras`, `DPM++ 2M Karras`, `DPM++ SDE Karras`, `DDIM`, `PLMS`, `UniPC`
    </ParamField>

    <ParamField type="integer">
      Defines the degree of border blurring for the filled area. A lower value results in a sharper border, maintaining clear delineation between masked and unmasked areas. Conversely, a higher value increases the blur effect, creating a smoother, more blended transition at the borders. This adjustment allows for greater control over the visual integration of the mask with the original image. Range \[0, 64].
    </ParamField>

    <ParamField type="string">
      Text input that specifies what to exclude from the generated images, divided by `,` . Range \[1, 1024].
    </ParamField>

    <ParamField type="string">
      VAE (Variational Auto Encoder). The sd\_vae can be accessed in the API /v3/models with query parameters type=vae, such as sd\_name: customVAE.safetensors. Get reference at [A brief introduction to VAE](/guides/model-apis-vae).
    </ParamField>

    <ParamField type="integer">
      A seed is a number from which Stable Diffusion generates noise, which, makes generation deterministic. Using the same seed and set of parameters will produce identical image each time, minimum -1. Defaults to -1.
    </ParamField>

    <ParamField type="object[]">
      LoRA is a fast and lightweight training method that inserts and trains a significantly smaller number of parameters instead of all the model parameters. Currently supports up to 5 LoRAs.

      <Expandable title="properties">
        <ParamField type="string">
          Name of lora, retrieve the corresponding sd\_name\_in\_api value by invoking the <a href="/api-reference/model-apis-get-model">Get Model API</a> endpoint with filter.types=lora as the query parameter.
        </ParamField>

        <ParamField type="number">
          The strength value of lora. The larger the value, the more biased the effect is towards lora, Range \[0, 1]
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object[]">
      Textual Inversion is a training method for personalizing models by learning new text embeddings from a few example images, currently supports up to 5 embeddings.

      <Expandable title="properties">
        <ParamField type="string">
          Name of textual Inversion model, you can call the <a href="/api-reference/model-apis-get-model">Get Model API</a> endpoint with parameter filter.types=textualinversion to retrieve the sd\_name\_in\_api field as the model\_name.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="integer">
      This parameter indicates the number of layers to stop from the bottom during optimization, so clip\_skip on 2 would mean, that in SD1.x model where the CLIP has 12 layers, you would stop at 10th layer, Range \[1, 12], get reference at [A brief introduction to Clip Skip](/guides/model-apis-clip-skip).
    </ParamField>

    <ParamField type="number(float)¦null">
      Conceptually, the `strength` indicates the degree to which the reference `image_base64` should be transformed. Must be between 0 and 1. `image_base64` will be used as a starting point, with increasing levels of noise added as the strength value increases. The number of denoising steps depends on the amount of noise initially added. When `strength` is 1, added noise will be maximum and the denoising process will run for the full number of iterations specified in `steps`. A value of 1, therefore, essentially ignores `image_base64`.
    </ParamField>

    <ParamField type="integer">
      Specifies whether to apply or protect the filled area. When set to 0, the inpainting process considers the entire image, which may result in the mask area failing to present the correct details, but the mask area will look more natural or blend better with the whole image. When set to 1, only the masked area is inpainted, ignoring the unmasked areas, which can produce more detailed and natural results within the mask but may appear strange or incompatible with the original background. Default is 0.<br />
      Enum: `0`, `1`
    </ParamField>

    <ParamField type="integer">
      This setting controls how many additional pixels can be used as a reference point for only masked mode. You can increase this amount if you are having trouble producing a proper image. This is a numerical value for how much margin to set when Only masked is selected. The downside of increasing this value is that it may decrease the quality of the output. Guidance: [https://civitai.com/articles/161/basic-inpainting-guide](https://civitai.com/articles/161/basic-inpainting-guide), Range \[0, 256]. Default is 8.
    </ParamField>

    <ParamField type="integer">
      Specifies whether to invert the mask. Set to 1 to invert the mask. Default is 0.<br />
      Enum: `0`, `1`
    </ParamField>

    <ParamField type="number">
      Noise multiplier for img2img settings. This scaling factor is applied to the random latent tensor for img2img. Lowering the value of this multiplier reduces the amount of noise introduced into the image transformation process, which can help reduce flickering or instability in the output image. Range \[0, 1.5]. Default is 0.5.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>

## Example

### I have no `mask` images. How do I generate `mask` parameters in the body?

You can use our playground to get the mask base64 information. Please be aware that mask images should have the same resolution as the input images. Guidance can be found here: [Click Here](https://novita.ai/playground#inpainting)

<Frame>
  <img />
</Frame>

### I already have mask images. How do I convert `mask` images to base64?

You can use the following code to convert mask images to base64.

```python theme={"system"}
import base64
# mask files path
filename_input = "mask_edited.png"

# read mask file
with open(filename_input, "rb") as f:
    base64_pic = base64.b64encode(f.read()).decode("utf-8")

# write mask file
with open("input.txt", "w") as f:
    f.write(base64_pic)
```

### Start requesting inpainting.

Please set the **`Content-Type`** header to **`application/json`** in your HTTP request to indicate that you are sending JSON data. Currently, **only JSON format is supported**.

`"model_name":"realisticVisionV40_v40VAE-inpainting_81543.safetensors"` in body represent inpainting models, which, can be accessed in API /v3/model with `sd_name` like %inpainting%.

`Request:`

```bash theme={"system"}
curl --location --request POST 'http://api.novita.ai/v3/async/inpainting' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{API Key}}' \
--data-raw '{
    "extra": {
        "response_image_type": "jpeg"
    },
    "request": {
        "model_name": "realisticVisionV40_v40VAE-inpainting_81543.safetensors",
        "prompt": "Leonardo DiCaprio",
        "negative_prompt": "(deformed iris, deformed pupils, semi-realistic, cgi, 3d, render, sketch, cartoon, drawing, anime), text, cropped, out of frame, worst quality, low quality, jpeg artifacts, ugly, duplicate, morbid, mutilated, extra fingers, mutated hands, poorly drawn hands, poorly drawn face, mutation, deformed, blurry, dehydrated, bad anatomy, bad proportions, extra limbs, cloned face, disfigured, gross proportions, malformed limbs, missing arms, missing legs, extra arms, extra legs, fused fingers, too many fingers, long neck, BadDream, UnrealisticDream",
        "image_num": 1,
        "steps": 25,
        "seed": -1,
        "clip_skip": 1,
        "guidance_scale": 7.5,
        "sampler_name": "Euler a",
        "mask_blur": 1,
        "inpainting_full_res": 1,
        "inpainting_full_res_padding": 32,
        "inpainting_mask_invert": 0,
        "initial_noise_multiplier": 1,
        "strength": 0.85,
        "image_base64": "{{base64 encoded image}}",
        "mask_image_base64": "{{base64 encoded mask image}}"
    }
}'
```

`Response:`

`````js theme={"system"}
{
    "code": 0,
    "msg": "",
    "data": {
        "task_id": "270f4fba-2cb0-4a56-8b82-xxxx"
    }
}
````"model_name":"realisticVisionV40_v40VAE-inpainting_81543.safetensors"` in body represent inpainting models, which, can be accessed in API /v3/model with `sd_name` like %inpainting%.

`Request:`
```bash
curl --location --request POST 'http://api.novita.ai/v3/async/inpainting' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{API Key}}' \
--data-raw '{
    "extra": {
        "response_image_type": "jpeg"
    },
    "request": {
        "model_name": "realisticVisionV40_v40VAE-inpainting_81543.safetensors",
        "prompt": "Leonardo DiCaprio",
        "negative_prompt": "(deformed iris, deformed pupils, semi-realistic, cgi, 3d, render, sketch, cartoon, drawing, anime), text, cropped, out of frame, worst quality, low quality, jpeg artifacts, ugly, duplicate, morbid, mutilated, extra fingers, mutated hands, poorly drawn hands, poorly drawn face, mutation, deformed, blurry, dehydrated, bad anatomy, bad proportions, extra limbs, cloned face, disfigured, gross proportions, malformed limbs, missing arms, missing legs, extra arms, extra legs, fused fingers, too many fingers, long neck, BadDream, UnrealisticDream",
        "image_num": 1,
        "steps": 25,
        "seed": -1,
        "clip_skip": 1,
        "guidance_scale": 7.5,
        "sampler_name": "Euler a",
        "mask_blur": 1,
        "inpainting_full_res": 1,
        "inpainting_full_res_padding": 32,
        "inpainting_mask_invert": 0,
        "initial_noise_multiplier": 1,
        "strength": 0.85,
        "image_base64": "{{base64 encoded image}}",
        "mask_image_base64": "{{base64 encoded mask image}}"
    }
}'
`````

`Response:`

```js theme={"system"}
{
    "code": 0,
    "msg": "",
    "data": {
        "task_id": "270f4fba-2cb0-4a56-8b82-xxxx"
    }
}
```


# Introduction
Source: https://novita.ai/docs/api-reference/model-apis-introduction



For LLM API, Novita AI provides compatibility with the OpenAI API standard, allowing you to use official OpenAI SDKs like openai-python, openai-node, and others to interact with our API. This means you can easily migrate your existing OpenAI-based applications to Novita AI with minimal code changes. Additionally, you can develop your own custom SDKs by following our [API reference](/api-reference/model-apis-llm-create-chat-completion), which details all available endpoints, parameters, and response formats. Our API supports key features like chat chat completions, completions, model listings, and model information retrieval, making it a flexible solution for your LLM needs.

<Card title="LLM API" icon="robot" href="/api-reference/model-apis-llm-create-chat-completion">
  Create Chat Completion / Create Completion / List Models / Retrieve Model.
</Card>

For Images, Audio and Video APIs, Novita AI provides official SDKs for Python and JavaScript to help you quickly integrate with our services. You can find detailed SDK guides and examples [here](/guides/model-apis-sdks). Additionally, we provide [API reference documentation](/api-reference/model-apis-introduction) that covers all endpoints, parameters, and response formats if you prefer to implement the integration yourself. Our APIs support a wide range of multimodal AI capabilities including text-to-image, image-to-image, text-to-video, image-to-video, and text-to-speech...

<Card title="Image, Audio and Video API" icon="photo-film" href="/api-reference/model-apis-llm-create-chat-completion">
  Text-to-Image / Image-to-Image / Text-to-Video / Image-to-Video / Text-to-Speech...
</Card>


# Kling V2.5 Turbo Image to Video
Source: https://novita.ai/docs/api-reference/model-apis-kling-2.5-turbo-i2v

POST https://api.novita.ai/v3/async/kling-2.5-turbo-i2v

Kling 2.5 Turbo Image-to-Video can generate cinematic, high-quality videos from a single image and text prompt. It features a new text-temporal engine, enhanced motion rendering, and faster inference speed, resulting in smooth action and content that closely matches the given prompt.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The initial frame image for the video. Supported formats: `.jpg`, `.jpeg`, `.png`. Image size must not exceed 10MB. Minimum resolution: 300x300 pixels.
</ParamField>

<ParamField type="string">
  Positive prompt text for video generation. Maximum length: 2500 characters.
</ParamField>

<ParamField type="string">
  Duration of the generated video (in seconds).

  Allowed values: `5`, `10`
</ParamField>

<ParamField type="number">
  Controls generation flexibility. Higher values increase adherence to the prompt but reduce creative freedom.

  Value range: 0 to 1
</ParamField>

<ParamField type="string">
  Video generation mode. Allowed value:

  * `pro`: professional mode
</ParamField>

<ParamField type="string">
  Negative prompt to avoid undesired content in the video. Maximum length: 2500 characters.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Kling V2.5 Turbo Text to Video
Source: https://novita.ai/docs/api-reference/model-apis-kling-2.5-turbo-t2v

POST https://api.novita.ai/v3/async/kling-2.5-turbo-t2v

Kling 2.5 Turbo is an advanced text-to-video model capable of generating ultra-smooth motion, cinematic visuals, and outputs that closely adhere to the input prompt.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Positive text prompt that guides the video generation. Maximum length: 2500 characters.
</ParamField>

<ParamField type="string">
  Duration of the generated video in seconds.

  Available options: `5`, `10`
</ParamField>

<ParamField type="string">
  Aspect ratio of the output video.

  Available options: `16:9`, `9:16`, `1:1`
</ParamField>

<ParamField type="number">
  Controls the adherence to the prompt. Higher values result in outputs that more strictly follow the prompt, while lower values allow for more creativity.

  Range: 0 to 1
</ParamField>

<ParamField type="string">
  Video generation mode. Supported values:

  * `pro`: Professional mode
</ParamField>

<ParamField type="string">
  Negative text prompt to specify elements to avoid in the output. Maximum length: 2500 characters.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Kling-o1 Image to Video
Source: https://novita.ai/docs/api-reference/model-apis-kling-o1-i2v

POST https://api.novita.ai/v3/async/kling-o1-i2v

Kling Omni Video O1 image-to-video tool leverages MVL (Multimodal Vision Language) technology to convert static images into dynamic cinematic videos. It maintains subject consistency while adding natural motion, physical simulation, and smooth scene dynamics.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  first\_frame is the first frame
</ParamField>

<ParamField type="string">
  The positive prompt for the generation.
</ParamField>

<ParamField type="integer">
  The duration of the generated media in seconds.

  Optional values: `5`, `10`
</ParamField>

<ParamField type="string">
  last\_frame is the last frame.
</ParamField>

<ParamField type="string">
  The aspect ratio of the generated video.

  Optional values: `16:9`, `9:16`, `1:1`
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Kling-o1 Reference Video Generation
Source: https://novita.ai/docs/api-reference/model-apis-kling-o1-ref2v

POST https://api.novita.ai/v3/async/kling-o1-ref2v

Kling Omni Video O1 reference video generation feature leverages character, prop, or scene references to generate creative videos from multiple perspectives. It extracts subject features and creates new video content while maintaining consistency between frames.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The video URL.
</ParamField>

<ParamField type="array">
  Including reference images of the element, scene, style, etc. Max 7.

  Array length: 0 - 7
</ParamField>

<ParamField type="string">
  The positive prompt for the generation.
</ParamField>

<ParamField type="integer">
  The duration of the generated media in seconds.

  Optional values: `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`
</ParamField>

<ParamField type="string">
  The aspect ratio of the generated video.

  Optional values: `16:9`, `9:16`, `1:1`
</ParamField>

<ParamField type="boolean">
  Select whether to keep the video original sound through the parameter.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Kling-o1 Text to Video
Source: https://novita.ai/docs/api-reference/model-apis-kling-o1-t2v

POST https://api.novita.ai/v3/async/kling-o1-t2v

Kling Omni Video O1 is Kuaishou's first unified multimodal video model using MVL (Multimodal Vision Language) technology. Its text-to-video mode can generate cinematic videos based on text prompts while maintaining subject consistency, natural physical simulation, and precise semantic understanding.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The positive prompt for the generation.
</ParamField>

<ParamField type="integer">
  The duration of the generated media in seconds.

  Optional values: `5`, `10`
</ParamField>

<ParamField type="string">
  The aspect ratio of the generated video.

  Optional values: `16:9`, `9:16`, `1:1`
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Kling-o1 Video Editing
Source: https://novita.ai/docs/api-reference/model-apis-kling-o1-video-edit

POST https://api.novita.ai/v3/async/kling-o1-video-edit

Kling Omni Video O1 video editor supports conversational video editing through natural language commands. With simple text instructions such as "remove pedestrians" or "change day to dusk", you can remove objects, replace backgrounds, modify styles, adjust weather/lighting, and transform scenes.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The video URL.
</ParamField>

<ParamField type="array">
  Including reference images of the element, scene, style, etc. Max 4.

  Array length: 0 - 4
</ParamField>

<ParamField type="string">
  The positive prompt for the generation.
</ParamField>

<ParamField type="boolean">
  Whether to use fast mode
</ParamField>

<ParamField type="string">
  The aspect ratio of the generated video.

  Optional values: `16:9`, `9:16`, `1:1`
</ParamField>

<ParamField type="boolean">
  Select whether to keep the video original sound through the parameter.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# KLING V1.6 Image to Video
Source: https://novita.ai/docs/api-reference/model-apis-kling-v1.6-i2v

POST https://api.novita.ai/v3/async/kling-v1.6-i2v

KLING V1.6 Image to Video is an AI image-to-video generation model developed by the Kuaishou AI Team. It transforms images into dynamic 5-second videos at 720p / 1080p resolution, offering high-quality visual outputs with enhanced motion and semantic understanding.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The mode of the video generation.

  Supports:

  * `Standard`: fast creation, lower cost, and generate 720p video.
  * `Professional`: high quality, higher cost, generate 1080p video, and allow set an end frame.

  Default: `Standard`.
</ParamField>

<ParamField type="string">
  The URL of the start frame image to be used for video generation.
</ParamField>

<ParamField type="string">
  The URL of the end frame image to be used for video generation.

  <Warning>Only available when `mode` is `Professional`.</Warning>
</ParamField>

<ParamField type="string">
  Prompt text required to guide the generation.

  Range: `1 <= x <= 2000`.
</ParamField>

<ParamField type="string">
  Negative prompts instruct the model on what elements to avoid generating.

  Range: `0 <= x <= 2000`.
</ParamField>

<ParamField type="integer">
  The length of the generated video in seconds. Default: `5`.<br />
  Optional values: `5`, `10`
</ParamField>

<ParamField type="float">
  Guidance scale parameter controls how closely the generated content follows the prompt.

  Range: `0 <= x <= 1`. Default: `0.5`.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>

## Example

Here is an example of how to use the KLING V1.6 Image to Video API.

1. Generate a task\_id by sending a POST request to the KLING V1.6 Image to Video API.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/kling-v1.6-i2v' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "mode": "Standard", 
    "image_url": "https://pub-f964a1c641c04024bce400ad128c8cd6.r2.dev/kling-v1.6-i2v-image",
    "prompt": "A cute dog standing up from a sitting position while wearing sunglasses",
    "negative_prompt": "low quality",
    "guidance_scale": 0.65
}'
```

`Response:`

```js theme={"system"}
{
    "task_id": "{Returned Task ID}"
}
```

2. Use `task_id` to get output videos.

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get videos url in `videos` of response.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id={Returned Task ID}' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "task": {
        "task_id": "{Returned Task ID}",
        "task_type": "KLING_V16_I2V_STANDARD",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 100
    },
    "images": [],
    "videos": [
        {
            "video_url": "{The URL of the generated video}",
            "video_url_ttl": "3600",
            "video_type": "mp4"
        }
    ]
}
```

`Video files:`

<video />


# KLING V1.6 Text to Video
Source: https://novita.ai/docs/api-reference/model-apis-kling-v1.6-t2v

POST https://api.novita.ai/v3/async/kling-v1.6-t2v

KLING V1.6 Text to Video is an AI text-to-video generation model developed by the Kuaishou AI Team. It transforms textual descriptions into dynamic 5-second videos at 720p resolution, offering high-quality visual outputs with enhanced motion and semantic understanding.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The mode of the video generation.

  Supports:

  * `Standard`: fast creation, lower cost, and generate 720p video.

  Default: `Standard`.
</ParamField>

<ParamField type="string">
  Prompt text required to guide the generation.

  Range: `1 <= x <= 2000`.
</ParamField>

<ParamField type="string">
  Negative prompts instruct the model on what elements to avoid generating.

  Range: `0 <= x <= 2000`.
</ParamField>

<ParamField type="integer">
  The length of the generated video in seconds. Default: `5`.<br />
  Optional values: `5`, `10`
</ParamField>

<ParamField type="float">
  Guidance scale parameter controls how closely the generated content follows the prompt.

  Range: `0 <= x <= 1`. Default: `0.5`.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>

## Example

Here is an example of how to use the KLING V1.6 Text to Video API.

1. Generate a task\_id by sending a POST request to the KLING V1.6 Text to Video API.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/kling-v1.6-t2v' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "mode": "Standard", 
    "prompt": "A cute dog standing up from a sitting position while wearing sunglasses",
    "negative_prompt": "low quality",
    "guidance_scale": 0.6,
}'
```

`Response:`

```js theme={"system"}
{
    "task_id": "{Returned Task ID}"
}
```

2. Use `task_id` to get output videos.

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get videos url in `videos` of response.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id={Returned Task ID}' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "task": {
        "task_id": "{Returned Task ID}",
        "task_type": "KLING_V16_T2V_STANDARD",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 100
    },
    "images": [],
    "videos": [
        {
            "video_url": "{The URL of the generated video}",
            "video_url_ttl": "3600",
            "video_type": "mp4"
        }
    ]
}
```

`Video files:`

<video />


# Kling V2.1 Image to Video
Source: https://novita.ai/docs/api-reference/model-apis-kling-v2.1-i2v

POST https://api.novita.ai/v3/async/kling-v2.1-i2v

Kling V2.1 is the latest evolution of Kuaishou's AI-powered video‑generation model, designed to seamlessly create short, cinematic‑quality clips from a single image or a text prompt. It represents a major leap forward from Kling 2.0, emphasizing motion fidelity, visual coherence, and prompt accuracy.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  First frame of the video; Supported image formats include `.jpg`, `.jpeg`, `.png`; The image file size cannot exceed 10MB, and the image resolution should not be less than 300\*300px.
</ParamField>

<ParamField type="string">
  Text prompt for generation; Positive text prompt; Cannot exceed 2500 characters.
</ParamField>

<ParamField type="string">
  The mode of the video generation.

  Supports:

  * `Standard`: fast creation, lower cost, and generate 720p video.
  * `Professional`: high quality, higher cost, generate 1080p video.

  Default: `Standard`.
</ParamField>

<ParamField type="string">
  The duration of the generated media in seconds.

  Available options: `5`, `10`
</ParamField>

<ParamField type="number">
  The guidance scale to use for the generation.

  Range: 0 to 1
  Step: 0.01
</ParamField>

<ParamField type="string">
  Negative text prompt; Cannot exceed 2500 characters.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Kling V2.1 Master Image to Video
Source: https://novita.ai/docs/api-reference/model-apis-kling-v2.1-i2v-master

POST https://api.novita.ai/v3/async/kling-v2.1-i2v-master

Kling 2.1 Master: The premium endpoint for Kling 2.1, designed for top-tier image-to-video generation with unparalleled motion fluidity, cinematic visuals, exceptional prompt precision, and 1080p video quality.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  First frame of the video; Supported image formats include `.jpg`, `.jpeg`, `.png`; The image file size cannot exceed 10MB, and the image resolution should not be less than 300\*300px.
</ParamField>

<ParamField type="string">
  Text prompt for generation; Positive text prompt; Cannot exceed 2500 characters.
</ParamField>

<ParamField type="string">
  The duration of the generated media in seconds.

  Available options: `5`, `10`
</ParamField>

<ParamField type="number">
  The guidance scale to use for the generation.

  Range: 0 to 1
  Step: 0.01
</ParamField>

<ParamField type="string">
  Negative text prompt; Cannot exceed 2500 characters.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Kling V2.1 Master Text to Video
Source: https://novita.ai/docs/api-reference/model-apis-kling-v2.1-t2v-master

POST https://api.novita.ai/v3/async/kling-v2.1-t2v-master

Kling V2.1 is the latest evolution of Kuaishou's AI-powered video‑generation model, designed to seamlessly create short, cinematic‑quality clips from a single image or a text prompt. It represents a major leap forward from Kling 2.0, emphasizing motion fidelity, visual coherence, and prompt accuracy.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Text prompt for generation; Positive text prompt; Cannot exceed 2500 characters.
</ParamField>

<ParamField type="string">
  The duration of the generated media in seconds.

  Available options: `5`, `10`
</ParamField>

<ParamField type="string">
  Generated video aspect ratio.

  Available options: `16:9`, `9:16`, `1:1`
</ParamField>

<ParamField type="number">
  The guidance scale to use for the generation.

  Range: 0 to 1
  Step: 0.1
</ParamField>

<ParamField type="string">
  Negative text prompt; Cannot exceed 2500 characters.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# List LoRA Training Task
Source: https://novita.ai/docs/api-reference/model-apis-list-training-task

GET https://api.novita.ai/v3/training

**This API retrieves information about all the user's training tasks.**

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<ParamField type="integer">
  The number of model records to query per request, within the range (0, 100].
</ParamField>

<ParamField type="string">
  The pagination.cursor parameter specifies the record from which to start returning results. If it is empty, the results will start from the beginning. Generally, the content of the next page is obtained by passing the next\_cursor field value from the response packet.
</ParamField>

## Response

<ResponseField name="tasks" type="object[]">
  <Expandable title="properties">
    <ResponseField name="task_name" type="string">
      The name of the training task.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      The unique identifier of the training task, which can be used to query the training status and results.
    </ResponseField>

    <ResponseField name="task_type" type="string">
      The type of the training task.
    </ResponseField>

    <ResponseField name="task_status" type="string">
      Represents the current status of a task, which is particularly useful for monitoring and managing the progress of training tasks. Each status indicates a specific phase in the task's lifecycle: UNKNOWN - The status of the task is not known or has not been updated yet; QUEUING - The task is in the queue waiting to be processed; TRAINING - The task is currently undergoing training processes; SUCCESS - The task has been completed successfully; CANCELED - The task was canceled before completion; FAILED - The task failed to complete successfully due to an error or issue.<br />
      Enum: `UNKNOWN`, `QUEUING`, `TRAINING`, `SUCCESS`, `CANCELED`, `FAILED`
    </ResponseField>

    <ResponseField name="created_at" type="integer">
      The timestamp of when the task was created.
    </ResponseField>

    <ResponseField name="models" type="object[]">
      <Expandable title="properties">
        <ResponseField name="model_name" type="string">
          The name of the model.
        </ResponseField>

        <ResponseField name="model_status" type="string">
          The status of the model. When the model is being deployed, the status will be `DEPLOYING`, and when the model is serving, the status will be `SERVING`.<br />
          Enum: `DEPLOYING`, `SERVING`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="properties">
    <ResponseField name="next_cursor" type="string" />
  </Expandable>
</ResponseField>

## Example

In this step, we can obtain all the information about trained models.

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/training?pagination.limit=10&pagination.cursor=c_0' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "tasks": [
        {
            "task_name": "test_01",
            "task_id": "a0c4cc90-0296-4972-a1d8-e6e227daf094",
            "task_type": "subject",
            "task_status": "SUCCESS",
            "created_at": 1699325415,
            "models": [
                {
                    "model_name": "model_1699325939_E83A88DAC5.safetensors",
                    "model_status": "SERVING"
                }
            ]
        },
        {
            "task_name": "test_02",
            "task_id": "51e9bf41-8f7a-464d-b5ad-2fa217a1ec93",
            "task_type": "subject",
            "task_status": "SUCCESS",
            "created_at": 1699267268,
            "models": [
                {
                    "model_name": "model_1699267603_27F0D9C81C.safetensors",
                    "model_status": "SERVING"
                }
            ]
        },
        {
            "task_name": "test_03",
            "task_id": "7bd205ab-63e9-452b-9a66-39c597000eaa",
            "task_type": "subject",
            "task_status": "FAILED",
            "created_at": 1699264338,
            "models": []
        }
    ],
    "pagination": {
        "next_cursor": "c_10"
    }
}
```

* `task_name`: The name of the training task.
* `task_id`: The unique identifier of the training task, which can be used to query the training status and results.
* `task_type`: The type of the training task.
* `task_status`: The status of the training task. Enum: `UNKNOWN`, `QUEUING`, `TRAINING`, `SUCCESS`, `CANCELED`, `FAILED`.
* `created_at`: The timestamp of when the training task was created.
* `models`: The trained models.
* `model_name`: The name of the model.
* `model_status`: The status of the model. Enum: `DEPLOYING`, `SERVING`.


# Cancel batch
Source: https://novita.ai/docs/api-reference/model-apis-llm-cancel-batch

POST https://api.novita.ai/openai/v1/batches/{batch_id}/cancel

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Path Parameters

<ParamField type="string">
  The unique identifier of the batch job to check.
</ParamField>

## Response

<ResponseField name="id" type="string">
  A unique identifier for the batch job.
</ResponseField>

<ResponseField name="object" type="string">
  The object type, which is always `batch`.
</ResponseField>

<ResponseField name="endpoint" type="string">
  The API endpoint that the batch job is using for processing requests.
</ResponseField>

<ResponseField name="input_file_id" type="string">
  The ID of the input file containing the batch requests.
</ResponseField>

<ResponseField name="output_file_id" type="string">
  The ID of the output file containing the batch results. Empty until the batch is completed.
</ResponseField>

<ResponseField name="error_file_id" type="string">
  The ID of the error file containing any errors that occurred during batch processing. Empty until errors occur.
</ResponseField>

<ResponseField name="completion_window" type="string">
  The time window for batch completion. Currently fixed at `48h`.
</ResponseField>

<ResponseField name="in_progress_at" type="string | null">
  The timestamp when the batch started processing. Null if not yet started.
</ResponseField>

<ResponseField name="expires_at" type="string | null">
  The timestamp when the batch will expire. Null if not set.
</ResponseField>

<ResponseField name="finalizing_at" type="string | null">
  The timestamp when the batch started finalizing. Null if not yet finalizing.
</ResponseField>

<ResponseField name="completed_at" type="string | null">
  The timestamp when the batch was completed. Null if not yet completed.
</ResponseField>

<ResponseField name="failed_at" type="string | null">
  The timestamp when the batch failed. Null if not failed.
</ResponseField>

<ResponseField name="expired_at" type="string | null">
  The timestamp when the batch expired. Null if not expired.
</ResponseField>

<ResponseField name="cancelling_at" type="string | null">
  The timestamp when the batch started cancelling. Null if not cancelling.
</ResponseField>

<ResponseField name="cancelled_at" type="string | null">
  The timestamp when the batch was cancelled. Null if not cancelled.
</ResponseField>

<ResponseField name="status" type="string">
  The current status of the batch job.

  Available statuses:

  * `VALIDATING` - The input file is being validated before the batch can begin
  * `PROGRESS` - Batch is in progress
  * `COMPLETED` - Batch processing completed successfully
  * `FAILED` - Batch processing failed
  * `EXPIRED` - Batch exceeded deadline
  * `CANCELLING` - Batch is being cancelled
  * `CANCELLED` - Batch was cancelled
</ResponseField>

<ResponseField name="errors" type="string">
  Error messages if any errors occurred during batch processing.
</ResponseField>

<ResponseField name="version" type="integer">
  The version number of the batch job.
</ResponseField>

<ResponseField name="created_at" type="string">
  The timestamp when the batch job was created.
</ResponseField>

<ResponseField name="updated_at" type="string | null">
  The timestamp when the batch job was last updated. Null if never updated.
</ResponseField>

<ResponseField name="created_by" type="string">
  The unique identifier of the user who created the batch job.
</ResponseField>

<ResponseField name="created_by_key_id" type="string">
  The API key ID used to create the batch job.
</ResponseField>

<ResponseField name="remark" type="string">
  Optional remark or note for the batch job.
</ResponseField>

<ResponseField name="total" type="integer">
  The total number of requests in the batch.
</ResponseField>

<ResponseField name="completed" type="integer">
  The number of completed requests in the batch.
</ResponseField>

<ResponseField name="failed" type="integer">
  The number of failed requests in the batch.
</ResponseField>

<ResponseField name="metadata" type="object | null">
  Additional metadata associated with the batch job. Null if no metadata is provided.
</ResponseField>

<ResponseField name="request_counts" type="object">
  Detailed request count information.

  <Expandable title="properties">
    <ResponseField name="total" type="integer">
      The total number of requests in the batch.
    </ResponseField>

    <ResponseField name="completed" type="integer">
      The number of successfully completed requests.
    </ResponseField>

    <ResponseField name="failed" type="integer">
      The number of failed requests.
    </ResponseField>
  </Expandable>
</ResponseField>


# Create batch
Source: https://novita.ai/docs/api-reference/model-apis-llm-create-batch

POST https://api.novita.ai/openai/v1/batches

After successfully [uploading the input file](/api-reference/model-apis-llm-upload-batch-input-file), initiate a batch by using the ID of the uploaded file. Note that the completion window is set to a fixed duration of 48 hours and cannot be modified.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  ID of the uploaded input file containing batch requests
</ParamField>

<ParamField type="string">
  The endpoint to use for batch processing. Available endpoints are `/v1/chat/completions` and `/v1/completions`.

  <Warning>
    Set the `endpoint` parameter to `/v1/chat/completions` or `/v1/completions` for OpenAI API compatibility.
  </Warning>
</ParamField>

<ParamField type="string">
  Time window for batch completion. The completion window is fixed at `48h` and is currently non-adjustable.
</ParamField>

## Response

<ResponseField name="id" type="string">
  A unique identifier for the batch job.
</ResponseField>

<ResponseField name="object" type="string">
  The object type, which is always `batch`.
</ResponseField>

<ResponseField name="endpoint" type="string">
  The API endpoint that the batch job is using for processing requests.
</ResponseField>

<ResponseField name="input_file_id" type="string">
  The ID of the input file containing the batch requests.
</ResponseField>

<ResponseField name="output_file_id" type="string">
  The ID of the output file containing the batch results. Empty until the batch is completed.
</ResponseField>

<ResponseField name="error_file_id" type="string">
  The ID of the error file containing any errors that occurred during batch processing. Empty until errors occur.
</ResponseField>

<ResponseField name="completion_window" type="string">
  The time window for batch completion. Currently fixed at `48h`.
</ResponseField>

<ResponseField name="in_progress_at" type="string | null">
  The timestamp when the batch started processing. Null if not yet started.
</ResponseField>

<ResponseField name="expires_at" type="string | null">
  The timestamp when the batch will expire. Null if not set.
</ResponseField>

<ResponseField name="finalizing_at" type="string | null">
  The timestamp when the batch started finalizing. Null if not yet finalizing.
</ResponseField>

<ResponseField name="completed_at" type="string | null">
  The timestamp when the batch was completed. Null if not yet completed.
</ResponseField>

<ResponseField name="failed_at" type="string | null">
  The timestamp when the batch failed. Null if not failed.
</ResponseField>

<ResponseField name="expired_at" type="string | null">
  The timestamp when the batch expired. Null if not expired.
</ResponseField>

<ResponseField name="cancelling_at" type="string | null">
  The timestamp when the batch started cancelling. Null if not cancelling.
</ResponseField>

<ResponseField name="cancelled_at" type="string | null">
  The timestamp when the batch was cancelled. Null if not cancelled.
</ResponseField>

<ResponseField name="status" type="string">
  The current status of the batch job.

  Available statuses:

  * `VALIDATING` - The input file is being validated before the batch can begin
  * `PROGRESS` - Batch is in progress
  * `COMPLETED` - Batch processing completed successfully
  * `FAILED` - Batch processing failed
  * `EXPIRED` - Batch exceeded deadline
  * `CANCELLING` - Batch is being cancelled
  * `CANCELLED` - Batch was cancelled
</ResponseField>

<ResponseField name="errors" type="string">
  Error messages if any errors occurred during batch processing.
</ResponseField>

<ResponseField name="version" type="integer">
  The version number of the batch job.
</ResponseField>

<ResponseField name="created_at" type="string">
  The timestamp when the batch job was created.
</ResponseField>

<ResponseField name="updated_at" type="string | null">
  The timestamp when the batch job was last updated. Null if never updated.
</ResponseField>

<ResponseField name="created_by" type="string">
  The unique identifier of the user who created the batch job.
</ResponseField>

<ResponseField name="created_by_key_id" type="string">
  The API key ID used to create the batch job.
</ResponseField>

<ResponseField name="remark" type="string">
  Optional remark or note for the batch job.
</ResponseField>

<ResponseField name="total" type="integer">
  The total number of requests in the batch.
</ResponseField>

<ResponseField name="completed" type="integer">
  The number of completed requests in the batch.
</ResponseField>

<ResponseField name="failed" type="integer">
  The number of failed requests in the batch.
</ResponseField>

<ResponseField name="metadata" type="object | null">
  Additional metadata associated with the batch job. Null if no metadata is provided.
</ResponseField>

<ResponseField name="request_counts" type="object">
  Detailed request count information.

  <Expandable title="properties">
    <ResponseField name="total" type="integer">
      The total number of requests in the batch.
    </ResponseField>

    <ResponseField name="completed" type="integer">
      The number of successfully completed requests.
    </ResponseField>

    <ResponseField name="failed" type="integer">
      The number of failed requests.
    </ResponseField>
  </Expandable>
</ResponseField>


# Create chat completion
Source: https://novita.ai/docs/api-reference/model-apis-llm-create-chat-completion

POST https://api.novita.ai/openai/v1/chat/completions

Creates a model response for the given chat conversation.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The name of the model to use.
</ParamField>

<ParamField type="object[]">
  A list of messages comprising the conversation so far.

  <Expandable title="properties">
    <ParamField type="string | object[] | null">
      The contents of the message. content is required for all messages, and may be null for assistant messages with function calls.

      You may use the following parameters depending on the modality.

      <Frame>
        <div>
          <Tabs>
            <Tab title="Text content">
              <p>Option 1:</p>
              <p>You can use the string type to represent the text contents of the message. </p>

              <br />

              <p>Option 2:</p>
              <p>Use an array of content parts, object\[]. Detailed fields are as follows:</p>

              <ParamField type="string">
                The type of the content part, in this case `text`.
              </ParamField>

              <ParamField type="string">
                The text content.
              </ParamField>
            </Tab>

            <Tab title="Image content">
              <p>Only vision language models can be used.</p>
              <p>An array of content parts, object\[]. Detailed fields are as follows:</p>

              <ParamField type="string">
                The type of the content part, in this case `image_url`.
              </ParamField>

              <ParamField type="string">
                <Expandable title="properties">
                  <ParamField type="string">
                    Either a URL of the image or the base64 encoded image data.
                  </ParamField>
                </Expandable>
              </ParamField>
            </Tab>

            <Tab title="Video content">
              <p>Only models that support video can be used.</p>
              <p>An array of content parts, object\[]. Detailed fields are as follows:</p>

              <ParamField type="string">
                The type of the content part, in this case `video_url`.
              </ParamField>

              <ParamField type="string">
                <Expandable title="properties">
                  <ParamField type="string">
                    URL of the video.
                  </ParamField>
                </Expandable>
              </ParamField>
            </Tab>

            <Tab title="Audio content">
              <p>Only models that support audio can be used.</p>
              <p>Output modality parameters:</p>

              <ParamField type="string[]">
                Set the modality of the model output. Currently support two types: `["text"]`, `["text","audio"]`.
                If `["text"]` is passed in, the model only returns text content. If `["text","audio"]` is passed in, the model will return both text content and audio content.
                Default is `["text"]`.
              </ParamField>

              <p>An array of content parts, object\[]. Detailed fields are as follows:</p>

              <ParamField type="string">
                The type of the content part, in this case `input_audio`.
              </ParamField>

              <ParamField type="object">
                <Expandable title="properties">
                  <ParamField type="string">
                    The URL or Base64 encoded data of the audio.
                  </ParamField>

                  <ParamField type="string">
                    The format of the audio.
                  </ParamField>
                </Expandable>
              </ParamField>
            </Tab>
          </Tabs>
        </div>
      </Frame>
    </ParamField>

    <ParamField type="string">
      The role of the messages author. One of system, user, or assistant.

      Enum: `system`, `user`, `assistant`
    </ParamField>

    <ParamField type="string">
      The name of the author of this message. May contain a-z, A-Z, 0-9, and underscores, with a maximum length of 64 characters.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="integer">
  The maximum number of tokens to generate in the completion.

  If the token count of your prompt (previous messages) plus max\_tokens exceed the model's context length, the behavior is depends on context\_length\_exceeded\_behavior. By default, max\_tokens will be lowered to fit in the context window instead of returning an error.
</ParamField>

<ParamField type="boolean | null">
  Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent events (SSE) as they become available, with the stream terminated by a `data: [DONE]` message.
</ParamField>

<ParamField type="object | null">
  Options for streaming response. Only set this when you set stream: true.

  <Expandable title="properties">
    <ParamField type="boolean">
      If set, an additional chunk will be streamed before the data: \[DONE] message. The usage field on this chunk shows the token usage statistics for the entire request, and the choices field will always be an empty array. All other chunks will also include a usage field, but with a null value.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="integer | null">
  How many completions to generate for each prompt.

  Note: Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for max\_tokens and stop.

  Required range: `1 < x < 128`
</ParamField>

<ParamField type="integer | null">
  If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result.
</ParamField>

<ParamField type="number | null">
  Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.

  Reasonable value is around 0.1 to 1 if the aim is to just reduce repetitive samples somewhat. If the aim is to strongly suppress repetition, then one can increase the coefficients up to 2, but this can noticeably degrade the quality of samples. Negative values can be used to increase the likelihood of repetition.

  See also presence\_penalty for penalizing tokens that have at least one appearance at a fixed rate.

  Required range: `-2 < x < 2`
</ParamField>

<ParamField type="number | null">
  Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.

  Reasonable value is around 0.1 to 1 if the aim is to just reduce repetitive samples somewhat. If the aim is to strongly suppress repetition, then one can increase the coefficients up to 2, but this can noticeably degrade the quality of samples. Negative values can be used to increase the likelihood of repetition.

  See also `frequency_penalty` for penalizing tokens at an increasing rate depending on how often they appear.

  Required range: `-2 < x < 2`
</ParamField>

<ParamField type="number | null">
  Applies a penalty to repeated tokens to discourage or encourage repetition. A value of 1.0 means no penalty, allowing free repetition. Values above 1.0 penalize repetition, reducing the likelihood of repeating tokens. Values between 0.0 and 1.0 reward repetition, increasing the chance of repeated tokens. For a good balance, a value of 1.2 is often recommended. Note that the penalty is applied to both the generated output and the prompt in decoder-only models.

  Required range: `0 < x < 2`
</ParamField>

<ParamField type="string | null">
  Up to 4 sequences where the API will stop generating further tokens. The returned text will contain the stop sequence.
</ParamField>

<ParamField type="number | null">
  What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.

  We generally recommend altering this or `top_p` but not both.

  Required range: `0 < x < 2`
</ParamField>

<ParamField type="number | null">
  An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top\_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.

  Required range: `0 < x <= 1`
</ParamField>

<ParamField type="integer | null">
  Top-k sampling is another sampling method where the k most probable next tokens are filtered and the probability mass is redistributed among only those k next tokens. The value of k controls the number of candidates for the next token at each step during text generation.

  Required range: `1 < x < 128`
</ParamField>

<ParamField type="number | null">
  float that represents the minimum probability for a token to be considered, relative to the probability of the most likely token.

  Required range: `0 <= x <= 1`
</ParamField>

<ParamField type="map[string, integer] | null">
  Modify the likelihood of specified tokens appearing in the completion.

  Accepts a JSON object that maps tokens to an associated bias value from -100 to 100.
  Mathematically, the bias is added to the logits generated by the model prior to
  sampling. The exact effect will vary per model.

  For example, by setting `"logit_bias":{"1639": 6}` will increase the likelihood of the token with token ID 1639.
</ParamField>

<ParamField type="boolean | null">
  Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message.
</ParamField>

<ParamField type="integer | null">
  An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability.  `logprobs` must be set to true if this parameter is used.

  Required range: `0 <= x <= 20`
</ParamField>

<ParamField type="object[] | null">
  A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for.

  Learn more about function calling in the [function calling guide](/guides/llm-function-calling).

  <Expandable title="properties">
    <ParamField type="string">
      The type of the tool.

      Supported types: `function`
    </ParamField>

    <ParamField type="object">
      <Expandable title="properties">
        <ParamField type="string">
          The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
        </ParamField>

        <ParamField type="string | null">
          A description of what the function does, used by the model to choose when and how to call the function.
        </ParamField>

        <ParamField type="object | null">
          The parameters the functions accepts, described as a JSON Schema object. See the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format.
        </ParamField>

        <ParamField type="boolean">
          Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the parameters field.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object | null">
  Allows to force the model to produce specific output format.

  Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema.

  Setting to `{ "type": "json_object" }` enables the older JSON mode, which ensures the message the model generates is valid JSON. Using `json_schema` is preferred for models that support it.

  <Expandable title="properties">
    <ParamField type="string">
      Enum: `text`, `json_object`, `json_schema`
    </ParamField>

    <ParamField type="object | null">
      JSON Schema response format. Used to generate structured JSON responses.

      Only supported when `type` is set to `json_schema`, and also required when `type` is set to `json_schema`.

      Please learn more in the [Structured Outputs guide](/guides/llm-structured-outputs).

      <Expandable title="properties">
        <ParamField type="string">
          The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
        </ParamField>

        <ParamField type="string | null">
          A description of what the response format is for, used by the model to determine how to respond in the format.
        </ParamField>

        <ParamField type="object | null">
          The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas [here](https://json-schema.org/specification).

          Supported types: `string`, `number`, `integer`, `boolean`, `array`, `object`, `enum`, `anyOf`.
        </ParamField>

        <ParamField type="boolean">
          Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is true.

          If you turn on Structured Outputs by supplying `strict: true` and call the API with an unsupported JSON Schema, you will receive an error.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="boolean | null">
  Whether to separate the reasoning from the "content" into "reasoning\_content" field.

  Supported models:

  * `deepseek/deepseek-r1-turbo`
</ParamField>

<ParamField type="boolean | null">
  Controls the switches between thinking and non-thinking modes.

  Supported models:

  * zai-org/glm-4.5
  * deepseek/deepseek-v3.1
  * deepseek/deepseek-v3.1-terminus
  * deepseek/deepseek-v3.2-exp
</ParamField>

## Response

<ResponseField name="choices" type="object[]">
  The list of chat completion choices.

  <Expandable title="properties">
    <ResponseField name="finish_reason" type="string">
      The reason the model stopped generating tokens. This will be "stop" if the model hit a natural stop point or a provided stop sequence, or "length" if the maximum number of tokens specified in the request was reached.

      Available options: `stop`, `length`
    </ResponseField>

    <ResponseField name="index" type="integer">
      The index of the chat completion choice.
    </ResponseField>

    <ResponseField name="message" type="object">
      <Expandable title="properties">
        <ResponseField name="role" type="string">
          The role of the author of this message.

          Available options: `system`, `user`, `assistant`
        </ResponseField>

        <ResponseField name="content" type="string | null">
          The contents of the message.
        </ResponseField>

        <ResponseField name="reasoning_content" type="string | null">
          The contents of the reasoning steps.

          <Warning>
            This field will only be available when `separate_reasoning` is set to true.
          </Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created" type="integer">
  The Unix time in seconds when the response was generated.
</ResponseField>

<ResponseField name="id" type="string">
  A unique identifier of the response.
</ResponseField>

<ResponseField name="model" type="string">
  The model used for the chat completion.
</ResponseField>

<ResponseField name="object" type="string">
  The object type, which is always `chat.completion`.
</ResponseField>

<ResponseField name="usage" type="object">
  Usage statistics.

  For streaming responses, usage field is included in the very last response chunk returned.

  <Expandable title="properties">
    <ResponseField name="completion_tokens" type="integer">
      The number of tokens in the generated completion.
    </ResponseField>

    <ResponseField name="prompt_tokens" type="integer">
      The number of tokens in the prompt.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      The total number of tokens used in the request (prompt + completion).
    </ResponseField>
  </Expandable>
</ResponseField>


# Create completion
Source: https://novita.ai/docs/api-reference/model-apis-llm-create-completion

POST https://api.novita.ai/openai/v1/completions

Creates a completion for the provided prompt and parameters.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The name of the model to use.
</ParamField>

<ParamField type="string">
  The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays.
</ParamField>

<ParamField type="integer">
  The maximum number of tokens that can be generated in the completion.

  The token count of your prompt plus max\_tokens cannot exceed the model's context length.
</ParamField>

<ParamField type="boolean | null">
  Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent events (SSE) as they become available, with the stream terminated by a `data: [DONE]` message.
</ParamField>

<ParamField type="object | null">
  Options for streaming response. Only set this when you set stream: true.

  <Expandable title="properties">
    <ParamField type="boolean">
      If set, an additional chunk will be streamed before the data: \[DONE] message. The usage field on this chunk shows the token usage statistics for the entire request, and the choices field will always be an empty array. All other chunks will also include a usage field, but with a null value.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="integer | null">
  How many completions to generate for each prompt.

  Note: Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for max\_tokens and stop.

  Required range: `1 < x < 128`
</ParamField>

<ParamField type="integer | null">
  If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result.
</ParamField>

<ParamField type="number | null">
  Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.

  Reasonable value is around 0.1 to 1 if the aim is to just reduce repetitive samples somewhat. If the aim is to strongly suppress repetition, then one can increase the coefficients up to 2, but this can noticeably degrade the quality of samples. Negative values can be used to increase the likelihood of repetition.

  See also presence\_penalty for penalizing tokens that have at least one appearance at a fixed rate.

  Required range: `-2 < x < 2`
</ParamField>

<ParamField type="number | null">
  Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.

  Reasonable value is around 0.1 to 1 if the aim is to just reduce repetitive samples somewhat. If the aim is to strongly suppress repetition, then one can increase the coefficients up to 2, but this can noticeably degrade the quality of samples. Negative values can be used to increase the likelihood of repetition.

  See also `frequency_penalty` for penalizing tokens at an increasing rate depending on how often they appear.

  Required range: `-2 < x < 2`
</ParamField>

<ParamField type="number | null">
  Applies a penalty to repeated tokens to discourage or encourage repetition. A value of 1.0 means no penalty, allowing free repetition. Values above 1.0 penalize repetition, reducing the likelihood of repeating tokens. Values between 0.0 and 1.0 reward repetition, increasing the chance of repeated tokens. For a good balance, a value of 1.2 is often recommended. Note that the penalty is applied to both the generated output and the prompt in decoder-only models.

  Required range: `0 < x < 2`
</ParamField>

<ParamField type="string | null">
  Up to 4 sequences where the API will stop generating further tokens. The returned text will contain the stop sequence.
</ParamField>

<ParamField type="number | null">
  What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.

  We generally recommend altering this or `top_p` but not both.

  Required range: `0 < x < 2`
</ParamField>

<ParamField type="number | null">
  An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top\_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.

  Required range: `0 < x <= 1`
</ParamField>

<ParamField type="integer | null">
  Top-k sampling is another sampling method where the k most probable next tokens are filtered and the probability mass is redistributed among only those k next tokens. The value of k controls the number of candidates for the next token at each step during text generation.

  Required range: `1 < x < 128`
</ParamField>

<ParamField type="number | null">
  float that represents the minimum probability for a token to be considered, relative to the probability of the most likely token.

  Required range: `0 <= x <= 1`
</ParamField>

<ParamField type="map[string, integer] | null">
  Modify the likelihood of specified tokens appearing in the completion.

  Accepts a JSON object that maps tokens to an associated bias value from -100 to 100.
  Mathematically, the bias is added to the logits generated by the model prior to
  sampling. The exact effect will vary per model.

  For example, by setting `"logit_bias":{"1639": 6}` will increase the likelihood of the token with token ID 1639.
</ParamField>

<ParamField type="integer | null">
  Include the log probabilities on the logprobs most likely output tokens, as well the chosen tokens. For example, if logprobs is 5, the API will return a list of the 5 most likely tokens.

  The maximum value for logprobs is 5.
</ParamField>

<ParamField type="integer">
  Defaults to 1. Generates best\_of completions server-side and returns the "best" (the one with the highest log probability per token). Results cannot be streamed.

  When used with n, best\_of controls the number of candidate completions and n specifies how many to return – best\_of must be greater than n.

  Note: Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for max\_tokens and stop.
</ParamField>

## Response

<ResponseField name="choices" type="array">
  The list of generated completion choices.

  <Expandable title="properties">
    <ResponseField name="finish_reason" type="string">
      The reason the model stopped generating tokens. This will be "stop" if the model hit a natural stop point or a provided stop sequence, or "length" if the maximum number of tokens specified in the request was reached.

      Enum: `stop`, `length`
    </ResponseField>

    <ResponseField name="index" type="integer">
      The index of the completion choice.
    </ResponseField>

    <ResponseField name="logprobs" type="object">
      The log probabilities of the most likely tokens.

      <Expandable title="properties">
        <ResponseField name="text_offset" type="array">
          Array of integers representing text offsets.
        </ResponseField>

        <ResponseField name="token_logprobs" type="array">
          Array of numbers representing token log probabilities.
        </ResponseField>

        <ResponseField name="tokens" type="array">
          Array of strings representing tokens.
        </ResponseField>

        <ResponseField name="top_logprobs" type="array">
          Array of objects containing top log probabilities.

          <Expandable title="properties">
            <ResponseField name="{key}" type="integer">
              Log probability value for the given key.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="text" type="string">
      The completion response.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created" type="integer">
  The Unix time in seconds when the response was generated.
</ResponseField>

<ResponseField name="id" type="string">
  A unique identifier of the response.
</ResponseField>

<ResponseField name="model" type="string">
  The model used for the completion.
</ResponseField>

<ResponseField name="object" type="string">
  The object type, which is always `text_completion`.
</ResponseField>

<ResponseField name="usage" type="object">
  Usage statistics.

  For streaming responses, usage field is included in the very last response chunk returned.

  <Expandable title="properties">
    <ResponseField name="completion_tokens" type="integer">
      The number of tokens in the generated completion.
    </ResponseField>

    <ResponseField name="prompt_tokens" type="integer">
      The number of tokens in the prompt.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      The total number of tokens used in the request (prompt + completion).
    </ResponseField>
  </Expandable>
</ResponseField>


# Create embeddings
Source: https://novita.ai/docs/api-reference/model-apis-llm-create-embeddings

POST https://api.novita.ai/openai/v1/embeddings

Creates an embedding vector representing the input text.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string | arrary">
  Input text to embed, encoded as a string or array of tokens. To embed multiple inputs in a single request, pass an array of strings or array of token arrays. The input must not exceed the max input tokens for the model (8192 tokens for text-embedding-ada-002), cannot be an empty string, and any array must be 2048 dimensions or less.
</ParamField>

<ParamField type="enum<string>">
  ID of the model to use. Enum: `baai/bge-m3`.
</ParamField>

<ParamField type="string">
  The format to return the embeddings in. Can be either float or base64.
</ParamField>

## Response

<ResponseField name="object" type="string">
  Fixed as list
</ResponseField>

<ResponseField name="data" type="array">
  List of embeddings vectors generated by the model.

  <Expandable title="properties">
    <ResponseField name="index" type="integer">
      The index of the embedding vector.
    </ResponseField>

    <ResponseField name="embedding" type="array">
      The embedding vector.
    </ResponseField>

    <ResponseField name="object" type="string">
      Fixed as embedding
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="model" type="string">
  The ID of the model used.
</ResponseField>

<ResponseField name="usage" type="object">
  Usage information.

  <Expandable title="properties">
    <ResponseField name="prompt_tokens" type="integer">
      The number of prompt tokens.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      The number of total tokens.
    </ResponseField>
  </Expandable>
</ResponseField>


# Create rerank
Source: https://novita.ai/docs/api-reference/model-apis-llm-create-rerank

POST https://api.novita.ai/openai/v1/rerank

Creates a rerank request.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The name of the model to use.
</ParamField>

<ParamField type="string">
  The search query.
</ParamField>

<ParamField type="string[]">
  Document List.
</ParamField>

<ParamField type="integer">
  Number of most relevant documents or indices to return.
</ParamField>

## Response

<ResponseField name="id" type="string">
  ID
</ResponseField>

<ResponseField name="results" type="object[]">
  <Expandable title="properties">
    <ResponseField name="document" type="object">
      Original document content.

      <Expandable title="properties">
        <ResponseField name="text" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="index" type="integer">
      The index value of the position in the input candidate doc array.
    </ResponseField>

    <ResponseField name="relevance_score" type="number">
      Similarity score.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Token usage statistics.

  <Expandable title="properties">
    <ResponseField name="completion_tokens" type="integer">
      The number of tokens in the generated completion.
    </ResponseField>

    <ResponseField name="prompt_tokens" type="integer">
      The number of tokens in the prompt.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      The total number of tokens used in the request (prompt + completion).
    </ResponseField>
  </Expandable>
</ResponseField>


# Delete file
Source: https://novita.ai/docs/api-reference/model-apis-llm-delete-file

DELETE https://api.novita.ai/openai/v1/files/{file_id}

Deletes a specific file using its file ID.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Path Parameters

<ParamField type="string">
  The unique identifier of the file to delete.
</ParamField>

## Response

<ResponseField name="deleted" type="boolean">
  Indicates whether the file was successfully deleted. Returns `true` if the deletion was successful.
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier of the deleted file.
</ResponseField>

<ResponseField name="object" type="string">
  The object type, which is always `file`.
</ResponseField>


# List batch
Source: https://novita.ai/docs/api-reference/model-apis-llm-list-batches

GET https://api.novita.ai/openai/v1/batches

Displays a list of all available batch jobs.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Response

<ResponseField name="data" type="array">
  An array of batch job objects.

  <Expandable title="Batch Object Properties">
    <ResponseField name="id" type="string">
      A unique identifier for the batch job.
    </ResponseField>

    <ResponseField name="object" type="string">
      The object type, which is always `batch`.
    </ResponseField>

    <ResponseField name="endpoint" type="string">
      The API endpoint that the batch job is using for processing requests.
    </ResponseField>

    <ResponseField name="input_file_id" type="string">
      The ID of the input file containing the batch requests.
    </ResponseField>

    <ResponseField name="output_file_id" type="string">
      The ID of the output file containing the batch results. Empty until the batch is completed.
    </ResponseField>

    <ResponseField name="error_file_id" type="string">
      The ID of the error file containing any errors that occurred during batch processing. Empty until errors occur.
    </ResponseField>

    <ResponseField name="completion_window" type="string">
      The time window for batch completion. Currently fixed at `48h`.
    </ResponseField>

    <ResponseField name="in_progress_at" type="string | null">
      The timestamp when the batch started processing. Null if not yet started.
    </ResponseField>

    <ResponseField name="expires_at" type="string | null">
      The timestamp when the batch will expire. Null if not set.
    </ResponseField>

    <ResponseField name="finalizing_at" type="string | null">
      The timestamp when the batch started finalizing. Null if not yet finalizing.
    </ResponseField>

    <ResponseField name="completed_at" type="string | null">
      The timestamp when the batch was completed. Null if not yet completed.
    </ResponseField>

    <ResponseField name="failed_at" type="string | null">
      The timestamp when the batch failed. Null if not failed.
    </ResponseField>

    <ResponseField name="expired_at" type="string | null">
      The timestamp when the batch expired. Null if not expired.
    </ResponseField>

    <ResponseField name="cancelling_at" type="string | null">
      The timestamp when the batch started cancelling. Null if not cancelling.
    </ResponseField>

    <ResponseField name="cancelled_at" type="string | null">
      The timestamp when the batch was cancelled. Null if not cancelled.
    </ResponseField>

    <ResponseField name="status" type="string">
      The current status of the batch job.

      Available statuses:

      * `VALIDATING` - The input file is being validated before the batch can begin
      * `PROGRESS` - Batch is in progress
      * `COMPLETED` - Batch processing completed successfully
      * `FAILED` - Batch processing failed
      * `EXPIRED` - Batch exceeded deadline
      * `CANCELLING` - Batch is being cancelled
      * `CANCELLED` - Batch was cancelled
    </ResponseField>

    <ResponseField name="errors" type="string">
      Error messages if any errors occurred during batch processing.
    </ResponseField>

    <ResponseField name="version" type="integer">
      The version number of the batch job.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      The timestamp when the batch job was created.
    </ResponseField>

    <ResponseField name="updated_at" type="string | null">
      The timestamp when the batch job was last updated. Null if never updated.
    </ResponseField>

    <ResponseField name="created_by" type="string">
      The unique identifier of the user who created the batch job.
    </ResponseField>

    <ResponseField name="created_by_key_id" type="string">
      The API key ID used to create the batch job.
    </ResponseField>

    <ResponseField name="remark" type="string">
      Optional remark or note for the batch job.
    </ResponseField>

    <ResponseField name="total" type="integer">
      The total number of requests in the batch.
    </ResponseField>

    <ResponseField name="completed" type="integer">
      The number of completed requests in the batch.
    </ResponseField>

    <ResponseField name="failed" type="integer">
      The number of failed requests in the batch.
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Additional metadata associated with the batch job. Null if no metadata is provided.
    </ResponseField>

    <ResponseField name="request_counts" type="object">
      Detailed request count information.

      <Expandable title="properties">
        <ResponseField name="total" type="integer">
          The total number of requests in the batch.
        </ResponseField>

        <ResponseField name="completed" type="integer">
          The number of successfully completed requests.
        </ResponseField>

        <ResponseField name="failed" type="integer">
          The number of failed requests.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="first_id" type="string">
  The ID of the first batch in the list.
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Indicates whether there are more batches available beyond this list.
</ResponseField>

<ResponseField name="last_id" type="string">
  The ID of the last batch in the list.
</ResponseField>

<ResponseField name="object" type="string">
  The object type, which is always `list`.
</ResponseField>


# List files
Source: https://novita.ai/docs/api-reference/model-apis-llm-list-files

GET https://api.novita.ai/openai/v1/files

Displays a list of all available files.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Response

<ResponseField name="code" type="string">
  HTTP status code indicating the result of the request.
</ResponseField>

<ResponseField name="message" type="string">
  A descriptive message about the request result.
</ResponseField>

<ResponseField name="data" type="array">
  An array of file objects.

  <Expandable title="File Object Properties">
    <ResponseField name="id" type="string">
      The unique identifier of the file.
    </ResponseField>

    <ResponseField name="object" type="string">
      The object type, which is always `file`.
    </ResponseField>

    <ResponseField name="bytes" type="integer">
      The size of the file in bytes.
    </ResponseField>

    <ResponseField name="filename" type="string">
      The name of the file.
    </ResponseField>

    <ResponseField name="created_at" type="integer">
      The Unix timestamp (in seconds) when the file was created.
    </ResponseField>

    <ResponseField name="expires_at" type="integer">
      The Unix timestamp (in seconds) when the file will expire. Only present for output files.
    </ResponseField>

    <ResponseField name="purpose" type="string">
      The purpose of the file.

      Available purposes:

      * `batch` - Input file for batch processing
      * `batch_output` - Output file from batch processing
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Additional metadata about the file.

      <Expandable title="properties">
        <ResponseField name="total_requests" type="integer">
          The total number of requests in the batch input file. Only present for batch input files.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>


# List models
Source: https://novita.ai/docs/api-reference/model-apis-llm-list-models

GET https://api.novita.ai/openai/v1/models

Lists the currently available models for the LLM API, and provides basic information about each one. This endpoint is compatible with OpenAI API.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Response

<ResponseExample>
  ```json theme={"system"}
  {
    "data": [
      {
        "created": 1733560109,
        "id": "meta-llama/llama-3.3-70b-instruct",
        "object": "model",
        "input_token_price_per_m": 3900,
        "output_token_price_per_m": 3900,
        "title": "meta-llama/llama-3.3-70b-instruct",
        "description": "The Meta Llama 3.3 multilingual large language model (LLM) is a pretrained and instruction tuned generative model in 70B (text in/text out). The Llama 3.3 instruction tuned text only model is optimized for multilingual dialogue use cases and outperforms many of the available open source and closed chat models on common industry benchmarks.\n\nSupported languages: English, German, French, Italian, Portuguese, Hindi, Spanish, and Thai.",
        "context_size": 131072
      },
      // more models here...
    ]
  }
  ```
</ResponseExample>

<ResponseField name="data" type="array">
  Array of model objects with the following properties:

  <Expandable title="Model Object Properties">
    <ResponseField name="id" type="string">
      The model identifier, which can be referenced in the API endpoints.
    </ResponseField>

    <ResponseField name="created" type="integer">
      The Unix timestamp (in seconds) when the model was created.
    </ResponseField>

    <ResponseField name="object" type="string">
      The object type, which is always "model".
    </ResponseField>

    <ResponseField name="input_token_price_per_m" type="integer">
      The price per million input tokens.
    </ResponseField>

    <ResponseField name="output_token_price_per_m" type="integer">
      The price per million output tokens.
    </ResponseField>

    <ResponseField name="title" type="string">
      The title of the model.
    </ResponseField>

    <ResponseField name="description" type="string">
      The description of the model.
    </ResponseField>

    <ResponseField name="context_size" type="integer">
      The maximum context size of the model.
    </ResponseField>
  </Expandable>
</ResponseField>


# Retrieve file
Source: https://novita.ai/docs/api-reference/model-apis-llm-query-file

GET https://api.novita.ai/openai/v1/files/{file_id}

Retrieves information about a specific file using its file ID.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Path Parameters

<ParamField type="string">
  The unique identifier of the file to retrieve information for.
</ParamField>

## Response

<ResponseField name="id" type="string">
  The unique identifier of the file.
</ResponseField>

<ResponseField name="object" type="string">
  The object type, which is always `file`.
</ResponseField>

<ResponseField name="bytes" type="integer">
  The size of the file in bytes.
</ResponseField>

<ResponseField name="filename" type="string">
  The name of the file.
</ResponseField>

<ResponseField name="created_at" type="integer">
  The Unix timestamp (in seconds) when the file was created.
</ResponseField>

<ResponseField name="expires_at" type="integer">
  The Unix timestamp (in seconds) when the file will expire. Only present for output files.
</ResponseField>

<ResponseField name="purpose" type="string">
  The purpose of the file.

  Available purposes:

  * `batch` - Input file for batch processing
  * `batch_output` - Output file from batch processing
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional metadata about the file.

  <Expandable title="properties">
    <ResponseField name="total_requests" type="integer">
      The total number of requests in the batch input file. Only present for batch input files.
    </ResponseField>
  </Expandable>
</ResponseField>


# Retrieve batch
Source: https://novita.ai/docs/api-reference/model-apis-llm-retrieve-batch

GET https://api.novita.ai/openai/v1/batches/{batch_id}

Retrieve batch using its batch ID.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Path Parameters

<ParamField type="string">
  The unique identifier of the batch job to check.
</ParamField>

## Response

<ResponseField name="id" type="string">
  A unique identifier for the batch job.
</ResponseField>

<ResponseField name="object" type="string">
  The object type, which is always `batch`.
</ResponseField>

<ResponseField name="endpoint" type="string">
  The API endpoint that the batch job is using for processing requests.
</ResponseField>

<ResponseField name="input_file_id" type="string">
  The ID of the input file containing the batch requests.
</ResponseField>

<ResponseField name="output_file_id" type="string">
  The ID of the output file containing the batch results. Empty until the batch is completed.
</ResponseField>

<ResponseField name="error_file_id" type="string">
  The ID of the error file containing any errors that occurred during batch processing. Empty until errors occur.
</ResponseField>

<ResponseField name="completion_window" type="string">
  The time window for batch completion. Currently fixed at `48h`.
</ResponseField>

<ResponseField name="in_progress_at" type="string | null">
  The timestamp when the batch started processing. Null if not yet started.
</ResponseField>

<ResponseField name="expires_at" type="string | null">
  The timestamp when the batch will expire. Null if not set.
</ResponseField>

<ResponseField name="finalizing_at" type="string | null">
  The timestamp when the batch started finalizing. Null if not yet finalizing.
</ResponseField>

<ResponseField name="completed_at" type="string | null">
  The timestamp when the batch was completed. Null if not yet completed.
</ResponseField>

<ResponseField name="failed_at" type="string | null">
  The timestamp when the batch failed. Null if not failed.
</ResponseField>

<ResponseField name="expired_at" type="string | null">
  The timestamp when the batch expired. Null if not expired.
</ResponseField>

<ResponseField name="cancelling_at" type="string | null">
  The timestamp when the batch started cancelling. Null if not cancelling.
</ResponseField>

<ResponseField name="cancelled_at" type="string | null">
  The timestamp when the batch was cancelled. Null if not cancelled.
</ResponseField>

<ResponseField name="status" type="string">
  The current status of the batch job.

  Available statuses:

  * `VALIDATING` - The input file is being validated before the batch can begin
  * `PROGRESS` - Batch is in progress
  * `COMPLETED` - Batch processing completed successfully
  * `FAILED` - Batch processing failed
  * `EXPIRED` - Batch exceeded deadline
  * `CANCELLING` - Batch is being cancelled
  * `CANCELLED` - Batch was cancelled
</ResponseField>

<ResponseField name="errors" type="string">
  Error messages if any errors occurred during batch processing.
</ResponseField>

<ResponseField name="version" type="integer">
  The version number of the batch job.
</ResponseField>

<ResponseField name="created_at" type="string">
  The timestamp when the batch job was created.
</ResponseField>

<ResponseField name="updated_at" type="string | null">
  The timestamp when the batch job was last updated. Null if never updated.
</ResponseField>

<ResponseField name="created_by" type="string">
  The unique identifier of the user who created the batch job.
</ResponseField>

<ResponseField name="created_by_key_id" type="string">
  The API key ID used to create the batch job.
</ResponseField>

<ResponseField name="remark" type="string">
  Optional remark or note for the batch job.
</ResponseField>

<ResponseField name="total" type="integer">
  The total number of requests in the batch.
</ResponseField>

<ResponseField name="completed" type="integer">
  The number of completed requests in the batch.
</ResponseField>

<ResponseField name="failed" type="integer">
  The number of failed requests in the batch.
</ResponseField>

<ResponseField name="metadata" type="object | null">
  Additional metadata associated with the batch job. Null if no metadata is provided.
</ResponseField>

<ResponseField name="request_counts" type="object">
  Detailed request count information.

  <Expandable title="properties">
    <ResponseField name="total" type="integer">
      The total number of requests in the batch.
    </ResponseField>

    <ResponseField name="completed" type="integer">
      The number of successfully completed requests.
    </ResponseField>

    <ResponseField name="failed" type="integer">
      The number of failed requests.
    </ResponseField>
  </Expandable>
</ResponseField>


# Retrieve file content
Source: https://novita.ai/docs/api-reference/model-apis-llm-retrieve-file-content

GET https://api.novita.ai/openai/v1/files/{file_id}/content

Retrieves the content of a specific file using its file ID. This is commonly used to download batch output files or error files.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Path Parameters

<ParamField type="string">
  The unique identifier of the file to retrieve content for.
</ParamField>

## Response

The response returns the raw file content. For batch output files, this will be in JSONL format where each line contains a batch request result.

**Example Response**

For batch output files, each line contains a response like this:

```json theme={"system"}
{
  "custom_id": "request-2589",
  "error": null,
  "id": "batch_req_task_d2c",
  "response": {
    "body": {
      "id": "29e1432c-edfb-44a4-b531-c23c600abfae",
      "object": "chat.completion",
      "created": 1754902266,
      "model": "deepseek-test",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "Hello! 👋 How can I assist you today? 😊"
          },
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 5,
        "completion_tokens": 13,
        "total_tokens": 18
      }
    },
    "request_id": "request-2589",
    "status_code": 200
  }
}
```


# Retrieve model
Source: https://novita.ai/docs/api-reference/model-apis-llm-retrieve-model

GET https://api.novita.ai/openai/v1/models/{model}

Retrieves a model instance, providing basic information about the model. This endpoint is compatible with OpenAI API.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Path Parameters

<ParamField type="string">
  The ID of the model to use for this request.
</ParamField>

## Response

<ResponseExample>
  ```json theme={"system"}
  {
    "created": 1733560109,
    "id": "meta-llama/llama-3.3-70b-instruct",
    "object": "model",
    "input_token_price_per_m": 3900,
    "output_token_price_per_m": 3900,
    "title": "meta-llama/llama-3.3-70b-instruct",
    "description": "The Meta Llama 3.3 multilingual large language model (LLM) is a pretrained and instruction tuned generative model in 70B (text in/text out). The Llama 3.3 instruction tuned text only model is optimized for multilingual dialogue use cases and outperforms many of the available open source and closed chat models on common industry benchmarks.\n\nSupported languages: English, German, French, Italian, Portuguese, Hindi, Spanish, and Thai.",
    "context_size": 131072,
  }
  ```
</ResponseExample>

<ResponseField name="id" type="string">
  The model identifier, which can be referenced in the API endpoints.
</ResponseField>

<ResponseField name="created" type="integer">
  The Unix timestamp (in seconds) when the model was created.
</ResponseField>

<ResponseField name="object" type="string">
  The object type, which is always "model".
</ResponseField>

<ResponseField name="input_token_price_per_m" type="integer">
  The price per million input tokens.
</ResponseField>

<ResponseField name="output_token_price_per_m" type="integer">
  The price per million output tokens.
</ResponseField>

<ResponseField name="title" type="string">
  The title of the model.
</ResponseField>

<ResponseField name="description" type="string">
  The description of the model.
</ResponseField>

<ResponseField name="context_size" type="integer">
  The maximum context size of the model.
</ResponseField>


# Upload file
Source: https://novita.ai/docs/api-reference/model-apis-llm-upload-batch-input-file

POST https://api.novita.ai/openai/v1/files

Upload the batch input file so that it can be correctly referenced when creating a batch.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="file">
  The batch input file to be uploaded should be in `.jsonl` format, with each line detailing an API inference request.

  Each request must have a unique `custom_id` to identify inference results in the output file after batch processing. The parameters within the `body` field of each line are used as the actual inference request parameters for the endpoint.

  <Warning>
    All requests within a single batch JSONL file must target the same model. Do not mix requests for different models in one batch.
  </Warning>

  Here is an example of an input file containing two requests:

  ```JSON theme={"system"}
  {"custom_id": "request-1", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "user", "content": "Hello, world!"}], "max_tokens": 400}}
  {"custom_id": "request-2", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}
  ```
</ParamField>

<ParamField type="string">
  The purpose of the uploaded file. For batch processing, this should be set to `batch`.

  Enum: `batch`
</ParamField>

## Response

<ResponseField name="id" type="string">
  The unique identifier of the uploaded file.
</ResponseField>

<ResponseField name="object" type="string">
  The object type, which is always `file`.
</ResponseField>

<ResponseField name="bytes" type="integer">
  The size of the uploaded file in bytes.
</ResponseField>

<ResponseField name="created_at" type="integer">
  The Unix timestamp (in seconds) when the file was created.
</ResponseField>

<ResponseField name="filename" type="string">
  The name of the uploaded file.
</ResponseField>

<ResponseField name="purpose" type="string">
  The purpose of the uploaded file.
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional metadata about the uploaded file.

  <Expandable title="properties">
    <ResponseField name="total_requests" type="integer">
      The total number of requests contained in the batch input file.
    </ResponseField>
  </Expandable>
</ResponseField>


# Merge Face
Source: https://novita.ai/docs/api-reference/model-apis-merge-face

POST https://api.novita.ai/v3/merge-face

**This API endpoint seamlessly merges the characteristics of two faces, enabling the creation of a composite image that integrates features from both inputs.**

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Optional extra parameters for the request.

  <Expandable title="properties">
    <ParamField type="string">
      The returned image type. Default is png.<br />
      Enum: `png`, `webp`, `jpeg`
    </ParamField>

    <ParamField type="object">
      Dedicated Endpoints settings, which only take effect for users who have already subscribed to the [Dedicated Endpoints Documentation](/guides/model-apis-dedicated-endpoints).

      <Expandable title="properties">
        <ParamField type="boolean">
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  The base64-encoded face image, with a maximum resolution of 2048 x 2048 and a maximum file size of 30 MB.
</ParamField>

<ParamField type="string">
  The base64-encoded original image, with a maximum resolution of 2048 x 2048 and a maximum file size of 30 MB.
</ParamField>

## Response

<ResponseField name="image_file" type="string">
  The Base64-encoded content of the returned image.
</ResponseField>

<ResponseField name="image_type" type="string">
  The returned image type.
</ResponseField>

## Example

This feature helps blend the details of two faces.

**Try it in the [playground](https://novita.ai/playground#merge-face).**

`Request:`

```bash theme={"system"}
curl --location --request POST 'https://api.novita.ai/v3/merge-face' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "face_image_file": "{{Base64 encoded image}}",
    "image_file": "{{Base64 encoded image}}"
}'
```

HTTP status codes in the 2xx range indicate that the request has been successfully accepted. Code 400 means there is an error with the request parameters, while status codes in the 5xx range indicate internal server errors.

You can obtain the image URL in the `image_file` field of the response in base64 format.

`Response:`

```js theme={"system"}
{
    "image_file": "{{Base64 encoded image}}",
    "image_type": "png"
}
```

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>


# Minimax Hailuo-02
Source: https://novita.ai/docs/api-reference/model-apis-minimax-hailuo-02

POST https://api.novita.ai/v3/async/minimax-hailuo-02

Minimax Hailuo-02 (also known as Hailuo) is an AI video generation model that supports both text-to-video and image-to-video generation. It can generate 6-second videos at 768p or 1080p resolution, and 10-second videos at 768p resolution.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Prompt text required to guide the generation.

  Range: `1 <= x <= 2000`.
</ParamField>

<ParamField type="string">
  The first frame image to be used for video generation. Supports public URL or Base64 encoding(`data:image/jpeg;base64,...`).
</ParamField>

<ParamField type="string">
  The end frame image to be used for video generation. Supports public URL or Base64 encoding(`data:image/jpeg;base64,...`).
</ParamField>

<ParamField type="integer">
  The length of the generated video in seconds. Default: `6`<br />
  Optional values: `6`, `10`
</ParamField>

<ParamField type="string">
  The resolution of the generated video. Default: `768P`

  * For 6-second videos: supports `768P`, `1080P`
  * For 10-second videos: supports `768P` only
</ParamField>

<ParamField type="boolean">
  Whether to enable prompt optimization.

  Default: `true`.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>

## Example

Here is an example of how to use the Minimax Hailuo-02 API.

1. Generate a task\_id by sending a POST request to the Minimax Hailuo-02 API.

`Request:`

```bash theme={"system"}
curl \
-X POST https://api.novita.ai/v3/async/minimax-hailuo-02 \
-H "Authorization: Bearer $your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "image": "https://doc-assets.novitai.com/minimax-hailuo-video-02-input-image.jpg",
  "prompt": "A gentleman leans on a retro-futuristic car under a streetlight, zooming out revealing classic design elements in a timeless, nostalgic style.",
  "duration": 6,
  "resolution": "768P",
  "enable_prompt_expansion": true
}'
```

`Response:`

```js theme={"system"}
{
    "task_id": "{Returned Task ID}"
}
```

2. Use `task_id` to get output videos.

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get videos url in `videos` of response.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id={Returned Task ID}' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "task": {
        "task_id": "{Returned Task ID}",
        "task_type": "MINIMAX_HAILUO_02",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 100
    },
    "images": [],
    "videos": [
        {
            "video_url": "{The URL of the generated video}",
            "video_url_ttl": "3600",
            "video_type": "mp4"
        }
    ]
}
```

`Video files:`

<video />


# Minimax Hailuo 2.3 Fast Image to Video
Source: https://novita.ai/docs/api-reference/model-apis-minimax-hailuo-2.3-fast-i2v

POST https://api.novita.ai/v3/async/minimax-hailuo-2.3-fast-i2v

Minimax Hailuo 2.3 Fast offers significantly accelerated video generation, effectively balancing quality and performance at a more cost-effective rate.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Prompt text required to guide the generation.

  Range: `1 <= x <= 2000`.
</ParamField>

<ParamField type="string">
  The image to be used for video generation. Supports public URL or Base64 encoding(`data:image/jpeg;base64,...`).
</ParamField>

<ParamField type="integer">
  The length of the generated video in seconds. Default: `6`<br />
  Optional values: `6`, `10`
</ParamField>

<ParamField type="string">
  The resolution of the generated video. Default: `768P`

  * For 6-second videos: supports `768P`, `1080P`
  * For 10-second videos: supports `768P` only
</ParamField>

<ParamField type="boolean">
  Whether to enable prompt optimization.

  Default: `true`.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Minimax Hailuo 2.3 Image to Video
Source: https://novita.ai/docs/api-reference/model-apis-minimax-hailuo-2.3-i2v

POST https://api.novita.ai/v3/async/minimax-hailuo-2.3-i2v

Minimax Hailuo 2.3 is a new video generation model, breakthroughs in body movement, facial expressions, physical realism, and prompt adherence.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Prompt text required to guide the generation.

  Range: `1 <= x <= 2000`.

  Supported 15 camera commands:

  * Truck: \[Truck left], \[Truck right]
  * Pan: \[Pan left], \[Pan right]
  * Push: \[Push in], \[Pull out]
  * Pedestal: \[Pedestal up], \[Pedestal down]
  * Tilt: \[Tilt up], \[Tilt down]
  * Zoom: \[Zoom in], \[Zoom out]
  * Shake: \[Shake]
  * Follow: \[Tracking shot]
  * Static: \[Static shot]

  Usage rules:

  * Combined movements: Multiple commands inside one \[] take effect simultaneously (e.g., \[Pan left,Pedestal up]). Recommended max: 3.
  * Sequential movements: Commands appear in order, e.g., "...\[Push in], then...\[Push out]".
  * Natural language: Free-form descriptions also work, but explicit commands yield more accurate results.
</ParamField>

<ParamField type="string">
  The image to be used for video generation. Supports public URL or Base64 encoding(`data:image/jpeg;base64,...`).
</ParamField>

<ParamField type="integer">
  The length of the generated video in seconds. Default: `6`<br />
  Optional values: `6`, `10`
</ParamField>

<ParamField type="string">
  The resolution of the generated video. Default: `768P`

  * For 6-second videos: supports `768P`, `1080P`
  * For 10-second videos: supports `768P` only
</ParamField>

<ParamField type="boolean">
  Whether to enable prompt optimization.

  Default: `true`.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Minimax Hailuo 2.3 Text to Video
Source: https://novita.ai/docs/api-reference/model-apis-minimax-hailuo-2.3-t2v

POST https://api.novita.ai/v3/async/minimax-hailuo-2.3-t2v

Minimax Hailuo 2.3 is a new video generation model, breakthroughs in body movement, facial expressions, physical realism, and prompt adherence.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Prompt text required to guide the generation.

  Range: `1 <= x <= 2000`.

  Supported 15 camera commands:

  * Truck: \[Truck left], \[Truck right]
  * Pan: \[Pan left], \[Pan right]
  * Push: \[Push in], \[Pull out]
  * Pedestal: \[Pedestal up], \[Pedestal down]
  * Tilt: \[Tilt up], \[Tilt down]
  * Zoom: \[Zoom in], \[Zoom out]
  * Shake: \[Shake]
  * Follow: \[Tracking shot]
  * Static: \[Static shot]

  Usage rules:

  * Combined movements: Multiple commands inside one \[] take effect simultaneously (e.g., \[Pan left,Pedestal up]). Recommended max: 3.
  * Sequential movements: Commands appear in order, e.g., "...\[Push in], then...\[Push out]".
  * Natural language: Free-form descriptions also work, but explicit commands yield more accurate results.
</ParamField>

<ParamField type="integer">
  The length of the generated video in seconds. Default: `6`<br />
  Optional values: `6`, `10`
</ParamField>

<ParamField type="string">
  The resolution of the generated video. Default: `768P`

  * For 6-second videos: supports `768P`, `1080P`
  * For 10-second videos: supports `768P` only
</ParamField>

<ParamField type="boolean">
  Whether to enable prompt optimization.

  Default: `true`.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# MiniMax Speech-02-hd Text to Speech
Source: https://novita.ai/docs/api-reference/model-apis-minimax-speech-02-hd

POST https://api.novita.ai/v3/minimax-speech-02-hd

This API supports synchronous text-to-speech (TTS) generation, with a maximum input length of 10,000 characters per request. It offers over 100 system and cloned voices, with customizable parameters including volume, pitch, speed, and output format. The API supports proportional voice mixing, fixed interval control, and multiple audio formats such as mp3, pcm, flac, and wav. Streaming output is also supported.

When submitting a long-text TTS request, please note that the returned audio URL is valid for 24 hours from the time it is generated. Be sure to download the audio within this period.

<Tip>Best suited for short sentence generation, voice chat, and online social scenarios. Processing is fast, but the text length is limited to less than 10,000 characters. For long-form text, we recommend using [asynchronous TTS synthesis](/api-reference/model-apis-minimax-speech-02-hd-async).</Tip>

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The text to be synthesized. The length must be less than 10,000 characters. Use line breaks to separate paragraphs.\
  To control the pause duration between speech segments, insert `<#x#>` between words or sentences, where `x` is the pause duration in seconds (supports 0.01–99.99, up to two decimal places).\
  Custom speech pauses between text segments are supported, allowing you to control the timing of pauses in the generated audio.\
  Note: Pause markers must be placed between two segments that can be pronounced, and multiple consecutive pause markers are not allowed.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="float">
      Range: \[0.5, 2], default is 1.0

      Controls the speech rate of the generated audio. Optional. Higher values result in faster speech.
    </ParamField>

    <ParamField type="float">
      Range: (0, 10], default is 1.0

      Controls the volume of the generated audio. Optional. Higher values result in louder audio.
    </ParamField>

    <ParamField type="int">
      Range: \[-12, 12], default is 0

      Controls the pitch of the generated audio. Optional. 0 means original timbre. The value must be an integer.
    </ParamField>

    <ParamField type="string">
      The requested timbre ID. Required (choose either this or timbre\_weights).

      Supports both system voices (ID) and cloned voices (ID). The available system voice IDs are as follows:

      * Wise\_Woman
      * Friendly\_Person
      * Inspirational\_girl
      * Deep\_Voice\_Man
      * Calm\_Woman
      * Casual\_Guy
      * Lively\_Girl
      * Patient\_Man
      * Young\_Knight
      * Determined\_Man
      * Lovely\_Girl
      * Decent\_Boy
      * Imposing\_Manner
      * Elegant\_Man
      * Abbess
      * Sweet\_Girl\_2
      * Exuberant\_Girl
    </ParamField>

    <ParamField type="string">
      Controls the emotion of the synthesized speech.

      Currently supports 7 emotions: happy, sad, angry, fearful, disgusted, surprised, neutral.

      Allowed values: `["happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral"]`
    </ParamField>

    <ParamField type="bool">
      This parameter supports English text normalization, which improves performance in number-reading scenarios, but this comes at the cost of a slight increase in latency. If not provided, the default is false.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Range: \[8000, 16000, 22050, 24000, 32000, 44100]

      The sample rate of the generated audio. Optional, default is 32000.
    </ParamField>

    <ParamField type="number">
      Range: \[32000, 64000, 128000, 256000]

      The bitrate of the generated audio. Optional, default is 128000. This parameter only applies to mp3 audio format.
    </ParamField>

    <ParamField type="string">
      The audio format of the output. Default is mp3. Options: `mp3`, `pcm`, `flac`, `wav`. wav is only supported for non-streaming output.
    </ParamField>

    <ParamField type="number">
      Number of audio channels. Default is 1 (mono). Options:

      1: mono

      2: stereo
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="list">
      Replacement of text, symbols and corresponding pronunciations that require manual handling.
      Replace the pronunciation (adjust the tone/replace the pronunciation of other characters) using the following format:

      \[“omg/oh my god”]

      For Chinese texts, tones are replaced by numbers, with 1 for the first tone (high), 2 for the second tone (rising), 3 for the third tone (low/dipping), 4 for the fourth tone (falling), and 5 for the fifth tone (neutral).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  Required if voice\_id is not provided (choose one of the two).

  <Expandable title="properties">
    <ParamField type="string">
      The requested timbre ID. Must be provided together with the weight parameter.
    </ParamField>

    <ParamField type="number">
      Range: \[1, 100]

      The weight, must be provided together with voice\_id. Up to 4 timbres can be mixed. The value must be an integer. The higher the proportion for a single timbre, the more the synthesized voice will resemble it.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="boolean">
  Whether to enable streaming. Default is false, i.e., streaming is disabled.
</ParamField>

<ParamField type="string">
  Enhances recognition of specified minor languages and dialects. Setting this parameter can improve speech performance in the specified language/dialect scenarios. If the minor language type is not clear, you can set it to "auto" and the model will automatically determine the language type. Supported values:

  `'Chinese', 'Chinese,Yue', 'English', 'Arabic', 'Russian', 'Spanish', 'French', 'Portuguese', 'German', 'Turkish', 'Dutch', 'Ukrainian', 'Vietnamese', 'Indonesian', 'Japanese', 'Italian', 'Korean', 'Thai', 'Polish', 'Romanian', 'Greek', 'Czech', 'Finnish', 'Hindi', 'auto'`
</ParamField>

<ParamField type="string">
  Controls the output format of the result. Optional values are `url` and `hex`. The default is `hex`. This parameter only takes effect in non-streaming scenarios; in streaming mode, only hex format is supported. The returned URL is valid for 24 hours.
</ParamField>

<ParamField type="object">
  Voice FX settings. Supported audio formats for this parameter:

  * Non-streaming: mp3, wav, flac
  * Streaming: mp3

  <Expandable title="properties">
    <ParamField type="integer">
      Pitch adjustment (darker/brighter). Range: \[-100, 100]. Values closer to -100 generate a deeper (darker) voice; values closer to 100 produce a brighter voice.
    </ParamField>

    <ParamField type="integer">
      Intensity adjustment (powerful/soft). Range: \[-100, 100]. Values closer to -100 generate a more powerful sound; values closer to 100 result in a softer sound.
    </ParamField>

    <ParamField type="integer">
      Timbre adjustment (magnetic/crisp). Range: \[-100, 100]. Values closer to -100 make the voice more full/magnetic; values closer to 100 make it crisper.
    </ParamField>

    <ParamField type="string">
      Sound effect setting (only one may be selected per request). Valid values:

      * `spacious_echo` (large space echo)
      * `auditorium_echo` (auditorium broadcast)
      * `lofi_telephone` (telephone distortion)
      * `robotic` (robotic effect)
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="audio" type="string">
  The synthesized audio segment, encoded in hex and generated in the format specified by `audio_setting.format` (mp3/pcm/flac). The return format is determined by the `output_format` parameter. When `stream` is true, only hex format is supported.
</ResponseField>

<ResponseField name="status" type="number">
  The current status of the audio stream. Returned only when `stream` is true. 1 indicates synthesis in progress, 2 indicates synthesis completed.
</ResponseField>

## Example

Below is an example of how to use the Minimax Speech-02-hd synchronous API.

1. Non-streaming (`stream` is false)

<Tip>
  If `output_format` is not set to `url`, the default return format is hex.
</Tip>

`Request:`

```bash theme={"system"}
curl \
-X POST https://api.novita.ai/v3/minimax-speech-02-hd \
-H "Authorization: Bearer $your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "text": "Audio generation technology is evolving rapidly, enabling the creation of speech, music, and sound effects from text or data inputs. It supports applications in media, accessibility, customer service, and content creation. With improved quality and customization, these tools are increasingly integrated into digital platforms across various industries.",
  "stream": false,
  "output_format": "url",
  "voice_setting": {
    "speed": 1.1,
    "voice_id": "Wise_Woman",
    "emotion": "happy"
  }
}'
```

`Response:`

```js theme={"system"}
{
  "audio": "https://faas-minimax-audio-v2.s3.ap-southeast-1.amazonaws.com/test/60af5b60-5159-421e-9d60-018e6bec4112-9086e96a-dbd1-4588-b025-608312e07244.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20250710%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20250710T113309Z&X-Amz-Expires=87400&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=d6e233423b6ab26c772820135394bbd474beaaeb03e1982f699f7e5583bacab7"
}
```

`Audio file:`

<video />

2. Streaming (`stream` is true)

`Request:`

```bash theme={"system"}
curl \
-X POST https://api.novita.ai/v3/minimax-speech-02-hd \
-H "Authorization: Bearer $your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "text": "Audio generation technology is evolving rapidly, enabling the creation of speech, music, and sound effects from text or data inputs. It supports applications in media, accessibility, customer service, and content creation. With improved quality and customization, these tools are increasingly integrated into digital platforms across various industries.",
  "stream": true,
  "voice_setting": {
    "speed": 1.1,
    "voice_id": "Wise_Woman",
    "emotion": "happy"
  }
}'
```

`Response:`

```bash theme={"system"}
data: {"audio": "fffb98c4d8 ... e12fc5be", "status": 1}
...
data: {"audio": "4944330453 ... 34505005", "status": 1}
...
data: {"audio": "fffb98c45f ... 04f61e30", "status": 1}
...
data: {"status": 2}
```


# MiniMax Speech-02-hd Async Long TTS
Source: https://novita.ai/docs/api-reference/model-apis-minimax-speech-02-hd-async

POST https://api.novita.ai/v3/async/minimax-speech-02-hd

This API supports asynchronous text-to-speech (TTS) generation, with a maximum limit of 1 million characters per request for text input. The resulting audio can be retrieved asynchronously. Over 100 system and cloned voices are available, with customizable parameters including pitch, speed, volume, bitrate, sample rate, and output format.

After submitting a long-text TTS request, please note that the returned audio URL is valid for 24 hours from the time it is generated. Be sure to download the audio within this period.

<Tip>Best suited for long-form text-to-speech generation, such as entire books. Task queue times may be longer. For short sentence generation, voice chat, or online social scenarios, we recommend using [synchronous TTS](/api-reference/model-apis-minimax-speech-02-hd).</Tip>

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The text to be synthesized. Maximum length: 50,000 characters.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Range: \[0.5, 2], default is 1.0.

      Controls the speech rate of the generated audio. Optional. Higher values result in faster speech.
    </ParamField>

    <ParamField type="number">
      Range: (0, 10], default is 1.0.

      Controls the volume of the generated audio. Optional. Higher values result in louder audio.
    </ParamField>

    <ParamField type="number">
      Range: \[-12, 12], default is 0.

      Controls the pitch of the generated audio. Optional. 0 means original timbre. The value must be an integer.
    </ParamField>

    <ParamField type="string">
      The requested voice ID.

      Supports both system voices (ID) and cloned voices (ID). The available system voice IDs are as follows:

      * Wise\_Woman
      * Friendly\_Person
      * Inspirational\_girl
      * Deep\_Voice\_Man
      * Calm\_Woman
      * Casual\_Guy
      * Lively\_Girl
      * Patient\_Man
      * Young\_Knight
      * Determined\_Man
      * Lovely\_Girl
      * Decent\_Boy
      * Imposing\_Manner
      * Elegant\_Man
      * Abbess
      * Sweet\_Girl\_2
      * Exuberant\_Girl
    </ParamField>

    <ParamField type="string">
      Controls the emotion of the synthesized speech.

      Currently supports 7 emotions: happy, sad, angry, fearful, disgusted, surprised, neutral.

      Allowed values: `["happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral"]`
    </ParamField>

    <ParamField type="bool">
      This parameter supports English text normalization, which improves performance in number-reading scenarios, but this comes at the cost of a slight increase in latency. If not provided, the default is false.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Range: \[8000, 16000, 22050, 24000, 32000, 44100]

      The sample rate of the generated audio. Optional, default is 32000.
    </ParamField>

    <ParamField type="number">
      Range: \[32000, 64000, 128000, 256000]

      The bitrate of the generated audio. Optional, default is 128000. This parameter only applies to mp3 audio format.
    </ParamField>

    <ParamField type="string">
      The audio format of the output. Default is mp3. Options: `mp3`, `pcm`, `flac`, `wav`. wav is only supported for non-streaming output.
    </ParamField>

    <ParamField type="number">
      Number of audio channels. Default is 1 (mono). Options:

      1: mono

      2: stereo
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="list">
      Replacement of text, symbols and corresponding pronunciations that require manual handling.
      Replace the pronunciation (adjust the tone/replace the pronunciation of other characters) using the following format:

      \[“omg/oh my god”]

      For Chinese texts, tones are replaced by numbers, with 1 for the first tone (high), 2 for the second tone (rising), 3 for the third tone (low/dipping), 4 for the fourth tone (falling), and 5 for the fifth tone (neutral).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Enhances recognition of specified minor languages and dialects. Setting this parameter can improve speech performance in the specified language/dialect scenarios. If the minor language type is not clear, you can set it to "auto" and the model will automatically determine the language type. Supported values:

  `'Chinese', 'Chinese,Yue', 'English', 'Arabic', 'Russian', 'Spanish', 'French', 'Portuguese', 'German', 'Turkish', 'Dutch', 'Ukrainian', 'Vietnamese', 'Indonesian', 'Japanese', 'Italian', 'Korean', 'Thai', 'Polish', 'Romanian', 'Greek', 'Czech', 'Finnish', 'Hindi', 'auto'`
</ParamField>

<ParamField type="object">
  Voice FX settings. Supported audio formats for this parameter: mp3, wav, flac

  <Expandable title="properties">
    <ParamField type="integer">
      Pitch adjustment (darker/brighter). Range: \[-100, 100]. Values closer to -100 generate a deeper (darker) voice; values closer to 100 produce a brighter voice.
    </ParamField>

    <ParamField type="integer">
      Intensity adjustment (powerful/soft). Range: \[-100, 100]. Values closer to -100 generate a more powerful sound; values closer to 100 result in a softer sound.
    </ParamField>

    <ParamField type="integer">
      Timbre adjustment (magnetic/crisp). Range: \[-100, 100]. Values closer to -100 make the voice more full/magnetic; values closer to 100 make it crisper.
    </ParamField>

    <ParamField type="string">
      Sound effect setting (only one may be selected per request). Valid values:

      * `spacious_echo` (large space echo)
      * `auditorium_echo` (auditorium broadcast)
      * `lofi_telephone` (telephone distortion)
      * `robotic` (robotic effect)
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>

## Example

Below is an example of how to use the MiniMax Speech-02-hd asynchronous API.

1. Generate a `task_id` by sending a POST request to the MiniMax Speech-02-hd API.

`Request:`

```bash theme={"system"}
curl \
-X POST https://api.novita.ai/v3/async/minimax-speech-02-hd \
-H "Authorization: Bearer $your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "text": "Audio generation technology is evolving rapidly, enabling the creation of speech, music, and sound effects from text or data inputs. It supports applications in media, accessibility, customer service, and content creation. With improved quality and customization, these tools are increasingly integrated into digital platforms across various industries.",
  "voice_setting": {
    "speed": 1.1,
    "voice_id": "Wise_Woman",
    "emotion": "happy"
  }
}'
```

`Response:`

```js theme={"system"}
{
    "task_id": "{Returned Task ID}"
}
```

2. Use the task\_id to retrieve the output audio.
   HTTP status codes in the 2xx range indicate the request was successfully accepted, while codes in the 5xx range indicate an internal server error.
   You can obtain the audio file from the audio\_url field in the audios section of the response.

`Response:`

```js theme={"system"}
{
  "extra": {},
  "task": {
    "task_id": "57afda9c-0d75-4f89-ab4e-554f902a5a4e",
    "task_type": "MINIMAX_SPEECH_02_HD",
    "status": "TASK_STATUS_SUCCEED",
    "reason": "",
    "eta": 0,
    "progress_percent": 0
  },
  "images": [],
  "videos": [],
  "audios": [
    {
      "audio_url": "https://faas-minimax-audio-v2.s3.ap-southeast-1.amazonaws.com/test/289125447749800-225bb323-3def-4b7f-b92f-7eccade04f3d.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20250710%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20250710T101656Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=bce290288e8e2017fd0daec4cca4938c3c72abb9d027482c3d95ca275529a8bb",
      "audio_url_ttl": "0",
      "audio_type": "mp3",
      "audio_metadata": null
    }
  ]
}
```

`Audio file:`

<video />


# MiniMax Speech-02-turbo Text to Speech
Source: https://novita.ai/docs/api-reference/model-apis-minimax-speech-02-turbo

POST https://api.novita.ai/v3/minimax-speech-02-turbo

This API supports synchronous text-to-speech (TTS) generation, with a maximum input length of 10,000 characters per request. It offers over 100 system and cloned voices, with customizable parameters including volume, pitch, speed, and output format. The API supports proportional voice mixing, fixed interval control, and multiple audio formats such as mp3, pcm, flac, and wav. Streaming output is also supported.

When submitting a long-text TTS request, please note that the returned audio URL is valid for 24 hours from the time it is generated. Be sure to download the audio within this period.

<Tip>Best suited for short sentence generation, voice chat, and online social scenarios. Processing is fast, but the text length is limited to less than 10,000 characters. For long-form text, we recommend using [asynchronous TTS synthesis](/api-reference/model-apis-minimax-speech-02-turbo-async).</Tip>

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The text to be synthesized. The length must be less than 10,000 characters. Use line breaks to separate paragraphs.\
  To control the pause duration between speech segments, insert `<#x#>` between words or sentences, where `x` is the pause duration in seconds (supports 0.01–99.99, up to two decimal places).\
  Custom speech pauses between text segments are supported, allowing you to control the timing of pauses in the generated audio.\
  Note: Pause markers must be placed between two segments that can be pronounced, and multiple consecutive pause markers are not allowed.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="float">
      Range: \[0.5, 2], default is 1.0

      Controls the speech rate of the generated audio. Optional. Higher values result in faster speech.
    </ParamField>

    <ParamField type="float">
      Range: (0, 10], default is 1.0

      Controls the volume of the generated audio. Optional. Higher values result in louder audio.
    </ParamField>

    <ParamField type="int">
      Range: \[-12, 12], default is 0

      Controls the pitch of the generated audio. Optional. 0 means original timbre. The value must be an integer.
    </ParamField>

    <ParamField type="string">
      The requested timbre ID. Required (choose either this or timbre\_weights).

      Supports both system voices (ID) and cloned voices (ID). The available system voice IDs are as follows:

      * Wise\_Woman
      * Friendly\_Person
      * Inspirational\_girl
      * Deep\_Voice\_Man
      * Calm\_Woman
      * Casual\_Guy
      * Lively\_Girl
      * Patient\_Man
      * Young\_Knight
      * Determined\_Man
      * Lovely\_Girl
      * Decent\_Boy
      * Imposing\_Manner
      * Elegant\_Man
      * Abbess
      * Sweet\_Girl\_2
      * Exuberant\_Girl
    </ParamField>

    <ParamField type="string">
      Controls the emotion of the synthesized speech.

      Currently supports 7 emotions: happy, sad, angry, fearful, disgusted, surprised, neutral.

      Allowed values: `["happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral"]`
    </ParamField>

    <ParamField type="bool">
      This parameter supports English text normalization, which improves performance in number-reading scenarios, but this comes at the cost of a slight increase in latency. If not provided, the default is false.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Range: \[8000, 16000, 22050, 24000, 32000, 44100]

      The sample rate of the generated audio. Optional, default is 32000.
    </ParamField>

    <ParamField type="number">
      Range: \[32000, 64000, 128000, 256000]

      The bitrate of the generated audio. Optional, default is 128000. This parameter only applies to mp3 audio format.
    </ParamField>

    <ParamField type="string">
      The audio format of the output. Default is mp3. Options: `mp3`, `pcm`, `flac`, `wav`. wav is only supported for non-streaming output.
    </ParamField>

    <ParamField type="number">
      Number of audio channels. Default is 1 (mono). Options:

      1: mono

      2: stereo
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="list">
      Replacement of text, symbols and corresponding pronunciations that require manual handling.
      Replace the pronunciation (adjust the tone/replace the pronunciation of other characters) using the following format:

      \[“omg/oh my god”]

      For Chinese texts, tones are replaced by numbers, with 1 for the first tone (high), 2 for the second tone (rising), 3 for the third tone (low/dipping), 4 for the fourth tone (falling), and 5 for the fifth tone (neutral).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  Required if voice\_id is not provided (choose one of the two).

  <Expandable title="properties">
    <ParamField type="string">
      The requested timbre ID. Must be provided together with the weight parameter.
    </ParamField>

    <ParamField type="number">
      Range: \[1, 100]

      The weight, must be provided together with voice\_id. Up to 4 timbres can be mixed. The value must be an integer. The higher the proportion for a single timbre, the more the synthesized voice will resemble it.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="boolean">
  Whether to enable streaming. Default is false, i.e., streaming is disabled.
</ParamField>

<ParamField type="string">
  Enhances recognition of specified minor languages and dialects. Setting this parameter can improve speech performance in the specified language/dialect scenarios. If the minor language type is not clear, you can set it to "auto" and the model will automatically determine the language type. Supported values:

  `'Chinese', 'Chinese,Yue', 'English', 'Arabic', 'Russian', 'Spanish', 'French', 'Portuguese', 'German', 'Turkish', 'Dutch', 'Ukrainian', 'Vietnamese', 'Indonesian', 'Japanese', 'Italian', 'Korean', 'Thai', 'Polish', 'Romanian', 'Greek', 'Czech', 'Finnish', 'Hindi', 'auto'`
</ParamField>

<ParamField type="string">
  Controls the output format of the result. Optional values are `url` and `hex`. The default is `hex`. This parameter only takes effect in non-streaming scenarios; in streaming mode, only hex format is supported. The returned URL is valid for 24 hours.
</ParamField>

<ParamField type="object">
  Voice FX settings. Supported audio formats for this parameter:

  * Non-streaming: mp3, wav, flac
  * Streaming: mp3

  <Expandable title="properties">
    <ParamField type="integer">
      Pitch adjustment (darker/brighter). Range: \[-100, 100]. Values closer to -100 generate a deeper (darker) voice; values closer to 100 produce a brighter voice.
    </ParamField>

    <ParamField type="integer">
      Intensity adjustment (powerful/soft). Range: \[-100, 100]. Values closer to -100 generate a more powerful sound; values closer to 100 result in a softer sound.
    </ParamField>

    <ParamField type="integer">
      Timbre adjustment (magnetic/crisp). Range: \[-100, 100]. Values closer to -100 make the voice more full/magnetic; values closer to 100 make it crisper.
    </ParamField>

    <ParamField type="string">
      Sound effect setting (only one may be selected per request). Valid values:

      * `spacious_echo` (large space echo)
      * `auditorium_echo` (auditorium broadcast)
      * `lofi_telephone` (telephone distortion)
      * `robotic` (robotic effect)
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="audio" type="string">
  The synthesized audio segment, encoded in hex and generated in the format specified by `audio_setting.format` (mp3/pcm/flac). The return format is determined by the `output_format` parameter. When `stream` is true, only hex format is supported.
</ResponseField>

<ResponseField name="status" type="number">
  The current status of the audio stream. Returned only when `stream` is true. 1 indicates synthesis in progress, 2 indicates synthesis completed.
</ResponseField>

## Example

Below is an example of how to use the Minimax Speech-02-turbo synchronous API.

1. Non-streaming (`stream` is false)

<Tip>
  If `output_format` is not set to `url`, the default return format is hex.
</Tip>

`Request:`

```bash theme={"system"}
curl \
-X POST https://api.novita.ai/v3/minimax-speech-02-turbo \
-H "Authorization: Bearer $your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "text": "Audio generation technology is evolving rapidly, enabling the creation of speech, music, and sound effects from text or data inputs. It supports applications in media, accessibility, customer service, and content creation. With improved quality and customization, these tools are increasingly integrated into digital platforms across various industries.",
  "stream": false,
  "output_format": "url",
  "voice_setting": {
    "speed": 1.1,
    "voice_id": "Wise_Woman",
    "emotion": "happy"
  }
}'
```

`Response:`

```js theme={"system"}
{
  "audio": "https://faas-minimax-audio-v2.s3.ap-southeast-1.amazonaws.com/test/60af5b60-5159-421e-9d60-018e6bec4112-9086e96a-dbd1-4588-b025-608312e07244.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20250710%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20250710T113309Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=d6e233425b6ab26c772820135394bbd474beaaeb03e1982f659f7e5583bfcab7"
}
```

`Audio file:`

<video />

2. Streaming (`stream` is true)

`Request:`

```bash theme={"system"}
curl \
-X POST https://api.novita.ai/v3/minimax-speech-02-turbo \
-H "Authorization: Bearer $your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "text": "Audio generation technology is evolving rapidly, enabling the creation of speech, music, and sound effects from text or data inputs. It supports applications in media, accessibility, customer service, and content creation. With improved quality and customization, these tools are increasingly integrated into digital platforms across various industries.",
  "stream": true,
  "voice_setting": {
    "speed": 1.1,
    "voice_id": "Wise_Woman",
    "emotion": "happy"
  }
}'
```

`Response:`

```bash theme={"system"}
data: {"audio": "fffb98c4d8 ... e12fc5be", "status": 1}
...
data: {"audio": "4944330453 ... 34505005", "status": 1}
...
data: {"audio": "fffb98c45f ... 04f61e30", "status": 1}
...
data: {"status": 2}
```


# MiniMax Speech-02-turbo Async Long TTS
Source: https://novita.ai/docs/api-reference/model-apis-minimax-speech-02-turbo-async

POST https://api.novita.ai/v3/async/minimax-speech-02-turbo

This API supports asynchronous text-to-speech (TTS) generation, with a maximum limit of 1 million characters per request for text input. The resulting audio can be retrieved asynchronously. Over 100 system and cloned voices are available, with customizable parameters including pitch, speed, volume, bitrate, sample rate, and output format.

After submitting a long-text TTS request, please note that the returned audio URL is valid for 24 hours from the time it is generated. Be sure to download the audio within this period.

<Tip>Best suited for long-form text-to-speech generation, such as entire books. Task queue times may be longer. For short sentence generation, voice chat, or online social scenarios, we recommend using [synchronous TTS](/api-reference/model-apis-minimax-speech-02-turbo).</Tip>

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The text to be synthesized. Maximum length: 50,000 characters.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Range: \[0.5, 2], default is 1.0.

      Controls the speech rate of the generated audio. Optional. Higher values result in faster speech.
    </ParamField>

    <ParamField type="number">
      Range: (0, 10], default is 1.0.

      Controls the volume of the generated audio. Optional. Higher values result in louder audio.
    </ParamField>

    <ParamField type="number">
      Range: \[-12, 12], default is 0.

      Controls the pitch of the generated audio. Optional. 0 means original timbre. The value must be an integer.
    </ParamField>

    <ParamField type="string">
      The requested voice ID.

      Supports both system voices (ID) and cloned voices (ID). The available system voice IDs are as follows:

      * Wise\_Woman
      * Friendly\_Person
      * Inspirational\_girl
      * Deep\_Voice\_Man
      * Calm\_Woman
      * Casual\_Guy
      * Lively\_Girl
      * Patient\_Man
      * Young\_Knight
      * Determined\_Man
      * Lovely\_Girl
      * Decent\_Boy
      * Imposing\_Manner
      * Elegant\_Man
      * Abbess
      * Sweet\_Girl\_2
      * Exuberant\_Girl
    </ParamField>

    <ParamField type="string">
      Controls the emotion of the synthesized speech.

      Currently supports 7 emotions: happy, sad, angry, fearful, disgusted, surprised, neutral.

      Allowed values: `["happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral"]`
    </ParamField>

    <ParamField type="bool">
      This parameter supports English text normalization, which improves performance in number-reading scenarios, but this comes at the cost of a slight increase in latency. If not provided, the default is false.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Range: \[8000, 16000, 22050, 24000, 32000, 44100]

      The sample rate of the generated audio. Optional, default is 32000.
    </ParamField>

    <ParamField type="number">
      Range: \[32000, 64000, 128000, 256000]

      The bitrate of the generated audio. Optional, default is 128000. This parameter only applies to mp3 audio format.
    </ParamField>

    <ParamField type="string">
      The audio format of the output. Default is mp3. Options: `mp3`, `pcm`, `flac`, `wav`. wav is only supported for non-streaming output.
    </ParamField>

    <ParamField type="number">
      Number of audio channels. Default is 1 (mono). Options:

      1: mono

      2: stereo
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="list">
      Replacement of text, symbols and corresponding pronunciations that require manual handling.
      Replace the pronunciation (adjust the tone/replace the pronunciation of other characters) using the following format:

      \[“omg/oh my god”]

      For Chinese texts, tones are replaced by numbers, with 1 for the first tone (high), 2 for the second tone (rising), 3 for the third tone (low/dipping), 4 for the fourth tone (falling), and 5 for the fifth tone (neutral).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Enhances recognition of specified minor languages and dialects. Setting this parameter can improve speech performance in the specified language/dialect scenarios. If the minor language type is not clear, you can set it to "auto" and the model will automatically determine the language type. Supported values:

  `'Chinese', 'Chinese,Yue', 'English', 'Arabic', 'Russian', 'Spanish', 'French', 'Portuguese', 'German', 'Turkish', 'Dutch', 'Ukrainian', 'Vietnamese', 'Indonesian', 'Japanese', 'Italian', 'Korean', 'Thai', 'Polish', 'Romanian', 'Greek', 'Czech', 'Finnish', 'Hindi', 'auto'`
</ParamField>

<ParamField type="object">
  Voice FX settings. Supported audio formats for this parameter: mp3, wav, flac

  <Expandable title="properties">
    <ParamField type="integer">
      Pitch adjustment (darker/brighter). Range: \[-100, 100]. Values closer to -100 generate a deeper (darker) voice; values closer to 100 produce a brighter voice.
    </ParamField>

    <ParamField type="integer">
      Intensity adjustment (powerful/soft). Range: \[-100, 100]. Values closer to -100 generate a more powerful sound; values closer to 100 result in a softer sound.
    </ParamField>

    <ParamField type="integer">
      Timbre adjustment (magnetic/crisp). Range: \[-100, 100]. Values closer to -100 make the voice more full/magnetic; values closer to 100 make it crisper.
    </ParamField>

    <ParamField type="string">
      Sound effect setting (only one may be selected per request). Valid values:

      * `spacious_echo` (large space echo)
      * `auditorium_echo` (auditorium broadcast)
      * `lofi_telephone` (telephone distortion)
      * `robotic` (robotic effect)
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>

## Example

Below is an example of how to use the MiniMax Speech-02-turbo asynchronous API.

1. Generate a `task_id` by sending a POST request to the MiniMax Speech-02-turbo API.

`Request:`

```bash theme={"system"}
curl \
-X POST https://api.novita.ai/v3/async/minimax-speech-02-turbo \
-H "Authorization: Bearer $your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "text": "Audio generation technology is evolving rapidly, enabling the creation of speech, music, and sound effects from text or data inputs. It supports applications in media, accessibility, customer service, and content creation. With improved quality and customization, these tools are increasingly integrated into digital platforms across various industries.",
  "voice_setting": {
    "speed": 1.1,
    "voice_id": "Wise_Woman",
    "emotion": "happy"
  }
}'
```

`Response:`

```js theme={"system"}
{
    "task_id": "{Returned Task ID}"
}
```

2. Use the task\_id to retrieve the output audio.
   HTTP status codes in the 2xx range indicate the request was successfully accepted, while codes in the 5xx range indicate an internal server error.
   You can obtain the audio file from the audio\_url field in the audios section of the response.

`Response:`

```js theme={"system"}
{
  "extra": {},
  "task": {
    "task_id": "57afda9c-0d75-4f89-ab4e-5584era5a4e",
    "task_type": "MINIMAX_SPEECH_02_TURBO",
    "status": "TASK_STATUS_SUCCEED",
    "reason": "",
    "eta": 0,
    "progress_percent": 0
  },
  "images": [],
  "videos": [],
  "audios": [
    {
      "audio_url": "https://faas-minimax-audio-v2.s3.ap-southeast-1.amazonaws.com/test/60af5b60-5159-421e-9d60-018e6bec4112-9086e96a-dbd1-4588-b025-608312e07244.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20250710%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20250710T113309Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=d6e233425b6ab26c772820135394bbd474beaaeb03e1982f659f7e5583bfcab7",
      "audio_url_ttl": "0",
      "audio_type": "mp3",
      "audio_metadata": null
    }
  ]
}
```

`Audio file:`

<video />


# MiniMax Speech-2.5-hd-preview Text to Speech
Source: https://novita.ai/docs/api-reference/model-apis-minimax-speech-2.5-hd

POST https://api.novita.ai/v3/minimax-speech-2.5-hd-preview

MiniMax's high-definition text-to-speech model, Compared to Speech 02 released in May, Speech 2.5 has three major breakthroughs: stronger multilingual expressiveness, more accurate voice replication, and broader coverage with 40 languages.

<Tip>Best suited for short sentence generation, voice chat, and online social scenarios. Processing is fast, but the text length is limited to less than 10,000 characters. For long-form text, we recommend using [asynchronous TTS synthesis](/api-reference/model-apis-minimax-speech-2.5-hd-async).</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The text to be synthesized. The length must be less than 10,000 characters. Use line breaks to separate paragraphs.\
  To control the pause duration between speech segments, insert `<#x#>` between words or sentences, where `x` is the pause duration in seconds (supports 0.01–99.99, up to two decimal places).\
  Custom speech pauses between text segments are supported, allowing you to control the timing of pauses in the generated audio.\
  Note: Pause markers must be placed between two segments that can be pronounced, and multiple consecutive pause markers are not allowed.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="float">
      Range: \[0.5, 2], default is 1.0

      Controls the speech rate of the generated audio. Optional. Higher values result in faster speech.
    </ParamField>

    <ParamField type="float">
      Range: (0, 10], default is 1.0

      Controls the volume of the generated audio. Optional. Higher values result in louder audio.
    </ParamField>

    <ParamField type="int">
      Range: \[-12, 12], default is 0

      Controls the pitch of the generated audio. Optional. 0 means original timbre. The value must be an integer.
    </ParamField>

    <ParamField type="string">
      The requested timbre ID. Required (choose either this or timbre\_weights).

      Supports both system voices (ID) and cloned voices (ID). The available system voice IDs are as follows:

      * Wise\_Woman
      * Friendly\_Person
      * Inspirational\_girl
      * Deep\_Voice\_Man
      * Calm\_Woman
      * Casual\_Guy
      * Lively\_Girl
      * Patient\_Man
      * Young\_Knight
      * Determined\_Man
      * Lovely\_Girl
      * Decent\_Boy
      * Imposing\_Manner
      * Elegant\_Man
      * Abbess
      * Sweet\_Girl\_2
      * Exuberant\_Girl
    </ParamField>

    <ParamField type="string">
      Controls the emotion of the synthesized speech.

      Currently supports 7 emotions: happy, sad, angry, fearful, disgusted, surprised, neutral.

      Allowed values: `["happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral"]`
    </ParamField>

    <ParamField type="bool">
      This parameter supports English text normalization, which improves performance in number-reading scenarios, but this comes at the cost of a slight increase in latency. If not provided, the default is false.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Range: \[8000, 16000, 22050, 24000, 32000, 44100]

      The sample rate of the generated audio. Optional, default is 32000.
    </ParamField>

    <ParamField type="number">
      Range: \[32000, 64000, 128000, 256000]

      The bitrate of the generated audio. Optional, default is 128000. This parameter only applies to mp3 audio format.
    </ParamField>

    <ParamField type="string">
      The audio format of the output. Default is mp3. Options: `mp3`, `pcm`, `flac`, `wav`. wav is only supported for non-streaming output.
    </ParamField>

    <ParamField type="number">
      Number of audio channels. Default is 1 (mono). Options:

      1: mono

      2: stereo
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="list">
      Replacement of text, symbols and corresponding pronunciations that require manual handling.
      Replace the pronunciation (adjust the tone/replace the pronunciation of other characters) using the following format:

      \[“omg/oh my god”]

      For Chinese texts, tones are replaced by numbers, with 1 for the first tone (high), 2 for the second tone (rising), 3 for the third tone (low/dipping), 4 for the fourth tone (falling), and 5 for the fifth tone (neutral).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  Required if voice\_id is not provided (choose one of the two).

  <Expandable title="properties">
    <ParamField type="string">
      The requested timbre ID. Must be provided together with the weight parameter.
    </ParamField>

    <ParamField type="number">
      Range: \[1, 100]

      The weight, must be provided together with voice\_id. Up to 4 timbres can be mixed. The value must be an integer. The higher the proportion for a single timbre, the more the synthesized voice will resemble it.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="boolean">
  Whether to enable streaming. Default is false, i.e., streaming is disabled.
</ParamField>

<ParamField type="string">
  Enhances recognition of specified minor languages and dialects. Setting this parameter can improve speech performance in the specified language/dialect scenarios. If the minor language type is not clear, you can set it to "auto" and the model will automatically determine the language type. Supported values:

  `'Chinese', 'Chinese,Yue', 'English', 'Arabic', 'Russian', 'Spanish', 'French', 'Portuguese', 'German', 'Turkish', 'Dutch', 'Ukrainian', 'Vietnamese', 'Indonesian', 'Japanese', 'Italian', 'Korean', 'Thai', 'Polish', 'Romanian', 'Greek', 'Czech', 'Finnish', 'Hindi', 'auto'`
</ParamField>

<ParamField type="string">
  Controls the output format of the result. Optional values are `url` and `hex`. The default is `hex`. This parameter only takes effect in non-streaming scenarios; in streaming mode, only hex format is supported. The returned URL is valid for 24 hours.
</ParamField>

<ParamField type="object">
  Voice FX settings. Supported audio formats for this parameter:

  * Non-streaming: mp3, wav, flac
  * Streaming: mp3

  <Expandable title="properties">
    <ParamField type="integer">
      Pitch adjustment (darker/brighter). Range: \[-100, 100]. Values closer to -100 generate a deeper (darker) voice; values closer to 100 produce a brighter voice.
    </ParamField>

    <ParamField type="integer">
      Intensity adjustment (powerful/soft). Range: \[-100, 100]. Values closer to -100 generate a more powerful sound; values closer to 100 result in a softer sound.
    </ParamField>

    <ParamField type="integer">
      Timbre adjustment (magnetic/crisp). Range: \[-100, 100]. Values closer to -100 make the voice more full/magnetic; values closer to 100 make it crisper.
    </ParamField>

    <ParamField type="string">
      Sound effect setting (only one may be selected per request). Valid values:

      * `spacious_echo` (large space echo)
      * `auditorium_echo` (auditorium broadcast)
      * `lofi_telephone` (telephone distortion)
      * `robotic` (robotic effect)
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="audio" type="string">
  The synthesized audio segment, encoded in hex and generated in the format specified by `audio_setting.format` (mp3/pcm/flac). The return format is determined by the `output_format` parameter. When `stream` is true, only hex format is supported.
</ResponseField>

<ResponseField name="status" type="number">
  The current status of the audio stream. Returned only when `stream` is true. 1 indicates synthesis in progress, 2 indicates synthesis completed.
</ResponseField>


# MiniMax Speech-2.5-hd-preview Async Long TTS
Source: https://novita.ai/docs/api-reference/model-apis-minimax-speech-2.5-hd-async

POST https://api.novita.ai/v3/async/minimax-speech-2.5-hd-preview

MiniMax's high-definition text-to-speech model, Compared to Speech 02 released in May, Speech 2.5 has three major breakthroughs: stronger multilingual expressiveness, more accurate voice replication, and broader coverage with 40 languages.

<Tip>Best suited for long-form text-to-speech generation, such as entire books. Task queue times may be longer. For short sentence generation, voice chat, or online social scenarios, we recommend using [synchronous TTS](/api-reference/model-apis-minimax-speech-2.5-hd).</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The text to be synthesized. Maximum length: 50,000 characters.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Range: \[0.5, 2], default is 1.0.

      Controls the speech rate of the generated audio. Optional. Higher values result in faster speech.
    </ParamField>

    <ParamField type="number">
      Range: (0, 10], default is 1.0.

      Controls the volume of the generated audio. Optional. Higher values result in louder audio.
    </ParamField>

    <ParamField type="number">
      Range: \[-12, 12], default is 0.

      Controls the pitch of the generated audio. Optional. 0 means original timbre. The value must be an integer.
    </ParamField>

    <ParamField type="string">
      The requested voice ID.

      Supports both system voices (ID) and cloned voices (ID). The available system voice IDs are as follows:

      * Wise\_Woman
      * Friendly\_Person
      * Inspirational\_girl
      * Deep\_Voice\_Man
      * Calm\_Woman
      * Casual\_Guy
      * Lively\_Girl
      * Patient\_Man
      * Young\_Knight
      * Determined\_Man
      * Lovely\_Girl
      * Decent\_Boy
      * Imposing\_Manner
      * Elegant\_Man
      * Abbess
      * Sweet\_Girl\_2
      * Exuberant\_Girl
    </ParamField>

    <ParamField type="string">
      Controls the emotion of the synthesized speech.

      Currently supports 7 emotions: happy, sad, angry, fearful, disgusted, surprised, neutral.

      Allowed values: `["happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral"]`
    </ParamField>

    <ParamField type="bool">
      This parameter supports English text normalization, which improves performance in number-reading scenarios, but this comes at the cost of a slight increase in latency. If not provided, the default is false.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Range: \[8000, 16000, 22050, 24000, 32000, 44100]

      The sample rate of the generated audio. Optional, default is 32000.
    </ParamField>

    <ParamField type="number">
      Range: \[32000, 64000, 128000, 256000]

      The bitrate of the generated audio. Optional, default is 128000. This parameter only applies to mp3 audio format.
    </ParamField>

    <ParamField type="string">
      The audio format of the output. Default is mp3. Options: `mp3`, `pcm`, `flac`, `wav`. wav is only supported for non-streaming output.
    </ParamField>

    <ParamField type="number">
      Number of audio channels. Default is 1 (mono). Options:

      1: mono

      2: stereo
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="list">
      Replacement of text, symbols and corresponding pronunciations that require manual handling.
      Replace the pronunciation (adjust the tone/replace the pronunciation of other characters) using the following format:

      \[“omg/oh my god”]

      For Chinese texts, tones are replaced by numbers, with 1 for the first tone (high), 2 for the second tone (rising), 3 for the third tone (low/dipping), 4 for the fourth tone (falling), and 5 for the fifth tone (neutral).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Enhances recognition of specified minor languages and dialects. Setting this parameter can improve speech performance in the specified language/dialect scenarios. If the minor language type is not clear, you can set it to "auto" and the model will automatically determine the language type. Supported values:

  `'Chinese', 'Chinese,Yue', 'English', 'Arabic', 'Russian', 'Spanish', 'French', 'Portuguese', 'German', 'Turkish', 'Dutch', 'Ukrainian', 'Vietnamese', 'Indonesian', 'Japanese', 'Italian', 'Korean', 'Thai', 'Polish', 'Romanian', 'Greek', 'Czech', 'Finnish', 'Hindi', 'auto'`
</ParamField>

<ParamField type="object">
  Voice FX settings. Supported audio formats for this parameter: mp3, wav, flac

  <Expandable title="properties">
    <ParamField type="integer">
      Pitch adjustment (darker/brighter). Range: \[-100, 100]. Values closer to -100 generate a deeper (darker) voice; values closer to 100 produce a brighter voice.
    </ParamField>

    <ParamField type="integer">
      Intensity adjustment (powerful/soft). Range: \[-100, 100]. Values closer to -100 generate a more powerful sound; values closer to 100 result in a softer sound.
    </ParamField>

    <ParamField type="integer">
      Timbre adjustment (magnetic/crisp). Range: \[-100, 100]. Values closer to -100 make the voice more full/magnetic; values closer to 100 make it crisper.
    </ParamField>

    <ParamField type="string">
      Sound effect setting (only one may be selected per request). Valid values:

      * `spacious_echo` (large space echo)
      * `auditorium_echo` (auditorium broadcast)
      * `lofi_telephone` (telephone distortion)
      * `robotic` (robotic effect)
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# MiniMax Speech-2.5-turbo-preview Text to Speech
Source: https://novita.ai/docs/api-reference/model-apis-minimax-speech-2.5-turbo

POST https://api.novita.ai/v3/minimax-speech-2.5-turbo-preview

MiniMax's high-definition text-to-speech model, Compared to Speech 02 released in May, Speech 2.5 has three major breakthroughs: stronger multilingual expressiveness, more accurate voice replication, and broader coverage with 40 languages.

<Tip>Best suited for short sentence generation, voice chat, and online social scenarios. Processing is fast, but the text length is limited to less than 10,000 characters. For long-form text, we recommend using [asynchronous TTS synthesis](/api-reference/model-apis-minimax-speech-2.5-turbo-async).</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The text to be synthesized. The length must be less than 10,000 characters. Use line breaks to separate paragraphs.\
  To control the pause duration between speech segments, insert `<#x#>` between words or sentences, where `x` is the pause duration in seconds (supports 0.01–99.99, up to two decimal places).\
  Custom speech pauses between text segments are supported, allowing you to control the timing of pauses in the generated audio.\
  Note: Pause markers must be placed between two segments that can be pronounced, and multiple consecutive pause markers are not allowed.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="float">
      Range: \[0.5, 2], default is 1.0

      Controls the speech rate of the generated audio. Optional. Higher values result in faster speech.
    </ParamField>

    <ParamField type="float">
      Range: (0, 10], default is 1.0

      Controls the volume of the generated audio. Optional. Higher values result in louder audio.
    </ParamField>

    <ParamField type="int">
      Range: \[-12, 12], default is 0

      Controls the pitch of the generated audio. Optional. 0 means original timbre. The value must be an integer.
    </ParamField>

    <ParamField type="string">
      The requested timbre ID. Required (choose either this or timbre\_weights).

      Supports both system voices (ID) and cloned voices (ID). The available system voice IDs are as follows:

      * Wise\_Woman
      * Friendly\_Person
      * Inspirational\_girl
      * Deep\_Voice\_Man
      * Calm\_Woman
      * Casual\_Guy
      * Lively\_Girl
      * Patient\_Man
      * Young\_Knight
      * Determined\_Man
      * Lovely\_Girl
      * Decent\_Boy
      * Imposing\_Manner
      * Elegant\_Man
      * Abbess
      * Sweet\_Girl\_2
      * Exuberant\_Girl
    </ParamField>

    <ParamField type="string">
      Controls the emotion of the synthesized speech.

      Currently supports 7 emotions: happy, sad, angry, fearful, disgusted, surprised, neutral.

      Allowed values: `["happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral"]`
    </ParamField>

    <ParamField type="bool">
      This parameter supports English text normalization, which improves performance in number-reading scenarios, but this comes at the cost of a slight increase in latency. If not provided, the default is false.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Range: \[8000, 16000, 22050, 24000, 32000, 44100]

      The sample rate of the generated audio. Optional, default is 32000.
    </ParamField>

    <ParamField type="number">
      Range: \[32000, 64000, 128000, 256000]

      The bitrate of the generated audio. Optional, default is 128000. This parameter only applies to mp3 audio format.
    </ParamField>

    <ParamField type="string">
      The audio format of the output. Default is mp3. Options: `mp3`, `pcm`, `flac`, `wav`. wav is only supported for non-streaming output.
    </ParamField>

    <ParamField type="number">
      Number of audio channels. Default is 1 (mono). Options:

      1: mono

      2: stereo
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="list">
      Replacement of text, symbols and corresponding pronunciations that require manual handling.
      Replace the pronunciation (adjust the tone/replace the pronunciation of other characters) using the following format:

      \[“omg/oh my god”]

      For Chinese texts, tones are replaced by numbers, with 1 for the first tone (high), 2 for the second tone (rising), 3 for the third tone (low/dipping), 4 for the fourth tone (falling), and 5 for the fifth tone (neutral).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  Required if voice\_id is not provided (choose one of the two).

  <Expandable title="properties">
    <ParamField type="string">
      The requested timbre ID. Must be provided together with the weight parameter.
    </ParamField>

    <ParamField type="number">
      Range: \[1, 100]

      The weight, must be provided together with voice\_id. Up to 4 timbres can be mixed. The value must be an integer. The higher the proportion for a single timbre, the more the synthesized voice will resemble it.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="boolean">
  Whether to enable streaming. Default is false, i.e., streaming is disabled.
</ParamField>

<ParamField type="string">
  Enhances recognition of specified minor languages and dialects. Setting this parameter can improve speech performance in the specified language/dialect scenarios. If the minor language type is not clear, you can set it to "auto" and the model will automatically determine the language type. Supported values:

  `'Chinese', 'Chinese,Yue', 'English', 'Arabic', 'Russian', 'Spanish', 'French', 'Portuguese', 'German', 'Turkish', 'Dutch', 'Ukrainian', 'Vietnamese', 'Indonesian', 'Japanese', 'Italian', 'Korean', 'Thai', 'Polish', 'Romanian', 'Greek', 'Czech', 'Finnish', 'Hindi', 'auto'`
</ParamField>

<ParamField type="string">
  Controls the output format of the result. Optional values are `url` and `hex`. The default is `hex`. This parameter only takes effect in non-streaming scenarios; in streaming mode, only hex format is supported. The returned URL is valid for 24 hours.
</ParamField>

<ParamField type="object">
  Voice FX settings. Supported audio formats for this parameter:

  * Non-streaming: mp3, wav, flac
  * Streaming: mp3

  <Expandable title="properties">
    <ParamField type="integer">
      Pitch adjustment (darker/brighter). Range: \[-100, 100]. Values closer to -100 generate a deeper (darker) voice; values closer to 100 produce a brighter voice.
    </ParamField>

    <ParamField type="integer">
      Intensity adjustment (powerful/soft). Range: \[-100, 100]. Values closer to -100 generate a more powerful sound; values closer to 100 result in a softer sound.
    </ParamField>

    <ParamField type="integer">
      Timbre adjustment (magnetic/crisp). Range: \[-100, 100]. Values closer to -100 make the voice more full/magnetic; values closer to 100 make it crisper.
    </ParamField>

    <ParamField type="string">
      Sound effect setting (only one may be selected per request). Valid values:

      * `spacious_echo` (large space echo)
      * `auditorium_echo` (auditorium broadcast)
      * `lofi_telephone` (telephone distortion)
      * `robotic` (robotic effect)
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="audio" type="string">
  The synthesized audio segment, encoded in hex and generated in the format specified by `audio_setting.format` (mp3/pcm/flac). The return format is determined by the `output_format` parameter. When `stream` is true, only hex format is supported.
</ResponseField>

<ResponseField name="status" type="number">
  The current status of the audio stream. Returned only when `stream` is true. 1 indicates synthesis in progress, 2 indicates synthesis completed.
</ResponseField>


# MiniMax Speech-2.5-turbo-preview Async Long TTS
Source: https://novita.ai/docs/api-reference/model-apis-minimax-speech-2.5-turbo-async

POST https://api.novita.ai/v3/async/minimax-speech-2.5-turbo-preview

MiniMax's high-definition text-to-speech model, Compared to Speech 02 released in May, Speech 2.5 has three major breakthroughs: stronger multilingual expressiveness, more accurate voice replication, and broader coverage with 40 languages.

<Tip>Best suited for long-form text-to-speech generation, such as entire books. Task queue times may be longer. For short sentence generation, voice chat, or online social scenarios, we recommend using [synchronous TTS](/api-reference/model-apis-minimax-speech-2.5-turbo).</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The text to be synthesized. Maximum length: 50,000 characters.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Range: \[0.5, 2], default is 1.0.

      Controls the speech rate of the generated audio. Optional. Higher values result in faster speech.
    </ParamField>

    <ParamField type="number">
      Range: (0, 10], default is 1.0.

      Controls the volume of the generated audio. Optional. Higher values result in louder audio.
    </ParamField>

    <ParamField type="number">
      Range: \[-12, 12], default is 0.

      Controls the pitch of the generated audio. Optional. 0 means original timbre. The value must be an integer.
    </ParamField>

    <ParamField type="string">
      The requested voice ID.

      Supports both system voices (ID) and cloned voices (ID). The available system voice IDs are as follows:

      * Wise\_Woman
      * Friendly\_Person
      * Inspirational\_girl
      * Deep\_Voice\_Man
      * Calm\_Woman
      * Casual\_Guy
      * Lively\_Girl
      * Patient\_Man
      * Young\_Knight
      * Determined\_Man
      * Lovely\_Girl
      * Decent\_Boy
      * Imposing\_Manner
      * Elegant\_Man
      * Abbess
      * Sweet\_Girl\_2
      * Exuberant\_Girl
    </ParamField>

    <ParamField type="string">
      Controls the emotion of the synthesized speech.

      Currently supports 7 emotions: happy, sad, angry, fearful, disgusted, surprised, neutral.

      Allowed values: `["happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral"]`
    </ParamField>

    <ParamField type="bool">
      This parameter supports English text normalization, which improves performance in number-reading scenarios, but this comes at the cost of a slight increase in latency. If not provided, the default is false.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Range: \[8000, 16000, 22050, 24000, 32000, 44100]

      The sample rate of the generated audio. Optional, default is 32000.
    </ParamField>

    <ParamField type="number">
      Range: \[32000, 64000, 128000, 256000]

      The bitrate of the generated audio. Optional, default is 128000. This parameter only applies to mp3 audio format.
    </ParamField>

    <ParamField type="string">
      The audio format of the output. Default is mp3. Options: `mp3`, `pcm`, `flac`, `wav`. wav is only supported for non-streaming output.
    </ParamField>

    <ParamField type="number">
      Number of audio channels. Default is 1 (mono). Options:

      1: mono

      2: stereo
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="list">
      Replacement of text, symbols and corresponding pronunciations that require manual handling.
      Replace the pronunciation (adjust the tone/replace the pronunciation of other characters) using the following format:

      \[“omg/oh my god”]

      For Chinese texts, tones are replaced by numbers, with 1 for the first tone (high), 2 for the second tone (rising), 3 for the third tone (low/dipping), 4 for the fourth tone (falling), and 5 for the fifth tone (neutral).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Enhances recognition of specified minor languages and dialects. Setting this parameter can improve speech performance in the specified language/dialect scenarios. If the minor language type is not clear, you can set it to "auto" and the model will automatically determine the language type. Supported values:

  `'Chinese', 'Chinese,Yue', 'English', 'Arabic', 'Russian', 'Spanish', 'French', 'Portuguese', 'German', 'Turkish', 'Dutch', 'Ukrainian', 'Vietnamese', 'Indonesian', 'Japanese', 'Italian', 'Korean', 'Thai', 'Polish', 'Romanian', 'Greek', 'Czech', 'Finnish', 'Hindi', 'auto'`
</ParamField>

<ParamField type="object">
  Voice FX settings. Supported audio formats for this parameter: mp3, wav, flac

  <Expandable title="properties">
    <ParamField type="integer">
      Pitch adjustment (darker/brighter). Range: \[-100, 100]. Values closer to -100 generate a deeper (darker) voice; values closer to 100 produce a brighter voice.
    </ParamField>

    <ParamField type="integer">
      Intensity adjustment (powerful/soft). Range: \[-100, 100]. Values closer to -100 generate a more powerful sound; values closer to 100 result in a softer sound.
    </ParamField>

    <ParamField type="integer">
      Timbre adjustment (magnetic/crisp). Range: \[-100, 100]. Values closer to -100 make the voice more full/magnetic; values closer to 100 make it crisper.
    </ParamField>

    <ParamField type="string">
      Sound effect setting (only one may be selected per request). Valid values:

      * `spacious_echo` (large space echo)
      * `auditorium_echo` (auditorium broadcast)
      * `lofi_telephone` (telephone distortion)
      * `robotic` (robotic effect)
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# MiniMax Speech-2.6-hd Text to Speech
Source: https://novita.ai/docs/api-reference/model-apis-minimax-speech-2.6-hd

POST https://api.novita.ai/v3/minimax-speech-2.6-hd

MiniMax's high-definition text-to-speech model, Compared to Speech 02 released in May, Speech 2.6 has three major breakthroughs: stronger multilingual expressiveness, more accurate voice replication, and broader coverage with 40 languages.

<Tip>Best suited for short sentence generation, voice chat, and online social scenarios. Processing is fast, but the text length is limited to less than 10,000 characters. For long-form text, we recommend using [asynchronous TTS synthesis](/api-reference/model-apis-minimax-speech-2.6-hd-async).</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The text to be synthesized. The length must be less than 10,000 characters. Use line breaks to separate paragraphs.\
  To control the pause duration between speech segments, insert `<#x#>` between words or sentences, where `x` is the pause duration in seconds (supports 0.01–99.99, up to two decimal places).\
  Custom speech pauses between text segments are supported, allowing you to control the timing of pauses in the generated audio.\
  Note: Pause markers must be placed between two segments that can be pronounced, and multiple consecutive pause markers are not allowed.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="float">
      Range: \[0.5, 2], default is 1.0

      Controls the speech rate of the generated audio. Optional. Higher values result in faster speech.
    </ParamField>

    <ParamField type="float">
      Range: (0, 10], default is 1.0

      Controls the volume of the generated audio. Optional. Higher values result in louder audio.
    </ParamField>

    <ParamField type="int">
      Range: \[-12, 12], default is 0

      Controls the pitch of the generated audio. Optional. 0 means original timbre. The value must be an integer.
    </ParamField>

    <ParamField type="string">
      The requested timbre ID. Required (choose either this or timbre\_weights).

      Supports both system voices (ID) and cloned voices (ID). The available system voice IDs are as follows:

      * Wise\_Woman
      * Friendly\_Person
      * Inspirational\_girl
      * Deep\_Voice\_Man
      * Calm\_Woman
      * Casual\_Guy
      * Lively\_Girl
      * Patient\_Man
      * Young\_Knight
      * Determined\_Man
      * Lovely\_Girl
      * Decent\_Boy
      * Imposing\_Manner
      * Elegant\_Man
      * Abbess
      * Sweet\_Girl\_2
      * Exuberant\_Girl
    </ParamField>

    <ParamField type="string">
      Controls the emotion of the synthesized speech.

      Currently supports 7 emotions: happy, sad, angry, fearful, disgusted, surprised, neutral.

      Allowed values: `["happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral"]`
    </ParamField>

    <ParamField type="bool">
      This parameter supports English text normalization, which improves performance in number-reading scenarios, but this comes at the cost of a slight increase in latency. If not provided, the default is false.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Range: \[8000, 16000, 22050, 24000, 32000, 44100]

      The sample rate of the generated audio. Optional, default is 32000.
    </ParamField>

    <ParamField type="number">
      Range: \[32000, 64000, 128000, 256000]

      The bitrate of the generated audio. Optional, default is 128000. This parameter only applies to mp3 audio format.
    </ParamField>

    <ParamField type="string">
      The audio format of the output. Default is mp3. Options: `mp3`, `pcm`, `flac`, `wav`. wav is only supported for non-streaming output.
    </ParamField>

    <ParamField type="number">
      Number of audio channels. Default is 1 (mono). Options:

      1: mono

      2: stereo
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="list">
      Replacement of text, symbols and corresponding pronunciations that require manual handling.
      Replace the pronunciation (adjust the tone/replace the pronunciation of other characters) using the following format:

      \[“omg/oh my god”]

      For Chinese texts, tones are replaced by numbers, with 1 for the first tone (high), 2 for the second tone (rising), 3 for the third tone (low/dipping), 4 for the fourth tone (falling), and 5 for the fifth tone (neutral).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  Required if voice\_id is not provided (choose one of the two).

  <Expandable title="properties">
    <ParamField type="string">
      The requested timbre ID. Must be provided together with the weight parameter.
    </ParamField>

    <ParamField type="number">
      Range: \[1, 100]

      The weight, must be provided together with voice\_id. Up to 4 timbres can be mixed. The value must be an integer. The higher the proportion for a single timbre, the more the synthesized voice will resemble it.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="boolean">
  Whether to enable streaming. Default is false, i.e., streaming is disabled.
</ParamField>

<ParamField type="string">
  Enhances recognition of specified minor languages and dialects. Setting this parameter can improve speech performance in the specified language/dialect scenarios. If the minor language type is not clear, you can set it to "auto" and the model will automatically determine the language type. Supported values:

  `'Chinese', 'Chinese,Yue', 'English', 'Arabic', 'Russian', 'Spanish', 'French', 'Portuguese', 'German', 'Turkish', 'Dutch', 'Ukrainian', 'Vietnamese', 'Indonesian', 'Japanese', 'Italian', 'Korean', 'Thai', 'Polish', 'Romanian', 'Greek', 'Czech', 'Finnish', 'Hindi', 'auto'`
</ParamField>

<ParamField type="string">
  Controls the output format of the result. Optional values are `url` and `hex`. The default is `hex`. This parameter only takes effect in non-streaming scenarios; in streaming mode, only hex format is supported. The returned URL is valid for 24 hours.
</ParamField>

<ParamField type="object">
  Voice FX settings. Supported audio formats for this parameter:

  * Non-streaming: mp3, wav, flac
  * Streaming: mp3

  <Expandable title="properties">
    <ParamField type="integer">
      Pitch adjustment (darker/brighter). Range: \[-100, 100]. Values closer to -100 generate a deeper (darker) voice; values closer to 100 produce a brighter voice.
    </ParamField>

    <ParamField type="integer">
      Intensity adjustment (powerful/soft). Range: \[-100, 100]. Values closer to -100 generate a more powerful sound; values closer to 100 result in a softer sound.
    </ParamField>

    <ParamField type="integer">
      Timbre adjustment (magnetic/crisp). Range: \[-100, 100]. Values closer to -100 make the voice more full/magnetic; values closer to 100 make it crisper.
    </ParamField>

    <ParamField type="string">
      Sound effect setting (only one may be selected per request). Valid values:

      * `spacious_echo` (large space echo)
      * `auditorium_echo` (auditorium broadcast)
      * `lofi_telephone` (telephone distortion)
      * `robotic` (robotic effect)
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="audio" type="string">
  The synthesized audio segment, encoded in hex and generated in the format specified by `audio_setting.format` (mp3/pcm/flac). The return format is determined by the `output_format` parameter. When `stream` is true, only hex format is supported.
</ResponseField>

<ResponseField name="status" type="number">
  The current status of the audio stream. Returned only when `stream` is true. 1 indicates synthesis in progress, 2 indicates synthesis completed.
</ResponseField>


# MiniMax Speech-2.6-hd Async Long TTS
Source: https://novita.ai/docs/api-reference/model-apis-minimax-speech-2.6-hd-async

POST https://api.novita.ai/v3/async/minimax-speech-2.6-hd

MiniMax's high-definition text-to-speech model, Compared to Speech 02 released in May, Speech 2.6 has three major breakthroughs: stronger multilingual expressiveness, more accurate voice replication, and broader coverage with 40 languages.

<Tip>Best suited for long-form text-to-speech generation, such as entire books. Task queue times may be longer. For short sentence generation, voice chat, or online social scenarios, we recommend using [synchronous TTS](/api-reference/model-apis-minimax-speech-2.6-hd).</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The text to be synthesized. Maximum length: 50,000 characters.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Range: \[0.5, 2], default is 1.0.

      Controls the speech rate of the generated audio. Optional. Higher values result in faster speech.
    </ParamField>

    <ParamField type="number">
      Range: (0, 10], default is 1.0.

      Controls the volume of the generated audio. Optional. Higher values result in louder audio.
    </ParamField>

    <ParamField type="number">
      Range: \[-12, 12], default is 0.

      Controls the pitch of the generated audio. Optional. 0 means original timbre. The value must be an integer.
    </ParamField>

    <ParamField type="string">
      The requested voice ID.

      Supports both system voices (ID) and cloned voices (ID). The available system voice IDs are as follows:

      * Wise\_Woman
      * Friendly\_Person
      * Inspirational\_girl
      * Deep\_Voice\_Man
      * Calm\_Woman
      * Casual\_Guy
      * Lively\_Girl
      * Patient\_Man
      * Young\_Knight
      * Determined\_Man
      * Lovely\_Girl
      * Decent\_Boy
      * Imposing\_Manner
      * Elegant\_Man
      * Abbess
      * Sweet\_Girl\_2
      * Exuberant\_Girl
    </ParamField>

    <ParamField type="string">
      Controls the emotion of the synthesized speech.

      Currently supports 7 emotions: happy, sad, angry, fearful, disgusted, surprised, neutral.

      Allowed values: `["happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral"]`
    </ParamField>

    <ParamField type="bool">
      This parameter supports English text normalization, which improves performance in number-reading scenarios, but this comes at the cost of a slight increase in latency. If not provided, the default is false.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Range: \[8000, 16000, 22050, 24000, 32000, 44100]

      The sample rate of the generated audio. Optional, default is 32000.
    </ParamField>

    <ParamField type="number">
      Range: \[32000, 64000, 128000, 256000]

      The bitrate of the generated audio. Optional, default is 128000. This parameter only applies to mp3 audio format.
    </ParamField>

    <ParamField type="string">
      The audio format of the output. Default is mp3. Options: `mp3`, `pcm`, `flac`, `wav`. wav is only supported for non-streaming output.
    </ParamField>

    <ParamField type="number">
      Number of audio channels. Default is 1 (mono). Options:

      1: mono

      2: stereo
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="list">
      Replacement of text, symbols and corresponding pronunciations that require manual handling.
      Replace the pronunciation (adjust the tone/replace the pronunciation of other characters) using the following format:

      \[“omg/oh my god”]

      For Chinese texts, tones are replaced by numbers, with 1 for the first tone (high), 2 for the second tone (rising), 3 for the third tone (low/dipping), 4 for the fourth tone (falling), and 5 for the fifth tone (neutral).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Enhances recognition of specified minor languages and dialects. Setting this parameter can improve speech performance in the specified language/dialect scenarios. If the minor language type is not clear, you can set it to "auto" and the model will automatically determine the language type. Supported values:

  `'Chinese', 'Chinese,Yue', 'English', 'Arabic', 'Russian', 'Spanish', 'French', 'Portuguese', 'German', 'Turkish', 'Dutch', 'Ukrainian', 'Vietnamese', 'Indonesian', 'Japanese', 'Italian', 'Korean', 'Thai', 'Polish', 'Romanian', 'Greek', 'Czech', 'Finnish', 'Hindi', 'auto'`
</ParamField>

<ParamField type="object">
  Voice FX settings. Supported audio formats for this parameter: mp3, wav, flac

  <Expandable title="properties">
    <ParamField type="integer">
      Pitch adjustment (darker/brighter). Range: \[-100, 100]. Values closer to -100 generate a deeper (darker) voice; values closer to 100 produce a brighter voice.
    </ParamField>

    <ParamField type="integer">
      Intensity adjustment (powerful/soft). Range: \[-100, 100]. Values closer to -100 generate a more powerful sound; values closer to 100 result in a softer sound.
    </ParamField>

    <ParamField type="integer">
      Timbre adjustment (magnetic/crisp). Range: \[-100, 100]. Values closer to -100 make the voice more full/magnetic; values closer to 100 make it crisper.
    </ParamField>

    <ParamField type="string">
      Sound effect setting (only one may be selected per request). Valid values:

      * `spacious_echo` (large space echo)
      * `auditorium_echo` (auditorium broadcast)
      * `lofi_telephone` (telephone distortion)
      * `robotic` (robotic effect)
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# MiniMax Speech-2.6-turbo Text to Speech
Source: https://novita.ai/docs/api-reference/model-apis-minimax-speech-2.6-turbo

POST https://api.novita.ai/v3/minimax-speech-2.6-turbo

MiniMax's high-definition text-to-speech model, Compared to Speech 02 released in May, Speech 2.6 has three major breakthroughs: stronger multilingual expressiveness, more accurate voice replication, and broader coverage with 40 languages.

<Tip>Best suited for short sentence generation, voice chat, and online social scenarios. Processing is fast, but the text length is limited to less than 10,000 characters. For long-form text, we recommend using [asynchronous TTS synthesis](/api-reference/model-apis-minimax-speech-2.6-turbo-async).</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The text to be synthesized. The length must be less than 10,000 characters. Use line breaks to separate paragraphs.\
  To control the pause duration between speech segments, insert `<#x#>` between words or sentences, where `x` is the pause duration in seconds (supports 0.01–99.99, up to two decimal places).\
  Custom speech pauses between text segments are supported, allowing you to control the timing of pauses in the generated audio.\
  Note: Pause markers must be placed between two segments that can be pronounced, and multiple consecutive pause markers are not allowed.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="float">
      Range: \[0.5, 2], default is 1.0

      Controls the speech rate of the generated audio. Optional. Higher values result in faster speech.
    </ParamField>

    <ParamField type="float">
      Range: (0, 10], default is 1.0

      Controls the volume of the generated audio. Optional. Higher values result in louder audio.
    </ParamField>

    <ParamField type="int">
      Range: \[-12, 12], default is 0

      Controls the pitch of the generated audio. Optional. 0 means original timbre. The value must be an integer.
    </ParamField>

    <ParamField type="string">
      The requested timbre ID. Required (choose either this or timbre\_weights).

      Supports both system voices (ID) and cloned voices (ID). The available system voice IDs are as follows:

      * Wise\_Woman
      * Friendly\_Person
      * Inspirational\_girl
      * Deep\_Voice\_Man
      * Calm\_Woman
      * Casual\_Guy
      * Lively\_Girl
      * Patient\_Man
      * Young\_Knight
      * Determined\_Man
      * Lovely\_Girl
      * Decent\_Boy
      * Imposing\_Manner
      * Elegant\_Man
      * Abbess
      * Sweet\_Girl\_2
      * Exuberant\_Girl
    </ParamField>

    <ParamField type="string">
      Controls the emotion of the synthesized speech.

      Currently supports 7 emotions: happy, sad, angry, fearful, disgusted, surprised, neutral.

      Allowed values: `["happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral"]`
    </ParamField>

    <ParamField type="bool">
      This parameter supports English text normalization, which improves performance in number-reading scenarios, but this comes at the cost of a slight increase in latency. If not provided, the default is false.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Range: \[8000, 16000, 22050, 24000, 32000, 44100]

      The sample rate of the generated audio. Optional, default is 32000.
    </ParamField>

    <ParamField type="number">
      Range: \[32000, 64000, 128000, 256000]

      The bitrate of the generated audio. Optional, default is 128000. This parameter only applies to mp3 audio format.
    </ParamField>

    <ParamField type="string">
      The audio format of the output. Default is mp3. Options: `mp3`, `pcm`, `flac`, `wav`. wav is only supported for non-streaming output.
    </ParamField>

    <ParamField type="number">
      Number of audio channels. Default is 1 (mono). Options:

      1: mono

      2: stereo
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="list">
      Replacement of text, symbols and corresponding pronunciations that require manual handling.
      Replace the pronunciation (adjust the tone/replace the pronunciation of other characters) using the following format:

      \[“omg/oh my god”]

      For Chinese texts, tones are replaced by numbers, with 1 for the first tone (high), 2 for the second tone (rising), 3 for the third tone (low/dipping), 4 for the fourth tone (falling), and 5 for the fifth tone (neutral).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  Required if voice\_id is not provided (choose one of the two).

  <Expandable title="properties">
    <ParamField type="string">
      The requested timbre ID. Must be provided together with the weight parameter.
    </ParamField>

    <ParamField type="number">
      Range: \[1, 100]

      The weight, must be provided together with voice\_id. Up to 4 timbres can be mixed. The value must be an integer. The higher the proportion for a single timbre, the more the synthesized voice will resemble it.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="boolean">
  Whether to enable streaming. Default is false, i.e., streaming is disabled.
</ParamField>

<ParamField type="string">
  Enhances recognition of specified minor languages and dialects. Setting this parameter can improve speech performance in the specified language/dialect scenarios. If the minor language type is not clear, you can set it to "auto" and the model will automatically determine the language type. Supported values:

  `'Chinese', 'Chinese,Yue', 'English', 'Arabic', 'Russian', 'Spanish', 'French', 'Portuguese', 'German', 'Turkish', 'Dutch', 'Ukrainian', 'Vietnamese', 'Indonesian', 'Japanese', 'Italian', 'Korean', 'Thai', 'Polish', 'Romanian', 'Greek', 'Czech', 'Finnish', 'Hindi', 'auto'`
</ParamField>

<ParamField type="string">
  Controls the output format of the result. Optional values are `url` and `hex`. The default is `hex`. This parameter only takes effect in non-streaming scenarios; in streaming mode, only hex format is supported. The returned URL is valid for 24 hours.
</ParamField>

<ParamField type="object">
  Voice FX settings. Supported audio formats for this parameter:

  * Non-streaming: mp3, wav, flac
  * Streaming: mp3

  <Expandable title="properties">
    <ParamField type="integer">
      Pitch adjustment (darker/brighter). Range: \[-100, 100]. Values closer to -100 generate a deeper (darker) voice; values closer to 100 produce a brighter voice.
    </ParamField>

    <ParamField type="integer">
      Intensity adjustment (powerful/soft). Range: \[-100, 100]. Values closer to -100 generate a more powerful sound; values closer to 100 result in a softer sound.
    </ParamField>

    <ParamField type="integer">
      Timbre adjustment (magnetic/crisp). Range: \[-100, 100]. Values closer to -100 make the voice more full/magnetic; values closer to 100 make it crisper.
    </ParamField>

    <ParamField type="string">
      Sound effect setting (only one may be selected per request). Valid values:

      * `spacious_echo` (large space echo)
      * `auditorium_echo` (auditorium broadcast)
      * `lofi_telephone` (telephone distortion)
      * `robotic` (robotic effect)
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="audio" type="string">
  The synthesized audio segment, encoded in hex and generated in the format specified by `audio_setting.format` (mp3/pcm/flac). The return format is determined by the `output_format` parameter. When `stream` is true, only hex format is supported.
</ResponseField>

<ResponseField name="status" type="number">
  The current status of the audio stream. Returned only when `stream` is true. 1 indicates synthesis in progress, 2 indicates synthesis completed.
</ResponseField>


# MiniMax Speech-2.6-turbo Async Long TTS
Source: https://novita.ai/docs/api-reference/model-apis-minimax-speech-2.6-turbo-async

POST https://api.novita.ai/v3/async/minimax-speech-2.6-turbo

MiniMax's high-definition text-to-speech model, Compared to Speech 02 released in May, Speech 2.6 has three major breakthroughs: stronger multilingual expressiveness, more accurate voice replication, and broader coverage with 40 languages.

<Tip>Best suited for long-form text-to-speech generation, such as entire books. Task queue times may be longer. For short sentence generation, voice chat, or online social scenarios, we recommend using [synchronous TTS](/api-reference/model-apis-minimax-speech-2.6-turbo).</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The text to be synthesized. Maximum length: 50,000 characters.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Range: \[0.5, 2], default is 1.0.

      Controls the speech rate of the generated audio. Optional. Higher values result in faster speech.
    </ParamField>

    <ParamField type="number">
      Range: (0, 10], default is 1.0.

      Controls the volume of the generated audio. Optional. Higher values result in louder audio.
    </ParamField>

    <ParamField type="number">
      Range: \[-12, 12], default is 0.

      Controls the pitch of the generated audio. Optional. 0 means original timbre. The value must be an integer.
    </ParamField>

    <ParamField type="string">
      The requested voice ID.

      Supports both system voices (ID) and cloned voices (ID). The available system voice IDs are as follows:

      * Wise\_Woman
      * Friendly\_Person
      * Inspirational\_girl
      * Deep\_Voice\_Man
      * Calm\_Woman
      * Casual\_Guy
      * Lively\_Girl
      * Patient\_Man
      * Young\_Knight
      * Determined\_Man
      * Lovely\_Girl
      * Decent\_Boy
      * Imposing\_Manner
      * Elegant\_Man
      * Abbess
      * Sweet\_Girl\_2
      * Exuberant\_Girl
    </ParamField>

    <ParamField type="string">
      Controls the emotion of the synthesized speech.

      Currently supports 7 emotions: happy, sad, angry, fearful, disgusted, surprised, neutral.

      Allowed values: `["happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral"]`
    </ParamField>

    <ParamField type="bool">
      This parameter supports English text normalization, which improves performance in number-reading scenarios, but this comes at the cost of a slight increase in latency. If not provided, the default is false.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Range: \[8000, 16000, 22050, 24000, 32000, 44100]

      The sample rate of the generated audio. Optional, default is 32000.
    </ParamField>

    <ParamField type="number">
      Range: \[32000, 64000, 128000, 256000]

      The bitrate of the generated audio. Optional, default is 128000. This parameter only applies to mp3 audio format.
    </ParamField>

    <ParamField type="string">
      The audio format of the output. Default is mp3. Options: `mp3`, `pcm`, `flac`, `wav`. wav is only supported for non-streaming output.
    </ParamField>

    <ParamField type="number">
      Number of audio channels. Default is 1 (mono). Options:

      1: mono

      2: stereo
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="list">
      Replacement of text, symbols and corresponding pronunciations that require manual handling.
      Replace the pronunciation (adjust the tone/replace the pronunciation of other characters) using the following format:

      \[“omg/oh my god”]

      For Chinese texts, tones are replaced by numbers, with 1 for the first tone (high), 2 for the second tone (rising), 3 for the third tone (low/dipping), 4 for the fourth tone (falling), and 5 for the fifth tone (neutral).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Enhances recognition of specified minor languages and dialects. Setting this parameter can improve speech performance in the specified language/dialect scenarios. If the minor language type is not clear, you can set it to "auto" and the model will automatically determine the language type. Supported values:

  `'Chinese', 'Chinese,Yue', 'English', 'Arabic', 'Russian', 'Spanish', 'French', 'Portuguese', 'German', 'Turkish', 'Dutch', 'Ukrainian', 'Vietnamese', 'Indonesian', 'Japanese', 'Italian', 'Korean', 'Thai', 'Polish', 'Romanian', 'Greek', 'Czech', 'Finnish', 'Hindi', 'auto'`
</ParamField>

<ParamField type="object">
  Voice FX settings. Supported audio formats for this parameter: mp3, wav, flac

  <Expandable title="properties">
    <ParamField type="integer">
      Pitch adjustment (darker/brighter). Range: \[-100, 100]. Values closer to -100 generate a deeper (darker) voice; values closer to 100 produce a brighter voice.
    </ParamField>

    <ParamField type="integer">
      Intensity adjustment (powerful/soft). Range: \[-100, 100]. Values closer to -100 generate a more powerful sound; values closer to 100 result in a softer sound.
    </ParamField>

    <ParamField type="integer">
      Timbre adjustment (magnetic/crisp). Range: \[-100, 100]. Values closer to -100 make the voice more full/magnetic; values closer to 100 make it crisper.
    </ParamField>

    <ParamField type="string">
      Sound effect setting (only one may be selected per request). Valid values:

      * `spacious_echo` (large space echo)
      * `auditorium_echo` (auditorium broadcast)
      * `lofi_telephone` (telephone distortion)
      * `robotic` (robotic effect)
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Minimax Video-01
Source: https://novita.ai/docs/api-reference/model-apis-minimax-video-01

POST https://api.novita.ai/v3/async/minimax-video-01

Minimax Video-01 (also known as Hailuo) is an AI video generation model that creates 6-second videos at 720p resolution and 25fps. It supports both text-to-video and image-to-video generation.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Prompt text required to guide the generation.

  Range: `1 <= x <= 2000`.
</ParamField>

<ParamField type="string">
  The URL of the first frame image to be used for video generation.
</ParamField>

<ParamField type="boolean">
  Whether to enable prompt optimization.

  Default: `true`.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>

## Example

Here is an example of how to use the Minimax Video-01 API.

1. Generate a task\_id by sending a POST request to the Minimax Video-01 API.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/minimax-video-01' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "prompt": "A cute panda is walking in the grassland slowly",
    "image_url": "https://pub-f964a1c641c04024bce400ad128c8cd6.r2.dev/minimax-video-01-image.jpg",
    "enable_prompt_expansion": True,
}'
```

`Response:`

```js theme={"system"}
{
    "task_id": "{Returned Task ID}"
}
```

2. Use `task_id` to get output videos.

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get videos url in `videos` of response.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id={Returned Task ID}' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "task": {
        "task_id": "{Returned Task ID}",
        "task_type": "MINIMAX_VIDEO_01",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 100
    },
    "images": [],
    "videos": [
        {
            "video_url": "{The URL of the generated video}",
            "video_url_ttl": "3600",
            "video_type": "mp4"
        }
    ]
}
```

`Video files:`

<video />


# MiniMax Quick Voice Cloning
Source: https://novita.ai/docs/api-reference/model-apis-minimax-voice-cloning

POST https://api.novita.ai/v3/minimax-voice-cloning

This interface will allow users to efficiently clone a voice, as specified in the audio file. Potential use cases include: IP voice cloning, voice cloning, and other scenarios where quick voice cloning is required.
The quick voice clone generated by this API is temporary. If you wish to permanently retain a cloned voice, you must use this voice in any T2A speech synthesis API within 168 hours (7 days) (excluding preview actions within this API). Otherwise, the cloned voice will be deleted.

Applicable scenarios for this API include: IP voice cloning, timbre cloning, and other use cases requiring rapid voice cloning.

Notes:

* The uploaded audio file must be in mp3, m4a, or wav format.
* The duration of the uploaded audio must be at least 10 seconds and no more than 5 minutes.
* The uploaded audio file size must not exceed 20 MB.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The URL of the audio file to be cloned. Supported formats: mp3, m4a, wav.
</ParamField>

<ParamField>
  Voice cloning parameters. Providing this parameter can help improve the similarity and stability of the synthesized voice.

  If this parameter is used, you must also upload a short sample audio (duration less than 8 seconds) and the corresponding transcript. Supported audio formats: mp3, m4a, wav.

  <Expandable title="properties">
    <ParamField type="string">
      Audio prompt parameter. The URL of the sample audio. Duration must be less than 8 seconds.
    </ParamField>

    <ParamField type="string">
      Audio prompt parameter. The transcript corresponding to the sample audio. The text must match the audio content, and end with punctuation.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Voice cloning preview parameter. The model will use the cloned voice to synthesize this text and return the result as an audio URL for preview. Maximum 2000 characters. Note: Preview will be charged according to the number of characters, at the same rate as T2A APIs.
</ParamField>

<ParamField type="string">
  Voice cloning preview parameter. Specifies the speech model to use for preview. Required if the "text" field is provided.<br />
  Options: `speech-02-hd`, `speech-02-turbo`, `speech-2.5-hd-preview`, `speech-2.5-turbo-preview`
</ParamField>

<ParamField type="float">
  Voice cloning parameter. Value range: \[0, 1]. If provided, sets the text validation accuracy threshold. Default is 0.7 if not specified.
</ParamField>

<ParamField type="bool">
  Voice cloning parameter. Whether to enable noise reduction. Defaults to false if not specified.
</ParamField>

<ParamField type="bool">
  Voice cloning parameter. Whether to enable volume normalization. Defaults to false if not specified.
</ParamField>

## Response

<ResponseField name="demo_audio_url" type="string">
  If both the preview text (<code>text</code>) and preview model (<code>model</code>) are provided in the request body, this parameter returns the preview audio as a URL.
</ResponseField>

<ResponseField name="voice_id" type="string">
  The generated <code>voice\_id</code>.
</ResponseField>

## Example

Below is an example of how to use the Minimax Voice Cloning API to clone a voice.

`Request:`

```bash theme={"system"}
curl \
-X POST https://api.novita.ai/v3/minimax-voice-cloning \
-H "Authorization: Bearer $your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "audio_url": "https://example.com/voice.mp3",
  "text": "Audio generation technology is evolving rapidly, enabling the creation of speech, music, and sound effects from text or data inputs. It supports applications in media, accessibility, customer service, and content creation. With improved quality and customization, these tools are increasingly integrated into digital platforms across various industries.",
  "model": "speech-01-hd",
  "need_noise_reduction": true,
  "need_volume_normalization": true
}'
```

`Response:`

```js theme={"system"}
{
  "demo_audio_url": "https://demo.com/audio.mp3", // Audio sample
  "voice_id": "xxxxxxx" // Generated voice_id
}
```


# PixVerse V4.5 Image to Video
Source: https://novita.ai/docs/api-reference/model-apis-pixverse-v4.5-i2v

POST https://api.novita.ai/v3/async/pixverse-v4.5-i2v

Generate high-quality videos from text descriptions and image using PixVerse's latest v4.5 model. Supports multiple resolutions, aspect ratios, and motion modes for versatile video creation.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Text prompt for video generation.

  * Maximum length: 2048 characters
  * Clear description of desired scene and motion
</ParamField>

<ParamField type="string">
  First frame of the video.

  * Supported image formats include .jpg/.jpeg/.png
  * The image file size cannot exceed 10MB
  * The image resolution should not be less than 300\*300px
  * The aspect ratio of the image should be between 1:2.5 \~ 2.5:1
</ParamField>

<ParamField type="string">
  Video quality. Default: `540p`<br />
  Accepted values:

  * fast\_mode is false: `360p`, `540p`, `720p`, `1080p`
  * fast\_mode is true: `360p`, `540p`, `720p`
</ParamField>

<ParamField type="string">
  Negative prompt for generation.

  * Maximum length: 2048 characters
</ParamField>

<ParamField type="boolean">
  Whether to enable fast mode, which will generate videos more quickly but may reduce quality and lower the price.

  Default: `false`.
</ParamField>

<ParamField type="string">
  Style preset (v3.5 only).<br />
  Accepted values: `anime`, `3d_animation`, `clay`, `comic`, `cyberpunk`
</ParamField>

<ParamField type="integer">
  The random seed to use for the generation.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# PixVerse V4.5 Text to Video
Source: https://novita.ai/docs/api-reference/model-apis-pixverse-v4.5-t2v

POST https://api.novita.ai/v3/async/pixverse-v4.5-t2v

Generate high-quality videos from text descriptions using PixVerse's latest v4.5 model. Supports multiple resolutions, aspect ratios, and motion modes for versatile video creation.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Text prompt for video generation.

  * Maximum length: 2048 characters
  * Clear description of desired scene and motion
</ParamField>

<ParamField type="string">
  Video aspect ratio. Default: `16:9`<br />
  Accepted values: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`
</ParamField>

<ParamField type="string">
  Video quality. Default: `540p`<br />
  Accepted values:

  * fast\_mode is false: `360p`, `540p`, `720p`, `1080p`
  * fast\_mode is true: `360p`, `540p`, `720p`
</ParamField>

<ParamField type="string">
  Negative prompt for generation.

  * Maximum length: 2048 characters
</ParamField>

<ParamField type="boolean">
  Whether to enable fast mode, which will generate videos more quickly but may reduce quality and lower the price.

  Default: `false`.
</ParamField>

<ParamField type="string">
  Style preset (v3.5 only).<br />
  Accepted values: `anime`, `3d_animation`, `clay`, `comic`, `cyberpunk`
</ParamField>

<ParamField type="integer">
  The random seed to use for the generation.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Progress
Source: https://novita.ai/docs/api-reference/model-apis-progress-deprecated

GET https://api.novita.ai/v2/progress

## GET Progress

This API provides a query for the result of image generation, which can be in progress, failed, or successful. If successful, it will return the S3 URL of the generated image.

## Request Headers

<ParamField type="string" />

## Query Parameters

<ParamField type="arraystring[]">
  The ID of the task being queried.
</ParamField>

## Response

<ResponseField name="code" type="integer">
  CodeNormal=0, CodeInternalError=-1, CodeInvalidJSON=1, CodeModelNotExist=2, CodeTaskIdNotExist=3, CodeInvalidAuth=4, CodeHostUnavailable=5, CodeParamRangeOutOfLimit=6, CodeCostBalanceFailure=7, CodeSamplerNotExist=8, CodeTimeout=9, CodeNotSupport=10
</ResponseField>

<ResponseField name="msg" type="string" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="status" type="integer" />

    <ResponseField name="progress" type="number" />

    <ResponseField name="eta_relative" type="number" />

    <ResponseField name="imgs" type="string[]¦null" />

    <ResponseField name="failed_reason" type="string" />

    <ResponseField name="current_images" type="string[]" />

    <ResponseField name="submit_time" type="string" />

    <ResponseField name="execution_time" type="string" />

    <ResponseField name="txt2img_time" type="string" />

    <ResponseField name="finish_time" type="string" />

    <ResponseField name="info" type="string" />

    <ResponseField name="enable_nsfw_detection" type="boolean" />

    <ResponseField name="nsfw_detection_result" type="object[]">
      <Expandable title="properties">
        <ResponseField name="valid" type="boolean" />

        <ResponseField name="confidence" type="number" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

request

```bash theme={"system"}
curl --location 'https://api.novita.ai/v2/progress?task_id=' \
--header 'Authorization: Bearer {{API Key}}'
```

response

```json theme={"system"}
{
  "code": 0,
  "msg": "",
  "data": {
    "status": 2,
    "progress": 1,
    "eta_relative": 0,
    "imgs": [
      "https://stars-test.s3.amazonaws.com/free/859d452b-f682-45fc-b0e7-5bd7b61a107d-0.png",
      "https://stars-test.s3.amazonaws.com/free/859d452b-f682-45fc-b0e7-5bd7b61a107d-1.png",
      "https://stars-test.s3.amazonaws.com/free/859d452b-f682-45fc-b0e7-5bd7b61a107d-2.png",
      "https://stars-test.s3.amazonaws.com/free/859d452b-f682-45fc-b0e7-5bd7b61a107d-3.png"
    ],
    "failed_reason": "",
    "current_images": [""],
    "submit_time": "2024-01-24 15:08:17",
    "execution_time": "2024-01-24 15:08:17",
    "txt2img_time": "2024-01-24 15:08:22",
    "finish_time": "2024-01-24 15:08:22",
    "info": "",
    "enable_nsfw_detection": true,
    "nsfw_detection_result": [
      {
        "valid": true,
        "confidence": 57.62467
      },
      {
        "valid": true,
        "confidence": 3.908125
      },
      {
        "valid": true,
        "confidence": 99.84468
      },
      {
        "valid": true,
        "confidence": 2.440833
      }
    ],
    "debug_info": {
      "submit_time_ms": 1706080097101,
      "execution_time_ms": 1706080097369,
      "txt2img_time_ms": 1706080102333,
      "finish_time_ms": 1706080102479
    }
  }
}
```


# Qwen-Image Edit
Source: https://novita.ai/docs/api-reference/model-apis-qwen-image-edit

POST https://api.novita.ai/v3/async/qwen-image-edit

Qwen-Image Edit — a 20B MMDiT model for next-gen image edit generation. Built on 20B Qwen-Image, it brings precise bilingual text editing (Chinese & English) while preserving style, and supports both semantic and appearance-level editing.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the image generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The prompt to generate an image from.
</ParamField>

<ParamField type="string">
  The image to generate an image from.
</ParamField>

<ParamField type="integer">
  The random seed to use for the generation. -1 means a random seed will be used. Range: -1 \~ 2147483647. Default is -1.
</ParamField>

<ParamField type="string">
  The format of the output image. Default is jpeg.<br />
  Enum: `jpeg`, `png`, `webp`
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Qwen-Image Text to Image
Source: https://novita.ai/docs/api-reference/model-apis-qwen-txt2img

POST https://api.novita.ai/v3/async/qwen-image-txt2img

Qwen-Image — a 20B MMDiT model for next-gen text-to-image generation. Especially strong at creating stunning graphic posters with native text.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the image generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Text prompt for image generation.
</ParamField>

<ParamField type="string">
  The size of the generated media in pixels (width\*height). Default is `1024*1024`. Range: 256 \~ 1536 per dimension.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>

## Example

Here is an example of how to use the Qwen-Image Text to Image API.

1. Generate a task\_id by sending a POST request to the Qwen-Image Text to Image API.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/qwen-image-txt2img' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "prompt": "A cinematic scene of a quiet girl with short brown hair sitting by a misty lake at dawn. She wears an oversized sweater, holding a warm mug. Soft morning light filters through the trees, cool tones, tranquil mood, light fog, 50mm photography style.",
    "size": "1024*1024"
}'
```

`Response:`

```js theme={"system"}
{
    "task_id": "{Returned Task ID}"
}
```

2. Use `task_id` to get output images.

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get image url in `images` of response.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id={Returned Task ID}' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "extra": {
        "has_nsfw_contents": []
    },
    "task": {
        "task_id": "0cdee604-7168-4ff4-9b2a-9793c0cc6cdf",
        "task_type": "QWEN_IMAGE_TEXT_TO_IMAGE",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 0
    },
    "images": [
        {
            "image_url": "https://d2p7pge43lyniu.cloudfront.net/output/9dc2f15a-0dd3-49a3-a121-a352f229c84b-u2_c61a700e-dfec-4c01-81c6-bf890ad68f6c.jpeg",
            "image_url_ttl": "0",
            "image_type": "jpeg",
            "nsfw_detection_result": null
        }
    ],
    "videos": [],
    "audios": []
}
```

`Image files:`

<Frame>
  <img alt="LLM API Providers" />
</Frame>


# Reimagine
Source: https://novita.ai/docs/api-reference/model-apis-reimagine

POST https://api.novita.ai/v3/reimagine

**This feature allows you to automatically generate variations of a single image.**

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Optional extra parameters for the request.

  <Expandable title="properties">
    <ParamField type="string">
      The returned image type. Default is png.Enum: `png, webp, jpeg`
    </ParamField>

    <ParamField type="object">
      Dedicated Endpoints settings, which only take effect for users who have already subscribed to the [Dedicated Endpoints Documentation](/guides/model-apis-dedicated-endpoints).

      <Expandable title="properties">
        <ParamField type="boolean">
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  The base64 of original image, with a maximum resolution of 1024 x 1024 and a maximum file size of 30 Mb.
</ParamField>

## Response

<ResponseField name="image_file" type="string">
  The Base64-encoded content of the returned image.
</ResponseField>

<ResponseField name="image_type" type="string">
  The returned image type.<br />
  Enum: `png`, `webp`, `jpeg`
</ResponseField>

## Example

This API allows you to automatically generate multiple variations of a single image.

**Try it in [playground](https://novita.ai/playground#reimagine).**

`Request:`

```bash theme={"system"}
curl --location --request POST 'https://api.novita.ai/v3/reimagine' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"image_file":"{{Base64 encoded image}}"
}'
```

HTTP status codes in the 2xx range indicate that the request has been successfully accepted. A code of 400 signifies a request parameter error, while status codes in the 5xx range indicate internal server errors.

You can retrieve the image URL in the `image_file` field of the response in base64 format.

`Response:`

```js theme={"system"}
{
    "image_file": "{{Base64 encoded image}}",
    "image_type": "png"
}
```

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>


# Remove Background
Source: https://novita.ai/docs/api-reference/model-apis-remove-background

POST https://api.novita.ai/v3/remove-background

**Automatically remove the background from images.**

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Optional extra parameters for the request.

  <Expandable title="properties">
    <ParamField type="string">
      The returned image type. Default is png.<br />
      Enum: `png`, `webp`, `jpeg`
    </ParamField>

    <ParamField type="object">
      Dedicated Endpoints settings, which only take effect for users who have already subscribed to the [Dedicated Endpoints Documentation](/guides/model-apis-dedicated-endpoints).

      <Expandable title="properties">
        <ParamField type="boolean">
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  The base64 original image, with a maximum resolution of 16M and a maximum file size of 30 Mb. Supports PNG and JPEG format images.
</ParamField>

## Response

<ResponseField name="image_file" type="string">
  The Base64-encoded content of the returned image.
</ResponseField>

<ResponseField name="image_type" type="string">
  The returned image type.<br />
  Enum: `png`, `webp`, `jpeg`
</ResponseField>

## Example

This API automatically removes the background from images.

**Try it in the [playground](https://novita.ai/playground#remove-background).**

`Request:`

```bash theme={"system"}
curl --location --request POST 'https://api.novita.ai/v3/remove-background' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"image_file":"{{Base64 encoded image}}"
}'
```

HTTP status codes in the 2xx range indicate that the request has been successfully accepted. A code of 400 means there is an error with the request parameters, while status codes in the 5xx range indicate internal server errors.

You can obtain the image URL in the `image_file` field of the response in base64 format.

`Response:`

```js theme={"system"}
{
    "image_file": "{{Base64 encoded image}}",
    "image_type": "png"
}
```

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>


# Remove Text
Source: https://novita.ai/docs/api-reference/model-apis-remove-text

POST https://api.novita.ai/v3/remove-text

`POST https://api.novita.ai/v3/remove-text`

**Automatically remove text from images.**

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Optional extra parameters for the request.

  <Expandable title="properties">
    <ParamField type="string">
      The returned image type. Default is png.<br />
      Enum: `png, webp, jpeg`
    </ParamField>

    <ParamField type="object">
      Dedicated Endpoints settings, which only take effect for users who have already subscribed to the [Dedicated Endpoints Documentation](/guides/model-apis-dedicated-endpoints).

      <Expandable title="properties">
        <ParamField type="boolean">
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  The base64 original image, with a maximum resolution of 1024 x 1024 pixels and a maximum file size of 30 Mb.
</ParamField>

## Response

<ResponseField name="image_file" type="string">
  The Base64-encoded content of the returned image.
</ResponseField>

<ResponseField name="image_type" type="string">
  The returned image type.<br />
  Enum: `png`, `webp`, `jpeg`
</ResponseField>

## Example

This API automatically removes text from images.

**Try it in [playground](https://novita.ai/playground#remove-text).**

`Request:`

```bash theme={"system"}
curl --location --request POST 'https://api.novita.ai/v3/remove-text' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "image_file": "{{Base64 encoded image}}"
}'
```

HTTP status codes in the 2xx range indicate that the request has been successfully accepted. A code of 400 means there is an error with the request parameters, while status codes in the 5xx range indicate internal server errors.

You can obtain the image URL in the `image_file` field of the response in base64 format.

`Response:`

```js theme={"system"}
{
    "image_file": "{{Base64 encoded image}}",
    "image_type": "jpeg"
}
```

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>


# Replace Background
Source: https://novita.ai/docs/api-reference/model-apis-replace-background

POST https://api.novita.ai/v3/replace-background

**Replace the background of images according to your prompt.**

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Optional extra parameters for the request.

  <Expandable title="properties">
    <ParamField type="string">
      The returned image type. Default is png.Enum: `png, webp, jpeg`
    </ParamField>

    <ParamField type="object">
      Dedicated Endpoints settings, which only take effect for users who have already subscribed to the [Dedicated Endpoints Documentation](/guides/model-apis-dedicated-endpoints).

      <Expandable title="properties">
        <ParamField type="boolean">
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  The base64 of original image, with a maximum resolution of 2048 x 2048 and a maximum file size of 30 Mb (width \<= 4096, height \<= 4096).
</ParamField>

## Response

<ResponseField name="image_file" type="string">
  The Base64-encoded content of the returned image.
</ResponseField>

<ResponseField name="image_type" type="string">
  The returned image type.<br />
  Enum: `png`, `webp`, `jpeg`
</ResponseField>

## Example

This API allows you to replace the background of images according to your prompt.

**Try it in [playground](https://novita.ai/playground#replace-background).**

`Request:`

```bash theme={"system"}
curl --location --request POST 'https://api.novita.ai/v3/replace-background' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"prompt":"in a warehouse",
"image_file":"{{Base64 encoded image}}"
}'
```

HTTP status codes in the 2xx range indicate that the request has been successfully accepted. A status code of 400 means there is an error with the request parameters, while status codes in the 5xx range indicate internal server errors.

You can obtain the image URL in the `image_file` field of the response in base64 format.

`Response:`

```js theme={"system"}
{
    "image_file": "{{Base64 encoded image}}",
    "image_type": "png"
}
```

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>


# Seedance V1 Lite Image to Video
Source: https://novita.ai/docs/api-reference/model-apis-seedance-v1-lite-i2v

POST https://api.novita.ai/v3/async/seedance-v1-lite-i2v

Seedance V1 Lite is an AI video model designed for coherent multi-shot video generation, offering smooth motion and precise adherence to detailed prompts. It supports resolutions of 480p, 720p, and 1080p.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Text prompt for video generation; Positive text prompt; Cannot exceed 2000 characters.
</ParamField>

<ParamField type="string">
  Input image supports both URL and Base64 format.

  * Supported image formats include `jpeg`, `png`, `webp`, `bmp`, `tiff`, `gif`.
  * The image file size cannot exceed 30MB.
  * Its shorter side must be greater than 300 pixels, and its longer side must be less than 6,000 pixels.
  * Its aspect ratio must be in the range of 0.4 to 2.5.
</ParamField>

<ParamField type="string">
  Video quality. Accepted values: `480p`, `720p`, `1080p`
</ParamField>

<ParamField type="string">
  The aspect ratio of the generated video.
  Accepted values: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `9:21`
</ParamField>

<ParamField type="string">
  End image, supports both URL and Base64 format.

  * Supported image formats include `jpeg`, `png`, `webp`, `bmp`, `tiff`, `gif`.
  * The image file size cannot exceed 30MB.
  * Its shorter side must be greater than 300 pixels, and its longer side must be less than 6,000 pixels.
  * Its aspect ratio must be in the range of 0.4 to 2.5.

  The first and last frame images provided can be the same. If the aspect ratios of the first and last frame images differ, the first frame image will be used as the reference, and the last frame image will be automatically cropped to match.
</ParamField>

<ParamField type="boolean">
  Determines if the camera position should remain fixed.
</ParamField>

<ParamField type="integer">
  The random seed to use for the generation. -1 means a random seed will be used.
</ParamField>

<ParamField type="integer">
  Specifies the length of the generated video in seconds. Available options: `5`, `10`
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Seedance V1 Lite Text to Video
Source: https://novita.ai/docs/api-reference/model-apis-seedance-v1-lite-t2v

POST https://api.novita.ai/v3/async/seedance-v1-lite-t2v

Seedance V1 Lite is an AI video model designed for coherent multi-shot video generation, offering smooth motion and precise adherence to detailed prompts. It supports resolutions of 480p, 720p, and 1080p.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Text prompt for video generation; Positive text prompt; Cannot exceed 2000 characters.
</ParamField>

<ParamField type="string">
  Video quality. Accepted values: `480p`, `720p`, `1080p`
</ParamField>

<ParamField type="string">
  The aspect ratio of the generated video.
  Accepted values: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `9:21`
</ParamField>

<ParamField type="integer">
  Specifies the length of the generated video in seconds. Available options: `5`, `10`
</ParamField>

<ParamField type="boolean">
  Determines if the camera position should remain fixed.
</ParamField>

<ParamField type="integer">
  The random seed to use for the generation. -1 means a random seed will be used.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Seedance V1 Pro Image to Video
Source: https://novita.ai/docs/api-reference/model-apis-seedance-v1-pro-i2v

POST https://api.novita.ai/v3/async/seedance-v1-pro-i2v

Seedance V1 Pro is an AI video model designed for coherent multi-shot video generation, offering smooth motion and precise adherence to detailed prompts. It supports resolutions of 480p, 720p, and 1080p.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Text prompt for video generation; Positive text prompt; Cannot exceed 2000 characters.
</ParamField>

<ParamField type="string">
  Input image supports both URL and Base64 format.

  * Supported image formats include `jpeg`, `png`, `webp`, `bmp`, `tiff`, `gif`.
  * The image file size cannot exceed 30MB.
  * Its shorter side must be greater than 300 pixels, and its longer side must be less than 6,000 pixels.
  * Its aspect ratio must be in the range of 0.4 to 2.5.
</ParamField>

<ParamField type="string">
  End image, supports both URL and Base64 format.

  * Supported image formats include `jpeg`, `png`, `webp`, `bmp`, `tiff`, `gif`.
  * The image file size cannot exceed 30MB.
  * Its shorter side must be greater than 300 pixels, and its longer side must be less than 6,000 pixels.
  * Its aspect ratio must be in the range of 0.4 to 2.5.

  The first and last frame images provided can be the same. If the aspect ratios of the first and last frame images differ, the first frame image will be used as the reference, and the last frame image will be automatically cropped to match.
</ParamField>

<ParamField type="string">
  Video quality. Accepted values: `480p`, `720p`, `1080p`
</ParamField>

<ParamField type="string">
  The aspect ratio of the generated video.
  Accepted values: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `9:21`
</ParamField>

<ParamField type="boolean">
  Determines if the camera position should remain fixed.
</ParamField>

<ParamField type="integer">
  The random seed to use for the generation. -1 means a random seed will be used.
</ParamField>

<ParamField type="integer">
  Specifies the length of the generated video in seconds. Available options: `5`, `10`
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Seedance V1 Pro Text to Video
Source: https://novita.ai/docs/api-reference/model-apis-seedance-v1-pro-t2v

POST https://api.novita.ai/v3/async/seedance-v1-pro-t2v

Seedance V1 Pro is an AI video model designed for coherent multi-shot video generation, offering smooth motion and precise adherence to detailed prompts. It supports resolutions of 480p, 720p, and 1080p.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Text prompt for video generation; Positive text prompt; Cannot exceed 2000 characters.
</ParamField>

<ParamField type="string">
  Video quality. Accepted values: `480p`, `720p`, `1080p`
</ParamField>

<ParamField type="string">
  The aspect ratio of the generated video.
  Accepted values: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `9:21`
</ParamField>

<ParamField type="integer">
  Specifies the length of the generated video in seconds. Available options: `5`, `10`
</ParamField>

<ParamField type="boolean">
  Determines if the camera position should remain fixed.
</ParamField>

<ParamField type="integer">
  The random seed to use for the generation. -1 means a random seed will be used.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Seedream 3.0 Text to Image
Source: https://novita.ai/docs/api-reference/model-apis-seedream-3-0-t2i

POST https://api.novita.ai/v3/seedream-3-0-txt2img

Experience fast and efficient image generation with Seedream 3.0, a state-of-the-art text-to-image model that produces high-quality images from textual prompts.

<Tip>
  Currently, only the model version `seedream-3-0-t2i-250415` is supported for Seedream 3.0.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The text prompt used to generate the image.
</ParamField>

<ParamField type="string">
  The Model ID or inference endpoint (Endpoint ID) to be used for this request. Currently, only `seedream-3-0-t2i-250415` for seedream 3.0 is supported.
</ParamField>

<ParamField type="string">
  Specifies the format of the generated image returned in the response. Default is `url`.<br />
  Supported values:<br />

  * `"url"`: Returns a downloadable JPEG image link.
  * `"b64_json"`: Returns the image data as a Base64-encoded JSON string.
</ParamField>

<ParamField type="string">
  Specifies the dimensions (width x height in pixels) of the generated image. Must be between \[512x512, 2048x2048]. Default is `1024x1024`.<br />
  Recommended aspect ratios and resolutions:<br />

  * `1024x1024` (1:1)
  * `864x1152` (3:4)
  * `1152x864` (4:3)
  * `1280x720` (16:9)
  * `720x1280` (9:16)
  * `832x1248` (2:3)
  * `1248x832` (3:2)
  * `1512x648` (21:9)
</ParamField>

<ParamField type="integer">
  Random seed to control the stochasticity of image generation. Range: \[-1, 2147483647]. If not specified, a seed will be automatically generated. To reproduce the same output, use the same seed value. Default is `-1`.
</ParamField>

<ParamField type="number">
  Controls how closely the output image aligns with the input prompt. The higher the value, the less freedom the model has, and the stronger the prompt correlation. Range: \[1, 10]. Default is `2.5`.
</ParamField>

<ParamField type="boolean">
  Specifies whether to add a watermark to the generated image. Default is `true`.<br />

  * `false`: No watermark.
  * `true`: Adds a watermark with the label "AI generated" in the bottom-right corner.
</ParamField>

## Response

<ResponseField name="image_urls" type="string[]">
  Array of generated image URLs. When `response_format` is set to `"url"`, this array contains the downloadable image links for the generated images.
</ResponseField>

<ResponseField name="binary_data_base64" type="string[]">
  Array of Base64-encoded image data. When `response_format` is set to `"b64_json"`, this array contains the generated images as Base64-encoded JSON strings.
</ResponseField>


# Seedream 4.0
Source: https://novita.ai/docs/api-reference/model-apis-seedream-4-0

POST https://api.novita.ai/v3/seedream-4.0

Seedream 4.0 is a cutting-edge image generation model that provides flexible image creation features, including 4K resolution support. The Seedream 4.0 API enables image generation from both text and other images.

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The prompt for image generation.

  The recommended length is no more than 600 English words. If the prompt is too long, the information may become scattered. The model might ignore details and only concentrate on the main points, resulting in a image with missing elements.
</ParamField>

<ParamField type="string[]">
  Enter the Base64 encoding or an accessible URL of the image to edit. Supports inputting a single image or multiple images.

  * Image URL: Make sure that the image URL is accessible.
  * Base64 encoding: The format must be `data:image/<image format>;base64,<Base64 encoding>`. <br />

    An input image must meet the following requirements:

    * Image format: jpeg, png
    * Aspect ratio (width/height): In the range \[1/3, 3]
    * Width and height (px): > 14
    * Size: No more than 10 MB
    * The value of total pixels: No more than 6000×6000
    * supports uploading a maximum of 10 reference images.
</ParamField>

<ParamField type="string">
  Set the specification for the generated image. Two methods are available but cannot be used together.

  * Method 1, specify the resolution.
    * Optional values: `1K`, `2K`, `4K`
  * Method 2, specify the width and height of the generated image in pixels.
    * Default: `2048x2048`
    * The value range of total pixels: `[1024x1024, 4096x4096]`
    * The aspect ratio value range: `[1/16, 16]`

  Recommended width and height:

  | Aspect ratio | Width and Height Pixel Values |
  | ------------ | ----------------------------- |
  | 1:1          | 2048x2048                     |
  | 4:3          | 2304x1728                     |
  | 3:4          | 1728x2304                     |
  | 16:9         | 2560x1440                     |
  | 9:16         | 1440x2560                     |
  | 3:2          | 2496x1664                     |
  | 2:3          | 1664x2496                     |
  | 21:9         | 3024x1296                     |
</ParamField>

<ParamField type="string">
  Controls whether to disable the batch generation feature.

  * `auto`: In automatic mode, the model automatically determines whether to return multiple images and how many images it will contain based on the user's prompt.
  * `disabled`: Disables batch generation feature. The model will only generate one image.
</ParamField>

<ParamField type="integer">
  Specifies the maximum number of images to generate in this request. This parameter is only effective when `sequential_image_generation` is set to `auto`.

  Value range: `[1, 15]`

  <Tip>
    Description

    The actual number of generated images is affected by `max_images` and the number of input reference images. Number of input reference images + Number of generated images ≤ 15.
  </Tip>
</ParamField>

<ParamField type="boolean">
  Adds a watermark to the generated image.

  * `false`: Does not add a watermark.
  * `true`: Adds a watermark with the text "AI generated" in the bottom-right corner of the image.
</ParamField>

## Response

<ResponseField name="images" type="string[]">
  An array containing links to download the generated images.
</ResponseField>


# Seedream 4.5
Source: https://novita.ai/docs/api-reference/model-apis-seedream-4.5

POST https://api.novita.ai/v3/seedream-4.5

API for the Seedream 4.5 image generation model, supporting text-to-image, single image-to-image, multi-image-to-image, and sequential image generation features.

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Specifies the size of the generated image. Method 1: Specify resolution (2K, 4K); Method 2: Specify width and height in pixels (e.g., 2048x2048). Total pixel range: \[3686400, 16777216], aspect ratio range: \[1/16, 16].
</ParamField>

<ParamField type="array">
  Array of input image information, supporting URL or Base64 encoding. Up to 14 reference images can be provided. Supported image formats: jpeg, png, webp, bmp, tiff, gif.

  Array length: 1 - 14
</ParamField>

<ParamField type="string">
  The prompt used to generate images, supporting both Chinese and English. Recommended not to exceed 300 Chinese characters or 600 English words.
</ParamField>

<ParamField type="boolean">
  Whether to add a watermark to the generated images.
</ParamField>

<ParamField type="object">
  Configuration for the prompt optimization feature.

  <Expandable title="properties">
    <ParamField type="string">
      Sets the mode for the prompt optimization feature. standard: Standard mode, higher quality but longer processing time; fast: Fast mode, shorter processing time but average quality. Currently only standard mode is supported.

      Optional values: `standard`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Controls whether to disable the sequential image generation feature. auto: Automatic mode, the model determines whether to return sequential images based on the prompt; disabled: Disables sequential image generation, only generates one image.

  Optional values: `auto`, `disabled`
</ParamField>

<ParamField type="object">
  Configuration for the sequential image generation feature. Only effective when sequential\_image\_generation is set to auto.

  <Expandable title="properties">
    <ParamField type="integer">
      Specifies the maximum number of images that can be generated in this request. Number of input reference images + number of generated images ≤ 15.

      Value range: \[1, 15]
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="images" type="string[]">
  Array of generated image information.
</ResponseField>


# Task Result
Source: https://novita.ai/docs/api-reference/model-apis-task-result

GET https://api.novita.ai/v3/async/task-result

**This API is used to retrieve images, audio, or video results from v3 asynchronous tasks using the `task_id`.**

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<ParamField type="string">
  Returned in the 200 response of v3 asynchronous APIs.
</ParamField>

## Response

<ResponseField name="extra" type="object">
  <Expandable title="properties">
    <ResponseField name="seed" type="string">
      A seed is a number from which Stable Diffusion generates noise, making generation deterministic. Using the same seed and set of parameters will produce identical images each time, minimum -1.
    </ResponseField>

    <ResponseField name="enable_nsfw_detection" type="boolean">
      When set to true, NSFW detection will be enabled, incurring an additional cost of \$0.0015 for each generated image.
    </ResponseField>

    <ResponseField name="debug_info" type="object">
      <Expandable title="properties">
        <ResponseField name="request_info" type="string">
          Records request parameters for debugging purposes.
        </ResponseField>

        <ResponseField name="submit_time_ms" type="string">
          The timestamp (in milliseconds) of when the task was submitted.
        </ResponseField>

        <ResponseField name="execute_time_ms" type="string">
          The timestamp (in milliseconds) of when the task started execution.
        </ResponseField>

        <ResponseField name="complete_time_ms" type="string">
          The timestamp (in milliseconds) of when the task was completed.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="task" type="object">
  Task information.

  <Expandable title="properties">
    <ResponseField name="task_id" type="string">
      Task ID.
    </ResponseField>

    <ResponseField name="status" type="string">
      Indicates the current status of a task. This parameter allows you to filter results based on the following status categories: `TASK_STATUS_QUEUED`: The task is queued and awaiting processing. `TASK_STATUS_SUCCEED`: The task has been processed successfully. `TASK_STATUS_FAILED`: The task failed during processing. `TASK_STATUS_PROCESSING`: The task is currently being processed.<br />
      Enum: `TASK_STATUS_QUEUED`, `TASK_STATUS_SUCCEED`, `TASK_STATUS_FAILED`, `TASK_STATUS_PROCESSING`
    </ResponseField>

    <ResponseField name="reason" type="string">
      Provides the reason for a task's failure. This parameter specifies the explanation or error message associated with tasks that did not succeed. Utilizing this filter can aid in diagnosing issues and implementing corrective actions for failed processes.
    </ResponseField>

    <ResponseField name="task_type" type="string">
      Specifies the type of task.
    </ResponseField>

    <ResponseField name="eta" type="number">
      Specifies the estimated time of completion for tasks, measured in seconds. This parameter is particularly relevant for video-type tasks, providing a forecast of how long it will take to complete the task based on current processing parameters and system load. This information can be vital for planning and resource management in environments with time-sensitive video processing requirements.
    </ResponseField>

    <ResponseField name="progress_percent" type="number">
      Progress of task completion in percentage. This feature is currently available only for: <br /> 1. Video Generator APIs; <br /> 2. Text-to-Image API and Image-to-Image API.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="images" type="object[]">
  Contains information about images associated with image-type tasks. This parameter provides detailed data on each image processed or generated during the task, such as file paths, metadata, or any image-specific attributes. It is returned only for tasks that involve image operations, facilitating enhanced tracking and management of image data.

  <Expandable title="properties">
    <ResponseField name="image_url" type="string">
      Image URL.
    </ResponseField>

    <ResponseField name="image_url_ttl" type="integer">
      Image expiration time in seconds.
    </ResponseField>

    <ResponseField name="image_type" type="string">
      Image type.<br />
      Enum: `jpeg`, `png`, `webp`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="videos" type="object[]">
  Contains information about videos associated with video-type tasks. This parameter provides detailed data on each video processed or generated during the task, such as file paths, metadata, or any video-specific attributes. It is returned only for tasks that involve video operations, facilitating enhanced tracking and management of video data.

  <Expandable title="properties">
    <ResponseField name="video_url" type="string">
      Video URL.
    </ResponseField>

    <ResponseField name="video_url_ttl" type="string">
      Video expiration time in seconds.
    </ResponseField>

    <ResponseField name="video_type" type="string">
      Video type.<br />
      Enum: `mp4`, `gif`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="audios" type="object[]">
  Contains information about audios associated with audio type tasks. This parameter provides detailed data on each audio processed or generated during the task, such as file paths, metadata, or any image-specific attributes. It is returned only for tasks that involve audio operations, facilitating enhanced tracking and management of audio data.

  <Expandable title="properties">
    <ResponseField name="audio_url" type="string">
      Audio url.
    </ResponseField>

    <ResponseField name="audio_url_ttl" type="string">
      Audio url expire time in seconds.
    </ResponseField>

    <ResponseField name="audio_type" type="string">
      Audio type.<br />
      Enum: `wav`
    </ResponseField>

    <ResponseField name="audio_metadata" type="object">
      Contains detailed metadata about audio files processed or generated during audio-related tasks.

      <Expandable title="properties">
        <ResponseField name="text" type="string" />

        <ResponseField name="start_time" type="float32">
          the start\_time of the text in seconds.
        </ResponseField>

        <ResponseField name="end_time" type="float32">
          the end\_time of the text in seconds.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

request

```bash theme={"system"}
curl --location --globoff 'https://api.novita.ai/v3/async/task-result?task_id={{Novita-TaskID}}' \
--header 'Authorization: Bearer {{API Key}}'
```

response

```json theme={"system"}
{
  "extra": {
    "seed": "158881667",
    "enable_nsfw_detection": false,
    "debug_info": {
      "request_info": "",
      "submit_time_ms": "",
      "execute_time_ms": "",
      "complete_time_ms": ""
    }
  },
  "task": {
    "task_id": "830d9c90-d53f-4c5a-8009-xxx",
    "status": "TASK_STATUS_SUCCEED",
    "reason": "",
    "task_type": "TXT_TO_IMG",
    "eta": 0,
    "progress_percent": 0
  },
  "images": [
    {
      "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/xxx",
      "image_url_ttl": 3600,
      "image_type": "jpeg",
      "nsfw_detection_result": {}
    }
  ],
  "videos": [],
  "audios": []
}
```


# Text to Image
Source: https://novita.ai/docs/api-reference/model-apis-text-to-image

POST https://api.novita.ai/v3/async/txt2img

**Generate images from text prompts using Stable Diffusion models.**

> This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the image generation results.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Optional extra parameters for the request.

  <Expandable title="properties">
    <ParamField type="string">
      The returned image type. Default is png.Enum: `png, webp, jpeg`
    </ParamField>

    <ParamField type="object">
      Webhook settings. More details can be found at [Webhook Documentation](/api-reference/model-apis-webhook).

      <Expandable title="properties">
        <ParamField type="string">
          The URL of the webhook endpoint. Novita AI will send the task generated outputs to your specified webhook endpoint.
        </ParamField>

        <ParamField type="object">
          By specifying Test Mode, a mock event will be sent to the webhook endpoint.

          <Expandable title="properties">
            <ParamField type="boolean">
              Set to true to enable Test Mode, or false to disable it. The default is false.
            </ParamField>

            <ParamField type="string">
              Control the data content of the mock event. When set to TASK\_STATUS\_SUCCEED, you'll receive a normal response; when set to TASK\_STATUS\_FAILED, you'll receive an error response.Enum: `TASK_STATUS_SUCCEED, TASK_STATUS_FAILED`
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      Customer storage settings for saving the generated outputs. <br /> By default, the generated outputs will be saved to Novita AI Storage temporarily and privately.

      <Expandable title="properties">
        <ParamField type="object">
          AWS S3 Bucket settings.

          <Expandable title="properties">
            <ParamField type="string">
              AWS S3 regions, <a href="https://docs.aws.amazon.com/general/latest/gr/rande.html">more details</a>.
            </ParamField>

            <ParamField type="string">
              AWS S3 bucket name.
            </ParamField>

            <ParamField type="string">
              AWS S3 bucket path for saving generated outputs.
            </ParamField>

            <ParamField type="boolean">
              Set this option to True to save the generated outputs directly to the specified path without creating any additional directory hierarchy. <br /> If set to False, Novita AI will create an additional directory in the path to save the generated outputs. The default is False.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      Dedicated Endpoints settings, which only take effect for users who have already subscribed to the [Dedicated Endpoints Documentation](/guides/model-apis-dedicated-endpoints).

      <Expandable title="properties">
        <ParamField type="boolean">
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="boolean">
      When set to true, NSFW detection will be enabled, incurring an additional cost of \$0.0015 for each generated image.
    </ParamField>

    <ParamField type="integer">
      0: Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols.<br /> 1: Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols; Non-Explicit Nudity, Obstructed Intimate Parts, Kissing on the Lips.<br /> 2: Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols; Non-Explicit Nudity, Obstructed Intimate Parts, Kissing on the Lips; Female Swimwear or Underwear, Male Swimwear or Underwear.Enum: `0, 1, 2`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      This parameter specifies the name of the model checkpoint. Retrieve the corresponding sd\_name value by invoking the <a href="/api-reference/model-apis-get-model">Query Model</a> API with filter.types=checkpoint as the query parameter.
    </ParamField>

    <ParamField type="string">
      Text input required to guide the image generation, divided by `,` . Range \[1, 1024].
    </ParamField>

    <ParamField type="integer">
      Width of image. Range \[128, 2048].
    </ParamField>

    <ParamField type="integer">
      Height of image. Range \[128, 2048].
    </ParamField>

    <ParamField type="integer">
      Images numbers generated in one single generation. Range \[1, 8].
    </ParamField>

    <ParamField type="integer">
      The number of denoising steps. More steps usually can produce higher quality images, but take more time to generate, Range \[1, 100].
    </ParamField>

    <ParamField type="number">
      This setting says how close the Stable Diffusion will listen to your prompt, higer guidance forces the model to better follow the prompt, but result in lower quality output. Range \[1, 30].
    </ParamField>

    <ParamField type="string">
      This parameter determines the denoising algorithm employed during the sampling phase of Stable Diffusion. Each option represents a distinct method by which the model incrementally generates new images. These algorithms differ significantly in their processing speed, output quality, and the specific characteristics of the images they generate, allowing users to tailor the image generation process to meet precise requirements. Get reference at [A brief introduction to Sampler](/guides/model-apis-sampler).Enum: `Euler a,Euler,LMS,Heun,DPM2,DPM2 a,DPM++ 2S a,DPM++ 2M,DPM++ SDE,DPM fast,DPM adaptive,LMS Karras,DPM2 Karras,DPM2 a Karras,DPM++ 2S a Karras,DPM++ 2M Karras,DPM++ SDE Karras,DDIM,PLMS,UniPC`
    </ParamField>

    <ParamField type="string">
      Text input that specifies what to exclude from the generated images, divided by `,` . Range \[1, 1024].
    </ParamField>

    <ParamField type="string">
      VAE (Variational Auto Encoder). sd\_vae can be accessed in the API /v3/models with query params type=vae, like sd\_name: customVAE.safetensors. Get reference at [A brief introduction to VAE](/guides/model-apis-vae).
    </ParamField>

    <ParamField type="integer">
      A seed is a number from which Stable Diffusion generates noise, which, makes generation deterministic. Using the same seed and set of parameters will produce identical image each time, minimum -1. Defaults to -1.
    </ParamField>

    <ParamField type="object[]">
      LoRA is a fast and lightweight training method that inserts and trains a significantly smaller number of parameters instead of all the model parameters. Currently supports up to 5 LoRAs.

      <Expandable title="properties">
        <ParamField type="string">
          Name of lora, retrieve the corresponding sd\_name\_in\_api value by invoking the <a href="/api-reference/model-apis-get-model">Get Model API</a> endpoint with filter.types=lora as the query parameter.
        </ParamField>

        <ParamField type="number">
          The strength value of lora. The larger the value, the more biased the effect is towards lora, Range \[0, 1]
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object[]">
      Textual Inversion is a training method for personalizing models by learning new text embeddings from a few example images, currently supports up to 5 embeddings.

      <Expandable title="properties">
        <ParamField type="string">
          Name of textual Inversion model, you can call the <a href="/api-reference/model-apis-get-model">Get Model API</a> endpoint with parameter filter.types=textualinversion to retrieve the sd\_name\_in\_api field as the model\_name.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      Upscale images while they are generating.

      <Expandable title="properties">
        <ParamField type="integer">
          Target width, Range \[128, 4096].
        </ParamField>

        <ParamField type="integer">
          Target height, Range \[128, 4096].
        </ParamField>

        <ParamField type="number">
          Defines the intensity of the `upscaler` model's effect. A value of 0 means the upscaler has no effect, while 1 results in maximum intensity, fully utilizing the upscaler's capabilities, range \[0, 1].
        </ParamField>

        <ParamField type="string">
          The `upscaler` model's name.Enum: `RealESRGAN_x4plus_anime_6B,RealESRNet_x4plus,Latent`
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      SD refiner.

      <Expandable title="properties">
        <ParamField type="number">
          The switch\_at parameter in the context of a refiner allows you to set the extent to which the refiner alters the output of a model. When set to 0, the refiner has no effect; at 1, it's fully active. Intermediate values like 0.5 provide a balanced effect, where the refiner is moderately engaged, enhancing or adjusting the output without dominating the original model's characteristics. This setting is particularly useful for fine-tuning the output to achieve a desired balance between refinement and the original generative features, Range \[0, 1].
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="bool">
      Make the resulting image's background transparent. Please note that if the transparent\_background is enabled, the extra response\_image\_type must be PNG, and only SDXL models are allowed.
    </ParamField>

    <ParamField type="bool">
      Used to control whether the Face Restoration feature is enabled.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>

## Example

### 1. Txt2img request with normal parameters

Please set the **`Content-Type`** header to **`application/json`** in your HTTP request to indicate that you are sending JSON data. Currently, **only JSON format is supported**.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/txt2img' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "extra": {
        "response_image_type": "jpeg"
    },
    "request": {
        "prompt": "a cute dog",
        "model_name": "sd_xl_base_1.0.safetensors",
        "negative_prompt": "nsfw, bottle, bad face",
        "width": 1024,
        "height": 1024,
        "image_num": 2,
        "steps": 20,
        "seed": -1,
        "clip_skip": 1,
        "sampler_name": "Euler a",
        "guidance_scale": 7.5
    }
}'
```

`Response:`

```bash theme={"system"}
{
    "task_id": "f10333f2-2dd7-4f56-a177-e3c02a774d9a"
}
```

**Use `task_id` to get images**

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get images url in `imgs` of response.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id=f10333f2-2dd7-4f56-a177-e3c02a774d9a' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
	"extra": {
		"seed": "392212448",
		"enable_nsfw_detection": false,
		"debug_info": {
			"request_info": "{\"model\":\"sd_xl_base_1.0.safetensors\",\"prompts\":[\"a cute dog\"],\"negative_prompts\":[\"nsfw, bottle,bad face\"],\"seeds\":[392212448],\"height\":384,\"width\":512,\"guidance_scale\":7.5,\"num_images_per_prompt\":2,\"num_inference_steps\":20,\"sampler_name\":\"Euler a\",\"clip_skip\":1}",
			"submit_time_ms": "1715052533293",
			"execute_time_ms": "1715052533362",
			"complete_time_ms": "1715052537148"
		}
	},
	"task": {
		"task_id": "f10333f2-2dd7-4f56-a177-e3c02a774d9a",
		"task_type": "TXT_TO_IMG",
		"status": "TASK_STATUS_SUCCEED",
		"reason": "",
		"eta": 0,
		"progress_percent": 0
	},
	"images": [{
		"image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/f10333f2-2dd7-4f56-a177-e3c02a774d9a/80443e6739584fcb82bc2cf4f3b557fb.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240507%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240507T032908Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=b375b64e0886d0253d5463af241a30bd4a1e4718287f37f73b0e80d5dce4d214",
		"image_url_ttl": "3600",
		"image_type": "jpeg",
		"nsfw_detection_result": null
	}, {
		"image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/f10333f2-2dd7-4f56-a177-e3c02a774d9a/9b16e333242244e58a4d03c4bfb1bca5.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240507%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240507T032908Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=fff0623985c741661497532eb682a7ae23094bcf2e55c4eee61e256e97c81e3c",
		"image_url_ttl": "3600",
		"image_type": "jpeg",
		"nsfw_detection_result": null
	}],
	"videos": [],
	"audios": []
}
```

### 2.Txt2img request with lora

Please set the **`Content-Type`** header to **`application/json`** in your HTTP request to indicate that you are sending JSON data. Currently, **only JSON format is supported**.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/txt2img' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "extra": {
        "response_image_type": "jpeg"
    },
    "request": {
        "prompt": "a cute dog",
        "model_name": "majicmixRealistic_v6_65516.safetensors",
        "negative_prompt": "nsfw, bottle,bad face",
        "width": 512,
        "height": 512,
        "image_num": 2,
        "steps": 20,
        "seed": 123,
        "clip_skip": 1,
        "sampler_name": "Euler a",
        "guidance_scale": 7.5,
        "loras": [
          {
            "model_name": "add_detail_44319",
            "strength": 0.7
          },
          {
            "model_name": "more_details_59655",
            "strength": 0.7
          }
        ]
    }
}'
```

`Response:`

```js theme={"system"}
{
    "task_id": "6469ca5b-5929-4200-b263-241020763eb8"
}
```

**Use `task_id` to get images**

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get images url in `imgs` of response.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id=6469ca5b-5929-4200-b263-241020763eb8' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "extra": {
        "seed": "123"
    },
    "task": {
        "task_id": "6469ca5b-5929-4200-b263-241020763eb8",
        "task_type": "TXT_TO_IMG",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 0
    },
    "images": [
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/6469ca5b-5929-4200-b263-241020763eb8/xxx.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240111%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240111T134101Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=bbe71142c83df530e1dfb6be1a26faa1d9907b24f0fc77b2aee399683c51b134",
            "image_url_ttl": "3600",
            "image_type": "jpeg"
        },
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/6469ca5b-5929-4200-b263-241020763eb8/xxx.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240111%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240111T134101Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=8fc609a70c35d7b12f7690443dae6e59d2550b76461e73b2fd8296ec4333e208",
            "image_url_ttl": "3600",
            "image_type": "jpeg"
        }
    ],
    "videos": []
}
```

### 3.Txt2img request with upscale

Please set the **`Content-Type`** header to **`application/json`** in your HTTP request to indicate that you are sending JSON data. Currently, **only JSON format is supported**.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/txt2img' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "extra": {
        "response_image_type": "jpeg"
    },
    "request": {
        "prompt": "a cute dog",
        "model_name": "realisticVisionV51_v51VAE_94301.safetensors",
        "negative_prompt": "nsfw, bottle,bad face",
        "width": 512,
        "height": 512,
        "image_num": 2,
        "steps": 20,
        "seed": 123,
        "clip_skip": 1,
        "sampler_name": "Euler a",
        "guidance_scale": 7.5,
        "hires_fix": {
            "target_width": 1024,
            "target_height": 1024,
            "strength": 0.8,
            "upscaler": "Latent"
        }
    }
}'
```

`Response:`

```js theme={"system"}
{
    "task_id": "6469ca5b-5929-4200-b263-241020763eb8"
}
```

**Use `task_id` to get images**

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get images url in `imgs` of response.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id=6469ca5b-5929-4200-b263-241020763eb8' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "extra": {
        "seed": "123",
        "enable_nsfw_detection": false
    },
    "task": {
        "task_id": "6469ca5b-5929-4200-b263-241020763eb8",
        "task_type": "TXT_TO_IMG",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 0
    },
    "images": [
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/6469ca5b-5929-4200-b263-241020763eb8/23a98c94383e466289b4ae39a2d1fe73.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240307%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240307T034029Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=3f45b6214e176fc90f3c78e04bc01e5883f25a0a8122409eb00ae8ea971d1be6",
            "image_url_ttl": "3600",
            "image_type": "jpeg",
            "nsfw_detection_result": null
        },
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/6469ca5b-5929-4200-b263-241020763eb8/19146c52474445e4ae2554ad807f7f6b.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240307%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240307T034029Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=a69c62262cdec60dd74f2efc2fd965cb98473112ce291542930d5b7d9b37755a",
            "image_url_ttl": "3600",
            "image_type": "jpeg",
            "nsfw_detection_result": null
        }
    ],
    "videos": []
}
```

### 4.Txt2img request with SDXL 1.0

Please set the **`Content-Type`** header to **`application/json`** in your HTTP request to indicate that you are sending JSON data. Currently, **only JSON format is supported**.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/txt2img' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "extra": {
        "response_image_type": "jpeg"
    },
    "request": {
        "prompt": "a cute dog",
        "model_name": "sd_xl_base_1.0.safetensors",
        "negative_prompt": "nsfw, bottle,bad face",
        "width": 1024,
        "height": 1024,
        "image_num": 1,
        "steps": 20,
        "seed": -1,
        "clip_skip": 1,
        "sampler_name": "Euler a",
        "guidance_scale": 7.5
    }
}'
```

`Response:`

```js theme={"system"}
{
    "task_id": "6469ca5b-5929-4200-b263-241020763eb8"
}
```

**Use `task_id` to get images**

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get images url in `imgs` of response.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id=6469ca5b-5929-4200-b263-241020763eb8' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "extra": {
        "seed": "3706472920",
        "enable_nsfw_detection": false
    },
    "task": {
        "task_id": "346b3562-ae4e-4849-a9fb-9318cb1a689d",
        "task_type": "TXT_TO_IMG",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 0
    },
    "images": [
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/346b3562-ae4e-4849-a9fb-9318cb1a689d/5698013f545d425cbcdeae00cef8c435.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240307%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240307T033747Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=68f00e2800de145d5c2c9d05f957a684283fa8dce41049337b8ce59267c49cf2",
            "image_url_ttl": "3600",
            "image_type": "jpeg",
            "nsfw_detection_result": null
        }
    ],
    "videos": []
}
```

### 5.Txt2img request with Textual Inversion(embedding)

Please set the **`Content-Type`** header to **`application/json`** in your HTTP request to indicate that you are sending JSON data. Currently, **only JSON format is supported**.

`Request for textual inversion names:`

```
curl --location --request GET 'https://api.novita.ai/v3/model?filter.visibility=public&pagination.limit=\
100&pagination.cursor=c_0&filter.types=textualinversion&filter.source=civitai' \
--header 'Authorization: Bearer {{API Key}}' | jq '.models[].sd_name'
```

`Response:`

```bash theme={"system"}
"epiCPhotoGasm-colorfulPhoto-neg_108119.pt"
"epiCNegative_66017.pt"
"verybadimagenegative_v1.3_21434.pt"
"FastNegativeV2_65067.pt"
"AS-YoungV2.pt"
"AS-YoungV2-neg.pt"
"AS-YoungestV2.pt"
"AS-YoungerV2.pt"
"AS-MidAged.pt"
"AS-Elderly.pt"
"AS-Adult.pt"
"AS-Adult-neg.pt"
"Adult.pt"
"MidAged.pt"
"unaestheticXLv13_98060.safetensors"
"unaestheticXL_Sky3.1_134255.safetensors"
"EasyNegativeV2_75525.safetensors"
"BadDream_53202.pt"
"UnrealisticDream_53204.pt"
"negative_hand-neg_43127.pt"
"bad_prompt_version2-neg_42594.pt"
"Asian-Less-Toon_39763.pt"
"badhandv4_16755.pt"
"easynegative_8955.safetensors"
"aestheticc-65800_8615.pt"
"corneo_side_deepthroat_6490.pt"
"corneo_tentacle_sex.pt"
"By bad artist -neg_6310.pt"
"dpthrt_5441.pt"
"ng_deepnegative_v1_75t_5845.pt"
"pureerosface_v1_5162.pt"
```

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/txt2img' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "extra": {
        "response_image_type": "jpeg"
    },
    "request": {
        "prompt": "1girl",
        "model_name": "realisticVisionV51_v51VAE_94301.safetensors",
        "negative_prompt": "nsfw, bottle,bad face",
        "width": 512,
        "height": 512,
        "image_num": 1,
        "steps": 20,
        "seed": -1,
        "clip_skip": 1,
        "sampler_name": "Euler a",
        "guidance_scale": 7.5,
        "embeddings": [
            {
                "model_name": "badhandv4_16755.pt"
            },
            {
                "model_name": "BadDream_53202.pt"
            }
        ]
    }
}'
```

`Response:`

```js theme={"system"}
{
    "task_id": "6469ca5b-5929-4200-b263-241020763eb8"
}
```

**Use `task_id` to get images**

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get images url in `imgs` of response.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id=6469ca5b-5929-4200-b263-241020763eb8' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "extra": {
        "seed": "767172278",
        "enable_nsfw_detection": false
    },
    "task": {
        "task_id": "22388880-1c37-4ae1-8738-2fe7f5e8af57",
        "task_type": "TXT_TO_IMG",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 0
    },
    "images": [
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/6469ca5b-5929-4200-b263-241020763eb8/72768e59c4884965824347bfb400e3fd.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240307%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240307T035327Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=e0a44ec5fe21d9e64dc59b1b53017df737218b8c7db6f4e6d2cd46ca8e42b2ab",
            "image_url_ttl": "3600",
            "image_type": "jpeg",
            "nsfw_detection_result": null
        }
    ],
    "videos": []
}
```

### 6.Txt2img request with nsfw\_detection

When set `enable_nsfw_detection` true, NSFW detection will be enabled, incurring an additional cost of \$0.0015 for each generated image.

`nsfw_detection_level`, nsfw check level, ranging from 0 to 2, with higher levels indicating stricter NSFW detection criteria. The default value is 0. The following table lists the NSFW detection criteria for each level.

* 0: Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols.
* 1: Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols; Non-Explicit Nudity, Obstructed Intimate Parts, Kissing on the Lips.
* 2: Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols; Non-Explicit Nudity, Obstructed Intimate Parts, Kissing on the Lips; Female Swimwear or Underwear, Male Swimwear or Underwear.

Please set the **`Content-Type`** header to **`application/json`** in your HTTP request to indicate that you are sending JSON data. Currently, **only JSON format is supported**.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/txt2img' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "extra": {
        "response_image_type": "jpeg",
        "enable_nsfw_detection": true,
        "nsfw_detection_level": 2
    },
    "request": {
        "prompt": "1girl,sexy",
        "model_name": "dreamshaper_8_93211.safetensors",
        "negative_prompt": "nsfw, bottle,bad face",
        "width": 512,
        "height": 512,
        "image_num": 4,
        "steps": 20,
        "seed": -1,
        "clip_skip": 1,
        "sampler_name": "Euler a",
        "guidance_scale": 7.5
    }
}'
```

`Response:`

```js theme={"system"}
{
    "code": 0,
    "msg": "",
    "data": {
        "task_id": "0fe0f291-05c9-41a4-83bb-3365d4b54f8b"
    }
}
```

**Use `task_id` to get images**

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get images url in `imgs` of response. There are two results in reponse.

* `enable_nsfw_detection`, when return with `true` means NSFW detection is enabled.

* `nsfw_detection_result`, presenting an array of NSFW detection outcomes for each image. The order of elements in the nsfw\_detection\_result array corresponds one-to-one with the sequence of images in the `images` field in the response. The `valid` field denotes the success of the NSFW detection process, while the `confidence` field, ranging from 0 to 100, signifies the confidence level of the NSFW detection result. Higher confidence values, nearing 100, suggest a greater likelihood of the corresponding image containing NSFW content.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id=0fe0f291-05c9-41a4-83bb-3365d4b54f8b' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "extra": {
        "seed": "1998521869",
        "enable_nsfw_detection": true
    },
    "task": {
        "task_id": "0fe0f291-05c9-41a4-83bb-3365d4b54f8b",
        "task_type": "TXT_TO_IMG",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 0
    },
    "images": [
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/0fe0f291-05c9-41a4-83bb-3365d4b54f8b/50dc49337e5d4ea289050198206b6a11.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240308%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240308T091609Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=b8cdebb0ffa90fa869843cbab9d2e348678f621bad35c4bf1f3f90637c512f59",
            "image_url_ttl": "3600",
            "image_type": "jpeg",
            "nsfw_detection_result": {
                "valid": true,
                "confidence": 93.7176
            }
        },
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/0fe0f291-05c9-41a4-83bb-3365d4b54f8b/9692d408ce65497ba2c1f5da99a72f12.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240308%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240308T091609Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=f213cbabdf6d411d9e414377ae2d538cd8dff692befdbe3fa0183c737aeea0c6",
            "image_url_ttl": "3600",
            "image_type": "jpeg",
            "nsfw_detection_result": {
                "valid": true,
                "confidence": 94.4329
            }
        },
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/0fe0f291-05c9-41a4-83bb-3365d4b54f8b/68336b4bd7194b9b87b53aabcfcd92cf.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240308%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240308T091609Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=faa315d2a0a97706486ff00d02399dc12dcd5eb08e9a538c9997bdf389137269",
            "image_url_ttl": "3600",
            "image_type": "jpeg",
            "nsfw_detection_result": {
                "valid": true,
                "confidence": 94.4224
            }
        },
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/0fe0f291-05c9-41a4-83bb-3365d4b54f8b/a8bc5e8263aa4d9389215b749e56af45.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240308%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240308T091609Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=4197c88e751861bbd30e8b9f1fadb67a6808f26e91b57c0ae5ed0512e05bb8ab",
            "image_url_ttl": "3600",
            "image_type": "jpeg",
            "nsfw_detection_result": {
                "valid": true,
                "confidence": 94.6823
            }
        }
    ],
    "videos": []
}
```


# Text to Image V2
Source: https://novita.ai/docs/api-reference/model-apis-text-to-image-v2-deprecated

POST https://api.novita.ai/v2/txt2img

<Warning>
  **The Text-to-Image V2 API is deprecated and will be removed in the future. Please migrate to [Text-to-Image V3](/api-reference/model-apis-text-to-image).**
</Warning>

## POST Text to Image V2

The text-to-image endpoint will return only a `task_id`. You should use the `task_id` to call the /v2/progress API endpoint to retrieve the image generation results. We will gradually phase out the V2 endpoints. It is recommended to use the V3 endpoints to generate images.

## Request Headers

<ParamField type="string" />

## Request Body

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      When set to true, NSFW detection will be enabled, incurring an additional cost of \$0.0015 for each generated image.
    </ParamField>

    <ParamField type="integer">
      \*\*\* 0 - Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols.\*\*\* 1 - Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols; Non-Explicit Nudity, Obstructed Intimate Parts, Kissing on the Lips.\*\*\* 2 - Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols; Non-Explicit Nudity, Obstructed Intimate Parts, Kissing on the Lips; Female Swimwear or Underwear, Male Swimwear or Underwear.<br />
      Enum: `0`, `1`, `2`
    </ParamField>

    <ParamField type="boolean¦null">
      You will receive empty preview images if `enable_progress_info` is set to false.
    </ParamField>

    <ParamField type="string">
      The format of the returned images; default: png<br />
      Enum: `png`, `jpeg`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Positive prompt words, separated by `,`. If you want to use LoRA, you can call the `/v3/model` endpoint with the parameter `filter.types=lora` to retrieve the `sd_name_in_api` field as the `model_name`. Remember that the format for LoRA models is `<lora:$sd_name:$weight>`.
</ParamField>

<ParamField type="string">
  Negative prompt words, separated by `,`.
</ParamField>

<ParamField type="string">
  This denoising process is called sampling because Stable Diffusion generates a new sample image at each step.<br />
  Enum: `DPM++ 2M Karras`, `DPM++ SDE Karras`, `DPM++ 2M SDE Exponential`, `DPM++ 2M SDE Karras`, `Euler a`, `Euler`, `LMS`, `Heun`, `DPM2`, `DPM2 a`, `DPM++ 2S a`, `DPM++ 2M`, `DPM++ SDE`, `DPM++ 2M SDE`, `DPM++ 2M SDE Heun`, `DPM++ 2M SDE Heun Karras`, `DPM++ 2M SDE Heun Exponential`, `DPM++ 3M SDE`, `DPM++ 3M SDE Karras`, `DPM++ 3M SDE Exponential`, `DPM fast`, `DPM adaptive`, `LMS Karras`, `DPM2 Karras`, `DPM2 a Karras`, `DPM++ 2S a Karras`, `Restart`, `DDIM`, `PLMS`, `UniPC`
</ParamField>

<ParamField type="integer">
  The number of images generated in one single generation. Range: \[0, 8]
</ParamField>

<ParamField type="integer">
  The number of generations. Range: \[0, 8]
</ParamField>

<ParamField type="integer">
  Think of steps as iterations in the image creation process. Range: (0, 50]
</ParamField>

<ParamField type="integer">
  This setting determines how closely Stable Diffusion will adhere to your prompt. Range: (0, 30]
</ParamField>

<ParamField type="integer">
  A seed is a number from which Stable Diffusion generates noise.
</ParamField>

<ParamField type="integer">
  Height of the image. Range: (0, 2048]
</ParamField>

<ParamField type="integer">
  Width of the image. Range: (0, 2048]
</ParamField>

<ParamField type="string">
  Name of the Stable Diffusion model. You can call the `/v3/model` endpoint with the parameter `filter.types=checkpoint` to retrieve the `sd_name_in_api` field as the `model_name`.
</ParamField>

<ParamField type="boolean">
  Enable the Stable Diffusion face restoration plugin.
</ParamField>

<ParamField type="null" />

<ParamField type="string¦null">
  VAE (Variational Auto Encoder). `sd_vae` can be accessed in the API /v3/model with query parameters `filter.types=vae` to retrieve the `sd_name` field as the `sd_vae`.
</ParamField>

<ParamField type="integer">
  This parameter indicates the number of layers to stop from the bottom during optimization, so clip\_skip on 2 would mean, that in SD1.x model where the CLIP has 12 layers, you would stop at 10th layer.
</ParamField>

<ParamField type="boolean¦null">
  Hires.fix function switch.
</ParamField>

<ParamField type="string¦null">
  Upscalers model names. AI upscalers are models trained with massive amounts of data.<br />
  Enum: `Latent`, `ESRGAN_4x`, `R-ESRGAN 4x+`, `R-ESRGAN 4x+ Anime6B`
</ParamField>

<ParamField type="number¦null">
  The magnification factor of the image, if params hr\_resize\_x and hr\_resize\_y are set, this parameter will be ignored.<br />
  Enum: `1`, `2`
</ParamField>

<ParamField type="integer¦null">
  The target image width, the maximum image size is 2048, only take effect when parameters hr\_scale=1.
</ParamField>

<ParamField type="integer¦null">
  The target image hight, the maximum image size is 2048, only take effect when parameters hr\_scale=1.
</ParamField>

<ParamField type="integer¦null">
  Image storage time (seconds). Range \[0, 604800]
</ParamField>

<ParamField type="object¦null">
  Refiner infos to enhances the image details.

  <Expandable title="properties">
    <ParamField type="string">
      Refiner checkpoint name. Currently only `sd_xl_refiner_1.0.safetensors` supported.<br />
      Enum: `sd_xl_refiner_1.0.safetensors`
    </ParamField>

    <ParamField type="number">
      weight of refiner, from 0 to 1.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]¦null">
  ControlNet.

  <Expandable title="properties">
    <ParamField type="string">
      Model to use on the image passed to this unit before using it for conditioning. \*\*\*Controlnets for SD 1.5: control\_v11e\_sd15\_ip2p, control\_v11e\_sd15\_shuffle, control\_v11f1e\_sd15\_tile, control\_v11f1p\_sd15\_depth, control\_v11p\_sd15\_canny, control\_v11p\_sd15\_inpaint, control\_v11p\_sd15\_lineart, control\_v11p\_sd15\_mlsd, control\_v11p\_sd15\_normalbae, control\_v11p\_sd15\_openpose, control\_v11p\_sd15\_scribble, control\_v11p\_sd15\_seg, control\_v11p\_sd15\_softedge, control\_v11p\_sd15s2\_lineart\_anime, ip-adapter-plus-face\_sd15, ip-adapter\_sd15\_plus, ip-adapter\_sd15; \*\*\*Controlnets for SDXL: t2i-adapter\_diffusers\_xl\_canny, t2i-adapter\_diffusers\_xl\_depth\_midas, t2i-adapter\_diffusers\_xl\_depth\_zoe, t2i-adapter\_diffusers\_xl\_lineart, t2i-adapter\_diffusers\_xl\_openpose, t2i-adapter\_diffusers\_xl\_sketch, t2i-adapter\_xl\_canny, t2i-adapter\_xl\_openpose, t2i-adapter\_xl\_sketch, ip-adapter\_xl
    </ParamField>

    <ParamField type="number¦null">
      weight of this unit. defaults to 1
    </ParamField>

    <ParamField type="string">
      base64 of input image
    </ParamField>

    <ParamField type="string">
      preprocessor to use on the image passed to this unit before using it for conditioning.<br />
      Enum: `none`, `canny`, `depth`, `depth_leres`, `depth_leres++`, `hed`, `hed_safe`, `mediapipe_face`, `mlsd`, `normal_map`, `openpose`, `openpose_hand`, `openpose_face`, `openpose_faceonly`, `openpose_full`, `clip_vision`, `color`, `pidinet`, `pidinet_safe`, `pidinet_sketch`, `pidinet_scribble`, `scribble_xdog`, `scribble_hed`, `segmentation`, `threshold`, `depth_zoe`, `normal_bae`, `oneformer_coco`, `oneformer_ade20k`, `lineart`, `lineart_coarse`, `lineart_anime`, `lineart_standard`, `shuffle`, `tile_resample`, `invert`, `lineart_anime_denoise`, `reference_only`, `reference_adain`, `reference_adain+attn`, `inpaint`, `inpaint_only`, `inpaint_only+lama`, `tile_colorfix`, `tile_colorfix+sharp`, `depth_anything`
    </ParamField>

    <ParamField type="integer¦null">
      0 for Balanced,1 for My prompt is more important 2 for ControlNet is more important<br />
      Enum: `0`, `1`, `2`
    </ParamField>

    <ParamField type="string¦null">
      Base64 of mask images, support jpg, jpeg and png format images. Only take effect when controlnet\_units.model set to control\_v11p\_sd15\_inpaint.
    </ParamField>

    <ParamField type="integer¦null">
      How to resize the input image so as to fit the output resolution of the generation. 0 represent JUST\_RESIZE, 1 represent RESIZE\_OR\_CORP, 2 represent RESIZE\_AND\_FILL<br />
      Enum: `0`, `1`, `2`
    </ParamField>

    <ParamField type="integer">
      Resolution of the preprocessor.
    </ParamField>

    <ParamField type="integer">
      First parameter of the preprocessor, only takes effect when preprocessor accepts arguments.
    </ParamField>

    <ParamField type="integer">
      Second parameter of the preprocessor, only takes effect when preprocessor accepts arguments.
    </ParamField>

    <ParamField type="number">
      ratio of generation where this unit starts to have an effect.
    </ParamField>

    <ParamField type="number">
      ratio of generation where this unit stops to have an effect.
    </ParamField>

    <ParamField type="boolean">
      Enable pixel-perfect preprocessor, when set to false, it means not to resize images.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="code" type="integer" />

<ResponseField name="msg" type="string" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="task_id" type="string" />

    <ResponseField name="warn" type="string" />
  </Expandable>
</ResponseField>

## Example

request

```bash theme={"system"}
curl --location 'https://api.novita.ai/v2/txt2img' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
  'extra': {
    'enable_nsfw_detection': false,
    'nsfw_detection_level': 0,
    'enable_progress_info': false
  },
  'prompt': 'Luxury suite design, Spacious suite area, Luxuriously plush large bed, Refined office desk, Carefully selected furniture for the luxurious suite, High-end and opulent decor, Private office and lounge area, Comfortably luxurious office chair, Amenities for luxury travelers, Premium bedding and linens, Uniquely designed lighting fixtures, Luxurious suite curtain design, Private work corner, Luxurious amenities, Lavish lounge area, Sophisticated indoor plant, decorations, Exquisite luxury design, Exclusive services for the luxury suite, Luxury color scheme. Exclusive furniture for the luxury suite, a bedroom with a large bed and a desk',
  'negative_prompt': '(badhandv4:1.2),(worst quality:2),(low quality:2),(normal quality:2),lowres,bad anatomy,bad hands,((monochrome)),((grayscale)) watermark,moles, easynegative ng_deepnegative_v1_75t, (oversized head:2), (big head:2), (deformed face:1.5),( blurry face:2), bad eyes, irregular eyes, asymmetric eyes, ugly, teeth, (navel:0.9), artefact, jpg artefact, blurry face, blurry, blurred, pixelated, bad eyes, crossed eyes, blurry eyes',
  'sampler_name': 'DPM++ 2M Karras',
  'batch_size': 1,
  'n_iter': 1,
  'steps': 25,
  'cfg_scale': 7,
  'seed': -1,
  'height': 512,
  'width': 512,
  'model_name': 'sd_xl_base_0.9.safetensors',
  'restore_faces': false,
  'restore_faces_model': '',
  'sd_vae': '',
  'clip_skip': 1,
  'enable_hr': false,
  'hr_upscaler': 'Latent',
  'hr_scale': 1,
  'hr_resize_x': null,
  'hr_resize_y': null,
  'img_expire_ttl': null,
  'sd_refiner': {
    'checkpoint': 'sd_xl_refiner_1.0.safetensors',
    'switch_at': null
  },
  'controlnet_units': [
    {
      'model': '',
      'weight': null,
      'input_image': '',
      'module': 'none',
      'control_mode': 0,
      'mask': '',
      'resize_mode': 0,
      'processor_res': null,
      'threshold_a': null,
      'threshold_b': null,
      'guidance_start': null,
      'guidance_end': null,
      'pixel_perfect': false
    }
  ]
}'
```

response

```json theme={"system"}
{
  "code": 0,
  "msg": "",
  "data": {
    "task_id": "d4cf3973-8414-4a5e-aa6f-ef54caf73662"
  }
}
```


# Text to Speech
Source: https://novita.ai/docs/api-reference/model-apis-text-to-speech

POST https://api.novita.ai/v3/async/txt2speech

**This Text-To-Speech API converts written text into natural-sounding speech across multiple languages. Utilizing advanced voice synthesis technology, it delivers clear and lifelike vocal output, suitable for a wide range of applications, including e-learning platforms, accessibility tools, virtual assistants, and multimedia presentations.**

> This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the speech generation results.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Optional extra parameters for the request.

  <Expandable title="properties">
    <ParamField type="string">
      The returned audio type. Default is wav.<br />
      Enum: `wav`, `mp3`
    </ParamField>

    <ParamField type="object">
      Webhook settings. More details can be found at [Webhook Documentation](/api-reference/model-apis-webhook).

      <Expandable title="properties">
        <ParamField type="string">
          The URL of the webhook endpoint. Novita AI will send the task generated outputs to your specified webhook endpoint.
        </ParamField>

        <ParamField type="object">
          By specifying Test Mode, a mock event will be sent to the webhook endpoint.

          <Expandable title="properties">
            <ParamField type="boolean">
              Set to true to enable Test Mode, or false to disable it. The default is false.
            </ParamField>

            <ParamField type="string">
              Control the data content of the mock event. When set to TASK\_STATUS\_SUCCEED, you'll receive a normal response; when set to TASK\_STATUS\_FAILED, you'll receive an error response.<br />
              Enum: `TASK_STATUS_SUCCEED`, `TASK_STATUS_FAILED`
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      Dedicated Endpoints settings, which only take effect for users who have already subscribed to the [Dedicated Endpoints Documentation](/guides/model-apis-dedicated-endpoints).

      <Expandable title="properties">
        <ParamField type="boolean">
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Voice ID<br />
      Enum: `Emily`, `James`, `Olivia`, `Michael`, `Sarah`, `John`
    </ParamField>

    <ParamField type="string">
      Identify the languages spoken in the generated audio<br />
      Enum: `en-US`, `zh-CN`, `ja-JP`
    </ParamField>

    <ParamField type="string[]">
      Source text for synthetic speech, UTF-8 encoded, supporting a maximum of 512 characters.
    </ParamField>

    <ParamField type="number">
      Control the volume of the generated audio; select a value between 1.0 and 2.0. The default value is 1.0.
    </ParamField>

    <ParamField type="number">
      Control the speed of the generated audio; select a value between 0.8 and 3.0. The default value is 1.0.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>

## Example

request

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/txt2speech' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
  "request": {
    "voice_id": "Emily",
    "language": "en-US",
    "texts": [
      "To be or not to be, that is a question."
    ],
    "volume": 1.2,
    "speed": 1.0
  }
}'
```

response

```json theme={"system"}
{
  "task_id": "b49df8dc-4a72-474b-a863-xxx"
}
```


# Text to Video
Source: https://novita.ai/docs/api-reference/model-apis-txt2video

POST https://api.novita.ai/v3/async/txt2video

**This API transforms textual descriptions into dynamic videos. By interpreting and visualizing the input text, it creates engaging video content that corresponds to the described scenarios, events, or narratives. This capability is ideal for content creation where the visual representation of text-based information enhances understanding or entertainment value.**

> This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Optional extra parameters for the request.

  <Expandable title="properties">
    <ParamField type="string">
      The returned video type. Default is mp4.<br />
      Enum: `mp4`, `gif`
    </ParamField>

    <ParamField type="object">
      Webhook settings. More details can be found at [Webhook Documentation](/api-reference/model-apis-webhook).

      <Expandable title="properties">
        <ParamField type="string">
          The URL of the webhook endpoint. Novita AI will send the task generated outputs to your specified webhook endpoint.
        </ParamField>

        <ParamField type="object">
          By specifying Test Mode, a mock event will be sent to the webhook endpoint.

          <Expandable title="properties">
            <ParamField type="boolean">
              Set to true to enable Test Mode, or false to disable it. The default is false.
            </ParamField>

            <ParamField type="string">
              Control the data content of the mock event. When set to TASK\_STATUS\_SUCCEED, you'll receive a normal response; when set to TASK\_STATUS\_FAILED, you'll receive an error response.<br />
              Enum: `TASK_STATUS_SUCCEED`, `TASK_STATUS_FAILED`
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      Dedicated Endpoints settings, which only take effect for users who have already subscribed to the [Dedicated Endpoints Documentation](/guides/model-apis-dedicated-endpoints).

      <Expandable title="properties">
        <ParamField type="boolean">
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Name of SD1.x checkpoints; this parameter specifies the name of the model checkpoint. Retrieve the corresponding sd\_name value by invoking the <a href="/api-reference/model-apis-get-model">Query Model</a> API with filter.types=checkpoint as the query parameter.
</ParamField>

<ParamField type="integer">
  Height of the video, range \[256, 1024]
</ParamField>

<ParamField type="integer">
  Width of the video, range \[256, 1024]
</ParamField>

<ParamField type="integer">
  The number of denoising steps. More steps usually produce higher quality content but take more time to generate. Range \[1, 50]
</ParamField>

<ParamField type="object[]">
  The total number of frames in prompts must be less than or equal to 128, where the total number of frames is the cumulative sum of all prompt frames.

  <Expandable title="properties">
    <ParamField type="integer">
      Frames of this video clip, Range \[8, 64]
    </ParamField>

    <ParamField type="string">
      Text input required to guide the generation, separated by `,`, Range \[1, 1024].
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Text input that will not guide the generation, separated by `,`, Range \[1, 1024].
</ParamField>

<ParamField type="number">
  This setting determines how closely Stable Diffusion will adhere to your prompt. Higher guidance forces the model to better follow the prompt but may result in lower quality output. Range \[1, 30].
</ParamField>

<ParamField type="integer">
  A seed is a number from which Stable Diffusion generates noise, which, makes generation deterministic. Using the same seed and set of parameters will produce identical content each time, minimum -1. Defaults to -1.
</ParamField>

<ParamField type="object[]">
  LoRA is a fast and lightweight training method that inserts and trains a significantly smaller number of parameters instead of all the model parameters. Currently supports up to 5 LoRAs.

  <Expandable title="properties">
    <ParamField type="string">
      Name of lora, retrieve the corresponding sd\_name\_in\_api value by invoking the <a href="/api-reference/model-apis-get-model">Get Model API</a> endpoint with filter.types=lora as the query parameter.
    </ParamField>

    <ParamField type="number">
      The strength value of lora. The larger the value, the more biased the effect is towards lora, Range \[0, 1]
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  Textual Inversion is a training method for personalizing models by learning new text embeddings from a few example images, currently supports up to 5 embeddings.

  <Expandable title="properties">
    <ParamField type="string">
      Name of textual Inversion model, you can call the <a href="/api-reference/model-apis-get-model">Get Model API</a> endpoint with parameter filter.types=textualinversion to retrieve the sd\_name\_in\_api field as the model\_name.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="boolean">
  The closed\_loop parameter controls the behavior of an animation when it loops. Specifically, it determines whether the last frame of the animation will transition smoothly back to the first frame.
</ParamField>

<ParamField type="integer">
  This parameter indicates the number of layers to stop from the bottom during optimization, so clip\_skip on 2 would mean, that in SD1.x model where the CLIP has 12 layers, you would stop at 10th layer, Range \[1, 12], get reference at [A brief introduction to Clip Skip](/guides/model-apis-clip-skip).
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>

## Example

This API helps generate videos from text. The returned video can be accessed via the API `/v3/async/task-result` using the `task_id`.

**Try it in [playground](https://novita.ai/playground#txt2video).**

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/txt2video' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "model_name": "darkSushiMixMix_225D_64380.safetensors",
    "height": 512,
    "width": 512,
    "steps": 20,
    "seed": -1,
    "prompts": [
        {
            "frames": 32,
            "prompt": "In the wintry dusk, a little girl holds matches tightly."
        },
        {
            "frames": 32,
            "prompt": "A little girl, barefoot on the frosty pavement, seeks solace."
        },
        {
            "frames": 32,
            "prompt": "A little girl with each match experiences a fleeting dance of warmth and hope."
        },
        {
            "frames": 32,
            "prompt": "In the quiet night, a little girl's silent story unfolds."
        }
    ],
    "negative_prompt": "nsfw, ng_deepnegative_v1_75t, badhandv4, (worst quality:2), (low quality:2), (normal quality:2), lowres, ((monochrome)), ((grayscale)), watermark"
}'
```

`Response:`

```js theme={"system"}
{
    "task_id": "fa20dff3-18cb-4417-a7f8-269456a35154"
}
```

**Use `task_id` to get images**

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get videos url in `videos` of response.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id=fa20dff3-18cb-4417-a7f8-269456a35154' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "task": {
        "task_id": "fa20dff3-18cb-4417-a7f8-269456a35154",
        "task_type": "TXT_TO_VIDEO",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 100
    },
    "images": [],
    "videos": [
        {
            "video_url": "https://faas-output-video.s3.ap-southeast-1.amazonaws.com/test/61bc0452-03a5-4e5b-ba78-2dbd3db6cc7d/99a87dec55c6431189aff4bad39fb4a0.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20231219%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20231219T143829Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=3b828cd8e72d9e83eb625e5e175defbfbcfc97acf4a605dc83588ae949b698b4",
            "video_url_ttl": "3600",
            "video_type": "mp4"
        }
    ]
}
```

`Video files:`

<video />


# Upscale
Source: https://novita.ai/docs/api-reference/model-apis-upscale

POST https://api.novita.ai/v3/async/upscale

**An indispensable tool for improving the quality of images generated by Stable Diffusion.**

> This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the image generation results.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Optional extra parameters for the request.

  <Expandable title="properties">
    <ParamField type="string">
      The returned image type. Default is png.<br />
      Enum: `png`, `webp`, `jpeg`
    </ParamField>

    <ParamField type="object">
      Webhook settings. More details can be found at [Webhook Documentation](/api-reference/model-apis-webhook).

      <Expandable title="properties">
        <ParamField type="string">
          The URL of the webhook endpoint. Novita AI will send the task generated outputs to your specified webhook endpoint.
        </ParamField>

        <ParamField type="object">
          By specifying Test Mode, a mock event will be sent to the webhook endpoint.

          <Expandable title="properties">
            <ParamField type="boolean">
              Set to true to enable Test Mode, or false to disable it. The default is false.
            </ParamField>

            <ParamField type="string">
              Control the data content of the mock event. When set to TASK\_STATUS\_SUCCEED, you'll receive a normal response; when set to TASK\_STATUS\_FAILED, you'll receive an error response.<br />
              Enum: `TASK_STATUS_SUCCEED`, `TASK_STATUS_FAILED`
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      Customer storage settings for saving the generated outputs. <br /> By default, the generated outputs will be saved to Novita AI Storage temporarily and privately.

      <Expandable title="properties">
        <ParamField type="object">
          AWS S3 Bucket settings.

          <Expandable title="properties">
            <ParamField type="string">
              AWS S3 regions, <a href="https://docs.aws.amazon.com/general/latest/gr/rande.html">more details</a>.
            </ParamField>

            <ParamField type="string">
              AWS S3 bucket name.
            </ParamField>

            <ParamField type="string">
              AWS S3 bucket path for saving generated outputs.
            </ParamField>

            <ParamField type="boolean">
              Set this option to True to save the generated outputs directly to the specified path without creating any additional directory hierarchy. <br /> If set to False, Novita AI will create an additional directory in the path to save the generated outputs. The default is False.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      Dedicated Endpoints settings, which only take effect for users who have already subscribed to the [Dedicated Endpoints Documentation](/guides/model-apis-dedicated-endpoints).

      <Expandable title="properties">
        <ParamField type="boolean">
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="boolean">
      When set to true, NSFW detection will be enabled, incurring an additional cost of \$0.0015 for each generated image.
    </ParamField>

    <ParamField type="integer">
      0: Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols.<br /> 1: Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols; Non-Explicit Nudity, Obstructed Intimate Parts, Kissing on the Lips.<br /> 2: Explicit Nudity, Explicit Sexual Activity, Sex Toys; Hate Symbols; Non-Explicit Nudity, Obstructed Intimate Parts, Kissing on the Lips; Female Swimwear or Underwear, Male Swimwear or Underwear.<br />
      Enum: `0`, `1`, `2`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      AI upscalers are models trained on massive amounts of data.<br />
      Enum: `RealESRGAN_x4plus_anime_6B`, `RealESRNet_x4plus`, `4x-UltraSharp`
    </ParamField>

    <ParamField type="string">
      The base64 of original image, with a maximum resolution of 2048x2048 and a maximum file size of 30 Mb.
    </ParamField>

    <ParamField type="number">
      The scale\_factor indicates the multiplier by which the original size will be upscaled. Valid range: (1, 4].
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>

## Example

This is an indispensable tool for improving the quality of images generated by Stable Diffusion.

**Try it in [playground](https://novita.ai/playground#upscale).**

`Request:`

```bash theme={"system"}
curl --location --request POST 'https://api.novita.ai/v3/async/upscale' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "extra": {
        "response_image_type": "jpeg"
    },
    "request": {
        "model_name": "RealESRGAN_x4plus_anime_6B",
        "scale_factor": 2,
        "image_base64": "{{base64 encoded image}}"
    }
}'
```

HTTP status codes in the 2xx range indicate that the request has been successfully accepted; code 400 indicates a request parameter error, while status codes in the 5xx range indicate internal server errors.

`Response:`

```js theme={"system"}
{
    "task_id": "71dd988e-632e-4339-b217-74bcbe6db0ee"
}
```

**Use `task_id` to retrieve images**

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can find the image URLs in the `imgs` field of the response.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/task-result?task_id=71dd988e-632e-4339-b217-74bcbe6db0ee' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "extra": {
        "enable_nsfw_detection": false
    },
    "task": {
        "task_id": "71dd988e-632e-4339-b217-74bcbe6db0ee",
        "task_type": "UPSCALE",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 0
    },
    "images": [
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/71dd988e-632e-4339-b217-74bcbe6db0ee/949a5ba965c84bd99764ca9b2f51fc6a.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240321%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240321T093338Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=e7d4dab3a82555d10ded8ad82769122b75b6bda179c60f3bacb978d85d23252e",
            "image_url_ttl": "3600",
            "image_type": "jpeg",
            "nsfw_detection_result": null
        }
    ],
    "videos": []
}
```

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>


# Upscale V2
Source: https://novita.ai/docs/api-reference/model-apis-upscale-v2-deprecated

POST https://api.novita.ai/v2/upscale

<Warning>
  **The Upscale V2 API is deprecated and will be removed in the future. Please migrate to [Upscale V3](/api-reference/model-apis-upscale).**
</Warning>

## POST Upscale V2

An indispensable tool for improving the quality of images generated by Stable Diffusion.

## Request Headers

<ParamField type="string" />

## Request Body

<ParamField type="string">
  Base64 encoded image
</ParamField>

<ParamField type="string|null">
  AI upscalers are models trained with massive amounts of data.
</ParamField>

<ParamField type="integer|null">
  Resizing mode:
</ParamField>

<ParamField type="number|null">
  The magnification factor of the image. For example, if you input upscaling\_resize:2 with an image size of 512x512, it will return images of 1024x1024 (the maximum image size is 2048).
</ParamField>

<ParamField type="integer|null">
  The target image width; the maximum image size is 2048.
</ParamField>

<ParamField type="integer|null">
  The target image height; the maximum image size is 2048.
</ParamField>

<ParamField type="boolean|null">
  Zoom in after cropping.
</ParamField>

<ParamField type="string|null">
  AI upscalers are models trained with massive amounts of data.
</ParamField>

<ParamField type="number|null">
  Range \[0\~1], Extras upscaler 2 visibility.
</ParamField>

<ParamField type="number|null">
  Range \[0\~1], GFPGAN visibility.
</ParamField>

<ParamField type="number|null">
  Range \[0\~1], CodeFormer visibility.
</ParamField>

<ParamField type="number|null">
  Range \[0\~1], CodeFormer weight (0 = maximum effect, 1 = minimum effect).
</ParamField>

<ParamField type="integer">
  Image storage time (seconds). Range \[0, 604800].
</ParamField>

## Response

<ResponseField name="code" type="integer">
  CodeNormal=0, CodeInternalError=-1, CodeInvalidJSON=1, CodeModelNotExist=2, CodeTaskIdNotExist=3, CodeInvalidAuth=4, CodeHostUnavailable=5, CodeParamRangeOutOfLimit=6, CodeCostBalanceFailure=7, CodeSamplerNotExist=8, CodeTimeout=9, CodeNotSupport=10
</ResponseField>

<ResponseField name="msg" type="string" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="task_id" type="string" />

    <ResponseField name="warn" type="string" />
  </Expandable>
</ResponseField>

## Example

request

```bash theme={"system"}
curl --location 'https://api.novita.ai/v2/upscale' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
  'image': '{{base64 encoded image}}',
  'upscaler_1': 'R-ESRGAN 4x+',
  'resize_mode': 1,
  'upscaling_resize': null,
  'upscaling_resize_w': 1024,
  'upscaling_resize_h': 1024,
  'upscaling_crop': true,
  'upscaler_2': 'R-ESRGAN 4x+',
  'extras_upscaler_2_visibility': 0.5,
  'gfpgan_visibility': 0.5,
  'codeformer_visibility': 0.5,
  'codeformer_weight': 0.5,
  'img_expire_ttl': null
}'
```

response

```json theme={"system"}
{
  "code": null,
  "msg": "",
  "data": {
    "task_id": "",
    "warn": ""
  }
}
```


# Video Merge Face
Source: https://novita.ai/docs/api-reference/model-apis-video-merge-face

POST https://api.novita.ai/v3/async/video-merge-face

**This API endpoint seamlessly integrates a face image into a target video, allowing you to replace the face in the video with the face from the image.**

> **Pricing:** \$0.0005 / Video Frame

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Optional extra parameters for the request.

  <Expandable title="properties">
    <ParamField type="string">
      The returned video type. Default is mp4.<br />
      Enum: `mp4`, `gif`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Upload your input video to our temporary secure storage following the instructions in the guide <a href="#_1-get-video-assets-id">Get video assets id</a>, and the video\_assets\_id is the identifier for your input video. Supported video formats: MP4, with a maximum resolution of 3840 x 2160 and a maximum file size of 100 Mb.
    </ParamField>

    <ParamField type="boolean">
      Whether to restore the output face image. If enabled, the output face video will be more detailed, but the API latency will be longer.
    </ParamField>

    <ParamField type="string">
      The base64-encoded face image, with a maximum resolution of 2048 x 2048 and a maximum file size of 30 MB.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>

## Example

### 1. Get Video Assets ID

`Request:`

```bash theme={"system"}
curl -X PUT -T "{{video file path}}" 'https://assets.novitai.com/video'
```

`Response:`

```js theme={"system"}
{
    "assets_id": "cjIvbm92aXRhLWFpLWFzc2V0L3ZpZGVvL0NLd0N3aHJwS0ZyYVduNWVoejVFV0tleGlzN0toNmRq"
}
```


# Vidu 2.0 Image to Video
Source: https://novita.ai/docs/api-reference/model-apis-vidu-2.0-img2video

POST https://api.novita.ai/v3/async/vidu-2.0-img2video

Vidu 2.0 Image to Video transforms static images into dynamic videos, incorporating creative storytelling and animations.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string[]">
  An image to be used as the start frame of the generated video.

  For fields that accept images:

  * Only accepts 1 image
  * Accepts public URL or Base64 format
  * Supported formats: png, jpeg, jpg, webp
  * The aspect ratio of the images must be less than 1:4 or 4:1
  * All images are limited to 50MB
  * The length of the base64 decode must be under 10MB, and it must include an appropriate content type string. For instance:

  ```
  data:image/png;base64,{base64_encode}
  ```
</ParamField>

<ParamField type="string">
  Text prompt for video generation, with a maximum length of 1500 characters.
</ParamField>

<ParamField type="integer">
  Video duration in seconds. Default is 4 seconds, with options available for `4` or `8` seconds.
</ParamField>

<ParamField type="integer">
  Random seed for video generation.

  * Defaults to a random seed number
  * Manually set values will override the default random seed
</ParamField>

<ParamField type="string">
  Resolution based on duration:

  * 4s: default 360p, options: `360p`, `720p`, `1080p`
  * 8s: default 720p, options: `720p`
</ParamField>

<ParamField type="string">
  The movement amplitude of objects in the frame. Default: `auto`<br />
  Accepted values: `auto`, `small`, `medium`, `large`
</ParamField>

<ParamField type="boolean">
  Whether to add background music to the generated video. Default: `false`<br />
  Acceptable values: `true`, `false`

  When true, the system will automatically add a suitable BGM. BGM has no time limit and the system automatically adapts.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Vidu 2.0 Reference to Video
Source: https://novita.ai/docs/api-reference/model-apis-vidu-2.0-reference2video

POST https://api.novita.ai/v3/async/v3/async/vidu-2.0-reference2video

Vidu 2.0 Reference to Videos generates videos using a reference image and text description. It supports various subjects, such as characters and objects. By uploading multiple perspectives of a subject, you can create videos that maintain visual consistency.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string[]">
  The model will use the provided images as references to generate a video with consistent subjects.

  For fields that accept images:

  * Accepts 1 to 3 images
  * Images Assets can be provided via URLs or Base64 encode
  * You must use one of the following codecs: PNG, JPEG, JPG, WebP
  * The dimensions of the images must be at least 128x128 pixels
  * The aspect ratio of the images must be less than 1:4 or 4:1
  * All images are limited to 50MB
  * The length of the base64 decode must be under 10MB, and it must include an appropriate content type string. For instance:

  ```
  data:image/png;base64,{base64_encode}
  ```
</ParamField>

<ParamField type="string">
  Text prompt for video generation, with a maximum length of 1500 characters.
</ParamField>

<ParamField type="integer">
  Video duration in seconds. Default: 4 seconds. Available option: `4`.
</ParamField>

<ParamField type="integer">
  Random seed for video generation.

  * Defaults to a random seed number
  * Manually set values will override the default random seed
</ParamField>

<ParamField type="string">
  The aspect ratio of the output video. Default: `16:9`<br />
  Accepted values: `16:9`, `9:16`, `1:1`
</ParamField>

<ParamField type="string">
  The resolution parameter defaults to 360p, with available options of `360p` and `720p`.
</ParamField>

<ParamField type="string">
  The movement amplitude of objects in the frame. Default: `auto`<br />
  Accepted values: `auto`, `small`, `medium`, `large`
</ParamField>

<ParamField type="boolean">
  Whether to add background music to the generated video. Default: `false`<br />
  Acceptable values: `true`, `false`

  When true, the system will automatically add a suitable BGM. BGM has no time limit and the system automatically adapts.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Vidu 2.0 Start End to Video
Source: https://novita.ai/docs/api-reference/model-apis-vidu-2.0-startend2video

POST https://api.novita.ai/v3/async/vidu-2.0-startend2video

Vidu 2.0 Start End to Video transforms static images into dynamic videos, incorporating creative storytelling and animations.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string[]">
  Two images: first is start frame, second is end frame.

  Notes:

  1. Public URL or Base64
  2. Aspect ratios must be close: ratio between start/end frame must be in 0.8\~1.25
  3. Format: png, jpeg, jpg, webp
  4. Max size: 50MB
  5. The length of the base64 decode must be under 10MB, and it must include an appropriate content type string. For instance:

  ```
  data:image/png;base64,{base64_encode}
  ```
</ParamField>

<ParamField type="string">
  Prompt description, max 1500 characters.
</ParamField>

<ParamField type="integer">
  Video duration in seconds. Default is 4 seconds, with options available for `4` or `8` seconds.
</ParamField>

<ParamField type="integer">
  Random seed for video generation.

  * Defaults to a random seed number
  * Manually set values will override the default random seed
</ParamField>

<ParamField type="string">
  Resolution based on duration:

  * 4s: default 360p, options: `360p`, `720p`, `1080p`
  * 8s: default 720p, options: `720p`
</ParamField>

<ParamField type="string">
  The movement amplitude of objects in the frame. Default: `auto`<br />
  Accepted values: `auto`, `small`, `medium`, `large`
</ParamField>

<ParamField type="boolean">
  Whether to add background music to the generated video. Default: `false`<br />
  Acceptable values: `true`, `false`

  When true, the system will automatically add a suitable BGM. BGM has no time limit and the system automatically adapts.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Vidu Q1 Image to Video
Source: https://novita.ai/docs/api-reference/model-apis-vidu-q1-img2video

POST https://api.novita.ai/v3/async/vidu-q1-img2video

Vidu Q1 Image to Video transforms static images into dynamic videos, incorporating creative storytelling and animations.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string[]">
  An image to be used as the start frame of the generated video.

  For fields that accept images:

  * Only accepts 1 image
  * Accepts public URL or Base64 format
  * Supported formats: png, jpeg, jpg, webp
  * The aspect ratio of the images must be less than 1:4 or 4:1
  * All images are limited to 50MB
  * The length of the base64 decode must be under 10MB, and it must include an appropriate content type string. For instance:

  ```
  data:image/png;base64,{base64_encode}
  ```
</ParamField>

<ParamField type="string">
  Text prompt for video generation, with a maximum length of 1500 characters.
</ParamField>

<ParamField type="integer">
  Video duration in seconds. The default is 5 seconds, with `5` being the only available option.
</ParamField>

<ParamField type="integer">
  Random seed for video generation.

  * Defaults to a random seed number
  * Manually set values will override the default random seed
</ParamField>

<ParamField type="string">
  Output video resolution. Default is 1080p, with `1080p` as the only option available.
</ParamField>

<ParamField type="string">
  The movement amplitude of objects in the frame. Default: `auto`<br />
  Accepted values: `auto`, `small`, `medium`, `large`
</ParamField>

<ParamField type="boolean">
  Whether to add background music to the generated video. Default: `false`<br />
  Acceptable values: `true`, `false`

  When true, the system will automatically add a suitable BGM. BGM has no time limit and the system automatically adapts.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Vidu Q1 Reference to Video
Source: https://novita.ai/docs/api-reference/model-apis-vidu-q1-reference2video

POST https://api.novita.ai/v3/async/vidu-q1-reference2video

Vidu Q1 Reference to Videos generates videos using a reference image and text description. It supports various subjects, such as characters and objects. By uploading multiple perspectives of a subject, you can create videos that maintain visual consistency.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string[]">
  The model will use the provided images as references to generate a video with consistent subjects.

  For fields that accept images:

  * Accepts 1 to 7 images
  * Images Assets can be provided via URLs or Base64 encode
  * You must use one of the following codecs: PNG, JPEG, JPG, WebP
  * The dimensions of the images must be at least 128x128 pixels
  * The aspect ratio of the images must be less than 1:4 or 4:1
  * All images are limited to 50MB
  * The length of the base64 decode must be under 10MB, and it must include an appropriate content type string. For instance:

  ```
  data:image/png;base64,{base64_encode}
  ```
</ParamField>

<ParamField type="string">
  Text prompt for video generation, with a maximum length of 1500 characters.
</ParamField>

<ParamField type="integer">
  Video duration in seconds. The default is 5 seconds, with `5` being the only available option.
</ParamField>

<ParamField type="integer">
  Random seed for video generation.

  * Defaults to a random seed number
  * Manually set values will override the default random seed
</ParamField>

<ParamField type="string">
  The aspect ratio of the output video. Default: `16:9`<br />
  Accepted values: `16:9`, `9:16`, `1:1`
</ParamField>

<ParamField type="string">
  Output video resolution. Default is 1080p, with `1080p` as the only option available.
</ParamField>

<ParamField type="string">
  The movement amplitude of objects in the frame. Default: `auto`<br />
  Accepted values: `auto`, `small`, `medium`, `large`
</ParamField>

<ParamField type="boolean">
  Whether to add background music to the generated video. Default: `false`<br />
  Acceptable values: `true`, `false`

  When true, the system will automatically add a suitable BGM. BGM has no time limit and the system automatically adapts.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Vidu Q1 Start End to Video
Source: https://novita.ai/docs/api-reference/model-apis-vidu-q1-startend2video

POST https://api.novita.ai/v3/async/vidu-q1-startend2video

Vidu Q1 Start End to Video transforms static images into dynamic videos, incorporating creative storytelling and animations.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string[]">
  Two images: first is start frame, second is end frame.

  Notes:

  1. Public URL or Base64
  2. Aspect ratios must be close: ratio between start/end frame must be in 0.8\~1.25
  3. Format: png, jpeg, jpg, webp
  4. Max size: 50MB
  5. The length of the base64 decode must be under 10MB, and it must include an appropriate content type string. For instance:

  ```
  data:image/png;base64,{base64_encode}
  ```
</ParamField>

<ParamField type="string">
  Prompt description, max 1500 characters.
</ParamField>

<ParamField type="integer">
  Video duration in seconds. The default is 5 seconds, with `5` being the only available option.
</ParamField>

<ParamField type="integer">
  Random seed for video generation.

  * Defaults to a random seed number
  * Manually set values will override the default random seed
</ParamField>

<ParamField type="string">
  Output video resolution. Default is 1080p, with `1080p` as the only option available.
</ParamField>

<ParamField type="string">
  The movement amplitude of objects in the frame. Default: `auto`<br />
  Accepted values: `auto`, `small`, `medium`, `large`
</ParamField>

<ParamField type="boolean">
  Whether to add background music to the generated video. Default: `false`<br />
  Acceptable values: `true`, `false`

  When true, the system will automatically add a suitable BGM. BGM has no time limit and the system automatically adapts.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Vidu Q1 Text to Video
Source: https://novita.ai/docs/api-reference/model-apis-vidu-q1-txt2video

POST https://api.novita.ai/v3/async/vidu-q1-text2video

Vidu Q1 Text to Video generates smooth and seamless videos by utilizing keyframes to maintain consistent themes.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  Text prompt for video generation, with a maximum length of 1500 characters.
</ParamField>

<ParamField type="string">
  The style of output video. Default: `general`<br />
  Accepted values: `general`, `anime`

  * `general`: General style. Allows style control through prompts
  * `anime`: Anime style. Optimized for anime aesthetics, with better performance for anime-related prompts
</ParamField>

<ParamField type="integer">
  Video duration in seconds. Default is 5 seconds, with `5` being the only available option.
</ParamField>

<ParamField type="integer">
  Random seed for video generation.

  * Defaults to a random seed number
  * Manually set values will override the default random seed
</ParamField>

<ParamField type="string">
  The aspect ratio of the output video. Default: `16:9`<br />
  Accepted values: `16:9`, `9:16`, `1:1`
</ParamField>

<ParamField type="string">
  Output video resolution. Default is 1080p, with `1080p` as the only option available.
</ParamField>

<ParamField type="string">
  The movement amplitude of objects in the frame. Default: `auto`<br />
  Accepted values: `auto`, `small`, `medium`, `large`
</ParamField>

<ParamField type="boolean">
  Whether to add background music to the generated video. Default: `false`<br />
  Acceptable values: `true`, `false`

  When true, the system will automatically add a suitable BGM. BGM has no time limit and the system automatically adapts.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Wan 2.1 Image to Video
Source: https://novita.ai/docs/api-reference/model-apis-wan-i2v

POST https://api.novita.ai/v3/async/wan-i2v

Accelerated inference for Wan 2.1 14B Image-to-Video, a comprehensive and open suite of video foundation models that pushes the boundaries of video generation. By default, the API will generate a video with 5 seconds.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Optional extra parameters for the request.

  <Expandable title="properties">
    <ParamField type="object">
      Webhook settings. More details can be found at [Webhook Documentation](/api-reference/model-apis-webhook).

      <Expandable title="properties">
        <ParamField type="string">
          The URL of the webhook endpoint. Novita AI will send the task generated outputs to your specified webhook endpoint.
        </ParamField>

        <ParamField type="object">
          By specifying Test Mode, a mock event will be sent to the webhook endpoint.

          <Expandable title="properties">
            <ParamField type="boolean">
              Set to true to enable Test Mode, or false to disable it.

              The default is `false`.
            </ParamField>

            <ParamField type="string">
              Control the data content of the mock event. When set to TASK\_STATUS\_SUCCEED, you'll receive a normal response; when set to TASK\_STATUS\_FAILED, you'll receive an error response.

              Supports: `TASK_STATUS_SUCCEED`, `TASK_STATUS_FAILED`.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Prompt text required to guide the generation.

  Range: `1 <= x <= 2000`.
</ParamField>

<ParamField type="string">
  The URL of the image to be used for video generation.
</ParamField>

<ParamField type="string">
  Negative prompts instruct the model on what elements to avoid generating.

  Range: `0 <= x <= 2000`.
</ParamField>

<ParamField type="integer">
  Width of the output video.

  Supports: `480`, `720`, `832`, `1280`.

  Default: `832`. If the width or height is not specified, the width and the height will be forced to `832` and `480` respectively.
</ParamField>

<ParamField type="integer">
  Height of the output video.

  Supports:

  * (480p) `832` for `width` of `480`
  * (480p) `480` for `width` of `832`
  * (720p) `1280` for `width` of `720`
  * (720p) `720` for `width` of `1280`

  Default: `480`. If the width or height is not specified, the width and the height will be forced to `832` and `480` respectively.

  <Warning>
    The output video will maintain the input image's aspect ratio, and the `width x height` setting only determines the output video's clarity. For example, a 720p video will be clearer than a 480p video.
  </Warning>
</ParamField>

<ParamField type="object[]">
  LoRA models to be applied to the video generation.

  Currently supports up to **3 LoRAs**.

  <Expandable title="properties">
    <ParamField type="string">
      The path to the LoRA model. You can specify either a LoRA model name from Hugging Face, for example: `Remade-AI/Painting`; or a model download URL from Civitai, for example: `https://civitai.com/api/download/models/1513385?type=Model&format=SafeTensor`.

      <Warning>
        The LoRA model must be compatible with Wan2.1 14B I2V, otherwise it will not work. Please check compatibility before using it.
      </Warning>
    </ParamField>

    <ParamField type="number">
      The scale value of lora. The larger the value, the more biased the effect is towards lora.

      Range: `0 <= x <= 4.0`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="integer">
  A seed is a number generates noise, which, makes generation deterministic. Using the same seed and set of parameters will produce identical content each time.

  Range: `-1 <= x <= 9999999999`. Default: `-1`.
</ParamField>

<ParamField type="integer">
  The number of inference steps.

  Range: `1 <= x <= 40`. Default: `30`.
</ParamField>

<ParamField type="float">
  Guidance scale parameter controls how closely the generated content follows the prompt.

  Range: `0 <= x <= 10`. Default: `5.0`.
</ParamField>

<ParamField type="float">
  The flow\_shift parameter primarily affects the speed and magnitude of object movement in the video. Higher values produce more pronounced and faster movement, while lower values make the motion slower and more subtle.

  Range: `1 <= x <= 10`. Default: `5.0`.
</ParamField>

<ParamField type="boolean">
  The enable\_safety\_checker parameter controls whether the safety filter is applied to the generated content. When enabled, it helps filter out potentially harmful or inappropriate content from the video output.

  Default: `true`.
</ParamField>

<ParamField type="boolean">
  Whether to enable fast mode, which will generate videos more quickly but may reduce quality and lower the price.

  Default: `false`.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>

## Example

Here is an example of how to use the Wan 2.1 Image to Video API.

1. Generate a task\_id by sending a POST request to the Wan 2.1 Image to Video API.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/wan-i2v' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "image_url": "https://pub-f964a1c641c04024bce400ad128c8cd6.r2.dev/wan-i2v-input-image.jpg",
    "height": 1280,
    "width": 720,
    "steps": 25,
    "seed": -1,
    "prompt": "A cute panda is walking in the grassland slowly."
}'
```

`Response:`

```js theme={"system"}
{
    "task_id": "{Returned Task ID}"
}
```

2. Use `task_id` to get output videos.

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get videos url in `videos` of response.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id={Returned Task ID}' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "task": {
        "task_id": "{Returned Task ID}",
        "task_type": "WAN_IMG_TO_VIDEO",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 100
    },
    "images": [],
    "videos": [
        {
            "video_url": "{The URL of the generated video}",
            "video_url_ttl": "3600",
            "video_type": "mp4"
        }
    ]
}
```

`Video files:`

<video />


# Wan 2.1 Text to Video
Source: https://novita.ai/docs/api-reference/model-apis-wan-t2v

POST https://api.novita.ai/v3/async/wan-t2v

Accelerated inference for Wan 2.1 14B Text-to-Video, a comprehensive and open suite of video foundation models that pushes the boundaries of video generation. By default, the API will generate a video with 5 seconds.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Optional extra parameters for the request.

  <Expandable title="properties">
    <ParamField type="object">
      Webhook settings. More details can be found at [Webhook Documentation](/api-reference/model-apis-webhook).

      <Expandable title="properties">
        <ParamField type="string">
          The URL of the webhook endpoint. Novita AI will send the task generated outputs to your specified webhook endpoint.
        </ParamField>

        <ParamField type="object">
          By specifying Test Mode, a mock event will be sent to the webhook endpoint.

          <Expandable title="properties">
            <ParamField type="boolean">
              Set to true to enable Test Mode, or false to disable it.

              The default is `false`.
            </ParamField>

            <ParamField type="string">
              Control the data content of the mock event. When set to TASK\_STATUS\_SUCCEED, you'll receive a normal response; when set to TASK\_STATUS\_FAILED, you'll receive an error response.

              Supports: `TASK_STATUS_SUCCEED`, `TASK_STATUS_FAILED`.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Prompt text required to guide the generation.

  Range: `1 <= x <= 2000`.
</ParamField>

<ParamField type="string">
  Negative prompts instruct the model on what elements to avoid generating.

  Range: `0 <= x <= 2000`.
</ParamField>

<ParamField type="integer">
  Width of the output video.

  Supports: `480`, `720`, `832`, `1280`.

  Default: `832`. If the width or height is not specified, the width and the height will be forced to `832` and `480` respectively.
</ParamField>

<ParamField type="integer">
  Height of the output video.

  Supports:

  * (480p) `832` for `width` of `480`
  * (480p) `480` for `width` of `832`
  * (720p) `1280` for `width` of `720`
  * (720p) `720` for `width` of `1280`

  Default: `480`. If the width or height is not specified, the width and the height will be forced to `832` and `480` respectively.
</ParamField>

<ParamField type="object[]">
  LoRA models to be applied to the video generation.

  Currently supports up to **3 LoRAs**.

  <Expandable title="properties">
    <ParamField type="string">
      The path to the LoRA model. You can specify either a LoRA model name from Hugging Face, for example: `Remade-AI/Cyberpunk`; or a model download URL from Civitai, for example: `https://civitai.com/api/download/models/1572591?type=Model&format=SafeTensor`.

      <Warning>
        The LoRA model must be compatible with Wan2.1 14B T2V, otherwise it will not work. Please check compatibility before using it.
      </Warning>
    </ParamField>

    <ParamField type="number">
      The scale value of lora. The larger the value, the more biased the effect is towards lora.

      Range: `0 <= x <= 4.0`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="integer">
  A seed is a number generates noise, which, makes generation deterministic. Using the same seed and set of parameters will produce identical content each time.

  Range: `-1 <= x <= 9999999999`. Default: `-1`.
</ParamField>

<ParamField type="integer">
  The number of inference steps.

  Range: `1 <= x <= 40`. Default: `30`.
</ParamField>

<ParamField type="float">
  Guidance scale parameter controls how closely the generated content follows the prompt.

  Range: `0 <= x <= 10`. Default: `5.0`.
</ParamField>

<ParamField type="float">
  The flow\_shift parameter primarily affects the speed and magnitude of object movement in the video. Higher values produce more pronounced and faster movement, while lower values make the motion slower and more subtle.

  Range: `1 <= x <= 10`. Default: `5.0`.
</ParamField>

<ParamField type="boolean">
  The enable\_safety\_checker parameter controls whether the safety filter is applied to the generated content. When enabled, it helps filter out potentially harmful or inappropriate content from the video output.

  Default: `true`.
</ParamField>

<ParamField type="boolean">
  Whether to enable fast mode, which will generate videos more quickly but may reduce quality and lower the price.

  Default: `false`.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>

## Example

Here is an example of how to use the Wan 2.1 Text to Video API.

1. Generate a task\_id by sending a POST request to the Wan 2.1 Text to Video API.

`Request:`

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/wan-t2v' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
    "height": 1280,
    "width": 720,
    "seed": -1,
    "prompt": "3D animation of a small, round, fluffy creature with big, expressive eyes explores a vibrant, enchanted forest. The creature, a whimsical blend of a rabbit and a squirrel, has soft blue fur and a bushy, striped tail. It hops along a sparkling stream, its eyes wide with wonder. The forest is alive with magical elements: flowers that glow and change colors, trees with leaves in shades of purple and silver, and small floating lights that resemble fireflies. The creature stops to interact playfully with a group of tiny, fairy-like beings dancing around a mushroom ring. The creature looks up in awe at a large, glowing tree that seems to be the heart of the forest."
}'
```

`Response:`

```js theme={"system"}
{
    "task_id": "{Returned Task ID}"
}
```

2. Use `task_id` to get output videos.

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get videos url in `videos` of response.

`Request:`

```bash theme={"system"}
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id={Returned Task ID}' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js theme={"system"}
{
    "task": {
        "task_id": "{Returned Task ID}",
        "task_type": "WAN_TXT_TO_VIDEO",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 100
    },
    "images": [],
    "videos": [
        {
            "video_url": "{The URL of the generated video}",
            "video_url_ttl": "3600",
            "video_type": "mp4"
        }
    ]
}
```

`Video files:`

<video />


# Wan 2.2 Image to Video
Source: https://novita.ai/docs/api-reference/model-apis-wan2.2-i2v

POST https://api.novita.ai/v3/async/wan-2.2-i2v

Wan 2.2 Professional Image-to-Video model generates a silent video based on the initial frame image and text. It offers significant improvements in visual detail and motion stability.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Basic input information, such as prompts.

  <Expandable title="properties">
    <ParamField type="string">
      Text prompt. Supports both English and Chinese, with a maximum length of 800 characters, and any excess will be automatically truncated.

      Example value: A small cat running on the grass.
    </ParamField>

    <ParamField type="string">
      Negative prompt, used to describe content that should be avoided in the video, allowing for restrictions on the video content.

      Supports both English and Chinese, with a maximum length of 500 characters. Any excess will be automatically truncated.

      Example value: Low resolution, errors, worst quality, low quality, incomplete, extra fingers, disproportionate, etc.
    </ParamField>

    <ParamField type="string">
      The URL of the initial frame image used for video generation.

      The URL must be publicly accessible and support HTTP or HTTPS protocols.

      Image restrictions:

      * Image formats: JPEG, JPG, PNG (no support for transparency), BMP, WEBP.
      * Image resolution: The width and height of the image should be within the range of \[360, 2000] pixels.
      * File size: No more than 10MB.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Video processing parameters, such as specifying the output video resolution and duration.

  <Expandable title="properties">
    <ParamField type="string">
      The resolution tier of the generated video. <br />
      Options: `480P`, `720P`, `1080P`
    </ParamField>

    <ParamField type="integer">
      The duration of the generated video.

      * `480P` and `720P` resolutions, the duration can be either `5` or `8` seconds.
      * `1080P` resolution, the duration is fixed at 5 seconds.

      Default value: `5`.
    </ParamField>

    <ParamField type="bool">
      Whether to enable intelligent prompt rewriting. When enabled, a large model is used to intelligently rewrite the input prompt. This significantly improves the generation effect for shorter prompts but increases processing time.

      * `true`: Default value, enable intelligent rewriting.
      * `false`: Do not enable intelligent rewriting.

      Example value: true.
    </ParamField>

    <ParamField type="integer">
      Random seed, used to control the randomness of the model's generated content. The value range is `[0, 2147483647]`.

      If not provided, the algorithm automatically generates a random number as the seed. To maintain relatively stable generated content, you can use the same seed parameter value.

      Example value: 12345.
    </ParamField>

    <ParamField type="array">
      1080P is not supported. List of LoRAs to apply (max 3).

      <Expandable title="properties">
        <ParamField type="string">
          Path to the LoRA model. <br />
          Example: `ostris/wan22_i2v_14b_orbit_shot_lora`.
        </ParamField>

        <ParamField type="float">
          Scale of the LoRA model

          Value range: 0.0 \~ 4.0
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Wan 2.2 Text to Video
Source: https://novita.ai/docs/api-reference/model-apis-wan2.2-t2v

POST https://api.novita.ai/v3/async/wan-2.2-t2v

Wan 2.2 Professional Text-to-Video model can generate high-quality video content based on text descriptions. Compared to previous models, it offers significant improvements in visual detail and motion stability, and can produce videos with durations of 5 seconds and 8 seconds.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Basic input information, such as prompts.

  <Expandable title="properties">
    <ParamField type="string">
      Text prompt. Supports both English and Chinese, with a maximum length of 800 characters, and any excess will be automatically truncated.

      Example value: A small cat running under the moonlight.
    </ParamField>

    <ParamField type="string">
      Negative prompt, used to describe content that should be avoided in the video, allowing for restrictions on the video content.

      Supports both English and Chinese, with a maximum length of 500 characters. Any excess will be automatically truncated.

      Example value: Low resolution, errors, worst quality, low quality, incomplete, extra fingers, disproportionate, etc.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Video processing parameters.

  <Expandable title="properties">
    <ParamField type="string">
      Supports resolutions for 480P, 720P, and 1080P.
      Used to specify the video resolution in the format of width\*height. The supported resolutions for different models are as follows:

      **480P tier**: Available video resolutions and their corresponding aspect ratios are:

      * `832*480`: 16:9.
      * `480*832`: 9:16.
      * `624*624`: 1:1.

      **720P tier**: Available video resolutions and their corresponding aspect ratios are:

      * `1280*720`: 16:9.
      * `720*1280`: 9:16.

      **1080P tier**: Available video resolutions and their corresponding aspect ratios are:

      * `1920*1080`: 16:9.
      * `1080*1920`: 9:16.
      * `1440*1440`: 1:1.
      * `1632*1248`: 4:3.
      * `1248*1632`: 3:4.

      <Warning>
        **Common misconceptions about the size parameter**: The size must be set to the specific values of the target resolution (e.g., `1280*720`), not the aspect ratio (e.g., `1:1`) or resolution tier name (e.g., `480P` or `720P`).
      </Warning>
    </ParamField>

    <ParamField type="integer">
      The duration of the generated video.

      * `480P` and `720P` resolutions, the duration can be either `5` or `8` seconds.
      * `1080P` resolution, the duration is fixed at 5 seconds.

      Default value: `5`.
    </ParamField>

    <ParamField type="bool">
      Whether to enable intelligent prompt rewriting. When enabled, a large model is used to intelligently rewrite the input prompt. This significantly improves the generation effect for shorter prompts but increases processing time.

      * `true`: Default value, enable intelligent rewriting.
      * `false`: Do not enable intelligent rewriting.
    </ParamField>

    <ParamField type="integer">
      Random seed, used to control the randomness of the model's generated content. The value range is `[0, 2147483647]`.

      If not provided, the algorithm automatically generates a random number as the seed. To maintain relatively stable generated content, you can use the same seed parameter value.
    </ParamField>

    <ParamField type="array">
      1080P is not supported. List of LoRAs to apply (max 3).

      <Expandable title="properties">
        <ParamField type="string">
          Path to the LoRA model. <br />
          Example: `Cseti/wan2.2-14B-Kinestasis_concept-lora-v1`.
        </ParamField>

        <ParamField type="float">
          Scale of the LoRA model

          Value range: 0.0 \~ 4.0
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Wan 2.5 Preview Image to Video
Source: https://novita.ai/docs/api-reference/model-apis-wan2.5-i2v

POST https://api.novita.ai/v3/async/wan-2.5-i2v-preview

Wan 2.5 Preview Image-to-Video model supports generating videos of 5 or 10 seconds based on the initial frame image and text. New audio capabilities: supports automatic dubbing, or you can provide a custom audio file.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Basic input information, such as prompts.

  <Expandable title="properties">
    <ParamField type="string">
      Text prompt. Supports both English and Chinese, with a maximum length of 2000 characters, and any excess will be automatically truncated.

      Example value: A small cat running on the grass.
    </ParamField>

    <ParamField type="string">
      Negative prompt, used to describe content that should be avoided in the video, allowing for restrictions on the video content.

      Supports both English and Chinese, with a maximum length of 500 characters. Any excess will be automatically truncated.

      Example value: Low resolution, errors, worst quality, low quality, incomplete, extra fingers, disproportionate, etc.
    </ParamField>

    <ParamField type="string">
      The URL of the initial frame image used for video generation.

      The URL must be publicly accessible and support HTTP or HTTPS protocols.

      Image restrictions:

      * Image formats: JPEG, JPG, PNG (no support for transparency), BMP, WEBP.
      * Image resolution: The width and height of the image should be within the range of \[360, 2000] pixels.
      * File size: No more than 10MB.
    </ParamField>

    <ParamField type="string">
      URL of the audio file that the model will use to generate the video. See audio settings for usage instructions.

      Audio restrictions:

      * Format: wav, mp3.
      * Duration: 3-30s.
      * File size: No more than 15MB.

      Overflow handling: If the audio length exceeds the duration value (5 seconds or 10 seconds), the first 5 seconds or 10 seconds will be automatically truncated, and the rest will be discarded. If the audio length is shorter than the video duration, the part beyond the audio length will be silent video. For example, if the audio is 3 seconds and the video duration is 5 seconds, the output video will have sound for the first 3 seconds and be silent for the last 2 seconds.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Video processing parameters, such as specifying the output video resolution and duration.

  <Expandable title="properties">
    <ParamField type="string">
      The resolution tier of the generated video. <br />
      Options: `480P`, `720P`, `1080P`. Default value: `1080P`.
    </ParamField>

    <ParamField type="integer">
      Specifies the duration of the generated video. Supported values: `5` or `10` seconds.

      Default value: `5`.
    </ParamField>

    <ParamField type="bool">
      Whether to enable intelligent prompt rewriting. When enabled, a large model is used to intelligently rewrite the input prompt. This significantly improves the generation effect for shorter prompts but increases processing time.

      * `true`: Default value, enable intelligent rewriting.
      * `false`: Do not enable intelligent rewriting.

      Example value: true.
    </ParamField>

    <ParamField type="boolean">
      Used to control whether to add audio.

      Parameter priority: audio\_url > audio, only takes effect when audio\_url is empty.

      * `true`: Default value, automatically add audio to the video.
      * `false`: Do not add audio, output silent video.

      Example value: true.
    </ParamField>

    <ParamField type="integer">
      Random seed, used to control the randomness of the model's generated content. The value range is `[0, 2147483647]`.

      If not provided, the algorithm automatically generates a random number as the seed. To maintain relatively stable generated content, you can use the same seed parameter value.

      Example value: 12345.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Wan 2.5 Preview Text to Video
Source: https://novita.ai/docs/api-reference/model-apis-wan2.5-t2v

POST https://api.novita.ai/v3/async/wan-2.5-t2v-preview

Wan 2.5 Preview Text-to-Video model can generate high-quality video content based on text descriptions, and can produce videos with durations of 5 seconds and 10 seconds. New audio capabilities: supports automatic dubbing, or you can provide a custom audio file.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Basic input information, such as prompts.

  <Expandable title="properties">
    <ParamField type="string">
      Text prompt. Supports both English and Chinese, with a maximum length of 2000 characters, and any excess will be automatically truncated.

      Example value: A small cat running under the moonlight.
    </ParamField>

    <ParamField type="string">
      Negative prompt, used to describe content that should be avoided in the video, allowing for restrictions on the video content.

      Supports both English and Chinese, with a maximum length of 500 characters. Any excess will be automatically truncated.

      Example value: Low resolution, errors, worst quality, low quality, incomplete, extra fingers, disproportionate, etc.
    </ParamField>

    <ParamField type="string">
      URL of the audio file that the model will use to generate the video. See audio settings for usage instructions.

      Audio restrictions:

      * Format: wav, mp3.
      * Duration: 3-30s.
      * File size: No more than 15MB.

      Overflow handling: If the audio length exceeds the duration value (5 seconds or 10 seconds), the first 5 seconds or 10 seconds will be automatically truncated, and the rest will be discarded. If the audio length is shorter than the video duration, the part beyond the audio length will be silent video. For example, if the audio is 3 seconds and the video duration is 5 seconds, the output video will have sound for the first 3 seconds and be silent for the last 2 seconds.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Video processing parameters.

  <Expandable title="properties">
    <ParamField type="string">
      Supports resolutions for 480P, 720P, and 1080P. Default value: `1920*1080` (1080P).
      Used to specify the video resolution in the format of width\*height. The supported resolutions for different models are as follows:

      **480P tier**: Available video resolutions and their corresponding aspect ratios are:

      * `832*480`: 16:9.
      * `480*832`: 9:16.
      * `624*624`: 1:1.

      **720P tier**: Available video resolutions and their corresponding aspect ratios are:

      * `1280*720`: 16:9.
      * `720*1280`: 9:16.
      * `960*960`: 1:1.
      * `1088*832`: 4:3.
      * `832*1088`: 3:4.

      **1080P tier**: Available video resolutions and their corresponding aspect ratios are:

      * `1920*1080`: 16:9.
      * `1080*1920`: 9:16.
      * `1440*1440`: 1:1.
      * `1632*1248`: 4:3.
      * `1248*1632`: 3:4.

      <Warning>
        **Common misconceptions about the size parameter**: The size must be set to the specific values of the target resolution (e.g., `1280*720`), not the aspect ratio (e.g., `1:1`) or resolution tier name (e.g., `480P` or `720P`).
      </Warning>
    </ParamField>

    <ParamField type="integer">
      Specifies the duration of the generated video. Supported values: `5` or `10` seconds.

      Default value: `5`.
    </ParamField>

    <ParamField type="bool">
      Whether to enable intelligent prompt rewriting. When enabled, a large model is used to intelligently rewrite the input prompt. This significantly improves the generation effect for shorter prompts but increases processing time.

      * `true`: Default value, enable intelligent rewriting.
      * `false`: Do not enable intelligent rewriting.
    </ParamField>

    <ParamField type="boolean">
      Used to control whether to add audio.

      Parameter priority: audio\_url > audio, only takes effect when audio\_url is empty.

      * `true`: Default value, automatically add audio to the video.
      * `false`: Do not add audio, output silent video.

      Example value: true.
    </ParamField>

    <ParamField type="integer">
      Random seed, used to control the randomness of the model's generated content. The value range is `[0, 2147483647]`.

      If not provided, the algorithm automatically generates a random number as the seed. To maintain relatively stable generated content, you can use the same seed parameter value.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Wan 2.6 Image to Video
Source: https://novita.ai/docs/api-reference/model-apis-wan2.6-i2v

POST https://api.novita.ai/v3/async/wan2.6-i2v

AI-based image-to-video service. Generate high-quality video content from input images and text prompts, providing professional video generation capabilities: ready-to-use REST inference API, best performance, zero cold start, and affordable pricing.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Text prompt that describes the expected elements and visual characteristics in the generated video. Supports both Chinese and English. Each Chinese character/letter counts as one character. The excess part will be automatically truncated.

      Length limit: 0 - 2000
    </ParamField>

    <ParamField type="string">
      URL of the input image or Base64-encoded data. Supports HTTP or HTTPS protocol. For local files, you can upload to obtain a temporary URL. Image limitations: formats: JPEG, JPG, PNG (transparent channels not supported), BMP, WEBP; resolution: width and height range \[360, 2000] (pixels); file size: no more than 10MB. Input image notes: 1. Use a public URL - HTTP or HTTPS supported; for local files, upload to obtain a temporary URL, e.g. [https://cdn.translate.alibaba.com/r/wanx-demo-1.png](https://cdn.translate.alibaba.com/r/wanx-demo-1.png). 2. Provide the Base64-encoded image string - format: data:;base64,; e.g. data:image/png;base64,GDU7MtCZEbTbmRZ... (string truncated for display). See documentation for more.
    </ParamField>

    <ParamField type="string">
      Name of video effect template. If not filled, no effects are used. Different templates support different special effects. Please query the template list before calling to avoid failure.
    </ParamField>

    <ParamField type="string">
      Audio file URL, which the model will use to generate the video. Supports HTTP or HTTPS protocol. Audio limitations: format wav/mp3; duration 3–30s; file size up to 15MB. If the audio is longer than duration (5s or 10s), only the first 5 or 10 seconds are used, the rest is discarded. If the audio is shorter than the video, the excess part of the video will be silent. For example, for a 3s audio and a 5s video, the first 3 seconds have sound, the last 2 seconds are silent.
    </ParamField>

    <ParamField type="string">
      Negative prompt: describes what content should NOT appear in the video. Supports both Chinese and English, up to 500 characters. Excess content is truncated.

      Length limit: 0 - 500
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="integer">
      Random seed. Range is \[0, 2147483647]. If not specified, the system generates a random seed. To improve reproducibility, it is recommended to set a fixed seed. Note: since generation is probabilistic, even with the same seed, results may differ.

      Value range: \[0, 2147483647]
    </ParamField>

    <ParamField type="boolean">
      Controls whether to add audio. Priority: audio\_url > audio. Only works when audio\_url is empty, see audio settings. true: (default) add audio automatically; false: no audio track in the video.
    </ParamField>

    <ParamField type="integer">
      Duration (in seconds) of the generated video. Duration affects cost; please check model pricing before use.

      Optional values: `5`, `10`, `15`
    </ParamField>

    <ParamField type="string">
      Video generation mode. single: single shot; multi: multi-shot.

      Optional values: `single`, `multi`
    </ParamField>

    <ParamField type="boolean">
      Add watermark at lower-right corner of the video (text fixed as "AI Generated"). false: (default) no watermark; true: watermark added.
    </ParamField>

    <ParamField type="string">
      Target resolution for the generated video. Supports 720P and 1080P.

      Optional values: `720P`, `1080P`
    </ParamField>

    <ParamField type="boolean">
      Whether to enable intelligent prompt rewriting. If enabled, a large language model rewrites the prompt for improved results (especially effective for short prompts, at the cost of additional time). true: (default) enabled; false: not enabled.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Wan 2.6 Text to Video
Source: https://novita.ai/docs/api-reference/model-apis-wan2.6-t2v

POST https://api.novita.ai/v3/async/wan2.6-t2v

AI-powered text-to-video service. Generate high-quality video content from text prompts, offering professional video generation capabilities: ready-to-use REST inference API, best-in-class performance, no cold start, and affordable pricing.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Text prompt describing the desired elements and visual features in the generated video. Supported in both Chinese and English, each Chinese character/letter counts as one character; excess will be automatically truncated.

      Length limit: 0 - 2000
    </ParamField>

    <ParamField type="string">
      Audio file URL to be used by the model to generate video. Supports HTTP or HTTPS. Audio limits: wav/mp3 format; duration 3\~30s; file size ≤ 15MB. Exceeding duration: if audio length exceeds duration value (5s or 10s), only the first 5s or 10s are kept, rest is discarded. If audio is shorter than video duration, the excess part of the video is silent. For example, if audio is 3s and video duration is 5s, the first 3s of the output video has sound, the last 2s is silent.
    </ParamField>

    <ParamField type="string">
      Negative prompt, describing content that should not appear in the video. Allows limiting the video content. Supported in Chinese and English, no more than 500 characters; excess will be automatically truncated.

      Length limit: 0 - 500
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="integer">
      Random seed. Range: \[0, 2147483647]. If not specified, the system generates a random seed. For better reproducibility, it is recommended to specify a seed value. Note: Due to probabilistic nature of the model, results might not be exactly identical even with the same seed.

      Value range: \[0, 2147483647]
    </ParamField>

    <ParamField type="string">
      Specify the resolution of the generated video in format width*height. Supports 720P options (1280*720/720*1280/960*960/1088*832/832*1088) and 1080P options (1920*1080/1080*1920/1440*1440/1632*1248/1248\*1632).

      Optional values: `1280*720`, `720*1280`, `960*960`, `1088*832`, `832*1088`, `1920*1080`, `1080*1920`, `1440*1440`, `1632*1248`, `1248*1632`
    </ParamField>

    <ParamField type="boolean">
      Whether to add audio. Parameter priority: audio\_url > audio. This parameter only works when audio\_url is empty. true: (default) automatically add audio to video; false: no audio, resulting in a silent video.
    </ParamField>

    <ParamField type="integer">
      Duration of the generated video in seconds. Options: 5, 10, 15; default is 5. Duration directly influences cost: cost = unit price (based on resolution) x duration (seconds). Please confirm model pricing before calling.

      Optional values: `5`, `10`, `15`
    </ParamField>

    <ParamField type="string">
      Video generation mode. 'single' for single-shot generation; 'multi' for multi-shot generation.

      Optional values: `single`, `multi`
    </ParamField>

    <ParamField type="boolean">
      Whether to add a watermark. The watermark will be at the bottom right of the video, labeled as "AI Generated". false: (default) no watermark; true: add watermark.
    </ParamField>

    <ParamField type="boolean">
      Whether to enable prompt intelligent rewriting. If enabled, a large model is used to smartly rewrite the input prompt, which can significantly improve results for short prompts but may increase processing time. true: (default) enable smart rewriting; false: do not enable.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Wan 2.6 Reference Video
Source: https://novita.ai/docs/api-reference/model-apis-wan2.6-v2v

POST https://api.novita.ai/v3/async/wan2.6-v2v

AI-based reference video service that supports generation of high-quality videos from text prompts, providing professional video generation capabilities: plug-and-play REST inference API, optimal performance, no cold start, and affordable pricing.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Text prompt describing the elements and visual features expected in the generated video. Supports both Chinese and English; each Chinese character/letter counts as one character; any excess will be automatically truncated.

      Length limit: 0 - 2000
    </ParamField>

    <ParamField type="string">
      URL of the audio file to be used for video generation by the model. Supports HTTP or HTTPS. Audio requirements: wav or mp3 format; duration 3 to 30 seconds; file size not exceeding 15MB. If the audio length exceeds the duration value (5s or 10s), only the first 5 or 10 seconds will be used, and the rest will be discarded. If the audio length is less than the video duration, the overflow part will be silent. For example, if the audio is 3 seconds and the video duration is 5 seconds, the first 3 seconds of the video will have sound and the last 2 seconds will be silent.
    </ParamField>

    <ParamField type="string">
      Negative prompt describing unwanted content in the video scene, which can restrict video visuals. Supports both Chinese and English, up to 500 characters; excess will be automatically truncated.

      Length limit: 0 - 500
    </ParamField>

    <ParamField type="array">
      Reference videos are indexed as characterx according to their order. For example, if there are two reference videos, the prompt should specify character1 sings by the road, character2 dances nearby. For a single reference video, still use character1.

      Array length: 1 - 3
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="integer">
      Random seed. The range is \[0, 2147483647]. If not specified, the system generates a random seed automatically. To improve reproducibility, it is recommended to fix the seed value. Note that results may not be completely deterministic even with the same seed.

      Value range: \[0, 2147483647]
    </ParamField>

    <ParamField type="string">
      Specify the resolution of the generated video in the format width*height. Supported 720P levels: 1280*720/720*1280/960*960/1088*832/832*1088; 1080P levels: 1920*1080/1080*1920/1440*1440/1632*1248/1248\*1632.

      Optional values: `1280*720`, `720*1280`, `960*960`, `1088*832`, `832*1088`, `1920*1080`, `1080*1920`, `1440*1440`, `1632*1248`, `1248*1632`
    </ParamField>

    <ParamField type="boolean">
      Whether to add audio. Parameter priority: audio\_url > audio; only effective when audio\_url is empty. true (default): the video will be generated with audio; false: the video will be silent.
    </ParamField>

    <ParamField type="integer">
      Duration of the generated video in seconds. Acceptable values are 5 or 10, default is 5. Duration directly affects cost: cost = unit price (based on resolution) × duration (seconds). Please check model pricing before using.

      Optional values: `5`, `10`
    </ParamField>

    <ParamField type="string">
      Video generation mode. 'single': single-shot generation; 'multi': multi-shot generation.

      Optional values: `single`, `multi`
    </ParamField>

    <ParamField type="boolean">
      Whether to add a watermark at the bottom right corner of the video. The watermark text is fixed as 'AI Generated.' false (default): no watermark; true: add watermark.
    </ParamField>

    <ParamField type="boolean">
      Enable prompt smart rewriting. If enabled, the input prompt will be intelligently rewritten by a large model. This can significantly improve the effect for shorter prompts, but will increase latency. true (default): enable smart rewriting; false: do not enable.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Webhook
Source: https://novita.ai/docs/api-reference/model-apis-webhook



**For the asynchronous V3 APIs, in addition to polling the [Task Result API](/api-reference/model-apis-task-result), you can now also listen for the `ASYNC_TASK_RESULT` event on your webhook endpoint.**

## Get Started

### Enable Webhook in Request

For the asynchronous V3 APIs that support webhooks, the webhook parameters are provided in the `extra.webhook` field. (For more details, please refer to the individual documentation pages for each API.) For example:

```js theme={"system"}
{
    "extra": {
        "webhook": {
            "url": "https://your-webhook-endpoint-url"
        }
        //...
    },
    // ...
}
```

When the task is finished, Novita AI will send the `ASYNC_TASK_RESULT` event to your webhook endpoint. For example:

```js theme={"system"}
// The webhook event content with API /v3/async/txt2image.
{
  "event_type": "ASYNC_TASK_RESULT",
  "payload": {
    "task": {
      "eta": 0,
      "progress_percent": 0,
      "reason": "",
      "status": "TASK_STATUS_SUCCEED",
      "task_id": "f6aec953-2e81-4e8b-938e-2ceab54d6df9",
      "task_type": "TXT_TO_IMG"
    },
    "extra": {
      "enable_nsfw_detection": false,
      "webhook": {
        "url": "https://your-webhook-endpoint-url"
      }
    },
    "images": [
      {
        "image_type": "jpeg",
        "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/test_data/image_01.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240602%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240602T150041Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=f22b3a2f93587e8f7e80ba88842ddf7d80d6481bbec6f94eedd241bb15718629",
        "image_url_ttl": "3600",
        "nsfw_detection_result": null
      }
    ],
    "videos": [],
    "audios": []
  }
}
```

**The schema of the `payload` fields is exactly the same as the response from the [Task Result API](/api-reference/model-apis-task-result).**

### Use Test Mode to Test Your Integration

You can test your integration without making actual API calls by enabling `Test Mode`. For example:

```js theme={"system"}
{
    "extra": {
        "webhook": {
            "url": "https://your-webhook-endpoint-url",
            "test_mode": {
                "enabled": true,
                // Set return_task_status to TASK_STATUS_SUCCEED to test the success response.
                // Set return_task_status to TASK_STATUS_FAILED to test the error response.
                "return_task_status": 'TASK_STATUS_SUCCEED'
            }
        },
        //...
    },
    // ...
}
```

Your webhook endpoint will receive **a simulated mock event**, which you can use to ensure that your integration works correctly.

### Retry Policy

Novita AI will retry up to five times if it fails to send the event to your webhook endpoint. This includes the following situations:

* The request to your endpoint times out (currently set to 5 seconds).
* Your endpoint returns a non-2xx status code.

## Best Practices

1. Your webhook endpoint must quickly return a successful status code **2xx** before executing any complex logic that could cause a timeout.
2. After receiving a webhook event, filter out any events other than `ASYNC_TASK_RESULT` to continue with your logic.
3. Before releasing features that rely on the webhook event, use `Test Mode` to thoroughly test your logic.
4. Use HTTPS for your webhook endpoint.


# Z Image Turbo
Source: https://novita.ai/docs/api-reference/model-apis-z-image-turbo

POST https://api.novita.ai/v3/async/z-image-turbo

Z-Image Turbo is a high-speed image generation model that supports rapid generation of high-quality images based on text prompts.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="integer">
  Random seed for generation. -1 means using a random seed. Range: -1 to 2147483647

  Value range: \[-1, 2147483647]
</ParamField>

<ParamField type="string">
  Pixel dimensions of the generated image (width\*height). Each dimension ranges from 256 to 1536 pixels
</ParamField>

<ParamField type="string">
  Positive prompt for generation
</ParamField>

<ParamField type="boolean">
  If enabled, the output will be encoded as a BASE64 string instead of a URL. This property is only available via API
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Z Image Turbo LoRA
Source: https://novita.ai/docs/api-reference/model-apis-z-image-turbo-lora

POST https://api.novita.ai/v3/async/z-image-turbo-lora

Z-Image Turbo LoRA is a high-speed image generation model that supports rapid generation of high-quality images based on text prompts, with support for applying custom LoRA weights.

<Tip>
  This is an **asynchronous** API; only the **task\_id** will be returned. You should use the **task\_id** to request the [**Task Result API**](/api-reference/model-apis-task-result) to retrieve the video generation results.
</Tip>

## Request Headers

<ParamField type="string">
  Supports: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="integer">
  Random seed for generation. -1 means using a random seed

  Value range: \[-1, 2147483647]
</ParamField>

<ParamField type="string">
  Pixel dimensions of the generated image (width\*height)
</ParamField>

<ParamField type="array">
  List of LoRAs to apply (maximum 3)

  Array length: 0 - 3

  <Expandable title="properties">
    <ParamField type="string">
      URL or path to the LoRA weights
    </ParamField>

    <ParamField type="number">
      Scale factor for the LoRA weights. Used to scale the LoRA weights before merging with the base model

      Value range: \[0, 4]
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Positive prompt for generation
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Use the task\_id to request the [Task Result API](/api-reference/model-apis-task-result) to retrieve the generated outputs.
</ResponseField>


# Unified Video Generation API
Source: https://novita.ai/docs/api-reference/reference-unified-video-generation

POST https://api.novita.ai/v3/video/create

<UnifiedAPI />


# Create Endpoint
Source: https://novita.ai/docs/api-reference/serverless-create-endpoint

POST https://api.novita.ai/gpu-instance/openapi/v1/endpoint/create

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="object">
  Endpoint configuration details.

  <Expandable title="properties">
    <ParamField type="string">
      Endpoint name. String, length limit: 0-220 characters.
    </ParamField>

    <ParamField type="string">
      Application name (appears in the URL). This is a customizable part of the Endpoint URL, defaults to the Endpoint ID if not specified.
    </ParamField>

    <ParamField type="object[]">
      Worker configuration. The valid range can be dynamically obtained via the parameter range API.

      <Expandable title="properties">
        <ParamField type="integer">
          Minimum number of workers.
        </ParamField>

        <ParamField type="integer">
          Maximum number of workers.
        </ParamField>

        <ParamField type="integer">
          Idle timeout (seconds). Unit: seconds.
        </ParamField>

        <ParamField type="integer">
          Maximum concurrency.
        </ParamField>

        <ParamField type="integer">
          Number of GPUs per worker.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object[]">
      HTTP ports. Only one is supported. Supported port range: 1-65535, except for 2222, 2223, and 2224 which are reserved for internal use.

      <Expandable title="properties">
        <ParamField type="string">
          HTTP port.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object[]">
      Auto-scaling policy. The valid range can be dynamically obtained via the parameter range API.

      <Expandable title="properties">
        <ParamField type="string">
          Policy type. Options:

          * `queue`: Queue latency policy, adjusts the number of workers based on the waiting time of requests in the queue.
          * `concurrency`: Queue request policy, automatically adjusts the number of workers based on the number of requests in the queue.
        </ParamField>

        <ParamField type="integer">
          The meaning of value depends on the type:

          * If type = queue, value is the queue waiting time in seconds.
          * If type = concurrency, value is the maximum number of requests in the queue.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object[]">
      Image information.

      <Expandable title="properties">
        <ParamField type="string">
          Image URL. String, length limit: 0-511 characters.
        </ParamField>

        <ParamField type="string">
          Private image credential ID (not required for public images or platform user images). String, length limit: 0-255 characters.
        </ParamField>

        <ParamField type="string">
          Container startup command. String, length limit: 0-2047 characters.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object[]">
      Product information.

      <Expandable title="properties">
        <ParamField type="string">
          Product ID.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="integer">
      System disk size (GB). Currently, set to a fixed value of 100.
    </ParamField>

    <ParamField type="object[]">
      Storage information (GB).

      <Expandable title="properties">
        <ParamField type="string">
          Storage type. Options:

          * `local`: Local storage.
          * `network`: Network storage.
        </ParamField>

        <ParamField type="integer">
          Local storage size, currently set to a fixed value of 30. Not required for network storage.
        </ParamField>

        <ParamField type="string">
          Network storage ID. Not required for local storage.
        </ParamField>

        <ParamField type="string">
          Mount path. String, length limit: 0-255 characters.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Cluster information. Required when mounting cloud storage, and must match the cluster ID where the cloud storage resides. String, length limit: 0-255 characters.
    </ParamField>

    <ParamField type="object[]">
      Environment variables.

      <Expandable title="properties">
        <ParamField type="string">
          Environment variable name.
        </ParamField>

        <ParamField type="string">
          Environment variable value.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      Health check endpoint.

      <Expandable title="properties">
        <ParamField type="string">
          Path to be checked via HTTP request for health monitoring.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="id" type="string">
  The created Endpoint ID.
</ResponseField>


# Delete Endpoint
Source: https://novita.ai/docs/api-reference/serverless-delete-endpoint

POST https://api.novita.ai/gpu-instance/openapi/v1/endpoint/delete

## Description

After deleting an endpoint, all worker processes associated with this endpoint will be automatically removed. Please proceed with caution.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The ID of the endpoint to delete.
</ParamField>


# Get Endpoint
Source: https://novita.ai/docs/api-reference/serverless-get-endpoint

GET https://api.novita.ai/gpu-instance/openapi/v1/endpoint

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<ParamField type="string">
  Endpoint ID.
</ParamField>

## Response

<ResponseField name="endpoint" type="object">
  Endpoint information.

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Endpoint ID.
    </ResponseField>

    <ResponseField name="name" type="string">
      Endpoint name.
    </ResponseField>

    <ResponseField name="appName" type="string">
      Application name.
    </ResponseField>

    <ResponseField name="state" type="object">
      Endpoint status.

      <Expandable title="properties">
        <ResponseField name="state" type="string">
          Endpoint status. When the value is `serving`, the endpoint is available for service.
        </ResponseField>

        <ResponseField name="error" type="string">
          Error code when the endpoint is in an abnormal state.
        </ResponseField>

        <ResponseField name="message" type="string">
          Error message when the endpoint is in an abnormal state.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="url" type="string">
      Endpoint URL. You can access your HTTP service via this URL.
    </ResponseField>

    <ResponseField name="workerConfig" type="object">
      Worker configuration for the endpoint.

      <Expandable title="properties">
        <ResponseField name="minNum" type="integer">
          Minimum number of workers.
        </ResponseField>

        <ResponseField name="maxNum" type="integer">
          Maximum number of workers.
        </ResponseField>

        <ResponseField name="freeTimeout" type="string">
          Idle timeout, in seconds.
        </ResponseField>

        <ResponseField name="maxConcurrent" type="string">
          Maximum concurrency.
        </ResponseField>

        <ResponseField name="gpuNum" type="integer">
          Number of GPUs per worker.
        </ResponseField>

        <ResponseField name="cudaVersion" type="string">
          CUDA version.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="policy" type="object">
      Auto-scaling policy for the endpoint.

      <Expandable title="properties">
        <ResponseField name="type" type="string">
          Policy type. Options:

          * `queue`: Queue latency policy, adjusts the number of workers based on the waiting time of requests in the queue.
          * `concurrency`: Queue request policy, automatically adjusts the number of workers based on the number of requests in the queue.
        </ResponseField>

        <ResponseField name="value" type="string">
          The meaning of value depends on the type:

          * If type = queue, value is the queue waiting time in seconds.
          * If type = concurrency, value is the maximum number of requests in the queue.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="image" type="object">
      Image configuration for the endpoint.

      <Expandable title="properties">
        <ResponseField name="image" type="string">
          Image URL.
        </ResponseField>

        <ResponseField name="authId" type="string">
          Image repository credential.
        </ResponseField>

        <ResponseField name="command" type="string">
          Container startup command.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="rootfsSize" type="integer">
      System disk size.
    </ResponseField>

    <ResponseField name="volumeMounts" type="object[]">
      Storage configuration for the endpoint.

      <Expandable title="properties">
        <ResponseField name="type" type="string">
          Storage type. Options:

          * `local`: Local storage.
          * `network`: Cloud storage.
        </ResponseField>

        <ResponseField name="id" type="string">
          Cloud storage ID.
        </ResponseField>

        <ResponseField name="size" type="integer">
          Returned when type = local, indicates the size of the local disk.
        </ResponseField>

        <ResponseField name="mountPath" type="string">
          Mount path for the storage.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="envs" type="object[]">
      Environment variables.

      <Expandable title="properties">
        <ResponseField name="key" type="string">
          Environment variable name.
        </ResponseField>

        <ResponseField name="value" type="string">
          Environment variable value.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ports" type="object[]">
      HTTP ports.

      <Expandable title="properties">
        <ResponseField name="port" type="integer">
          HTTP port.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="workers" type="object[]">
      Worker information for the endpoint.

      <Expandable title="properties">
        <ResponseField name="id" type="string">
          Worker ID.
        </ResponseField>

        <ResponseField name="state" type="object">
          Worker status.

          <Expandable title="properties">
            <ResponseField name="state" type="string">
              Worker status. When the value is `running`, the worker is available for service.
            </ResponseField>

            <ResponseField name="error" type="string">
              Error code when the worker is in an abnormal state.
            </ResponseField>

            <ResponseField name="message" type="string">
              Error message when the worker is in an abnormal state.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="log" type="string">
          Log path for the worker.
        </ResponseField>

        <ResponseField name="metrics" type="string">
          Monitoring information for the worker.
        </ResponseField>

        <ResponseField name="healthy" type="boolean">
          Whether the worker is healthy.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="products" type="object[]">
      Product information.

      <Expandable title="properties">
        <ResponseField name="id" type="string">
          Product ID.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="healthy" type="object">
      Health check configuration for the endpoint.

      <Expandable title="properties">
        <ResponseField name="path" type="string">
          Path to be checked via HTTP request for health monitoring.
        </ResponseField>

        <ResponseField name="initialDelay" type="integer">
          Time to wait after startup before starting health checks, in seconds.
        </ResponseField>

        <ResponseField name="period" type="integer">
          Interval between health checks, in seconds.
        </ResponseField>

        <ResponseField name="timeout" type="integer">
          Timeout for health checks, in seconds.
        </ResponseField>

        <ResponseField name="successThreshold" type="integer">
          Number of consecutive successes required to consider the check successful after a previous failure.
        </ResponseField>

        <ResponseField name="failureThreshold" type="integer">
          Number of consecutive failures required to consider the check failed after a previous success.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="clusterID" type="string">
      Cluster ID where the cloud storage resides. Returned when using cloud storage.
    </ResponseField>

    <ResponseField name="log" type="string">
      Log path for the endpoint.
    </ResponseField>
  </Expandable>
</ResponseField>


# List Endpoints
Source: https://novita.ai/docs/api-reference/serverless-list-endpoint

GET https://api.novita.ai/gpu-instance/openapi/v1/endpoints

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Query Parameters

<ParamField type="integer">
  Maximum number of items returned per page.
</ParamField>

<ParamField type="integer">
  Current page number.
</ParamField>

## Response

<ResponseField name="endpoints" type="object[]">
  Endpoint information.

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Endpoint ID.
    </ResponseField>

    <ResponseField name="name" type="string">
      Endpoint name.
    </ResponseField>

    <ResponseField name="appName" type="string">
      Application name.
    </ResponseField>

    <ResponseField name="state" type="object">
      Endpoint status.

      <Expandable title="properties">
        <ResponseField name="state" type="string">
          Endpoint status. When the value is `serving`, the endpoint is available for service.
        </ResponseField>

        <ResponseField name="error" type="string">
          Error code when the endpoint is in an abnormal state.
        </ResponseField>

        <ResponseField name="message" type="string">
          Error message when the endpoint is in an abnormal state.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="url" type="string">
      Endpoint URL. You can access your HTTP service via this URL.
    </ResponseField>

    <ResponseField name="workerConfig" type="object">
      Worker configuration for the endpoint.

      <Expandable title="properties">
        <ResponseField name="minNum" type="integer">
          Minimum number of workers.
        </ResponseField>

        <ResponseField name="maxNum" type="integer">
          Maximum number of workers.
        </ResponseField>

        <ResponseField name="freeTimeout" type="string">
          Idle timeout, in seconds.
        </ResponseField>

        <ResponseField name="maxConcurrent" type="string">
          Maximum concurrency.
        </ResponseField>

        <ResponseField name="gpuNum" type="integer">
          Number of GPUs per worker.
        </ResponseField>

        <ResponseField name="cudaVersion" type="string">
          CUDA version.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="policy" type="object">
      Auto-scaling policy for the endpoint.

      <Expandable title="properties">
        <ResponseField name="type" type="string">
          Policy type. Options:

          * `queue`: Queue latency policy, adjusts the number of workers based on the waiting time of requests in the queue.
          * `concurrency`: Queue request policy, automatically adjusts the number of workers based on the number of requests in the queue.
        </ResponseField>

        <ResponseField name="value" type="string">
          The meaning of value depends on the type:

          * If type = queue, value is the queue waiting time in seconds.
          * If type = concurrency, value is the maximum number of requests in the queue.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="image" type="object">
      Image configuration for the endpoint.

      <Expandable title="properties">
        <ResponseField name="image" type="string">
          Image URL.
        </ResponseField>

        <ResponseField name="authId" type="string">
          Image repository credential.
        </ResponseField>

        <ResponseField name="command" type="string">
          Container startup command.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="rootfsSize" type="integer">
      System disk size.
    </ResponseField>

    <ResponseField name="volumeMounts" type="object[]">
      Storage configuration for the endpoint.

      <Expandable title="properties">
        <ResponseField name="type" type="string">
          Storage type. Options:

          * `local`: Local storage.
          * `network`: Cloud storage.
        </ResponseField>

        <ResponseField name="id" type="string">
          Cloud storage ID. Returned when type = network.
        </ResponseField>

        <ResponseField name="size" type="integer">
          Returned when type = local, indicates the size of the local disk.
        </ResponseField>

        <ResponseField name="mountPath" type="string">
          Mount path for the storage.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="envs" type="object[]">
      Environment variables.

      <Expandable title="properties">
        <ResponseField name="key" type="string">
          Environment variable name.
        </ResponseField>

        <ResponseField name="value" type="string">
          Environment variable value.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ports" type="object[]">
      HTTP ports.

      <Expandable title="properties">
        <ResponseField name="port" type="string">
          HTTP port.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="workers" type="object[]">
      Worker information for the endpoint.

      <Expandable title="properties">
        <ResponseField name="id" type="string">
          Worker ID.
        </ResponseField>

        <ResponseField name="state" type="object">
          Worker status.

          <Expandable title="properties">
            <ResponseField name="state" type="string">
              Worker status. When the value is `running`, the worker is available for service.
            </ResponseField>

            <ResponseField name="error" type="string">
              Error code when the worker is in an abnormal state.
            </ResponseField>

            <ResponseField name="message" type="string">
              Error message when the worker is in an abnormal state.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="log" type="string">
          Log path for the worker.
        </ResponseField>

        <ResponseField name="metrics" type="string">
          Monitoring information for the worker.
        </ResponseField>

        <ResponseField name="healthy" type="boolean">
          Whether the worker is healthy.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="products" type="object[]">
      Product information.

      <Expandable title="properties">
        <ResponseField name="id" type="string">
          Product ID.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="healthy" type="object">
      Health check configuration for the endpoint.

      <Expandable title="properties">
        <ResponseField name="path" type="string">
          Path to be checked via HTTP request for health monitoring.
        </ResponseField>

        <ResponseField name="initialDelay" type="integer">
          Time to wait after startup before starting health checks, in seconds.
        </ResponseField>

        <ResponseField name="period" type="integer">
          Interval between health checks, in seconds.
        </ResponseField>

        <ResponseField name="timeout" type="integer">
          Timeout for health checks, in seconds.
        </ResponseField>

        <ResponseField name="successThreshold" type="integer">
          Number of consecutive successes required to consider the check successful after a previous failure.
        </ResponseField>

        <ResponseField name="failureThreshold" type="integer">
          Number of consecutive failures required to consider the check failed after a previous success.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="clusterID" type="string">
      Cluster ID where the cloud storage resides. Returned when using cloud storage.
    </ResponseField>

    <ResponseField name="log" type="string">
      Log path for the endpoint.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of results.
</ResponseField>


# Get Endpoint Parameter Limit Ranges
Source: https://novita.ai/docs/api-reference/serverless-query-endpoint-limit

GET https://api.novita.ai/gpu-instance/openapi/v1/endpoint/limit

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Response

<ResponseField name="minRootfsSize" type="integer">
  Minimum root filesystem size (GB).
</ResponseField>

<ResponseField name="maxRootfsSize" type="integer">
  Maximum root filesystem size (GB).
</ResponseField>

<ResponseField name="freeRootfsSize" type="integer">
  Free root filesystem size (GB).
</ResponseField>

<ResponseField name="minLocalVolumeSize" type="integer">
  Minimum local volume size (GB).
</ResponseField>

<ResponseField name="maxLocalVolumeSize" type="integer">
  Maximum local volume size (GB).
</ResponseField>

<ResponseField name="freeLocalVolumeSize" type="integer">
  Free local volume size (GB).
</ResponseField>

<ResponseField name="minWorkerNum" type="integer">
  Minimum number of worker nodes.
</ResponseField>

<ResponseField name="maxWorkerNum" type="integer">
  Maximum number of worker nodes.
</ResponseField>

<ResponseField name="minFreeTimeout" type="integer">
  Minimum idle timeout (seconds).
</ResponseField>

<ResponseField name="maxFreeTimeout" type="integer">
  Maximum idle timeout (seconds).
</ResponseField>

<ResponseField name="minConcurrencyNum" type="integer">
  Minimum concurrency.
</ResponseField>

<ResponseField name="maxConcurrencyNum" type="integer">
  Maximum concurrency.
</ResponseField>

<ResponseField name="minQueueWaitTime" type="integer">
  Minimum queue wait time (seconds).
</ResponseField>

<ResponseField name="maxQueueWaitTime" type="integer">
  Maximum queue wait time (seconds).
</ResponseField>

<ResponseField name="minRequestNum" type="integer">
  Minimum number of requests.
</ResponseField>

<ResponseField name="maxRequestNum" type="integer">
  Maximum number of requests.
</ResponseField>

<ResponseField name="minGPUNum" type="integer">
  Minimum number of GPUs.
</ResponseField>

<ResponseField name="maxGPUNum" type="integer">
  Maximum number of GPUs.
</ResponseField>

<ResponseField name="cudaVersionList" type="string[]">
  Supported CUDA version list.
</ResponseField>


# Update Endpoint
Source: https://novita.ai/docs/api-reference/serverless-update-endpoint

POST https://api.novita.ai/gpu-instance/openapi/v1/endpoint/update

## Description

When updating an endpoint, all parameters must be provided in full.

## Request Headers

<ParamField type="string">
  Enum: `application/json`
</ParamField>

<ParamField type="string">
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Request Body

<ParamField type="string">
  The ID of the endpoint to update.
</ParamField>

<ParamField type="string">
  Endpoint name.
</ParamField>

<ParamField type="string">
  Cluster information. Required when mounting cloud storage, and must match the cluster ID where the cloud storage resides. String, length limit: 0-255 characters.
</ParamField>

<ParamField type="object[]">
  Worker configuration. The valid range can be dynamically obtained via the parameter range API.

  <Expandable title="properties">
    <ParamField type="integer">
      Minimum number of workers.
    </ParamField>

    <ParamField type="integer">
      Maximum number of workers.
    </ParamField>

    <ParamField type="integer">
      Idle timeout (seconds). Unit: seconds.
    </ParamField>

    <ParamField type="integer">
      Maximum concurrency.
    </ParamField>

    <ParamField type="integer">
      Number of GPUs per worker.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  HTTP ports. Only one is supported. Supported port range: 1-65535, except for 2222, 2223, and 2224 which are reserved for internal use.

  <Expandable title="properties">
    <ParamField type="string">
      HTTP port.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  Auto-scaling policy. The valid range can be dynamically obtained via the parameter range API.

  <Expandable title="properties">
    <ParamField type="string">
      Policy type. Options:

      * `queue`: Queue latency policy, adjusts the number of workers based on the waiting time of requests in the queue.
      * `concurrency`: Queue request policy, automatically adjusts the number of workers based on the number of requests in the queue.
    </ParamField>

    <ParamField type="integer">
      The meaning of value depends on the type:

      * If type = queue, value is the queue waiting time in seconds.
      * If type = concurrency, value is the maximum number of requests in the queue.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  Image information.

  <Expandable title="properties">
    <ParamField type="string">
      Image URL. String, length limit: 0-511 characters.
    </ParamField>

    <ParamField type="string">
      Private image credential ID (not required for public images or platform user images). String, length limit: 0-255 characters.
    </ParamField>

    <ParamField type="string">
      Container startup command. String, length limit: 0-2047 characters.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  Storage information (GB).

  <Expandable title="properties">
    <ParamField type="string">
      Storage type. Options:

      * `local`: Local storage.
      * `network`: Network storage.
    </ParamField>

    <ParamField type="integer">
      Local storage size, currently set to a fixed value of 30. Not required for network storage.
    </ParamField>

    <ParamField type="string">
      Network storage ID. Not required for local storage.
    </ParamField>

    <ParamField type="string">
      Mount path. String, length limit: 0-255 characters.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  Environment variables.

  <Expandable title="properties">
    <ParamField type="string">
      Environment variable name.
    </ParamField>

    <ParamField type="string">
      Environment variable value.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object[]">
  Health check endpoint path.

  <Expandable title="properties">
    <ParamField type="string">
      Health check path.
    </ParamField>
  </Expandable>
</ParamField>


# September 5, 2025 Product Updates
Source: https://novita.ai/docs/changelog/01-09-25--05-09-25



## **Model APIs Updates**

### **New Features**

* **Optimize the Novita LLM Playground**

  The Novita LLM Playground supports TTFT/TPS performance demonstration.

  Updated time: September 3, 2025

***

## **GPUs Updates**

### **New Features**

* **Prewarm image**

  Prewarming image can shorten the time for instances to pull image and save costs

  Updated time: September 1, 2025


# June 2, 2024
Source: https://novita.ai/docs/changelog/02-06-24



For the asynchronous V3 APIs, to receive the generated outputs, in addition to polling the [Task Result API](/api-reference/model-apis-task-result),
<br />now you can also listen to **"ASYNC\_TASK\_RESULT"** event on your webhook endpoint.

Also, you can test your integration without making actual API calls by enabling Test Mode, which will help you thoroughly test your logic.
<br />More details can be found at: [Webhook](/api-reference/model-apis-webhook).


# June 6, 2025 Product Updates
Source: https://novita.ai/docs/changelog/02-06-25--06-06-25



## **New Features**

* **Recommend GPUs according to model templates**

  Recommend GPUs based on model templates to help developers quickly decide on GPU selection.

  Updated time: June 6, 2025
* **New API Error Code Reference for Model Services**

  To enhance the developer experience, we’ve added a detailed list of API error codes for **image, video, audio, and large language model services** in our Documentation Center. It covers common issues like request validation, format limits, and content compliance, helping you troubleshoot more efficiently.

  Visit the [Documentation](https://novita.ai/docs/api-reference/basic-error-code) Center to learn more.

  Updated time: June 6, 2025


# July 03, 2025 Notice
Source: https://novita.ai/docs/changelog/03-07-25



### **Model Decommissioning Notice**

To continuously enhance platform service efficiency, focus on core product capability upgrades, and deliver more advanced, high-quality, and standardized services, Novita will decommission certain large language models (LLMs) on **July 5, 2025(UTC 0:00)**. **The deprecated models and their corresponding replacements** are listed below:

| **Deprecated Models**            | **Deprecation Date** | **Replacement Models** |
| :------------------------------- | :------------------- | :--------------------- |
| thudm/glm-z1-9b-0414             | 2025-7-5             | qwen/qwen3-4b-fp8      |
| thudm/glm-4-9b-0414              | 2025-7-5             | qwen/qwen3-4b-fp8      |
| thudm/glm-z1-rumination-32b-0414 | 2025-7-5             | qwen/qwen3-32b-fp8     |
| thudm/glm-z1-32b-0414            | 2025-7-5             | qwen/qwen3-30b-a3b-fp8 |


# Nov 3, 2025 Product Updates
Source: https://novita.ai/docs/changelog/03-11-25



**Purpose**

Storage-related costs for Agent Sandbox have continued to increase, and the platform can no longer maintain free storage usage.To ensure sustainable operations and more efficient resource allocation, the Agent Sandbox Storage Billing feature has been launched.

**Billing Scope**

* Storage space used by Sandbox Templates
* Files and data retained when a Sandbox is paused

**Free Period**

A half-month free period is provided until November 17, 2025 (UTC).

During this period, users will not be charged and can check their usage at:

[https://novita.ai/sandbox-console/usage](https://novita.ai/sandbox-console/usage)

**Next Steps**

After the free period, storage billing will take effect. Users will be notified in advance via in-app messages or email.

Updated time: Nov 3, 2025


# August 8, 2025 Notice
Source: https://novita.ai/docs/changelog/04-08-25--08-08-25



## **Model APIs Updates**

### **New Features**

* **New Model Available: Qwen-Image**

  The **Qwen-Image** is a 20B MMDIT model for next-gen text-to-image generation. Especially strong at creating stunning graphic posters with native text.

  Key Highlights:

  * SOTA text rendering — rivals GPT-4o in English, best-in-class for Chinese
  * In-pixel text generation — no overlays, fully integrated
  * Bilingual support, diverse fonts, complex layouts

  Also excels at general image generation — from photorealistic to anime, impressionist to minimalist. A true creative powerhouse.

  Get started now: [Qwen-Image](https://novita.ai/docs/api-reference/model-apis-qwen-txt2img#qwen-image-text-to-image)

  Updated time: August 6, 2025
* **New Model Available: Wan 2.2 Text to Video, Wan 2.2 Image to Video**

  Wan2.2 is the world's first open-source MoE-architecture video generation model with cinematic control. Its Mixture-of-Experts (MoE) architecture scales model capacity without increasing computational requirements.

  Key Highlights:

  * First-of-its-kind MoE Architecture: The first model to apply an MoE framework to video generation, drastically cutting down on resource consumption.
  * 50% More Efficient: Saves approximately 50% of computational resources compared to models of a similar parameter scale.
  * Enhanced Capabilities: Achieves significant improvements in generating complex motion, character interactions, and overall aesthetic quality.

  Get started now: [Wan 2.2 Text to Video](https://novita.ai/docs/api-reference/model-apis-wan2.2-t2v), [Wan 2.2 Image to Video](https://novita.ai/docs/api-reference/model-apis-wan2.2-i2v)

  Updated time: August 8, 2025

***

## **GPUs Updates**

### **New Features**

* **Add region selection when creating an endpoint in Serverless**

  Novita now supports creating endpoints in selected regions.

  Updated time: August 5, 2025


# February 6, 2025
Source: https://novita.ai/docs/changelog/06-02-25



**Announcement: qwen/qwen-2-72b-instruct Model Decommission Notice**

We plan to decommission the **qwen/qwen-2-72b-instruct** model on **February 6 2025, at 23:59 Pacific Standard Time (PST).**

Please make any necessary preparations in advance. Thank you for your understanding and support!


# May 9, 2025 Product Updates
Source: https://novita.ai/docs/changelog/06-05-25--09-05-25



## **Model APIs Updates**

### **New Features**

* **Added filters to the Model Library for easier model selection**

  **Model API now features a newly launched filtering system!** Users can now filter models in the Model Library by **provider, pricing, context length, and model specifications**, enabling faster discovery and more efficient model selection and usage.

  Updated time: May 9, 2025


# September 6, 2024
Source: https://novita.ai/docs/changelog/06-09-24



📢 Video Merge Face API is now available on Novita AI.

You can integrate them via API: [https://novita.ai/api-reference/model-apis-video-merge-face](/api-reference/model-apis-video-merge-face).


# April 7, 2024
Source: https://novita.ai/docs/changelog/07-04-24



Now the LLM Chat API supports seamless integration into your product, offering compatibility with the OpenAI API standard. 🚀
<br />More details: [LLM API Docmentation](/guides/llm-api).


# April 11, 2025 Product Updates
Source: https://novita.ai/docs/changelog/07-04-25--11-04-25



## **New Features**

* **Template Library Added to Console**

  1. We've added a Template Library to the console, featuring templates created by both the official team and the user community.
  2. In addition to deploying and saving templates, users are encouraged to **share templates** they like by copying the link **with a single click**.
  3. To contribute your own templates, simply **set the visibility** to Public when creating one. Public templates will appear in the Template Library, and those that gain popularity may be featured.

  Updated time: April 7, 2025
* **New Model: meta-llama/llama-4-maverick-17b-128e-instruct-fp8**

  Novita has deployed **Llama 4 Maverick 17B Instruct (128E)** , a high-performance multimodal language model developed by Meta using a **Mixture-of-Experts (MoE)** architecture. The model dynamically activates 17 billion parameters per inference from a total of 400 billion parameters, distributed across 128 expert modules. It supports **text and image inputs in 12 languages**, and produces **text and code outputs**. Designed specifically for **vision-language tasks**, the model has been instruction-tuned to handle assistant-style interactions, image reasoning, and a wide range of general multimodal applications.

  Updated time: April 7, 2025
* **New Model: meta-llama/llama-4-scout-17b-16e-instruct**

  Novita has deployed **Llama 4 Scout 17B Instruct (16E)**, a **Mixture-of-Experts (MoE)** language model developed by Meta. The model dynamically activates 17 billion parameters per inference from a total of 109 billion parameters, utilizing 16 expert modules each time. It supports **multimodal inputs** (text and images) and generates **text or code outputs** in **12 languages**. Designed for **intelligent assistant interactions** and **visual reasoning tasks**, It also supports a **10 million-token context window**, and was trained on a **massive 40-trillion-token dataset**.

  Updated time: April 7, 2025

## **Improvements**

* **Improved Instance Status Visibility**

  Two new intermediate statuses—**“Starting”** and **“Stopping”**—have been introduced to provide **more granular visibility** during instance state transitions.

  Updated time: April 10, 2025


# July 11, 2025 Product Updates
Source: https://novita.ai/docs/changelog/07-07-25--11-07-25



## **Model APIs Updates**

### **New Features**

* **MiniMax Speech-02 and MiniMax Voice Cloning Now Available on Novita**

  Novita now supports **MiniMax Speech-02-HD** and **MiniMax Speech-02-Turbo** audio generation models, along with the **MiniMax Voice Cloning** model.

  **MiniMax Speech-02** features powerful generalization capabilities, effortlessly handling speech across 32 languages, various accents, and a wide range of emotional tones. Since its release in May, it has consistently ranked No.1 globally on the Artificial Analysis leaderboard.

  **MiniMax Voice Cloning** is designed for use cases such as IP voice replication and timbre cloning, offering fast and accurate voice reproduction. It supports both mono and stereo voice cloning, enabling quick replication of a target voice from an audio sample.

  Get started now: [**MiniMax Speech-02-HD**](https://novita.ai/docs/api-reference/model-apis-minimax-speech-02-hd)\[[**********; MiniMax Speech-02-Turbo; MiniMax Voice Cloning.**********](https://novita.ai/docs/api-reference/model-apis-minimax-voice-cloning)]\([https://novita.ai/docs/api-reference/model-apis-minimax-speech-02-turbo](https://novita.ai/docs/api-reference/model-apis-minimax-speech-02-turbo))

  Updated time: July 10, 2025
* **GLM-4.1V-9B-Thinking Now Available on Novita**

  As a lightweight model with 9 billion parameters, **GLM-4.1V-9B-Thinking** delivers impressive performance—matching or even surpassing the 72B-parameter Qwen-2.5-VL-72B in 18 out of 28 authoritative benchmark evaluations.

  It excels in image-text understanding, scientific and mathematical reasoning, and video comprehension tasks. The model also supports ultra-high-resolution images up to 4K and accepts inputs with arbitrary aspect ratios.

  Get started now: [**GLM-4.1V-9B-Thinking**](https://novita.ai/models/llm/thudm-glm-4.1v-9b-thinking)**.**

  Updated time: July 10, 2025
* **Kimi-K2-Instruct Now Available on Novita**

  **Kimi K2** is a state-of-the-art Mixture-of-Experts (MoE) language model featuring 32 billion active parameters and 1 trillion total parameters.

  Trained with the Muon optimizer, Kimi K2 delivers exceptional performance in frontier knowledge tasks, reasoning, and coding. It is also carefully optimized for agent capabilities—designed specifically for tool use, advanced reasoning, and autonomous problem solving.

  Get started now: [**Kimi-K2-Instruct**](https://novita.ai/models/llm/thudm-glm-4.1v-9b-thinking)

  Updated time: July 11, 2025

***

## **GPUs Updates**

### **New Features**

* **Instance migration supports migrating system disks**

  Supports instance migration and also supports migrating the system disk. After migration, instance information (such as instance ID, egress IP, etc.) will not change. After migration, the mirroring will be stored in the Novita official mirroring repository. If the system disk is migrated, the system disk data will be packaged into a mirroring and migrated together to the new resource. The new mirroring contains the system disk data and is ready to use immediately.

  Updated time: July 7, 2025
* **GPU Instance metrics**

  Supports real-time monitoring of the following data:

  * CPU Utilization
  * Memory Utilization
  * GPU Utilization
  * Video Memory Utilization
  * System Disk Utilization

  Updated time: July 9, 2025


# December 7, 2024
Source: https://novita.ai/docs/changelog/07-12-24



Llama 3.3 70B is Here!

We're thrilled to announce the launch of Llama 3.3 70B, a model optimized for multilingual dialogue. It delivers exceptional performance, surpassing many open-source and proprietary chat models in industry benchmarks.

Pricing: **\$0.39 per 1M tokens** (input & output).


# September 12, 2025 Product Updates
Source: https://novita.ai/docs/changelog/08-09-25--12-09-25



## **Model APIs Updates**

### **New Features**

* **Wan2.2 I2V and Wan2.2 T2V supported LoRA**

  Wan2.2 I2V and Wan2.2 T2V supported LoRA.

  1080P is not supported. List of LoRAs to apply (max 3).

  Updated time: September 9, 2025


# January 9, 2025
Source: https://novita.ai/docs/changelog/09-01-25



For improved security, **API Keys** will no longer be visible in plaintext after creation. Please make sure to save your key when it's generated, as it cannot be retrieved afterward.


# May 9, 2024
Source: https://novita.ai/docs/changelog/09-05-24



Now Novita AI has released the Text-To-Speech API.

Text-To-Speech API generates realistic speech in various languages
<br />👉 [Text-To-Speech API Docmentation](/api-reference/model-apis-text-to-speech).


# March 14, 2025 Product Updates
Source: https://novita.ai/docs/changelog/10-03-25--14-03-25



## **New Features**

* **Embedding Model-BAAI: BGE-M3 is Added to Model Library**

  Novita supports the `baai/bge-m3` text embedding model. This model is capable of simultaneously achieving three core functionalities: dense retrieval, multi-vector retrieval, and sparse retrieval. Designed to be compatible with over 100 languages, it supports a variety of input formats, ranging from short sentences to long texts of up to 8,192 tokens.

  For detailed usage instructions, please refer to the API documentation: [Model-BAAI: BGE-M3](https://novita.ai/docs/api-reference/model-apis-llm-create-embeddings)

  Updated time: March 13, 2025
* **Login Security: Limit on Incorrect Password Attempts**

  To enhance account security, a login attempt limit has been implemented: Maximum 5 incorrect passwords within 1 hour.

  Updated time: March 11, 2025

## **Improvements**

* **Pricing Update for Wan 2.1 T2V Video Model**

  Optimized pricing strategy for video generation models: The pricing for all resolutions is now standardized at \$0.08 per second.

  Updated time: March 10, 2025


# April 11, 2024
Source: https://novita.ai/docs/changelog/11-04-24



We've recently added more hot LLM models for you, now the supported models include:

* lzlv\_70b ([https://huggingface.co/lizpreciatior/lzlv\\\_70b\\\_fp16\\\_hf](https://huggingface.co/lizpreciatior/lzlv\\_70b\\_fp16\\_hf))

* Nous-Hermes-2-Mixtral-8x7B-DPO ([https://huggingface.co/NousResearch/Nous-Hermes-2-Mixtral-8x7B-DPO](https://huggingface.co/NousResearch/Nous-Hermes-2-Mixtral-8x7B-DPO))

* gryphe/mythomax-l2-13b ([https://huggingface.co/Gryphe/MythoMax-L2-13b](https://huggingface.co/Gryphe/MythoMax-L2-13b))

* nousresearch/nous-hermes-llama2-13b ([https://huggingface.co/NousResearch/Nous-Hermes-Llama2-13b](https://huggingface.co/NousResearch/Nous-Hermes-Llama2-13b))


# August 15, 2025 Product Updates
Source: https://novita.ai/docs/changelog/11-08-25--15-08-25



## **Model APIs Updates**

### **New Features**

* **Batch Inference API for Large Language Models**

  Our Batch Inference API enables asynchronous processing of high-volume inference requests while maintaining full compatibility with the OpenAI API standard. This cost-efficient solution is ideal when immediate results aren't required, offering significantly higher rate limits than online calls while guaranteeing delivery within a reasonable 48-hour window.

  Perfect for:

  • Evaluation and data analysis at scale

  • Large dataset classification

  • Offline document summarization generation

  **Pricing:** Available at 50% off standard model inference API rates.

  Updated time: August 13, 2025
* **New Model Available: Vidu Q1**

  **Vidu Q1** is a multimodal video generation model globally launched by Shengshu Technology in April 2025. It features direct output capability at 1080P resolution and AI sound synchronization functionality. The model achieves state-of-the-art (SOTA) performance in video quality and semantic consistency metrics on VBench-1.0, as well as in commonsense reasoning and physical understanding dimensions on VBench-2.0. Additionally, it ranks first in both anime and realistic style categories on the SuperCLUE text-to-video leaderboard in China.

  Discover the power of Vidu Q1 on Novita by exploring its [text-to-video](https://novita.ai/docs/api-reference/model-apis-vidu-q1-txt2video), [image-to-video](https://novita.ai/docs/api-reference/model-apis-vidu-q1-img2video), [start-end-to-video](https://novita.ai/docs/api-reference/model-apis-vidu-q1-startend2video), and [reference-to-video](https://novita.ai/docs/api-reference/model-apis-vidu-q1-reference2video) generation capabilities—and bring your creative ideas to life.

  Updated time: August 14, 2025
* **New Model Available: Vidu 2.0**

  **Vidu 2.0** is a multimodal video generation model globally launched by Shengshu Technology in January 2025. It can generate a single 4-second video clip at 512P resolution within 10 seconds, delivering more consistent styles and themes, smoother transitions between the first and last frames, and producing four materials in one go—doubling efficiency.

  Discover the efficiency of Vidu 2.0 on this platform by exploring its [image-to-video](https://novita.ai/docs/api-reference/model-apis-vidu-2.0-img2video), [start-end-to-video](https://novita.ai/docs/api-reference/model-apis-vidu-2.0-startend2video), and [reference-to-video](https://novita.ai/docs/api-reference/model-apis-vidu-2.0-reference2video) generation capabilities—and see how effortless video creation can be.

  Updated time: August 14, 2025


# November 11, 2024
Source: https://novita.ai/docs/changelog/11-11-24



Building on our last update, where we brought you unbeatable pricing on Llama 3.1 8B, our team has kept working hard to bring even more savings across our platform!

📉 New Pricing for LLama 3.1 70B Instruct

* Input: **\$0.34/Mtokens** (↓33.3% from \$0.51)
* Output: **\$0.39/Mtokens** (↓47.2% from \$0.74)

These new rates are live on both Novita AI and OpenRouter, where we've secured the #1 spot for competitive pricing.


# May 16, 2025 Product Updates
Source: https://novita.ai/docs/changelog/12-05-25--16-05-25



## **Model APIs Updates**

### **Improvements**

* **Hunyuan Video Fast Now 67% Cheaper**

  We’ve significantly reduced the pricing for the Hunyuan Video Fast model — **now only one-third of the original price**. Enjoy high-quality video generation at a much lower cost.

  Updated time: May 13, 2025

***

## **GPUs Updates**

### **New Features**

* **Compute Capacity Expanded to Cover All Major Continents**

  Our global compute footprint continues to grow. Leveraging a distributed resource pool, we now offer GPU services across all major continents—empowering customers worldwide.

  **New Regions:**

  1. **Middle East:** United Arab Emirates (AS-AE-01)
  2. **Europe:** United Kingdom (EU-GB-01)
  3. **South Asia:** India (AS-IN-01)
  4. **South America:** Brazil (SA-BR-01)

  Updated time: May 13, 2025

### **Improvements**

* **Explore & Instances Interface Enhancements**

  We’ve refined both the Explore and Instances pages to surface more information and streamline interactions:

  1. Display architecture names for H100, H200, and A100 GPU card types
  2. On the Explore page, display the maximum GPUs supported per server as "\[card count] max" and streamline the per-instance GPU selector.
  3. On the Instances page, display the number of GPUs configured for each instance

  Updated time: May 15, 2025


# February 14, 2025
Source: https://novita.ai/docs/changelog/14-02-25



We've introduced a referral program for developers. Refer a friend to Novita, and both of you will receive \$20 in DeepSeek API credits, with a total of up to \$500 in credits available.

For more details, please refer to [Referral Program](https://novita.ai/referral).


# March 14, 2024
Source: https://novita.ai/docs/changelog/14-03-24



We've released novita.ai Javascript SDK version 1.0.35, available at [https://www.npmjs.com/package/novita-sdk/v/1.0.35](https://www.npmjs.com/package/novita-sdk/v/1.0.35).

This version introduces the img2ImgV3 and txt2ImgV3 methods for calling the API v3 txt2img and img2img,
<br />and you can find examples here: [https://github.com/novitalabs/javascript-sdk/blob/main/examples](https://github.com/novitalabs/javascript-sdk/blob/main/examples).


# April 18, 2025 Product Updates
Source: https://novita.ai/docs/changelog/14-04-25--18-04-25



## **New Features**

* **Sign Up with Google, GitHub, or Hugging Face Now Supported**

  Users can now register quickly and securely using their existing **Google**, **GitHub**, or **Hugging Face** accounts—no need to create a new password.

  Updated time: April 17, 2025
* **Rate Limit Display Added for LLM Usage in Console**

  The console now displays **rate limit information** for large language models (LLMs), allowing users to easily view the default request limits for each model and better plan their usage.

  In addition, a new rate limit increase request entry has been added, enabling users to submit requests for higher limits based on specific business needs.

  Updated time: April 17, 2025
* **New Video Model Added: Wan 2.1 I2V**

  The **Wan 2.1 I2V (Image-to-Video)** model is now available on the platform. It enables the generation of continuous video sequences from a single input image.

  This model delivers strong performance in **motion consistency**, **visual stability**, and **detail fidelity**, making it well-suited for **creative content generation**, **virtual character animation**, and related use cases.

  Updated time: April 16, 2025
* **Pricing Update for Video Model Wan 2.1 T2V**

  We’ve introduced a **resolution-based pricing model** for the **Wan 2.1 T2V (Text-to-Video)** model.\
  Users are now charged based on the output video resolution, enabling more flexible and cost-effective usage based on quality requirements.

  Updated time: April 16, 2025
* **Function Calling Now Supported on meta-llama/llama-4-maverick-17b-128e-instruct-fp8**

  The model `meta-llama/llama-4-maverick-17b-128e-instruct-fp8` supports the function call feature. For usage instructions, please refer to the [documentation](https://novita.ai/docs/guides/llm-function-calling).

  Updated time: April 14, 2025
* **Function Calling Now Supported on meta-llama/llama-4-scout-17b-16e-instruct**

  The model `meta-llama/llama-4-scout-17b-16e-instruct` supports the function call feature. For usage instructions, please refer to the [documentation](https://novita.ai/docs/guides/llm-function-calling).

  Updated time: April 14, 2025


# May 14, 2025 Notice
Source: https://novita.ai/docs/changelog/14-05-25



### **Model Decommissioning Notice**

To continuously enhance platform service efficiency, focus on core product capability upgrades, and deliver more advanced, high-quality, and standardized services, Novita will decommission certain large language models (LLMs) on **May 28, 2025(UTC 00:00)** . **The deprecated models and their corresponding replacements** are listed below:

| **Deprecated Models**                    | **Deprecation Date** | **Replacement Models**            |
| :--------------------------------------- | :------------------- | :-------------------------------- |
| jondurbin/airoboros-l2-70b               | 2025-5-28            | sao10k/l3-70b-euryale-v2.1        |
| qwen/qwen3-14b-fp8                       | 2025-5-28            | qwen/qwen3-32b-fp8                |
| qwen/qwen3-0.6b-fp8                      | 2025-5-28            | qwen/qwen3-32b-fp8                |
| qwen/qwen3-1.7b-fp8                      | 2025-5-28            | qwen/qwen3-32b-fp8                |
| meta-llama/llama-3.2-11b-vision-instruct | 2025-5-28            | qwen/qwen2.5-vl-72b-instruct      |
| google/gemma-2-9b-it                     | 2025-5-28            | google/gemma-3-27b-it             |
| meta-llama/llama-3.1-70b-instruct        | 2025-5-28            | meta-llama/llama-3.3-70b-instruct |
| qwen/qwq-32b                             | 2025-5-28            | meta-llama/llama-3.3-70b-instruct |


# July 18, 2025 Product Updates
Source: https://novita.ai/docs/changelog/14-07-25--18-07-25



## **GPUs Updates**

### **New Features**

* **GPU Instance Spot Pricing**

  Advantages of Functional Features:

  1. Greatest Advantage: **Affordable!! The price is generally 50% off the on-demand price**, making it highly price-competitive in the market. For example, the current price of 4090 is \$0.35, while the spot 4090 price is as low as \$0.18, and larger usage volumes may result in greater discounts.
  2. Why is it so cheap? Spot instances are essentially designed to handle idle inventory, so **they may be reclaimed at any time due to resource shortages** (instance termination).
  3. How can we ensure the stability of our customers' business as much as possible while keeping costs low? Our spot billing instances will adopt the following strategies:
     * After creation, it enjoys **a 1-hour grace period**, during which the instance is guaranteed not to be reclaimed
     * Before resource recycling, a notice will be sent **1 hour in advance, and another notice will be sent 5 minutes before instance recycling**. When customers receive the notice, they can back up their data, while we give customers more time to back up their data!

  Updated time: July 18, 2025

***

## **Agent SandBox Updates**

### **New Features**

* **The product page for Agent Sandbox is now live**

  This page provides a concise overview of Agent Sandbox's core features, use cases, pricing model, and helpful documentation, enabling users to quickly get started and explore its powerful capabilities.

  **Agent Sandbox** is a high-performance cloud runtime purpose-built for **AI Agent workloads**, designed to support the full lifecycle of autonomous agents.

  Key features include:

  * **Millisecond-Level Startup**
  * **Secure Isolation**
  * **High Concurrency**

  Explore the [Agent Sandbox](https://novita.ai/sandbox) product page to discover more details!

  Updated time: July 18, 2025


# September 19, 2025 Product Updates
Source: https://novita.ai/docs/changelog/15-09-25--19-09-25



## **Model APIs Updates**

### **New Features**

* **Seedream-4.0 Now Available**

  Seedream is a state-of-the-art (SOTA) multimodal image creation model based on a cutting-edge architecture. It breaks the creative boundaries of traditional text-to-image models by natively supporting text, single-image, and multi-image inputs. Users can freely combine text and images to enable diverse creative approaches within the same model, including multi-image fusion creation with subject consistency, image editing, and batch image generation. This makes image creation more free and controllable.

  Charges are based on the actual number of images generated; no fees will be incurred for failed generation.

  Updated time: September 19, 2025

***

## **Agent SandBox Updates**

### **New Features**

* **Metrics History Available for Paused Sandboxes**

  When a Sandbox is in Paused state, you can now access metrics data from up to 72 hours before the last pause time.  This enhancement allows developers to review and analyze recent activity even after a Sandbox has been paused.

  Updated time: September 18, 2025


# January 16, 2025
Source: https://novita.ai/docs/changelog/16-01-25



We're excited to bring DeepSeek V3, a state-of-the-art MoE language model, to Novita AI!

Why Choose DeepSeek V3?

* A robust 671B total parameter model, outperforming open-source peers and rivaling top-tier closed-source models.
* Performs exceptionally well for coding tasks, making it a great companion for developers.
* Handle complex inputs with 16K context size and 16K max output.
* Just \$0.89/M tokens, delivering exceptional value without compromising performance.

How to Access DeepSeek-V3:

* Explore it through our Playground: [https://novita.ai/models/llm/deepseek-deepseek\_v3](https://novita.ai/models/llm/deepseek-deepseek_v3);
* Use it seamlessly via OpenRouter: [https://openrouter.ai/deepseek/deepseek-chat](https://openrouter.ai/deepseek/deepseek-chat).

Experience the future of AI—try DeepSeek V3 today! 🚀


# June 20, 2025 Product Updates
Source: https://novita.ai/docs/changelog/16-06-25--20-06-25



## **Model APIs Updates**

### **New Features**

* **MiniMax-Hailuo-02 Now Available on Novita**

  Novita now supports MiniMax’s latest high-performance video generation model — **Hailuo 02**.

  Hailuo 02 delivers industry-leading instruction-following capabilities and excels at generating videos in complex physical scenarios, including high-intensity stunt simulations. It supports ultra-high-definition video generation, with:

  * Up to **6 seconds** at **768P or 1080P**
  * Up to **10 seconds** at **768P**

  Explore more creative possibilities with one of the most advanced video models available.

  Get started now: [**MinMax-Hailuo-02**](https://novita.ai/models/image#minimax-hailuo-02)

  Updated time: June 18, 2025

***

## **GPUs Updates**

### **New Features**

* **Instances are allowed to upgrade in any state**

  Updated time: June 17, 2025


# Weekly Product Updates - March 21, 2025
Source: https://novita.ai/docs/changelog/17-03-25--21-03-25



## **New Features**

* **LLM Full Model Upgrade: Function Calling & Structured Outputs Available Now**

  Novita now supports Function Calling and Structured Outputs for all capability-supported models on the platform. Developers can now filter models using these tags for more precise API integration and structured data generation that aligned with custom schemas. Refer to the API documentation for details: [**Function calling**](https://novita.ai/docs/guides/llm-function-calling) & [**Structured Outputs**](https://novita.ai/docs/guides/llm-structured-outputs)

  Updated time: March 21, 2025
* **Image Dedicated Endpoint now supports billing queries**

  Billing for Image Dedicated Endpoints now includes monthly query support.

  Updated time: March 21, 2025
* **The annual and monthly subscription functionality of GPU Instance is now officially released**

  1. **Flexible Billing Model:** Users can freely choose between on-demand and monthly subscription when launching instances.
  2. **Enhanced Resource Guarantee:** During the monthly subscription period, even if an instance is shut down, it remains reserved for the user, significantly enhancing the user experience.
  3. **Seamless Service Transition:** Supports converting on-demand instances to annual or monthly subscriptions, as well as renewals during the subscription period.
  4. **Monthly Subscription Discounts:** Monthly subscriptions start at a 10% discount over pay-as-you-go, with additional saving for longer terms.

  Updated time: March 19, 2025
* **Team members' nicknames are now displayed in the task lists for Instance, Serverless GPUs, and more**

  When the account is in Team mode, the GPUs Console now displays member nicknames.

  Updated time: March 18, 2025


# August 22, 2025 Product Updates
Source: https://novita.ai/docs/changelog/18-08-25--22-08-25



## **Model APIs Updates**

### **New Features**

* **New Model Available: MiniMax Speech-2.5**

  Novita now features MiniMax's next-generation Text-to-Speech models: **Speech-2.5-HD** and **Speech-2.5-Rurbo**. Speech 2.5 represents a major breakthrough in voice generation, delivering significant advancements in multi-language expressiveness, voice cloning fidelity, and language coverage.

  Speech-2.5-HD (High-Fidelity):The latest HD model, offering exceptional prosody and remarkable voice cloning accuracy.Specifically designed for high-quality audio applications, providing studio-grade, high-fidelity sound.

  Speech-2.5-Turbo:The latest Turbo model, engineered for extreme responsiveness and ultra-low latency.Ideal for high-concurrency, real-time scenarios and includes support for 40 languages.

  Get started now: [MiniMax Speech-2.5-hd-preview Text to Speech](https://novita.ai/docs/api-reference/model-apis-minimax-speech-2.5-hd), [MiniMax Speech-2.5-turbo-preview Text to Speech](https://novita.ai/docs/api-reference/model-apis-minimax-speech-2.5-turbo)

  Updated time: August 21, 2025
* **New Model Available: Qwen-Image-Edit**

  Built upon the powerful 20B Qwen-Image model, Qwen-Image-Edit extends its unique text rendering capabilities into the image editing domain, enabling highly precise in-image text manipulation.

  Key Highlights:

  * **Comprehensive Editing:** Supports a full spectrum of edits, from precise local adjustments (adding, removing, or modifying elements while keeping the rest of the image intact) to high-level creative edits (like IP creation, object rotation, and style transfer).
  * **Precise Text Editing:** Directly add, delete, or modify both Chinese and English text within an image while perfectly preserving the original font, size, and style.
  * **SOTA Performance:** Achieves state-of-the-art (SOTA) results on multiple public benchmarks, establishing it as a powerful foundational model for image editing tasks.

  Get started now:[**Qwen-Image-Edit**](https://novita.ai/docs/api-reference/model-apis-qwen-image-edit)

  Updated time: August 21, 2025
* **New Model Available: Pixverse V4.5 Text to Video, Pixverse V4.5 Image to Video**

  Pixverse 4.5 is the latest AI video model released by Pixverse AI. It introduces major upgrades in cinematic control, multi-image fusion, and complex motion handling.

  Key Highlights:

  * **20+ Cinematic Camera Controls:** Access over 20 camera controls like panning and zooming, all precisely guided by text prompts for professional-grade results.
  * **Multi-Image Reference & Fusion:** Seamlessly fuse elements from multiple reference images with the new Fusion mode for richer, stylistically consistent videos.
  * **Optimized Complex Motion:** Superior handling of complex actions like high-speed movement and group interactions, delivering smoother and more natural animations.

  Get started now:[ Pixverse V4.5 Text to Video](https://novita.ai/docs/api-reference/model-apis-pixverse-v4.5-t2v), [PixVerse V4.5 Image to Video](https://novita.ai/docs/api-reference/model-apis-pixverse-v4.5-i2v)

  Updated time: August 21, 2025

***

## **Platform Service Updates**

### **New Features**

* **Budget Management Now Live for Teams**

  Our new Budget Management feature is now available, giving you precise control over your team's API spending. This system is designed to help you efficiently manage member-level spending limits, with key capabilities including:

  * **Member-Level Budget Control:** Assign unique spending caps to individual team members.
  * **Smart Enforcement & Alerts:** Automatically prevent cost overruns and receive timely notifications.
  * **Flexible Budget Types:** Implement one-time or recurring (daily, weekly, or monthly) budgets.
  * **Real-Time Adjustments:** Instantly modify budget allocations as your needs change.

  To get started, visit [Billing > Budgets](https://novita.ai/billing/budgets) in your console. For more details, please see our [help documentation](https://novita.ai/docs/guides/budgets).

  **Updated:** August 20, 2025


# April 19, 2024
Source: https://novita.ai/docs/changelog/19-04-24



🔥 Llama 3 models are now available on novita.ai.

You can try them out in the playground:

* meta-llama/llama-3-8b-instruct: [https://novita.ai/model-api/llm-api/playground#meta-llama-llama-3-8b-instruct](https://novita.ai/llm-api/playground#meta-llama-llama-3-8b-instruct)

* meta-llama/llama-3-70b-instruct: [https://novita.ai/model-api/llm-api/playground#meta-llama-llama-3-70b-instruct](https://novita.ai/llm-api/playground#meta-llama-llama-3-70b-instruct)


# May 23, 2025 Product Updates
Source: https://novita.ai/docs/changelog/19-05-25--23-05-25



## **Model APIs Updates**

### **New Features**

* **Kling V1.6: Now Supports 10-Second Video Generation**

  Kling V1.6 now supports generating videos up to 10 seconds long, enabling more complete and coherent visual storytelling. Ideal for short narratives, ad snippets, and dynamic showcases. Get started now:  [Novita AI KLING V1.6 Text to Video API | Generate videos from text](https://novita.ai/docs/api-reference/model-apis-kling-v1.6-t2v) and [Novita AI KLING V1.6 Image to Video API | Generate videos from images](https://novita.ai/docs/api-reference/model-apis-kling-v1.6-i2v).

  Updated time: May 21, 2025

***

## **GPUs Updates**

### **New Features**

* **New GPU Type L40S Now Available**

  The **L40S** is a **high-performance data center GPU** from NVIDIA, built on the Ada Lovelace architecture. It is optimized for **multi-tasking scenarios** such as AI inference, large model training, graphics rendering, and virtualization. The L40S is well-suited for **inference and training of medium to large language models** like LLaMA, GPT, and BERT, as well as for **Stable Diffusion and image/video generation**. It supports concurrent operation of multiple hardware engines and offers excellent **multi-user VM deployment** and **GPU virtualization capabilities**. Get started now: [Novita AI](https://novita.ai/gpus-console).

  Updated time: May 23, 2025


# July 19, 2024
Source: https://novita.ai/docs/changelog/19-07-24



Novita AI has released **"GPU Instance"**, which provides cost-effective, accessible high-performance computing with easy GPU access, ideal for complex AI tasks. Users benefit from on-demand rental, optimizing efficiency and cost-effectiveness.
<br />For more details, please visit: [https://novita.ai/gpu-instance](https://novita.ai/gpu-instance).


# October 19, 2024
Source: https://novita.ai/docs/changelog/19-10-24



We've recently deployed some new LLM models. You can try them out in the playground:

* **qwen/qwen-2-72b-instruct**: [https://novita.ai/llm-api/playground#qwen-qwen-2-72b-instruct](https://novita.ai/llm-api/playground#qwen-qwen-2-72b-instruct)

* **qwen/qwen-2.5-72b-instruct**: [https://novita.ai/llm-api/playground#qwen-qwen-2.5-72b-instruct](https://novita.ai/llm-api/playground#qwen-qwen-2.5-72b-instruct)

* **qwen/qwen-2-7b-instruct**: [https://novita.ai/llm-api/playground#qwen-qwen-2-7b-instruct](https://novita.ai/llm-api/playground#qwen-qwen-2-7b-instruct)

* **sao10k/l31-70b-euryale-v2.2**: [https://novita.ai/llm-api/playground#sao10k-l31-70b-euryale-v2.2](https://novita.ai/llm-api/playground#sao10k-l31-70b-euryale-v2.2)

Or integrate with API: [LLM API Documentation](/guides/llm-api).


# December 19, 2024
Source: https://novita.ai/docs/changelog/19-12-24



The **Team** feature is now available.

**With Team, you can:**

* Convert your personal account into a team account or join an existing team to collaborate with others;
* Invite other users to join your team, and share the team's resources with them;
* Manage your members' permissions to the team's resources by assigning different roles;
* Analyze usage data for each team member.

For more information, please visit: [Team Documentation](/guides/team).


# March 20, 2024
Source: https://novita.ai/docs/changelog/20-03-24



We've released novita.ai Python SDK version 0.5.0 🐍

This version introduces the txt2img\_v3 and img2img\_v3 methods for calling the API v3 txt2img and img2img,
<br />and you can find examples here: [https://github.com/novitalabs/python-sdk/tree/main/examples](https://github.com/novitalabs/python-sdk/tree/main/examples).


# April 25, 2025 Product Updates
Source: https://novita.ai/docs/changelog/21-04-25--25-04-25



## **Model APIs Updates**

### **New Features**

* **New Models: The GLM-4-0414 Series and the Qwen2.5-7B-Instruct Model**

  As early as March this year, Zhipu AI had announced plans to open source new GLM models in mid-April, and true to their word, the GLM-4-0414 series was launched on schedule. The newly open-sourced models cover three categories: **foundation, reasoning, and reflection**. According to official data, some models in this series can rival OpenAI’s GPT-4o and DeepSeek’s V3/R1 series in performance.

  As a one-stop AIGC cloud service platform, Novita promptly launched the above models along with a limited-time free version of the Qwen2.5-7B-Instruct model. Novita also carried out full-chain optimization on the models, significantly reducing inference latency while maintaining the original model accuracy. Developers can efficiently access and utilize these models through API interfaces.

  1. [thudm/glm-4-9b-0414](https://novita.ai/models/llm/thudm-glm-4-9b-0414)
  2. [thudm/glm-z1-9b-0414](https://novita.ai/models/llm/thudm-glm-z1-9b-0414)
  3. [thudm/glm-z1-32b-0414](https://novita.ai/models/llm/thudm-glm-z1-32b-0414)
  4. [thudm/glm-4-32b-0414](https://novita.ai/models/llm/thudm-glm-4-32b-0414)
  5. [thudm/glm-z1-rumination-32b-0414](https://novita.ai/models/llm/thudm-glm-z1-rumination-32b-0414)

  Updated time: April 25, 2025
* **New Product: LLM Dedicated Endpoint**

  Novita introduces LLM Dedicated Endpoint – a fully managed, high-performance AI deployment solution. Designed for scaling teams and growing businesses, it delivers reliable, high-performance AI infrastructure without the complexity of self-management.\_For details, see:  [Dedicated Endpoint](https://novita.ai/dedicated-endpoint)

  Updated time: April 22, 2025
* **Novita Referral Vouchers Now Usable Across All LLM Models**

  Novita's referral program vouchers can be used with all LLM models, subject to applicable rate limits. For details, see: [llm-rate-limits](https://novita.ai/docs/guides/llm-rate-limits)

  Updated time: April 21, 2025

***

## **GPUs Updates**

### **Improvements**

* **Optimized Storage Architecture for GPU Container Instances**

  To address the overlap between system disks and local disks, we have updated the instance storage policy. Effective immediately, the option to configure **a local disk for new instances has been discontinued**. Instances and templates that have already been created with local disk settings will remain unaffected.

  Following these changes, instances now support **system disk expansion**. For instances that have existing local disks, users can now unmount or resize the local disk space. When local storage is unmounted, all associated data will be automatically migrated to the system disk to ensure data continuity.\
  For more details, please refer to the [Instance Management](https://novita.ai/gpus-console/instances) page.

  Updated time: April 24, 2025


# July 25, 2025 Product Updates
Source: https://novita.ai/docs/changelog/21-07-25--25-07-25



## **Model APIs Updates**

### **New Features**

* **New Model Available: Qwen3 Coder 480B A35B Instruct**

  Novita now supports **Qwen3 Coder 480B A35B Instruct**, the cutting-edge open-source coding model from the Qwen team. This model delivers performance on par with Claude Sonnet for agentic coding, browser automation, and other core development tasks, enabling highly efficient code generation and the handling of complex problems.

  Get started now: [**Qwen3 Coder 480B A35B Instruct**](https://novita.ai/models/llm/qwen-qwen3-coder-480b-a35b-instruct)

  Updated time: July 23, 2025
* **New Model Available: Qwen3 235B A22b Thinking 2507**

  Novita now supports Qwen3 235B A22B Instruct 2507, a powerful Mixture-of-Experts (MoE) model designed for ultimate performance and efficiency. By activating just 22B of its 235B parameters during inference, it dynamically handles diverse tasks with incredible speed.

  With its native 262k-token context window, the model excels at demanding use cases, including analyzing long documents, comprehending full code repositories, and performing complex multi-paragraph reasoning.

  Get started now: [**Qwen3 235B A22b Thinking 2507**](https://novita.ai/models/llm/qwen-qwen3-235b-a22b-thinking-2507)

  Updated time: July 23, 2025

***

## **Platform Service Updates**

### **Improvements**

* **Pricing Page Optimization**

  Non-MoE Models are now systematically sorted by vendor/manufacturer for clear differentiation

  Dedicated MoE (Mixture of Experts) category added and placed at the end of the page for quick access

  Updated time: July 22, 2025


# January 22, 2025
Source: https://novita.ai/docs/changelog/22-01-25



Introducing the brand-new Novita AI, including our new brand logo and site style.

<Frame>
  <img />
</Frame>

We've reimagined our brand to reflect what we've always stood for: rock-solid infrastructure that empowers developers to build the future. From startups to larger organizations, we're making AI cloud accessible to all.


# September 28, 2025 Product Updates
Source: https://novita.ai/docs/changelog/22-09-25--28-09-25



## **Model APIs Updates**

### **New Features**

* **qwen/qwen3-vl-235b-a22b-thinking Model Release**

  Qwen3-VL—the most powerful vision-language model in the Qwen series to date. Novita offers world-first support!

  Updated time: September 24, 2025
* **qwen/qwen3-vl-235b-a22b-instruct Model Release**

  Qwen3-VL—the most powerful vision-language model in the Qwen series to date. Novita offers world-first support!

  Updated time: September 24, 2025
* **minimax-hailuo-02 First-last Frame**

  First-Last Frame is a video generation technology introduced by Hailuo AI. By specifying the start and end images (the first and last frames), it automatically generates dynamic transition videos in between. The technology supports complex instruction execution and delivers cinematic-quality effects, making it suitable for applications such as e-commerce advertising, one-click outfit changes, and more.

  Updated time: September 26, 2025
* **Seedance V1 Lite/Pro**

  Seedance 1.0 is the latest video generation foundational model launched by ByteDance's Doubao AI team, featuring both lite and pro versions. Its capabilities and pricing are fully aligned with the official website.

  [Seedance V1 Lite Text to Video](https://novita.ai/docs/api-reference/model-apis-seedance-v1-lite-t2v)

  [Seedance V1 Lite Image to Video](https://novita.ai/docs/api-reference/model-apis-seedance-v1-lite-i2v)

  [**Seedance V1 Pro Text to Video**](https://novita.ai/docs/api-reference/model-apis-seedance-v1-pro-t2v)

  [**Seedance V1 Pro Image to Video**](https://novita.ai/docs/api-reference/model-apis-seedance-v1-pro-i2v)

  Updated time: September 28, 2025

***

## **GPUs Updates**

### **New Features**

* **Subscribtion Instance Auto-Renewal Feature**

  Supports setting up automatic renewal for Subscribtion Instances.

  Updated time: September 22, 2025
* **Creating instances and templates support the function of specifying the minimum CUDA version**

  Creating instances and templates support the function of specifying the minimum CUDA version.

  Updated time: September 25, 2025


# January 24, 2025
Source: https://novita.ai/docs/changelog/24-01-25



Today, Novita AI has been onboarded to **Artificial Analysis**, which provides benchmarking and related information to support people & organizations in choosing the right model for their use-case and which provider to use for that model.

Please check out our performance benchmarks at: [https://artificialanalysis.ai/providers/novita](https://artificialanalysis.ai/providers/novita).


# Weekly Product Updates - March 28, 2025
Source: https://novita.ai/docs/changelog/24-03-25--28-03-25



## **New Features**

* **Added new model: deepseek-v3-0324**

  deepseek-v3-0324 is the latest high-performance large language model launched by Novita, representing the newest version of the flagship conversational model series from the DeepSeek team. It adopts a Mixture-of-Experts (MoE) architecture and boasts a parameter scale of 685 billion parameters.

  Updated time: March 26, 2025

## **Improvements**

* **Optimized third-party login integration**

  Fixed an issue where multiple clicks on third-party login prevented users from signing in.

  Updated time: March 28, 2025
* **Exclusive discounts now displayed in "Explore-Template and** **GPU Server" section**

  Customers with exclusive discounts now see discounted prices directly within the "Explore-Template and GPU Server" sections, rather than solely in billing. This provides clearer discount visibility to support decision-making.

  Updated time: March 26, 2025
* **Improved user interaction for the Model Library**

  Clicking "See All" in a Model Library category now takes users directly to a dedicated page showcasing all templates within that category, instead of redirecting them to the homepage.

  Updated time: March 24, 2025


# July 24, 2024
Source: https://novita.ai/docs/changelog/24-07-24



🔥 Llama 3.1 models are now available on Novita AI.

You can try them out in the playground:

* **meta-llama/llama-3.1-405b-instruct**: [https://novita.ai/llm-api/playground#meta-llama-llama-3.1-405b-instruct](https://novita.ai/llm-api/playground#meta-llama-llama-3.1-405b-instruct)

* **meta-llama/llama-3.1-70b-instruct**: [https://novita.ai/llm-api/playground#meta-llama-llama-3.1-70b-instruct](https://novita.ai/llm-api/playground#meta-llama-llama-3.1-70b-instruct)

* **meta-llama/llama-3.1-8b-instruct**: [https://novita.ai/llm-api/playground#meta-llama-llama-3.1-8b-instruct](https://novita.ai/llm-api/playground#meta-llama-llama-3.1-8b-instruct)

Or integrate with API: [LLM API Documentation](/guides/llm-api).


# August 29, 2025 Product Updates
Source: https://novita.ai/docs/changelog/25-08-25--29-08-25



## **Model APIs Updates**

### **New Features**

* **New Model Available**

  **Kling V2.1**:

  Kling V2.1 is the latest evolution of Kuaishou’s AI-powered video‑generation model, designed to seamlessly create short, cinematic‑quality clips from a single image or a text prompt. It represents a major leap forward from Kling 2.0, emphasizing motion fidelity, visual coherence, and prompt accuracy.

  **Kling 2.1 Master**:

  The premium endpoint for Kling 2.1, designed for top-tier image-to-video generation with unparalleled motion fluidity, cinematic visuals, exceptional prompt precision, and 1080p video quality.

  **Seedance V1 Lite**:

  Seedance V1 Lite is an AI video model designed for coherent multi-shot video generation, offering smooth motion and precise adherence to detailed prompts. It supports resolutions of 480p, 720p, and 1080p.

  **Seedance V1 Pro**:

  Seedance V1 Pro is an AI video model designed for coherent multi-shot video generation, offering smooth motion and precise adherence to detailed prompts. It supports resolutions of 480p, 720p, and 1080p.

  Updated time: August 29, 2025

***

## **GPUs Updates**

### **New Features**

* **Self-migration function of faulty devices**

  When a user enables automatic migration, in the event of device failure, the system will automatically migrate the instance to a healthy node within the same cluster, and the instance ID, port mapping address, etc. will remain unchanged;

  It should be noted that:

  1. During the migration process, the user's instance will still experience**short-term interruption**, and the interruption time depends on the size of the system disk;
  2. Therefore, this feature is very suitable for **stateless tasks**. For stateful tasks, it is recommended not to enable this feature for the time being. After receiving a fault notification, users can choose to perform migration during off-peak business hours. In the future, we will also upgrade the feature for this scenario;

  Updated time: August 25, 2025


# LLM Serverless Model Deprecation Notice
Source: https://novita.ai/docs/changelog/25-12-25



**Dear Developer,**

We are writing to inform you of upcoming changes to our **Serverless Endpoints**.

As part of our regular product lifecycle management to ensure high performance and resource optimization, we will be deprecating a list of specific models on **January 8, 2026 (UTC)**.

**You have 14 days** from today to update your integration before these models are removed from the **Serverless Endpoints**.

***

## Impacted Models & Recommended Alternatives

Please refer to the table below to see if your application is using any of the impacted models and find their recommended alternatives:

| **Deprecated model**                  | **Recommended alternatives**      |
| :------------------------------------ | :-------------------------------- |
| baichuan/baichuan-m2-32b              | qwen/qwen3-32b-fp8                |
| paddlepaddle/paddleocr-vl             | qwen/qwen3-vl-8b-instruct         |
| qwen/qwen3-reranker-8b                | baai/bge-reranker-v2-m3           |
| deepseek/deepseek-ocr                 | qwen/qwen3-vl-235b-a22b-instruct  |
| thudm/glm-4.1v-9b-thinking            | zai-org/glm-4.6v                  |
| deepseek/deepseek-r1-distill-qwen-14b | deepseek/deepseek-r1-0528         |
| meta-llama/llama-3.2-3b-instruct      | meta-llama/llama-3.3-70b-instruct |
| google/gemma-3-12b-it                 | google/gemma-3-27b-it             |
| gryphe/mythomax-l2-13b                | deepseek/deepseek-v3-0324         |
| deepseek/deepseek-r1-0528-qwen3-8b    | deepseek/deepseek-r1-0528         |
| deepseek/deepseek-r1-distill-qwen-32b | deepseek/deepseek-r1-0528         |
| qwen/qwen3-8b-fp8                     | qwen/qwen3-next-80b-a3b-instruct  |

***

## What actions should you take?

To avoid service interruption, please choose one of the following options before the deadline:

### Option 1: Switch to the Alternative (Recommended)

Update your API code to point to the **Recommended Alternative** listed above.

These newer models offer improved reasoning capabilities, faster inference speeds, and better cost-efficiency.

### Option 2: Continue Using Legacy Models (via Dedicated Endpoints)

If your workflow strictly requires a specific version from the deprecated list (e.g., for reproducibility or specific fine-tuning), you can deploy it on your own private GPU resources using our **Dedicated Endpoints**.

* **Benefit:** This guarantees exclusive access, zero cold starts, and consistent performance.
* **Action:** [https://novita.ai/dedicated-endpoint](https://novita.ai/dedicated-endpoint)

***

## Timeline

* **Announcement Date:** December 25, 2025
* **End of Life (EOL):** January 8, 2026 (UTC)

**Note:** After the EOL date, API requests to any models in the **Deprecated** list via Serverless Endpoints will result in an error.

If you have any questions or need assistance with the migration, please reach out to us via our **Discord** community or submit a support ticket.

Best regards,

**The Novita AI Team**


# March 26, 2025 Notice
Source: https://novita.ai/docs/changelog/26-03-25



## Platform Service Adjustment Notice

### 1. Model Decommissioning Notice

To continuously enhance platform service efficiency, focus on core product capability upgrades, and deliver more advanced, high-quality, and standardized services, Novita platform will decommission certain large language models (LLMs) on April 3, 2025(UTC 0:00). The list of models scheduled for removal is as follows:

* teknium/openhermes-2.5-mistral-7b
* qwen/qwen-2-7b-instruct
* nousresearch/nous-hermes-llama2-13b
* qwen/qwen-2-vl-72b-instruct
* openchat/openchat-7b


# May 30, 2025 Product Updates
Source: https://novita.ai/docs/changelog/26-05-25--30-05-25



## **Model APIs Updates**

### **New Features**

* **New Model Available: DeepSeek-R1-0528**

  Novita now supports the latest high-performance DeepSeek model — [**DeepSeek-R1-0528**](https://novita.ai/models/llm/deepseek-deepseek-r1-0528).

  Released by the DeepSeek team as an open-source model, DeepSeek-R1-0528 features impressive reasoning capabilities, particularly achieving performance comparable to OpenAI's o1 model in mathematics, coding, and reasoning tasks.

  Updated time: May 28, 2025

### **Discontinued Features**

* **Certain LLMs Officially Decommissioned**

  To continuously improve model performance and enhance user experience, several large language models (LLMs) have now been officially decommissioned. Below is the list of retired models along with their recommended replacements:

  | **Deprecated Models**                    | **Deprecation Date** | **Replacement Models**            |
  | :--------------------------------------- | :------------------- | :-------------------------------- |
  | jondurbin/airoboros-l2-70b               | 2025-05-28           | sao10k/l3-70b-euryale-v2.1        |
  | qwen/qwen3-14b-fp8                       | 2025-05-28           | qwen/qwen3-32b-fp8                |
  | qwen/qwen3-0.6b-fp8                      | 2025-05-28           | qwen/qwen3-32b-fp8                |
  | qwen/qwen3-1.7b-fp8                      | 2025-05-28           | qwen/qwen3-32b-fp8                |
  | meta-llama/llama-3.2-11b-vision-instruct | 2025-05-28           | qwen/qwen2.5-vl-72b-instruct      |
  | google/gemma-2-9b-it                     | 2025-05-28           | google/gemma-3-27b-it             |
  | meta-llama/llama-3.1-70b-instruct        | 2025-05-28           | meta-llama/llama-3.3-70b-instruct |
  | qwen/qwq-32b                             | 2025-05-28           | meta-llama/llama-3.3-70b-instruct |

  If you encounter any issues during this transition, please don’t hesitate to contact our technical support team.

  Updated time: May 28, 2025

***

## **GPUs Updates**

### **New Features**

* **New Bare Metal Server Reservation Page Launched**

  Novita has launched a [**bare metal server reservation interface**](https://novita.ai/gpu-baremetal) on the official website. Users can now browse available GPU models that support bare metal services, along with detailed configuration information.

  **Bare metal** refers to a computing service that provides **direct access to physical servers without a virtualization layer**, offering superior performance, greater control, and lower latency. It is ideal for scenarios with high demands on resource isolation and computing power, such as deep learning, AI model training, and large-scale inference.

  If you require bare metal resources, you can **select your preferred GPU model and complete the reservation online** to gain exclusive access to dedicated physical servers.

  Updated time: May 30, 2025


# December 26, 2024
Source: https://novita.ai/docs/changelog/26-12-24



Introducing the **Observability system**, which helps you monitor the availability and performance of your services in Novita AI.

The Observability system is currently in beta and only available for the LLM API service, more details can be found in the [LLM API Metrics Documentation](/guides/observability-llm-api-metrics).


# Nov 11, 2025 Product Updates
Source: https://novita.ai/docs/changelog/27-10-25--07-11-25



## **Agent Sandbox Updates**

### **New Features**

* **Agent Sandbox Storage Billing**

  Agent Sandbox storage billing is now enabled to address increasing storage costs and support sustainable operations.

  **Billing Scope:**

  * Storage used by Sandbox Templates

  * Data retained when a Sandbox is paused

  **Free Period:**\
  Free until **November 17, 2025 (UTC)**.\
  Users can view usage at: [https://novita.ai/sandbox-console/usage](https://novita.ai/sandbox-console/usage)

  **Next Steps:**\
  Billing will begin after the free period. Users will be notified in advance via in-app message or email.

  Updated time: Nov 3, 2025
* **Sandbox Auto Pause and Resume**

  Sandboxes now automatically enter a paused state during inactivity and seamlessly resume when accessed again.

  This helps reduce unnecessary resource usage while ensuring fast recovery when workloads restart.

  Guide → [*Sandbox Auto Pause and Resume*](https://novita.ai/docs/guides/sandbox-auto-persistence)

  Updated time: Nov 6, 2025
* **Sandbox Auto Pause and Resume**

  Sandboxes now automatically enter a paused state during inactivity and seamlessly resume when accessed again.

  This helps reduce unnecessary resource usage while ensuring fast recovery when workloads restart.

  Guide → [*Sandbox Auto Pause and Resume*](https://novita.ai/docs/guides/sandbox-auto-persistence)

  Updated time: Nov 6, 2025
* **Sandbox Clone**

  You can now duplicate an existing Sandbox—including its code, environment state, and configurations—with a single click.

  This is ideal for parallel experimentation, debugging, or creating environment snapshots.

  Guide → [*Sandbox Clone*](https://novita.ai/docs/guides/sandbox-clone)

  Updated time: Nov 6, 2025
* **Sandbox Idle Timeout**

  Sandboxes will automatically shut down after a configurable idle period.\
  This helps avoid unexpected costs and ensures better resource hygiene for long-running projects.

  Guide → [*Sandbox Idle Timeout*](https://novita.ai/docs/guides/sandbox-idle-timeout)

  Updated time: Nov 6, 2025
* **Template Version Management**

  Sandbox templates now support full version lifecycle management.\
  You can create, publish, update, or roll back template versions—making environment consistency and team collaboration much easier.

  Guide → [*Template Version Management*](https://novita.ai/docs/guides/sandbox-template-version-management)

  Updated time: Nov 6, 2025


# November 27, 2024
Source: https://novita.ai/docs/changelog/27-11-24



The latest Llama 3.2 Instruct models are now available at Novita AI, offering outstanding performance at competitive prices:

* **Llama 3.2 3B Instruct:** \$0.03/Mtokens (input), \$0.05/Mtokens (output)
* **Llama 3.2 1B Instruct:** \$0.02/Mtokens (input and output)
* **Llama 3.2 11B Vision Instruct:** \$0.06/Mtokens (input and output)

Experience these cutting-edge models in our newly updated LLM playground.


# April 30, 2025 Product Updates
Source: https://novita.ai/docs/changelog/28-04-25--30-04-25



## **Model APIs Updates**

### **New Features**

* **Rate Limits Now Applied to Image, Video, and Audio APIs**

  Rate limiting has been enabled for the **Image, Video, and Audio API products** to ensure reliable performance and fair usage:

  1. **IPM (Images Per Minute)**: Caps the number of images that can be generated per minute.
  2. **RPM (Requests Per Minute)**: Limits total API calls per minute across all endpoints.

  If your requests exceed the set thresholds, rate limit errors will be returned.

  You can check your current limits and request higher quotas directly in the console. Look for the **“Increase Limit”** button next to each metric if your use case requires more capacity.

  Updated time: April 30, 2025
* **Five Qwen3 Series Models Now Available**

  We’ve added five new models from the Qwen3 series on Novita.:

  1. [Qwen3 0.6B](https://novita.ai/models/llm/qwen-qwen3-0.6b-fp8)
  2. [Qwen3 1.7B](https://novita.ai/models/llm/qwen-qwen3-1.7b-fp8)
  3. [Qwen3 4B](https://novita.ai/models/llm/qwen-qwen3-4b-fp8)
  4. [Qwen3 8B](https://novita.ai/models/llm/qwen-qwen3-8b-fp8)
  5. [Qwen3 14B](https://novita.ai/models/llm/qwen-qwen3-14b-fp8)

  Updated time: April 30, 2025
* **New Model: DeepSeek Prover V2 671B**

  Novita supports [**DeepSeek Prover V2 671B**](https://novita.ai/models/llm/deepseek-deepseek-prover-v2-671b) via Serverless Endpoints.

  Updated time: April 30, 2025
* **Updated LLM API Rate Limits**

  User accounts are now automatically tiered into **L1-L5 service levels** based on **recent top-up amount**, with each tier granting different **RPM (Requests Per Minute)** and **TPM (Tokens Per Minute)** limits. For more details, please refer to [Rate limits - Documentation](https://novita.ai/docs/guides/llm-rate-limits).

  Updated time: April 30, 2025
* **First Batch of Large-Parameter Qwen3 Models Now Available**

  Three large-parameter Qwen3 models have been newly launched:

  1. [Qwen3-235B-A22B](https://novita.ai/models/llm/qwen-qwen3-235b-a22b-fp8)
  2. [Qwen3-30B-A3B](https://novita.ai/models/llm/qwen-qwen3-30b-a3b-fp8)
  3. [Qwen3-32B](https://novita.ai/models/llm/qwen-qwen3-32b-fp8)

  Updated time: April 29, 2025


# May 28, 2024
Source: https://novita.ai/docs/changelog/28-05-24



The img2img Playground now supports ControlNet and IPAdapter,
<br />visit [https://novita.ai/model-api/playground#img2img](https://novita.ai/model-api/playground#img2img) to have a try.

And txt2img Playground allows you to share your parameters with a share-link.
<br />Here is my share for you: [https://novita.ai/model-api/playground?share=2930971716886178](https://novita.ai/model-api/playground?share=2930971716886178).


# August 1, 2025 Notice
Source: https://novita.ai/docs/changelog/28-07-25--01-08-25



## **Model APIs Updates**

### **New Features**

* **New Model Available: Seedream 3.0 Text to Image**

  The **Seedream 3.0 Text to Image** model is a new generation text-to-image model built on ByteDance’s large visual model. It offers accurate understanding of textual input and the ability to generate images with high text-image alignment and aesthetic quality. The model supports direct output at resolutions below 2048, with significantly improved performance across various scenarios.

  Get started now: [**Seedream 3.0 Text to Image**](https://novita.ai/docs/api-reference/model-apis-seedream-3-0-t2i)

  Updated time: August 1, 2025


# February 29, 2024
Source: https://novita.ai/docs/changelog/29-02-24



We've launched some new features lately, here are the details:

1. You can now check if the civitai models exist on novita.ai. Simply copy the civitai model page URL and paste it into the search box at [https://novita.ai/model-api/model](https://novita.ai/model-api/model).

2. SDXL Lightning LoRAs are now supported in the API /v3/async/txt2img. Available models include sdxl\_lightning\_2step\_lora, sdxl\_lightning\_4step\_lora, and sdxl\_lightning\_8step\_lora.

***

[View More](https://discord.gg/QwpfJqcxCX)


# April 29, 2024
Source: https://novita.ai/docs/changelog/29-04-24



Now you can chat with your favorite character by using the novita.ai LLM features.
<br />Play it now 👉 [https://novita.ai//model-api/llm-api/playground](https://novita.ai/llm-api/playground)


# July 4, 2025 Product Updates
Source: https://novita.ai/docs/changelog/30-06-25-04-07-2025



## **Model APIs Updates**

### **New Features**

* **Novita LLMs Dedicated Endpoints**

  Fully Managed Deployment for Your Custom AI Models

  High cost performance

  * Deploy available models and LoRA adapters on customizable GPU endpoints with per-hour billing.
  * Lower prices, No hard rate limits, Cheaper under high utilization, Custom base models and multiple LoRAs, Predictable performance unaffected.

    Learn more about [Pricing](https://novita.ai/pricing) and read this [Blog](https://blogs.novita.ai/deploy-custom-base-model-with-llm-dedicated-endpoint/) to learn how to deploy a custom base model with Novita LLMs Dedicated Endpoints.

  Updated time: July 4, 2025

***

## **Agent SandBox Updates**

### **New Features**

* **Agent Sandbox Is Now Live**

  **Agent Sandbox** is a high-performance cloud runtime purpose-built for **AI Agent workloads**, designed to support the full lifecycle of autonomous agents.

  Key capabilities include:

  * Millisecond-level startup, optimized for high-concurrency tasks
  * **Multi-language support**, including Python, JavaScript, and C++
  * Enables **code execution, web access, and system-level interactions**
  * **Per-second billing** for vCPU and memory — flexible, cost-efficient usage

  As the **infrastructure foundation for the runtime era of AI Agents**, Agent Sandbox empowers the next generation of generative agents with fast, scalable, and reliable execution capabilities.

  Visit the [**Documentation**](https://novita.ai/docs/guides/sandbox-overview) Center to learn more.

  Updated time: June 30, 2025

***

## **Platform Service Updates**

### **Improvements**

* **In-App Messaging Now Live for Critical Notifications**

  Our new **in-app messaging system** is now available, allowing you to receive important platform-level updates in one place, including:

  * **GPU failures, service interruptions, and operational alerts**
  * **Account-related notices**, such as coupon delivery or login activity
  * **Promotional events and platform campaigns**

  All messages can be viewed in your **Message Center** in the console. Stay informed, effortlessly.

  Updated time: July 1, 2025

***


# April 04, 2025 Product Updates
Source: https://novita.ai/docs/changelog/31-03-25--04-04-25



## **New Features**

* **Added Support for Hugging Face Login**

  Users can now sign in using their Hugging Face account. Social login now supports Hugging Face in addition to Google and GitHub.

  Updated time: April 02, 2025
* **Added Qwen2.5 VL 72B Instruct to the Model Library**

  Qwen2.5 VL 72B Instruct is the latest high-performance multimodal large language model launched by Novita.

  Featuring enhanced visual comprehension capabilities, it also demonstrates strong performance in complex reasoning and decision-making tasks.

  Updated time: March 31, 2025
* **Added Gemma-3-27b-it to the Model Library**

  Gemma-3-27b-it is the latest high-performance multimodal large language model launched by Novita.

  Built on Gemini 2.0 architecture, it possesses cross-modal reasoning capabilities across text, images, and short videos.

  Updated time: March 31, 2025


# July 31, 2025 Notice
Source: https://novita.ai/docs/changelog/31-07-25



### **Model Decommissioning Notice**

To optimize resources and enhance the overall user experience, Novita will decommission the **Stable Diffusion 3  API** on **August 15, 2025 (UTC 0:00).**

The API will be inaccessible after this date. Please update your applications before then to prevent service interruptions.


# LLM FAQs
Source: https://novita.ai/docs/guides/LLM-FAQ



## Voucher Usage Guide

### What types of voucher does Novita provide?

Novita currently offers the following types of vouchers to help users experience the platform's services:

* **New User Voucher**: Available to first-time registered users for trying out services of various types of models.
* **Referral Voucher**: Earned by inviting others to register and complete tasks on the platform.

## Rate Limits for Model Usage

### What are the RPM limits for different users?

RPM (Requests Per Minute) limits vary based on a user's verification level and account status. For detailed limits, please refer to the official documentation:

<Tip>
  👉 For further assistance, please [book a call with our sales team](https://meet.brevo.com/novita-ai/contact-sales)
</Tip>

## RPM Adjustment and Upgrade Policy

### Can users apply for increased RPM limits?

Yes. Novita allows flexible RPM upgrades based on usage needs. Rules are listed as below:

* **DeepSeek models**: The platform will strive to accommodate reasonable scaling needs.
* **Other models**: RPM increases are evaluated based on model cost and actual user behavior, subject to capacity availability.

### **Application process:**

User → Customer Manager / Tech Support → Product Team Review & Approval

### **What happens if actual usage falls short of the committed RPM?**

If the user's actual RPM remains below the committed level for one consecutive week, the platform will adjust the rate limits policy as:

* Reduce the limit to the peak RPM in the past week, or
* Revert to the model's default rate limit (whichever is lower).

### **Is self-service RPM upgrade supported?**

Yes. Novita plans to launch an **RPM Upgrade Package**, allowing users to manage and increase RPM limits independently, without manual approval.

For further assistance, please [book a call with our sales team](https://meet.brevo.com/novita-ai/contact-sales).

### How to control thinking function of Zai-org/GLM-4.5 when calling its API?

When calling API zai-org/glm-4.5, there always exists some situations where thinking function is not needed. In these cases, if you want to turn thinking function off, you can simply add one fixed sentence called:

```python theme={"system"}
"enable_thinking": false 
```

at the bottom, for example:

```python theme={"system"}
{
  "model": "zai-org/glm-4.5",
  "messages": [
  {
   "role": "user",
   "content": "How is the weather in New York?"
  }
 ],
 "temperature": 0.7,
 "stream": false,
 "max_tokens": 500,
 "tool_choice": "auto",
 "enable_thinking": false
}
```


# AI Gradio 
Source: https://novita.ai/docs/guides/ai-gradio

Explore ai-gradio and Novita AI to build interactive AI demos effortlessly with powerful large language models.

AI-gradio simplifies AI development with its intuitive Python package, built on Gradio's framework. Pairing it with Novita AI unlocks powerful capabilities through cutting-edge large language models, which deliver exceptional value through Novita AI's reliable APIs, optimized performance, and cost-effective pricing—all within AI-gradio's user-friendly interface.

This step-by-step guide will access Novita AI's LLMs API on ai-gradio including methods to install ai-gradio and use Novita AI's LLMs in ai-gradio.

## How to Install ai-gradio

```python theme={"system"}
# Install core package
pip install ai-gradio

# Install with specific provider support
pip install 'ai-gradio[openai]'     # OpenAI support
pip install 'ai-gradio[gemini]'     # Google Gemini support
pip install 'ai-gradio[anthropic]'  # Anthropic Claude support
pip install 'ai-gradio[groq]'       # Groq support

# Install all providers
pip install 'ai-gradio[all]'
```

## How to use Novita AI's LLMs in ai-gradio

### Step 1: Set up environment variables.

* Set NOVITA\_API\_KEY to your Novita API key.

```python theme={"system"}
export NOVITA_API_KEY=<your api key>
```

### Step 2: Modify the app.py entry file.

```python theme={"system"}
import gradio as gr
import ai_gradio
gr.load(
    name='novita:deepseek/deepseek-r1',
    src=ai_gradio.registry,
).launch()
```

### Step 3: Run the app.py file with python.[​](https://novita.ai/docs/guides/third-party-langflow-guide#accessing-novita-ai-llm-api-on-langflow)


# AnythingLLM
Source: https://novita.ai/docs/guides/anythingllm

Step-by-step guide to set up AnythingLLM with Novita AI models for secure, document-based AI applications.

With AnythingLLM, you gain seamless access to a comprehensive suite of Novita AI LLM models, including DeepSeek, Llama, Qwen, and more, along with vector database solutions. The integration enables you to effortlessly build and deploy AI-powered applications that handle complex language tasks while ensuring privacy and control.

This guide will walk you through installing and integrating AnythingLLM, connecting Novita AI’s models, enabling web search functionality, and setting up a knowledge base for dynamic and intelligent document interactions.

## **What is AnythingLLM?**

AnythingLLM is a full-stack application designed to give you the flexibility of using both commercial LLMs and popular open-source LLMs, along with vector database solutions. You can run this application locally or host it remotely, offering a secure, private environment to interact intelligently with your documents.

By integrating these resources, AnythingLLM allows you to build a highly functional AI-powered chat interface that handles complex language tasks without compromising privacy or control.

## Key Features

* **Thread-like Structure Workspace**: Workspaces act as threads, organizing related documents in a contained space. Each Workspace isolates documents from others, preserving a unique context for each project or topic.
* **Flexibility for Personal and Businesses:** Install AnythingLLM and its full suite of tools as a single application on your personal desktop. And Fine-grained permissioning and access control for organization is also built-in.
* **Security:** AnythingLLM only talks to the services you connect to and can run fully on your machine without internet connectivity.

## Prerequisites

Before you begin, make sure you have the following:

* Novita AI LLM API Key:
  * Visit [Novita AI’s website](https://novita.ai/) and create an account.
  * After logging in, go to the [Key Management](https://novita.ai/settings/key-management) page to generate your API Key. This key is required to connect Novita AI’s models to AnythingLLM.

    <Frame>
      ![Novita AI key management](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/dify-1.png)
    </Frame>
* **AnythingLLM Software**:Download and install [AnythingLLM software](https://anythingllm.com/desktop) from the official website.

<Frame>
  <img alt="AnythingLLM Software" />
</Frame>

* **A Working Knowledge Base** (Optional):If you plan to use your own documents for knowledge augmentation, prepare them for upload.

## How to install AnythingLLM on Linux locally?

For Linux users, you can install AnythingLLM by running this command on terminal:

curl -fsSL

[<u>https://s3.us-west-1.amazonaws.com/public.useanything.com/latest/installer.sh</u>](https://s3.us-west-1.amazonaws.com/public.useanything.com/latest/installer.sh) | sh

This will download the latest version of AnythingLLM’s AppImage, unpack it, and then supply a symlink to seamlessly run AnythingLLM. This script will unpack the app in `$HOME/AnythingLLMDesktop`.

You can start the app at any time by running `./AnythingLLMDesktop/start`. This will boot the app with full logging.

## Integration Steps

### 1. Connect Novita AI to AnythingLLM

To connect Novita AI’s models with **AnythingLLM**, follow these steps:

* In the application, click on the **🔧 Settings** icon located in the lower-left corner.

  <Frame>
    <img alt="Open AnythingLLM setting" />
  </Frame>
* Go to the **LLM API Providers** section, **and then** select **Novita AI** from the dropdown menu.

  <Frame>
    <img alt="LLM API Providers" />
  </Frame>
* In the **Novita API Key** field, **paste your Novita AI API Key** (the one you generated earlier).
* Click **Save** to complete the integration.

Now, AnythingLLM will have access to all Novita AI’s models, allowing you to use them in your applications.

### 2. Enable Web Search

AnythingLLM allows you to search the web in real-time by enabling web search capabilities. Follow these steps to set up web search functionality:

* **Navigate to Agent Skills**: In the settings or main interface, locate the **Agent Skills** section.
* **Enable Scrape Websites and Web Search**: Toggle the option to turn on both **Scrape Websites** and **Web Search** capabilities.
* **Choose Web Search Providers**: You can choose from the following recommended search providers:
  * **DuckDuckGo**: A free and privacy-focused web search using DuckDuckGo's HTML interface.
  * **Google Search Engine**: Powered by a custom Google Search Engine. It’s free for up to 100 queries per day.
  * **Bing Search**: Powered by the Bing Search API. It’s free for up to 1000 queries per month.

<Frame>
  <img alt="Enable Web Search" />
</Frame>

### 3. Create a Knowledge Base

Next, you’ll want to build a knowledge base for your assistant to use. Follow these steps:

* Click the Upload icon of the Workspace.

  <Frame>
    <img alt="Click the Upload icon of the Workspace" />
  </Frame>
* Upload local documents or website links.
* Select the file(s) or webpage you wish to upload to the workspace.
* Once the file is selected, click **Move to Workspace** to transfer the document(s) to the AnythingLLM workspace.
* Save your files and click **Save and Embed** to finalize the process.
* Your knowledge base is now set up and ready for use.

  <Frame>
    <img alt="Save and embed in AnythingLLM" />
  </Frame>

### 4. Try Asking Questions

In AnythingLLM, ask questions using **@agent**.

The model will respond based on your documents and search results, with citations or references from the files.

<Frame>
  <img alt="Try Asking Questions" />
</Frame>


# Automatic Top-Up
Source: https://novita.ai/docs/guides/auto-top-up



When you enable **"Automatic Top-Up"**, your account will automatically add credit if the balance falls below a specified threshold. Please follow the steps below to set up this feature:

### 1. Enable Automatic Top-Up

Go to <a href="https://novita.ai/billing/payment-methods">Payment Methods</a> in the console.

<Frame>
  <img />
</Frame>

If you don't have a payment method, click **"Add payment method"**. You'll be redirected to Stripe's secure page to add one, and we do not store any payment information.

### 2. Automatic Top-Up Settings

After you turn on the **"Automatic Payments"** switch, a configuration popup will appear automatically.

Set valid values for **"When credit goes below"** and **"Bring credit back up to"**, then click **"Save settings"** to complete the process.

<Frame>
  <img />
</Frame>


# Run Axolotl on Novita AI
Source: https://novita.ai/docs/guides/axolotl

Discover how to fine-tune large language models (LLMs) effortlessly with Axolotl on Novita AI.

Axolotl offers a robust, flexible framework for training LLMs using advanced techniques, supporting various model architectures and training strategies. Ideal for researchers and developers, Axolotl combined with Novita AI’s powerful, hardware-free infrastructure streamlines workflows, removing local hardware constraints.

This guide provides a step-by-step process to deploy and run Axolotl on Novita AI, unlocking the full potential of your AI model training projects.

## How to Use Axolotl:main-latest on Novita AI

Step 1: Access [**the GPU Instance Console**](https://novita.ai/gpus)

* Click `Get Started` to access the GPU Instance console.

<Frame>
  <img alt="Step1 Accessthe GPU Instance Console Pn" />
</Frame>

Step 2: Choose a Template and GPU Type

* Browse various official templates and GPU card options.
* Select [**the Axolotl:main-latest template**](https://novita.ai/gpus-console?templateId=311).
* Click `Deploy` under the 4090 GPU card to proceed to the instance creation page.

<Frame>
  <img alt="Step2 Choosea Templateand GPU Type Pn" />
</Frame>

Step 3: Adjust Disk and Configuration Parameters

* In the `Disk` section, adjust the size of the system disk and local disk.
* In the `Configuration` section, modify settings such as the image, startup commands, ports, and environment variables.
* Check the box for Start Jupyter Notebook to launch Jupyter.

<Frame>
  <img alt="Step3 Adjust Diskand Configuration Parameters Pn" />
</Frame>

Step 4: Confirm Configuration and Deploy

* Review the instance configuration and costs on the confirmation page.
* Click `Deploy` to start the deployment process.

<Frame>
  <img alt="Step4 Confirm Configurationand Deploy Pn" />
</Frame>

Step 5: Wait for Deployment to Complete

* Wait for the instance to finish deploying.

<Frame>
  <img alt="Step5 Waitfor Deploymentto Complete Pn" />
</Frame>

Step 6: Manage and Monitor Instances

* Once deployment is complete, the system will redirect you to the `Instance Management` page.
* Locate your newly created instance, which will initially show a Pulling status (indicating the image is being downloaded).
* Click the small arrow on the right side of the instance to view details.
* Monitor the image pull progress. Once complete, the instance will transition to Running status.
* Click `Logs` to view deployment logs.

<Frame>
  ### &#x20; <img alt="Step6 Manageand Monitor Instances Pn" />
</Frame>

Step 7: Check Instance Logs

* Go to the `Instance Logs` tab to check if the service is starting.
* Wait for the service to finish initializing.

<Frame>
  ### &#x20; <img alt="Step7 Check Instance Logs Pn" />
</Frame>

Step 8: Connect to Jupyter Lab

* Close the logs page.
* Click `Connect` to open the connection information page.
* Locate the `Connection Options` section and click `Connect to Jupyter Lab` to access the Jupyter interface.

<Frame>
  ### &#x20; <img alt="Step8 Connectto Jupyter Lab Pn" />
</Frame>

Step 9: Access Jupyter Lab

* Wait for the Jupyter Lab web interface to load.
* Open `Terminal` to run an official example and verify the service is working correctly.

<Frame>
  ### &#x20; <img alt="Step9 Access Jupyter Lab Pn" />
</Frame>

Step 10: Run a Fine-Tuning Example

* Execute the official example code to perform a fine-tuning task.

```bash theme={"system"}
# Fetch axolotl examples
axolotl fetch examples

# Or, specify a custom path
axolotl fetch examples --dest path/to/folder

# Train a model using LoRA
axolotl train examples/llama-3/lora-1b.yml
```

**Note:** You can't change the default mount path for the network volume in the console. It can only be set when creating an instance or via OpenAPI. Set your desired mount path during instance creation when attaching a volume.


# Browser Use
Source: https://novita.ai/docs/guides/browseruse

Easily enhance your browsing experience by integrating Novita AI with Browser Use for intelligent web interactions.

Browser Use is an open-source library that empowers LLMs to directly control web browsers, revolutionizing web interaction with advanced automation. By integrating Novita AI's powerful LLMs and tools, Browser Use enables seamless browsing, content generation, and task automation for an optimized user experience.

This tutorial will show you how to integrate the Novita AI API with Browser Use to automate browser interactions.

## **How to Use Browser Use with Novita AI**

### **Prerequisites**

* Python 3.11 or higher
* A Novita AI API key

### **Installation**

Step 1: Install Browser Use using pip:

```bash theme={"system"}
pip install browser-use
```

Step 2: Install Playwright (required for browser automation):

```bash theme={"system"}
playwright install chromium
```

### **Obtaining Novita AI LLM API Key**

* Create an account: Visit [Novita AI’s website](https://novita.ai/) and sign up for an account.
* Generate your API Key: After logging in, navigate to the [Key Management](https://novita.ai/settings/key-management) page to generate your API key. This key is essential to connect Novita AI’s models to Cursor.

  <Frame>
    ![Novita AI key management](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/dify-1.png)
  </Frame>

### **Environment Setup**

Create a `.env` file in your project root and add your Novita API key:

```bash theme={"system"}
NOVITA_API_KEY=your_api_key_here
```

### Basic Implementation

* Here's a complete example of using Browser Use with Novita AI's API:

```python theme={"system"}
"""
Web automation using Novita AI and Browser Use
"""

import asyncio
import os

from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from pydantic import SecretStr

from browser_use import Agent

# Load environment variables
load_dotenv()

api_key = os.getenv('NOVITA_API_KEY', '')
if not api_key:
    raise ValueError('NOVITA_API_KEY is not set')


async def run_search():
    agent = Agent(
        task=(
            '1. Go to https://www.reddit.com/r/LocalLLaMA '
            "2. Search for 'browser use' in the search bar "
            '3. Click on first result '
            '4. Return the first comment'
        ),
        llm=ChatOpenAI(
            base_url='https://api.novita.ai/openai',
            model='deepseek/deepseek-v3-0324',
            api_key=SecretStr(api_key),
        ),
        use_vision=False,
    )

    await agent.run()


if __name__ == '__main__':
    asyncio.run(run_search())
```

### **Creating Your Own Tasks**

* You can customize the `task` parameter to perform a wide variety of web tasks:

```python theme={"system"}
task="Compare the price of gpt-4o and DeepSeek-V3"
```

* For more complex tasks, you might want to enable vision capabilities:

```python theme={"system"}
agent = Agent(
    task="Find and summarize the latest news about AI on TechCrunch",
    llm=ChatOpenAI(
        base_url='https://api.novita.ai/openai',
        model='deepseek/deepseek-v3-0324',
        api_key=SecretStr(api_key),
    ),
    use_vision=True,
)
```


# Budgets
Source: https://novita.ai/docs/guides/budgets



The **Team Member Budgets** feature allows you to set flexible spending limits for each member,helping you effectively control overall costs.

> **Note**: This feature is only available for team accounts. Personal accounts or accounts not part of a team will see the menu but cannot access budget management functionalities. You can convert your personal account into a team account or join an existing team to collaborate with others.

## Permissions

* Only the **Team Owner**, **Admin**, and **Billing Roles** can check and manage team budgets.
* **Developer** and **Basic Roles** can only view their own budget type and budget limit, and cannot make changes.

## Budget Control Modes

For all team members, the system enforces budget execution and reset logic based on each member’s **Budget Type**.

### 1. Budget Type Description

| **Budget Type** | **Description** |         **Example**         |
| :-------------: | :-------------: | :-------------------------: |
|  **Unlimited**  |     No limit    |       Unlimited usage       |
|   **One-time**  | One-time budget | budget frozen once consumed |

### 2. Budget Type Switching

When an administrator changes a member’s budget type, the system applies the following transition rules:

| **Switch Path**      | **Processing Logic**                                                                                                     |
| :------------------- | :----------------------------------------------------------------------------------------------------------------------- |
| Unlimited → One-time | The new budget will take effect immediately, with current spending reset to zero and tracked under the new budget cycle. |
| One-time → Unlimited | Current quota and restrictions are immediately discarded, and unlimited quota begins.                                    |

## Adjusting Member Budget Limits

Please follow the steps below to adjust a member’s budget:

1. Go to the [**Team Member Budgets**](https://novita.ai/billing/budgets) page.
2. Find the relevant member in the list, or use the search box to quickly locate them. Budgets can be configured for both current team members and invited members who are pending acceptance.

<img alt="Budges01 Pn" />

3. Click the "**Edit"** button and select the desired budget type.
   * New members are set to **Unlimited** by default, and this can be changed at any time.
   * The **One-time** budget type allows you to set a specific budget limit.

<img alt="Budges02 Pn" />

4. Click the "**Refresh"** button to get the latest budget and consumption data.

<img alt="Budges03 Pn" />

> **Note**: Budget changes take effect immediately. Once a member’s quota is exhausted, they will be unable to initiate new service calls.

## Budget Usage & Service Invocation Rules

* All API Keys created by a member share the same budget pool.
* Before any service is started, the system will automatically check both the wallet balance and the member’s remaining quota. If either is insufficient, the request will be denied.
* Upon reaching the budget limit, all related tasks will be automatically stopped.


# ChatBox
Source: https://novita.ai/docs/guides/chatbox

Integrate Novita AI with Chatbox to streamline your LLM experience across devices with powerful models and a seamless chat interface.

With the Novita AI & Chatbox integration, you gain comprehensive access to Novita AI’s powerful suite of LLMs, including GLM 4.5, Deepseek, Qwen, and more.

This guide will walk you through integrating Novita AI’s LLMs with the ChatBox platform.

## What is ChatBox

ChatBox is an open-source, cross-platform AI chat application designed to interact with a variety of LLMs. It supports a wide range of LLM providers including OpenAI, Claude, Google Gemini, and Novita AI. With features like multi-language support, advanced prompt management, image generation via DALL·E 3, and collaboration tools, Chatbox enables developers and users alike to create and manage AI workflows efficiently.

## Integration Steps

### Step 1 Open Settings

Open the Chatbox app and find the **Settings** at the bottom left.

<img alt="opensettings.png" />

### Step 2 Locate Novita AI

The Settings page defaults to the Model Providers tab. Scroll through the model list to find Novita AI.

<img alt="locatenovita.png" />

### Step 3 Model Selection

Select Novita AI to view the model selection section, where several default models are available, including models supported by Novita such as deepseek-v3-0324, deepseek-r1-0528, glm 4.5, and more. For the complete list of available models, visit [https://novita.ai/models](https://novita.ai/models).

<img alt="modelselection.png" />

Click **Fetch** to open the model list. From there, you can add models to the default list or remove existing ones as needed.

<img alt="fetch.png" />

### Step 4 Check API Key

Here, you can enter your API key. After entering it, click **Check**. If you see the message **“Connection successful”**, it means you're all set to start using it.

<img alt="apikey.png" />

### Step 5 Start Using

Start a new chat. Enter "Hello" and receive a reply. You should see that the response is provided by Novita AI.

<img alt="startnewchat.png" />

## Embedded Model Use

### Step 1 Locate Knowledge Base

Click **"Settings"**, then **"Knowledge Base"**. If there’s nothing there yet, you’ll be prompted to create a new one (the screenshot shows one already created).

<img alt="locatekb.png" />

### Step 2 Create Knowledge Base

When creating a new knowledge base, remember to select your desired **embedding model**, then click **"Create"**.

<img alt="createkb.png" />

### Step 3 Start Using

Return to the **chat page**, and click the **knowledge base icon** below the input box. Then, select the knowledge base you just created. Now start your conversation with Novita AI LLM on ChatBox.

<img alt="startkb.png" />


# Claude Code
Source: https://novita.ai/docs/guides/claude-code



Claude Code is an AI-powered coding assistance published by Anthropic that provides a terminal interface, allowing developers to delegate complex programming tasks directly from the terminal to Claude Code for completion.

Now, Novita provides [Anthropic SDK compatible LLM API services](/guides/llm-anthropic-compatibility), enabling you to easily use Novita LLM models in Claude Code to complete tasks. Please refer to the guide below to complete the integration process.

## Quick Start

### 1. Install Claude Code

<Warning>
  Before installing Claude Code, please ensure your local environment has [Node.js 18 or higher](https://nodejs.org/en/download/) installed.
</Warning>

To install Claude Code, run the following command:

<CodeGroup>
  ```bash Bash icon=terminal theme={"system"}
  npm install -g @anthropic-ai/claude-code
  ```
</CodeGroup>

### 2. Start your first session

<Tip>
  import  from '/snippets/setup-api-key-guide.mdx';

  <SetupApiKeyGuide />
</Tip>

<Tip>
  Please find the list of models currently available for use in Claude Code [here](/guides/llm-anthropic-compatibility#supported-models).
</Tip>

Open the terminal and set up environment variables as follows:

<CodeGroup>
  ```bash Bash icon=terminal theme={"system"}
  # Set the Anthropic SDK compatible API endpoint provided by Novita.
  export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
  export ANTHROPIC_AUTH_TOKEN="<Novita API Key>"
  # Set the model provided by Novita.
  export ANTHROPIC_MODEL="moonshotai/kimi-k2-instruct"
  export ANTHROPIC_SMALL_FAST_MODEL="moonshotai/kimi-k2-instruct"
  ```
</CodeGroup>

Next, navigate to your project directory and start Claude Code. You will see the Claude Code prompt inside a new interactive session:

<CodeGroup>
  ```bash Bash icon=terminal theme={"system"}
  cd <your-project-directory>
  claude .
  ```
</CodeGroup>

<Frame>
  <img />
</Frame>

### 3. Build a web game from scratch

Input your task description, then press `Enter` to start this task.

```bash Bash icon=terminal theme={"system"}
> Create a ping-pong web game. Use only HTML, CSS, and JavaScript, try to create some novel content, and the final output should be a single HTML file.
```

<Frame>
  <img />
</Frame>

Claude Code will analyze your requirements, create a multi-step plan, and automatically begin executing the tasks.

<Frame>
  <img />
</Frame>

After completing each task, Claude Code will mark it as complete and proceed to plan and explain the details of the next task.

<Frame>
  <img />
</Frame>

### 4. Task Results and Preview

After all tasks are completed, you will see the following messages in the terminal:

<Frame>
  <img />
</Frame>

At this point, you can open the `gravity-pong.html` file in your browser to view and play the game.

<Frame>
  <img />
</Frame>

### 5. Use Git with Claude Code

Claude Code makes Git operations conversational:

```bash Bash icon=terminal theme={"system"}
> what files have I changed?
```

```bash Bash icon=terminal theme={"system"}
> commit my changes with a descriptive message
```

You can also prompt for more complex Git operations:

```bash Bash icon=terminal theme={"system"}
> create a new branch called feature/quickstart
```

```bash Bash icon=terminal theme={"system"}
> show me the last 5 commits
```

```bash Bash icon=terminal theme={"system"}
> help me resolve merge conflicts
```

### 6. Improve the game

As we can see, this game needs improvement: the orbs' position overlaps with the paddle's position, which affects the gaming experience. Next, we will reposition the orbs to the top-right corner and add game restart functionality.

```bash Bash icon=terminal theme={"system"}
> Position the orbs in the top-right corner and support game restart functionality.
```

<Frame>
  <img />
</Frame>

This is the game preview after the improvement:

<Frame>
  <img />
</Frame>

## Try More Workflows

For reference, the following provides some prompt examples for different workflows:

* Code Refactoring

```bash Bash icon=terminal theme={"system"}
> Please refactor the current project using Next.js framework.
```

* Write Unit Tests

```bash Bash icon=terminal theme={"system"}
> Please write some unit tests for the pricing policy in the project.
```

* Update Documentation

```bash Bash icon=terminal theme={"system"}
> Please update the installation dependencies section in the README.
```

* Code Review

```bash Bash icon=terminal theme={"system"}
> Please review the changes and provide optimization suggestions.
```

## Common Commands

| Command                     | Description                       | Example                             |
| :-------------------------- | :-------------------------------- | :---------------------------------- |
| `claude`                    | Start interactive mode            | `claude`                            |
| `claude "task description"` | Run a one-time task               | `claude "fix the build error"`      |
| `claude -p "query"`         | Run one-off query, then exit      | `claude -p "explain this function"` |
| `claude -c`                 | Continue most recent conversation | `claude -c`                         |
| `claude -r`                 | Resume a previous conversation    | `claude -r`                         |
| `claude commit`             | Create a Git commit               | `claude commit`                     |
| `/clear`                    | Clear conversation history        | `> /clear`                          |
| `/help`                     | View available commands           | `> /help`                           |
| `exit` or Ctrl+C            | Exit Claude Code                  | `> exit`                            |


# CodeCompanion
Source: https://novita.ai/docs/guides/codecompanion

Supercharge Your Neovim Workflow with Novita AI and CodeCompanion.nvim.

CodeCompanion.nvim is a lightweight yet powerful Neovim plugin that connects advanced language models (LLMs) directly to your editor, enabling developers to work smarter and faster. With built-in support for Novita AI’s state-of-the-art models, this integration transforms your workflow by offering intelligent code suggestions, automated debugging, and streamlined refactoring tools.

In this comprehensive guide, we’ll walk you through the step-by-step process of setting up Novita AI with CodeCompanion.nvim. Learn how to optimize your Neovim setup and unlock the full power of AI-assisted coding for faster, smarter development.

## How to Leverage Novita AI with CodeCompanion.nvim

You can find the GitHub repository of CodeCompanion.nvim here: [olimorris/codecompanion.nvim](https://github.com/olimorris/codecompanion.nvim).

### Step 1: Generate Your Novita AI API Key

1. [Log in](https://novita.ai/user/login) to your Novita AI account.
2. Access the [Key Management Page](https://novita.ai/settings/key-management).
3. Create a new API key and copy it for later use.

### Step 2: Select a Model

1. Visit the[ Novita AI Model Library](https://novita.ai/models).
2. Choose a model that suits your needs (e.g., `meta-llama/llama-3.1-8b-instruct`).
3. Note down the model name.

### Step 3: Configure CodeCompanion

<Warning>
  We assume you have already installed the Neovim, and if not, you can install it by referring to the [Neovim Installation Guide](https://github.com/neovim/neovim/blob/master/INSTALL.md).
</Warning>

1. Open your [Neovim](https://neovim.io/) configuration file (`init.lua` or equivalent).

<Tip>
  The Neovim configuration file is typically located at: `~/.config/nvim/init.lua` (for macOS or Linux). And you can create this directory and file if they don't exist yet.
</Tip>

2. Install the CodeCompanion plugin.

You can install the plugin by referring to the [CodeCompanion.nvim Installation Guide](https://codecompanion.olimorris.dev/installation.html).

3. Add the following setup for CodeCompanion in your Neovim configuration file:

```lua theme={"system"}
require("codecompanion").setup({
    adapters = {
        novita = {
            base_url = "https://api.novita.ai/openai",
            api_key = "<YOUR_API_KEY>", -- Replace with your actual API key
            model = "meta-llama/llama-3.1-8b-instruct" -- Replace with your chosen model
        }
    }
})
```

4. Save and reload Neovim.

### Step 4: Verify Integration

1. Run the following command in Neovim:

```vim theme={"system"}
:checkhealth codecompanion
```

2. Ensure all dependencies are installed and configured correctly.

### Step 5: Test Novita AI Features

1. Open a code file in Neovim and start using CodeCompanion.nvim features such as inline suggestions or chat-based assistance.
2. For example:
   * Use shortcuts to trigger intelligent code completions.
   * Start a chat session by invoking `:CodeCompanionChat` for interactive problem-solving.


# Continue
Source: https://novita.ai/docs/guides/continue

Discover how Continue and Novita AI join forces to supercharge your software development workflow.

The powerful integration of Continue and Novita AI brings AI-powered development directly into your coding environment. This can help you access intelligent code suggestions, automated testing, and real-time pair programming without switching contexts. Novita AI excels at deploying AI models instantly through our intuitive API, scales effortlessly with our cost-effective GPU infrastructure, and maintains peak performance throughout your development process.

Our step-by-step guide walks you through Novita AI implementation on Continue, covering methods of using Continue.dev and integrating Novita AI with Continue using an API Key.

## How to use Continue.dev?

### VS Code

Step 1: Click `Install `to add the Continue extension from Visual Studio Marketplace.

Step 2: Click`Install`again in VS Code to complete the Continue extension setup.

Step 3: Move the Continue logo to your right sidebar for enhanced workflow access.

<Frame>
  <img alt="How to use Continue.dev-VS Code" />
</Frame>

### JetBrains

Step 1: Access IDE settings by pressing Ctrl + Alt + S in your JetBrains environment.

Step 2: Navigate to plugins and search Continue in the JetBrains marketplace.

Step 3: Click `Install`and find the Continue logo on your right toolbar.

<Frame>
  <img alt="How to use Continue.dev-JetBrains" />
</Frame>

## How to Integrate Novita AI with Continue Using an API Key

### Step 1: Open VS Code

<Frame>
  <img alt="How to Integrate Novita AI with Continue Using an API Key-Open VS Code" />
</Frame>

### Step 2: Search Continue

* Navigate to extensions and search Continue in the top search bar.

  <Frame>
    <img alt="How to Integrate Novita AI with Continue Using an API Key-Search Continue" />
  </Frame>

### Step 3: Install Continue

* Install the Continue extension by selecting the first result.

  <Frame>
    <img alt="How to Integrate Novita AI with Continue Using an API Key-Install Continue" />
  </Frame>

### Step 4: Click Continue

* Click the Continue icon on your left sidebar after installation completes.

  <Frame>
    <img alt="How to Integrate Novita AI with Continue Using an API Key-Click Continue" />
  </Frame>

### Step 5: Add your Chat Model (e.g. Novita AI)

* Select Novita AI from the provider menu in each marked location.

  <Frame>
    <img alt="How to Integrate Novita AI with Continue Using an API Key-Add your Chat Model 1" />
  </Frame>

### Step 6: Enter the API key from Novita AI and Get Connected

* Copy your Novita AI API Key from the user avatar section for authentication.

<Frame>
  <img alt="How to Integrate Novita AI with Continue Using an API Key- Enter the API key from Novita AI and Get Connected" />
</Frame>


# Cursor
Source: https://novita.ai/docs/guides/cursor

Learn how to integrate your Novita AI API keys with Cursor to unlock powerful AI models for programming. Get step-by-step instructions for seamless setup.

This guide will walk you through the steps needed to integrate Novita AI's models with Cursor. Using your own API keys, you can leverage Novita AI's large language models (LLMs) for custom AI messages in Cursor. This integration ensures that you can run AI-powered conversations and interactions while keeping full control over your API usage and cost.

## What is Cursor?

Cursor is a code editor built for programming with AI. It integrates with multiple large language models (LLMs) and allows you to input your own API keys, giving you full control over AI usage and costs. Whether you're coding or interacting with AI, Cursor streamlines the experience with features like smart autocomplete, auto-suggestions, and multi-model support, all within your development environment.

## Prerequisites

Before you begin the integration, ensure you have the following:

### **Novita AI LLM API Key**

* **Create an account**: Visit [Novita AI’s website](https://novita.ai/) and sign up for an account.
* **Generate your API Key**: After logging in, navigate to the [Key Management](https://novita.ai/settings/key-management) page to generate your API key. This key is essential to connect Novita AI’s models to Cursor.

  <Frame>
    ![Novita AI key management](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/dify-1.png)
  </Frame>
* **Select a Model Name**: You’ll need to copy the model name you want to use from Novita AI’s [Model Library](https://novita.ai/models/llm/deepseek-deepseek-r1). Some available models include:
  * `deepseek/deepseek-r1`
  * `deepseek/deepseek-v3`
  * `deepseek/deepseek-r1-distill-llama-70b`
  * `deepseek/deepseek-r1-distill-llama-8b`
  * `deepseek/deepseek-r1-distill-qwen-32b`
  * `deepseek/deepseek-r1-distill-qwen-14b`

    <Frame>
      <img alt="" />
    </Frame>

### **Download the Cursor App**

* Go to the official [Cursor website](https://cursor.com/) and download the Cursor app.
* Download Cursor App from [official website](https://cursor.com/)

## Integration Steps

### Connect Novita AI to Cursor

* Open the **Cursor App** and go to **Settings**.
* Navigate to the **Models** section.
* Uncheck all the other models that are pre-configured in Cursor.
* In the **Model Name** field, paste the model name you copied from the **Novita AI Model Library** (e.g., `deepseek/deepseek-r1`).
* Enter your **Novita AI API key** in the designated field.
* Click the **Verify** button to ensure your API key is correct. Once validated, the API key will be activated.
* In the **Open AI Base URL** field, override the default URL with the Novita AI endpoint:[`https://api.novita.ai/openai`](https://api.novita.ai/openai)

By following these steps, you’ll link your Novita AI API key with the Cursor app, enabling you to use Novita AI’s models through CursorStart a Chat with AI in Cursor.

### Start a Chat with AI in Cursor

To open the **Chat** interface, either:

* Click on **Toggle AI Pane**, or
* Press the keyboard shortcut **Ctrl + Alt + B** to start a new chat.

You can now send prompts and interact with the models you've added.

<Frame>
  <img alt="Start a Chat with AI in Cursor" />
</Frame>

## Notes on Cursor Features

* **Tab Completion, Apply from Chat, and Composer**: These features require specialized models and will not work with custom API keys. If you wish to use these specific features, consider switching to the default models provided by Cursor.


# DeepSearcher
Source: https://novita.ai/docs/guides/deepsearcher

Easily access module support from Novita AI on DeepSearcher to build advanced search applications.

[DeepSearcher](https://github.com/zilliztech/deep-searcher) is an open-source solution designed to transform private data search and reasoning by integrating cutting-edge large language models (LLMs) with vector databases such as Milvus. With support for LLMs and embedding models from Novita AI, this powerful configuration delivers unmatched accuracy and efficiency in private data search.

This step-by-step guide will walk you through how to quickly and easily configure Novita AI with DeepSearcher.

## How to use DeepSearcher with Novita

Step 1: Follow the example in `examples/basic_example.py` .

<Frame>
  <img alt="Step1followtheexample Jpe" />
</Frame>

Step 2: Add the following code below the line `config = Configuration()` :

```python theme={"system"}
config.set_provider_config("llm", "NOVITA", {"model": "deepseek/deepseek-r1-turbo"})
config.set_provider_config("embedding", "NovitaEmbedding", {"model": "baai/bge-m3"})
```

<Frame>
  <img alt="Step2addcodebelowunderthelineconfig=configuration Jpe" />
</Frame>

Step 3: Run `examples/basic_example.py` to execute the integration.

You'll get the following results:

<Frame>
  <img alt="Output1 Jpe" />
</Frame>

<Frame>
  <img alt="Output2 Jpe" />
</Frame>

<Frame>
  <img alt="Output3 Jpe" />
</Frame>

<Frame>
  <img alt="Output4 Jpe" />
</Frame>

<Frame>
  <img alt="Output5 Jpe" />
</Frame>


# Dify
Source: https://novita.ai/docs/guides/dify

Learn how to integrate Novita AI’s DeepSeek LLMs with Dify to build intelligent, multi-turn AI applications for smarter, context-aware conversations.

With the Novita AI & Dify integration, you gain seamless access to a comprehensive suite of Novita AI LLM models, including DeepSeek, Llama, Qwen, and more, enabling you to effortlessly build and deploy advanced AI applications tailored to your needs.

This guide will walk you through integrating Novita AI’s DeepSeek R1 model with the Dify platform, enabling you to create AI applications with advanced multi-turn reasoning capabilities. DeepSeek ensures your AI applications understand the context and can hold natural, dynamic conversations, making interactions feel human-like.

## What is Dify?

**Dify** is an open-source platform that simplifies the development of generative AI applications. Whether you’re building a chatbot, knowledge assistant, or other AI-powered tools, Dify makes it easy to integrate advanced language models like **Novita AI’s DeepSeek** and deploy them quickly, with minimal coding.

### Key Features of Dify:

* **Visual Development**: Dify’s drag-and-drop interface allows you to quickly create and deploy applications without extensive coding, reducing development time.
* **Knowledge Base Augmentation**: Enhance AI responses using **Retrieval-Augmented Generation (RAG)**. This feature connects your AI to internal documents or specialized data for accurate, contextual, and informative answers.
* **Workflow Expansion**: Integrate sophisticated logic into your AI apps with **functional nodes**. You can also connect third-party platforms for additional functionality.
* **Data Insights**: Track important performance metrics such as conversations, engagement, and response quality. Dify also integrates with specialized analytics platforms to monitor and improve AI performance.

## Prerequisites

Before you begin, make sure you have:

* **Novita AI LLM API Key**:
  * Visit [Novita AI’s website](https://novita.ai) and create an account.
  * After logging in, go to the [**Key Management**](https://novita.ai/settings/key-management) page to generate your **API Key**. This key is required to connect Novita AI’s models to Dify.

    <Frame>
      ![Novita AI key management](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/dify-1.png)
    </Frame>
* **Dify Account**:
  * Sign up for a Dify account at [Dify.ai](https://dify.ai) to start building AI applications.

## Integration Steps

### 1. Connect Novita AI to Dify

To connect Novita AI’s models with Dify:

* Log in to your Dify account.
* Click on your profile icon or name in the top-right corner and select **Settings**.
* In the **Model Providers** section, find **Novita AI** in the list.
* Paste your **Novita AI API Key** into the provided field and click **Save**.

With this integration, you’ll now have access to **DeepSeek R1** and other Novita AI models directly in Dify.

### 2. Create a DeepSeek AI Application

Once the integration is complete, you can create an application powered by DeepSeek R1:

* From the Dify homepage, click **Create Blank App** in the left sidebar.
* Choose **Chatbot** as the application type.

  <Frame>
    <img alt="Choose Chatbot as the application type" />
  </Frame>
* Give your app a name (e.g., “DeepSeek R1 Bot”) and click **Create**.

  <Frame>
    <img alt="Give your app a name and click Create." />
  </Frame>
* From the **Model** dropdown, select **Novita AI DeepSeek R1**.

  <Frame>
    <img alt="From the Model dropdown, select Novita AI DeepSeek R1" />
  </Frame>

### 3. Enable Knowledge Base for Enhanced Text Analysis

To improve your AI’s response accuracy, augment it with a **knowledge base**. Using **Retrieval-Augmented Generation (RAG)**, your AI will be able to access documents and generate more contextually relevant responses.

#### Step 1: Create a Knowledge Base

* In Dify, go to the **Knowledge Base** section and click **Create Knowledage**.

  <Frame>
    <img alt="go to the Knowledge Base section and click Create Knowledage." />
  </Frame>
* Upload documents (e.g., guides, FAQs, manuals) that provide relevant information for your AI to use.

  <Frame>
    <img alt="Upload documents " />
  </Frame>
* Use **Parent-Child Segmentation Mode** to maintain document hierarchy and context, ensuring DeepSeek processes the content correctly and understands relationships between sections.

  <Frame>
    <img alt="Use Parent-Child Segmentation Mode " />
  </Frame>

#### Step 2: Integrate the Knowledge Base into Your AI App

* In your chatbot’s **Context Settings**, click the option to **Add Knowledge Base**.

  <Frame>
    <img alt="Add Knowledge Base" />
  </Frame>
* Choose the documents you uploaded and integrate them into your app’s context to improve its responses.

#### Step 3: Share Your AI Application

Once your AI app is ready, you can share or embed it on external platforms:

<Frame>
  <img alt="Share Your AI Application" />
</Frame>

* **Public Link**: Generate a public link for others to access your AI application.
* **Embed on Websites**: Embed your app directly onto your website using Dify’s provided embed code.

### 4. Enhance AI Capabilities with Workflow-based Applications

If you need more than just a chatbot, Dify supports **workflow-based applications**. This allows you to add custom business logic and extend your AI’s capabilities by using functional nodes.

* Choose **Workflow** as the application type.
* Use **drag-and-drop nodes** to define your app’s behavior based on conditions or actions.
* Integrate external APIs (e.g., Google Search, databases) to provide richer data for your AI to process, enabling more insightful and automated responses.

  <Frame>
    <img alt="Workflow-based Applications" />
  </Frame>

Integrating Novita AI’s DeepSeek R1 with Dify provides a robust platform for creating advanced AI applications. With DeepSeek’s multi-turn reasoning, your AI App can have more dynamic, context-aware conversations, making it highly effective for building chatbots, knowledge assistants, and more.


# DocsGPT
Source: https://novita.ai/docs/guides/docsgpt

Seamlessly integrate Novita AI with DocsGPT to unlock powerful AI models for enhanced workflows.

DocsGPT simplifies documentation with AI-powered assistance. Integrating it with Novita AI enhances its performance, offering faster processing, scalable resources, and advanced model support for improved productivity.

This guide walks you through how to use DocsGPT with Novita AI based on the OpenAl APl, offering a way to query your content and get served customized answers.

## **How to use DocsGPT**

### **Prerequisites:**

**Docker:** Ensure you have [Docker ](https://docs.docker.com/engine/install/)installed and running on your system.

### **Launching DocsGPT (macOS and Linux)**

For macOS and Linux users, the easiest way to launch DocsGPT is using the provided `setup.sh` script. This script automates the configuration process and offers several setup options.

Step 1: Download the DocsGPT repository

* First, you need to download the DocsGPT repository to your local machine. You can do this using Git:

```bash theme={"system"}
git clone https://github.com/arc53/DocsGPT.git
cd DocsGPT
```

Step 2: Run the `setup.sh` script

* Navigate to the DocsGPT directory in your terminal and execute the `setup.sh` script:

```bash theme={"system"}
./setup.sh
```

This interactive script will guide you through setting up DocsGPT. It offers four options: using the public API, running locally, connecting to a local inference engine, or using a cloud API provider. The script will automatically configure your `.env` file and handle necessary downloads and installations based on your chosen option.

### **Launching DocsGPT (Windows)**

For Windows users, please refer to the [Docker Deployment documentation](https://docs.docsgpt.cloud/Deploying/Docker-Deploying) for detailed step-by-step instructions on setting up DocsGPT using Docker.

## **How to Integrate Novita AI API with DocsGPT**

Step 1: Log in to[ Novita AI ](https://novita.ai)and create an [API Key](https://novita.ai/settings/key-management)

<Frame>
  <img alt="images/3-1LogintoNovitaAI.png" />
</Frame>

<Frame>
  <img alt="images/3-2CreateanAPIKey.png" />
</Frame>

Step 2: Select option4 and connect cloud API provider in your terminal

<Frame>
  <img alt="images/2SelectOption4andConnectCloudAPIProvider.png" />
</Frame>

Step 3: Choose option7 Novita and enter the API key you just created

<Frame>
  <img alt="images/4ChooseOption7NovitaandEntertheAPIKeyYouJustCreated.png" />
</Frame>

Step 4: Wait for the startup process to complete

<Frame>
  <img alt="images/5WaitfortheStartupProcesstoComplete.png" />
</Frame>

Step 5: Access DocsGPT in your browser

* Once the setup is complete and Docker containers are running, navigate to [http://localhost:5173/](http://localhost:5173) in your web browser to access the DocsGPT web application.

<Frame>
  <img alt="images/6AccesstheApplicationathttp-localhost-5173.jpeg" />
</Frame>

Step 6: Stopping DocsGPT

* To stop DocsGPT, simply open a new terminal in the `DocsGPT` directory and run:

```bash theme={"system"}
docker compose -f deployment/docker-compose.yaml down
```

* (or the specific `docker compose` command shown at the end of the `setup.sh` execution, which may include optional compose files depending on your choices).


# Common Error Codes
Source: https://novita.ai/docs/guides/error



This document summarizes the most common error codes returned by the Novita API platform, along with definitions, causes, and recommended solutions to help users troubleshoot efficiently.

***

## Error Code 400

**Description**: Invalid request parameters.\
**Solution**:\
Review the error message details and check whether the parameter formats, field names, or value ranges comply with the API documentation.

***

## Error Code 401

**Description**: API Key is missing or incorrect.\
**Solution**:

* Ensure the API Key is provided in the request;
* Verify that the API Key is correct and has not expired;
* If using environment variables or config files, confirm they are being read correctly during execution.

***

## Error Code 403

**Description**: Access denied due to insufficient permissions.\
**Solution**:

* Verify that your account associated with the API Key has permission to access the requested model;
* Some models require identity verification to access:
  * Log in to the console and check your account’s verification status;
  * If not verified, complete identity verification first;
  * Alternatively, use an API Key from an already verified account.

***

## Error Code 429

**Description**: Rate limit exceeded (Too Many Requests).\
**Solution**:

* Check if the limit is due to **TPM** (tokens per minute) or **RPM** (requests per minute);
* Refer to the official Rate Limits documentation;
* To raise your rate limit, contact support or use a verified account.

***

## Error Code 503 / 504

**Description**: Backend timeout or service unavailable, often caused by high system load or throttling.

### Possible Causes:

* GPU or CPU overload on model service nodes;
* Long generation time on non-streaming requests exceeds gateway timeout;
* Failures in downstream services (e.g., Redis, model engine);
* Traffic shaping module activated surge protection and returned 503.

### Recommended Solutions:

**For API Users**:

* **Enable retry mechanism**: Use exponential backoff to prevent repeated overload;
* **Switch to streaming mode**: Streaming responses return tokens as they’re generated, lowering latency and timeout risk;
* **Optimize client settings**: Ensure `client_timeout` and `proxy_timeout` exceed 60 seconds;
* **Avoid peak periods**: For high concurrency scenarios, retry during off-peak hours.

**For Platform Ops**:

* Enhance monitoring and auto-scaling of model services;
* Adjust gateway-level `proxy_read_timeout` appropriately;
* Implement fine-grained throttling rules (e.g., priority queues, core-business prioritization);
* Use Prometheus + Alertmanager to trigger alerts on 503/504 spikes.

***

## Error Code 500

**Description**: Internal server error—typically caused by backend exceptions or model engine crashes.\
**Solution**:

* These issues usually require platform-side resolution. Contact support to investigate logs and system resources;
* Optionally, try switching models or falling back to a less resource-intensive configuration.

***

## Other Errors

For undefined or undocumented errors:

* First, refer to the `message` field in the API response;
* Next, check request logs or console traces;
* Finally, contact Novita support or submit a ticket for further assistance.


# FAQ
Source: https://novita.ai/docs/guides/faq



Here are some frequently asked questions about Novita AI. Before contacting our support team, please check the FAQs below to help you quickly find solutions.

## <Icon icon="microchip" /> GPU Instance

### 1. How to check the price of the GPU instances?

You can check the price of GPU instances and their configurations (container disk, volume disk, network volume, etc.) on the <a href="https://novita.ai/gpu-instance/pricing">Pricing Page</a>.

### 2. When does the billing for GPU instance start?

Billing starts when the instance status changes to "**Pulling**" status.

### 3. Introduction of container disk, volume disk, and network volume.

* **Container Disk**
  * Does not support dynamic expansion, can only specify capacity when creating an instance;
  * Mount directory: `/` (cannot be customized);
  * Data will be saved when saving the image;
  * Supports **60GB** free quota, charges will apply for the excess part, for details refer to: [Billing Instructions](/guides/gpu-instance-pricing)

* **Volume Disk**
  * Supports dynamic expansion;
  * Default mount directory: `/workspace` (customizable);
  * Data will **not** be saved when saving the image;
  * Read and write speed is the same as the container disk;
  * Volume Disk capacity requires additional charges, for details refer to: [Billing Instructions](/guides/gpu-instance-pricing).

* **Network Volume**
  * Supports dynamic expansion;
  * Default mount directory: `/network` (customizable);
  * Network volume has an independent lifecycle, unrelated to the instance, even if the instance is deleted, the network volume data still exists;
  * Overall read and write speed is slower than the container disk or volume disk (depending on specific usage);
  * Network volume capacity requires additional charges, for details refer to: [Billing Instructions](/guides/gpu-instance-pricing)

### 4. Why can't the instance be restarted after it stops?

After the instance stops, the resources belonging to the instance may have been preempted. In this case, it is recommended to first [save the image](/guides/gpu-instance-save-image) based on the target instance, and then create a new instance based on the saved image before.

<Warning>
  After saving the instance image, the data on the container disk will be saved with the image, but the data on the volume disk will not. It is recommended to use the [network volume](/guides/gpu-instance-quickstart-manage-network-volume) for data with high persistence requirements.
</Warning>

### 5. How to handle abnormal instance status?

First, try to troubleshoot the problem through the "System Logs" and "Instance Logs" of the instance. If the problem cannot be resolved, you can <a href="https://discord.gg/YyPRAzwp7P">contact us</a>.

<Frame>
  <img />
</Frame>

### 6. No instance specifications with a specified CUDA version.

CUDA versions are backward compatible. For example, if your service relies on CUDA version 12.1, you can choose an instance specification with a CUDA version greater than or equal to 12.1.

### 7. What is the maximum CUDA version supported by the platform?

You can check the allowed CUDA versions in the "Filter" module at the bottom right corner of the <a href="https://novita.ai/gpu-instance/console/explore">Explore</a>.

<Frame>
  <img />
</Frame>

### 8. How to diagnose the "Save Image" failure?

First, try to troubleshoot the problem through the logs of the <a href="https://novita.ai/gpu-instance/console/jobs">"Save Image"</a> task. If you are saving the image to a private repository address, please check whether your <a href="https://novita.ai/gpu-instance/console/settings">Container Registry Auth Configuration</a> is correct. If the problem cannot be resolved, you can <a href="https://discord.gg/YyPRAzwp7P">contact us</a>.

<Frame>
  <img />
</Frame>

### 9. Can dedicated IP be supported?

Yes. Currently, this capability is not open to the public. If you have such requirements, please <a href="https://discord.gg/YyPRAzwp7P">contact us</a>.

### 10. How to check the GPU usage of the instance?

Due to the PID isolation of Docker containers, the `nvidia-smi` command cannot be used to view the process. You can install the `py3nvml` library and use the shell command to check the GPU usage:

```bash theme={"system"}
# Install the py3nvml library.
$ pip install py3nvml
# Check the GPU usage.
$ py3smi
Fri Sep 20 12:17:39 2024
+-----------------------------------------------------------------------------+
| NVIDIA-SMI                        Driver Version: 550.54.14                 |
+---------------------------------+---------------------+---------------------+
| GPU Fan  Temp Perf Pwr:Usage/Cap|        Memory-Usage | GPU-Util Compute M. |
+=================================+=====================+=====================+
|   5 35%   28C    8   11W / 450W |   353MiB / 24564MiB |       0%    Default |
+---------------------------------+---------------------+---------------------+

+-----------------------------------------------------------------------------+
| Processes:                                                       GPU Memory |
| GPU        Owner      PID      Uptime  Process Name                   Usage |
+=============================================================================+
+-----------------------------------------------------------------------------+
```

## <Icon icon="credit-card" /> Payments

### 1. How can I avoid top-up failures?

Top-up failures are generally caused by two main reasons:

* **Rejection from the card issuer.** This may occur for the following reasons. Please check or contact your card issuer for details:
  * The corresponding payment channel is not activated.
  * The credit card has expired or been frozen.
  * The credit card balance is insufficient.
  * The card number is incorrect.
  * The security code is incorrect.

* **Risk control measures from the payment channel.** Please check and make any necessary adjustments:
  * The device ID is associated with a high number of cards.
  * The number of cards declined using this email address is very high.
  * The time since this card was first seen on the Stripe network with this device ID is very short.
  * The authorization rate associated with this email address is very low.
  * The name on the email address does not match the name on the card.


# Image Prewarm
Source: https://novita.ai/docs/guides/gpu-image-prewarm



The image prewarm feature supports synchronizing specified images from the source image repository to the cluster's local cache in advance. When instances start or elastic scaling is triggered in Serverless scenarios, images can be loaded directly from the local cache, avoiding remote repository pulls, improving startup performance and optimizing scaling response time.

<Info>
  By default: The system will select cache nodes within the cluster for image prewarm, and other nodes will pull images from these nodes via the internal network when starting instances or scaling.
</Info>

## Operation Steps

1. **Navigate to the Image Prewarm page**.

2. **Create a prewarm task**:

   Click the **"Create Image Prewarm Task"** button to enter the task creation page and complete the following configurations:

   * You can **manually enter the image address**, or **directly select a template** to load the images configured in the template.
   * If the image is located in a **non-public repository**, you need to select **pre-configured image repository authentication information**.
   * Select the target **prewarm region**.
   * Select the **card type** (GPU/accelerator card type) to be prewarmed; if not selected, the system will prewarm **all card types** by default.
   * Click **"Confirm Create"**, and the system will generate the image prewarm task.

3. **View task status**:

   You can view task progress and status in real-time in the **prewarm task list**.

4. **Create a template based on prewarmed images**:

   After prewarm is complete, you can directly **create an image template** based on the prewarmed images for subsequent instance or service deployment.

<Warning>
  Notes:

  During the image prewarm process, images will be pulled in parallel across multiple nodes in the cluster. Please confirm in advance whether the source image repository has **access rate limiting policies**.

  If rate limiting or bandwidth restrictions exist, the prewarm task may remain in an executing state for an extended period or fail.
</Warning>

## Quota Limits

Currently, the image prewarm feature supports **up to 5 concurrent prewarm tasks** by default, and the **image pull quota limit per task is 100 GB**.

If you need to adjust the number of concurrent tasks or the pull quota per task, please contact technical support for assistance with configuration.


# How to Choose a GPU?
Source: https://novita.ai/docs/guides/gpu-instance-choose-a-gpu



## Introduction

Novita AI offers a variety of GPU container cloud computing specifications to meet different virtualization capability needs, supporting a wide range of business applications and service scenarios.

Each computing specification is divided into several families based on hardware capability differences. Each family utilizes different Intel processors, CPU/memory ratios, GPU cards, cloud disk types, and network card virtualization methods to achieve differentiated computing, storage, and network performance. Each family is further subdivided into various instance specifications, with higher specifications offering stronger performance.

## How to Choose a GPU

| Model     | Memory   | Single Precision (FP32) | Half Precision (FP16) | Description                                                                                                                                                                                                                                             |
| --------- | -------- | ----------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tesla P40 | 24 GB    | 11.76 T                 | 11.76 T               | Based on the earlier Pascal architecture, suitable for tasks requiring large memory and using versions of cuda before 11.x.                                                                                                                             |
| TITAN XP  | 12 GB    | 12.15 T                 | 12.15 T               | An older model under the Pascal architecture, a suitable entry-level choice for beginners.                                                                                                                                                              |
| 1080 Ti   | 11 GB    | 11.34 T                 | 11.34 T               | A product of the same generation as TITAN XP, suitable for entry-level users, though its 11 GB memory may be limiting in some cases.                                                                                                                    |
| 2080Ti    | 11 GB    | 13.45 T                 | 53.8 T                | Turing architecture GPU, offers good performance, especially suitable for mixed precision computing scenarios, with a high cost-performance ratio.                                                                                                      |
| V100      | 16/32 GB | 15.7 T                  | 125 T                 | A high-end product designed for professional computing scenarios, especially suitable for high half-precision computing tasks, leading the previous generation of compute cards.                                                                        |
| 3060      | 12 GB    | 12.74 T                 | About 24 T            | If the memory of 1080 Ti does not meet the requirements, 3060 provides a good alternative, especially suitable for beginners and requires the use of cuda 11.x.                                                                                         |
| A4000     | 16 GB    | 19.17 T                 | About 76 T            | Balanced memory and computing power, suitable for intermediate users. Requires the use of cuda 11.x environment.                                                                                                                                        |
| 3080Ti    | 12 GB    | 34.10 T                 | About 70 T            | Excellent performance output makes it an ideal choice for scenarios not requiring extreme memory. Requires the use of cuda 11.x.                                                                                                                        |
| A5000     | 24 GB    | 27.77 T                 | About 117 T           | High-performance GPU, suitable for scenarios requiring large memory and high half-precision computing power. Requires the use of cuda 11.x.                                                                                                             |
| 3090      | 24 GB    | 35.58 T                 | About 71 T            | Provides excellent performance and memory quota, suitable for a wide range of application scenarios, the first choice for cost-effectiveness. Requires the use of cuda 11.x.                                                                            |
| A40       | 48 GB    | 37.42 T                 | 149.7 T               | Huge memory capacity, computing power close to 3090, suitable for computing tasks with extremely high memory requirements. Requires the use of cuda 11.x.                                                                                               |
| A100 SXM4 | 40/80 GB | 19.5 T                  | 312 T                 | Top professional computing GPU, with huge memory and half-precision computing capability, suitable for the most complex computing tasks. Supports NVLink, optimized for multi-card parallel computing. Requires the use of cuda 11.x.                   |
| 4090      | 24 GB    | 82.58 T                 | 165.2 T               | A new generation high-performance GPU, provides excellent single precision and half precision computing capability, suitable for scenarios with high cost-performance ratio. Apart from relatively small memory, it has almost no obvious shortcomings. |

## Notes

* GPU instance prices and configuration options (system disk, data disk, public IP, etc.) can be viewed on the console page. These prices are for reference only, and the actual order on the Novita AI console shall prevail.
* Instance specifications vary by region and availability zone; please refer to the actual display on the console.
* GPU instances can only be changed within the same specification family. For detailed information, please refer to the document on modifying instance specifications.
* For purchasing instances, please refer to the sections on purchasing GPU container cloud computing instances and purchasing high-performance computing GPU instances.

**Actual supply is subject to the [GPU Market](https://novita.ai/gpu-instance/console/explore).**


# Edit Instance
Source: https://novita.ai/docs/guides/gpu-instance-edit-instance



When you need to modify the "Volume Disk Size", "Expose HTTP Ports" or "Expose TCP Ports" of a GPU instance, you can use <a href="https://novita.ai">Novita AI</a> **Edit Instance** feature. Here's how to use this feature.

1. Go to the <a href="https://novita.ai/gpus-console/instances">Instances</a> page and locate the instance you want to modify. Click "More Operations - Edit".

2. In the pop-up edit window, modify the instance configuration and click the "Save" button.

<Tip>
  * You can modify the instance configuration while the instance is running, and the instance will not restart after modification;
  * Changes are expected to take effect within 1 minute.
</Tip>

<Warning>
  * The "Volume Disk Size" configuration can only be increased, not decreased;
  * New "Expose HTTP Ports" and "Expose TCP Ports" cannot conflict with ports that are already in use.
</Warning>


# Jupyter Lab
Source: https://novita.ai/docs/guides/gpu-instance-jupyterlab



Jupyter Lab is an interactive notebook that supports over 40 programming languages. Jupyter Lab is an open-source web application that facilitates the creation and sharing of literate programming documents, supporting real-time code execution, mathematical equations, visualizations, and markdown editing.

The official templates of GPU instance come with a pre-installed Jupyter Lab environment. To enable this feature, please checkout the **"Start Jupyter Notebook"** option when deploying the instance.

<Warning>
  Some official templates may not support the Jupyter Lab environment. If you have specific requirements, please reach out to us through the <a href="https://discord.gg/YyPRAzwp7P">Discord channel</a>.
</Warning>

## Accessing Jupyter Lab

While the GPU instance is running, you can click the **"Connect"** button in the bottom right corner of the instance, then click **"Connect to Jupyter Lab"** in the pop-up window to access the Jupyter Lab webpage deployed on that instance.


# Overview
Source: https://novita.ai/docs/guides/gpu-instance-overview



<u>**GPU Instance**</u> provides cost-effective, accessible high-performance computing with easy GPU access, making it ideal for complex AI tasks. Users benefit from on-demand rental, optimizing both efficiency and cost-effectiveness.

## Features

* Rich **built-in templates** help you quickly deploy GPU instances for AI tasks out of the box;
* Start a GPU instance **in seconds**, helping you quickly handle traffic peaks;
* Provides nodes in **multiple global regions** to deploy GPUs closer to your users for minimal latency;
* Provides **free local storage** and allows you to attach network volume, also provides free network transfer;
* Billing is **accurate to the second**, charging only for the actual running time of the GPU container instances;
* **Affordable pricing** save costs by up to 50%.

## Terminology

* **Container Image**: Docker-compatible OCI image reference, supporting both public registries and private repositories with authentication.
* **Environment Variables**: Runtime configuration key-value pairs injected into containers for dynamic configuration and secrets management.
* **HTTP/TCP Ports**: Network endpoints exposed by containers for communication. HTTP ports (e.g., 80, 443) for web services, TCP ports for general network protocols.
* **Container Disk**: Root filesystem partition containing OS and system binaries. Mounted as read-write at container startup.
* **Volume Disk**: High-performance ephemeral storage directly attached to the GPU instance. Optimized for I/O intensive workloads but non-persistent across instance restarts.
* **Network Volume**: Network-attached storage service that allows users to access and manage data through a network. Data can be stored on remote servers and accessed from any device.

If you have any questions, you can first check the [FAQs for GPU Instance](/guides/faq#gpu-instance).


# GPU Instance Pricing
Source: https://novita.ai/docs/guides/gpu-instance-pricing



## On-Demand Pricing

### Introduction

On-Demand Pricing is designed to offer users the flexibility to access computational resources without any long-term commitments or upfront costs. This pricing model is ideal for users who require compute power on an as-needed basis, whether for short-term projects, variable workloads, or unpredictable processing demands.

### Billing Structure of On-Demand Pricing

Includes "computing resources" and "storage resources", you can view the billing details on the <a href="https://novita.ai/gpu-instance/console/billing">Billing Explore</a>.

#### 1. Computing Resources

**<u>Cost = Instance Unit Price × Billing Duration × Number of Cards</u>**

<Tip>
  * Billing duration is accurate to the second and settled hourly;

  * You can view the unit prices of various instance specifications on the <a href="https://novita.ai/gpu-instance/console">GPU Instance Explore</a>;

  * The billing start time is when the instance is successfully created and enters the **pulling** state, and the billing stop time is when the instance is stopped.
</Tip>

#### 2. Storage Resources

| **Billing Item** | **Billing Method** | **Explanation**                                                                            | **Billing Logic**                                      |
| ---------------- | ------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
| Container Disk   | Pay-as-you-go      | Supports **60GB** free quota, charges for the excess based on capacity and usage duration. | Unit price for the excess capacity: **\$0.005/GB/day** |
| Volume Disk      | Pay-as-you-go      | Charges based on capacity and usage duration.                                              | Unit price: **\$0.005/GB/day**                         |
| Network Volume   | Pay-as-you-go      | Charges based on capacity and usage duration.                                              | Unit price: **\$0.002/GB/day**                         |

### Advantages of On-Demand Pricing for Different Scenarios

* **Short-Term Projects**: For projects with a limited duration, On-Demand Pricing allows you to align your compute costs with the project timeline.

* **Variable Workloads**: If your workloads fluctuate, On-Demand Pricing provides the flexibility to scale up or down as needed without incurring fixed costs.

* **Testing and Development**: For testing new applications or developing code, On-Demand Pricing offers a cost-effective way to access necessary compute resources without long-term financial commitments.


# Connect to Instance
Source: https://novita.ai/docs/guides/gpu-instance-quickstart-connect-to-instance



## Connect via SSH with an SSH Key (Recommended)

### Linux/MacOS

1. On Ubuntu or Mac, use the following command to generate an RSA SSH public/private key pair:

```bash theme={"system"}
ssh-keygen -t rsa
```

2. Force the agent to load the new private key and verify that it's loaded:

```bash theme={"system"}
ssh-add; ssh-add -l
```

3. Retrieve the content of your SSH public key:

```bash theme={"system"}
cat ~/.ssh/id_rsa.pub
```

1. Paste the content into the "SSH Public Keys" section in the <a href="https://novita.ai/gpu-instance/console/settings">Console - Settings</a>.

Here is an example of an SSH public key:

```txt theme={"system"}
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDopiaR1Q6Na6dW1QTK7hMuHVi+gXqutY5pUvrWCgeyjcBtBLHejxDQjdNt+qWQRORK/fZzrmyA8/ghani0rZlGPN3bYw1RXFHitt+bD1jVgtJzOmjMQdpMVALnZASQMoQQcCqVJ8PG5Xc08TciACS7S/Ltz3VdZfIq1tih969GCzCe3sctSFBuTwqUDnyrQ6iqSBhPSfQS7nCC/CwzMi3rDg0JzW2NHzIBsbvy0gdXy1ZtC4kkCr7/lUWAgZLk52v3s2CTXCg6QXnhWx+Q/dHOJVAEEucY4o8bo4rF4Bj+ifgEHFtUEfoK9+yj3OLbWfpIxyzhHK+nNXz3UaOMSC8D ultra@novita.ai
```

### Windows

Generating SSH keys on Windows requires additional command-line tools like Cmder, with operations similar to those on Linux.

Since most machine learning and AI programming is performed on Linux, we strongly recommend installing a Linux subsystem on your Windows machine, such as WSL.

### Common Issues

If you encounter a "Permission denied (publickey)" error, it might be due to:

* Attempting to run SSH/SCP from within an instance;
* Incorrect key setup or using the wrong/unmatched key;
* The SSH key format used is incorrect or unsupported;
* The private key wasn't correctly loaded with `ssh-add`; you may need to use the `-i` parameter;
* New or updated keys not taking effect for already created resources;
* Incorrect SSH key permission settings.

Use the `ssh -vv` command for detailed information.

## Connect via SSH with a Password

Go to <a href="https://novita.ai/gpu-instance/console/instances">Console - Instances</a>, select the instance you want to connect to, click "Connect", and copy the "Basic SSH Terminal" command to your terminal. Log in using the password provided in the pop-up window.


# Create Instances
Source: https://novita.ai/docs/guides/gpu-instance-quickstart-create-instances



## Step 1: Prepare Docker Image

You need to package your runtime environment into a Docker image and upload it to an image repository in advance. Currently, <a href="https://novita.ai">Novita AI</a> supports specifying both "public image repository" and "private image repository" (including access credentials).

Additionally, you can use the <a href="https://novita.ai/gpus-console/explore">public image templates</a> provided by the platform to quickly create instances.

## Step 2: Create GPU Instance

After entering the <a href="https://novita.ai/gpus-console/explore">Explore</a> page, select an image template and choose your desired specifications, then click the "Deploy" button.

<Tip>
  You can use the "Filter" feature in the bottom right corner to find the instance specifications you need.
</Tip>

## Configuration Explanation

| Configuration          | Description                                                                                                                                                                                                                                |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CPU                    | The number of vCPU cores you select for your instance. The vCPU count will affect the instance's processing capability and performance, with more vCPUs being beneficial for compute-intensive applications.                               |
| Memory                 | The size of RAM in GB specified for each instance. Memory is crucial for running applications and overall instance speed.                                                                                                                  |
| Supported CUDA Version | CUDA is a parallel computing platform and API model developed by NVIDIA. Choosing the correct CUDA version is important if you plan to run applications optimized for NVIDIA GPUs, such as machine learning and 3D rendering applications. |
| Ports                  | You can expose your ports according to your service needs. The platform will provide port mapping services for your service. Multiple ports can be entered, separated by commas.                                                           |
| Environment Variables  | Used to specify parameters for the operating system's runtime environment. You can set environment variables here directly, and the platform will automatically initialize them for you.                                                   |
| GPU Instance Pricing   | More details can be found at [GPU Instance Pricing](/guides/gpu-instance-pricing).                                                                                                                                                         |
| Base Image             | The Docker image provided by the platform.                                                                                                                                                                                                 |
| Custom Image           | The Docker image name you specify, which the platform will default to pulling from DockerHub. Ensure that the image name is entered correctly.                                                                                             |

After the instance is successfully created, you can refer to the [Manage Instances](/guides/gpu-instance-quickstart-manage-instances) guide to access the instance.


# Manage Instances
Source: https://novita.ai/docs/guides/gpu-instance-quickstart-manage-instances



In this guide, we will show you how to stop or terminate your instances.

## Stop an Instance

* Go to <a href="https://novita.ai/gpu-instance/console/instances">Console - Instances</a>;
* In the instance list, select the instance you need to stop;
* Click the **More Operations - Stop** button;
* Confirm the **Stop** action in the pop-up window.

<Warning>
  After stopping your instance, you can start it later, but it is not guaranteed to be available because the resources may have been preempted, and all data will be saved for 7 days at most.

  Please note that you will be **charged for volume storage** while your instance is stopped. If you won't start this instance later, please terminate it to avoid disk charges.
</Warning>

## Terminate an Instance

* In the instance list, find the instance and click the **More Operations** button;
* In the action menu, select the **Terminate** option;
* Confirm the **Terminate** action in the pop-up window.

<Warning>
  Please note that terminating an instance will permanently delete the data on the instance.
</Warning>


# Manage Network Volume
Source: https://novita.ai/docs/guides/gpu-instance-quickstart-manage-network-volume



"Network Volume" can provide multi-instance shared storage space for GPU container instances, with the characteristics of large capacity and multi-instance sharing. Network volumes are billed on a per-second basis. Please note that if your account is in arrears and no instances are running, your Network Volume will be **released 3 days later**. Network Volume is provided in the pursuit of running tasks using its GPUs and is **not meant to be a long-term backup solution**. It is highly advisable to continually back up anything you want to save offsite locally or to a cloud provider.

## Create Network Volume

1. Go to the <a href="https://novita.ai/gpu-instance/console/storage">Console - Storage</a> page and click on "+ New Network Volume".
2. Select the "Data Center" where the Network Volume will reside. The "Data Center" is tightly bound to your instance and currently does not support cross-Data Center mounting of Network Volumes to instances.
3. Enter the "Volume Name" and capacity in GB for the Network Volume partition, and click "Save" after verifying that the details are correct.

## Edit Network Volume

You can edit your Network Volume through the console as follows:

1. Go to the <a href="https://novita.ai/gpu-instance/console/storage">Console - Storage</a> page, locate the Network Volume you plan to expand, and click the "..." button in the upper right corner.
2. Click the "Edit" button to modify the Network Volume configuration.

<Warning>
  Please note that we currently only support the expansion of the Network Volume capacity, and the storage capacity cannot be less than the size before modification.
</Warning>

## Delete Network Volume

You can delete your Network Volume through the console as follows:

1. Go to the <a href="https://novita.ai/gpu-instance/console/storage">Console - Storage</a> page, locate the Network Volume you plan to delete, and click the "..." button in the upper right corner.
2. Click the "Delete" button to delete the Network Volume.

<Warning>
  Please note that deletion of a Network Volume is irreversible. Once deleted, all data stored on it **will be permanently lost**, please proceed with caution.
</Warning>


# Preparations
Source: https://novita.ai/docs/guides/gpu-instance-quickstart-preparations



## Preliminary Preparations

Before deploying a new GPU instance, please be aware of the following points:

* First, create your Novita AI account and ensure you have enough credits in your account. Refer to our [Quickstart](/guides/quickstart) for more information.
* Confirm that you have read and understood the product introductions, pricing, features, usage restrictions, and terms of service for [Novita AI](https://novita.ai).
* Understand the billing methods for GPU instances. Here's some guidance: [GPU Instance Pricing](/guides/gpu-instance-pricing).


# Save Image
Source: https://novita.ai/docs/guides/gpu-instance-save-image



<a href="https://novita.ai">Novita AI</a> GPU instance supports the "Save Image" feature, which allows you to export the current instance as a Docker image.

For **instance migration scenarios**, you can first save the current instance as an image, and then specify the exported Docker image address when creating an instance in another region.

1. To ensure the integrity of the exported Docker image, please make sure the instance has been exited. You can also stop the instance by clicking "More Operations - Stop".

2. For instances in the "exited" state, you can click the "More Operations - Save Image" button at the bottom right corner of the instance to save the image.

3. In the pop-up form, input the "Image Path", for private repositories, include the "Container Registry Credentials", and then click the "Save" button.

4. You can view the progress of the "Save Image" job on the <a href="https://novita.ai/gpus-console/jobs">Jobs</a> page.


# Upgrade Instance
Source: https://novita.ai/docs/guides/gpu-instance-upgrade-instance



When you need to modify the "Docker Image", "Container Start Parameters" or "Container Environment Variables" of a GPU instance, you can use <a href="https://novita.ai">Novita AI</a> **Upgrade Instance** feature. Here's how to use this feature.

<Tip>
  * While upgrading the instance, the instance will be reset, but the resources originally occupied by the instance **will be retained**.
</Tip>

<Warning>
  * When upgrading the instance, the platform will save your system disk data, but if the data is incompatible with the upgraded instance system, the data cannot be successfully restored to the new instance.
</Warning>

1. Go to the <a href="https://novita.ai/gpus-console/instances">Instances</a> page and locate the instance you want to upgrade. Click "More Operations - Upgrade".

2. In the pop-up edit dialog, modify the image and other configurations, and click the "Upgrade" button after confirming everything is correct.


# Overview
Source: https://novita.ai/docs/guides/gpus-overview



Novita AI **GPUs** provides:

* **[GPU Instance](/guides/gpu-instance-overview):** A dedicated virtual machine with full control over GPU hardware, ideal for long-running, predictable workloads.
* **[Serverless GPUs](/guides/serverless-gpus-overview):** A fully managed, on-demand GPU service that dynamically scales and charges based on actual usage, perfect for burstable and sporadic tasks.

<CardGroup>
  <Card title="Create your first GPU instance" icon="box" href="/guides/gpu-instance-quickstart-preparations">
    Here's a guide on how to create, manage and use your first GPU instance.
  </Card>

  <Card title="Set up a Serverless Endpoint from Scratch" icon="box" href="/guides/serverless-gpus-quickstart-preparations">
    To learn about the Serverless GPUs, follow this guide.
  </Card>
</CardGroup>


# Helicone
Source: https://novita.ai/docs/guides/helicone

Get Started with Helicone Monitoring for Novita AI: Step-by-Step LLM Integration Guide.

Novita AI's integration with Helicone's observability platform marks a significant advancement in LLM development. This combination provides developers with a streamlined inference platform and comprehensive monitoring capabilities, transforming how teams work with Large Language Models.

By leveraging Helicone's monitoring tools through Novita AI's infrastructure, developers gain access to robust analytics and performance insights. This guide will walk you through setting up Helicone AI Gateway, obtaining Novita AI API Key, and integrating Novita AI API with Helicone.

## **Setting Up Helicone AI Gateway**

Getting started with [Helicone AI Gateway ](https://www.helicone.ai/)only requires four steps: creating an account, generating an API key, picking your preferred integration method, and sending your first request.

### **Step1: Create an Account**

* After account creation, you can move forward with the setup process.

### **Step 2: Generate an API Key**

* Go to Settings: Locate and select your organization name in the upper-left corner, then select `Settings` from the dropdown.

  <Frame>
    <img alt="Step 2- Generate an API Key-Go to Settings-page" />
  </Frame>
* Select the API Key Tab.

  <Frame>
    <img alt="Step 2- Generate an API Key-Select the API Key Tab-page" />
  </Frame>
* Generate New Key: Click on `Generate new key`. During the API key creation process, you can enable `read` and `write` permissions. Write keys enable access to Helicone through our proxy service, feedback or any other Helicone service when calling  `POST` or using our gateway.

  <Frame>
    <img alt="Step 2- Generate an API Key-Select the API Key Tab-page" />
  </Frame>

### **Step 3: Pick Your Preferred Integration Method**

* Choose your provider from the options below to view specific instructions.

### **Step 4: Send Your First Request**

* Upon receiving your requests, you will see them in the `Requests` tab.
* Your new request will be immediately visible on the `Dashboard`.

## **Obtaining Novita AI API Key**

To obtain your [Novita AI API key](https://novita.ai/), simply log into your account, navigate to the LLM API key management section, and add the necessary credits to begin.

### **Step 1: Go to Novita AI and Log in**

* Novita AI offers multiple login options: use your Google or GitHub credentials for instant account creation, or register directly with your email address.

  <Frame>
    <img alt="" />
  </Frame>

### **Step 2: Manage Novita AI LLM API Key**

Novita AI ensures secure API access by using Bearer authentication, where your API key is included in the header format "Authorization: Bearer \{\{API Key}}".

* Your first login generates a default key automatically - access all keys through the "Key Management" section in settings.
* Additional keys can be created using the “+ Add New Key” function.

  <Frame>
    <img alt="" />
  </Frame>

## **How to Integrate Novita AI API with Helicone**

The Novita AI-Helicone integration requires three simple steps: accessing both platform accounts, configuring your API keys as environment variables (HELICONE\_API\_KEY and NOVITA\_API\_KEY), and updating the base URL with proper authentication headers.

### **Step 1: Log into your Novita AI Account and Helicone Account**

* Access your [Novita AI](https://novita.ai/) account or create one, then generate your API key directly from the dashboard.
* Sign in to [Helicone](https://www.helicone.ai/) (or create a new account) to obtain your API key.

### **Step 2: Set HELICONE\_API\_KEY and NOVITA\_API\_KEY as Environment Variables**

```bash theme={"system"}
$env:HELICONE_API_KEY="<your API key>"
$env:NOVITA_API_KEY="<your API key>"
```

### **Step 3: Modify the Base URL and Add Auth Headers**

* Update the following Novita AI URL with the Helicone Gateway URL.

[`https://api.novita.ai`](https://api.novita.ai) -> [`https://novita.helicone.ai`](https://novita.helicone.ai)

* Then add the following headers for authentication:

```bash theme={"system"}
* curl -H "Authorization: Bearer <your API key>"
```

**Example**

* Now you can use this simple fetch call to interact with any Novita AI model.
* ```bash theme={"system"}
  curl \
  --header 'Authorization: Bearer <NOVITA_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "deepseek/deepseek-r1",
    "messages": [
      {
        "role": "user",
        "content": "What language is mostly spoken in Singapore?"
      }
    ]
  }' \
  --url https://novita.helicone.ai/v3/chat/completions
  ```


# Hugging Face
Source: https://novita.ai/docs/guides/huggingface

Get a simple guide to streamline AI deployment with Novita AI + Hugging Face. 

Novita AI's integration with Hugging Face Platform enables advanced serverless inference capabilities. This provides direct access to Hub model pages through optimized infrastructure, offering developers a streamlined setup experience. With full support for Hugging Face's JavaScript and Python SDKs, Novita AI simplifies model deployment and scaling without infrastructure management.

Our comprehensive guide walks you through Novita AI implementation on Hugging Face, covering both web interface and SDK integration methods.

## **Using Novita AI on Hugging Face in the Website UI**

### **Step 1: Configure API Keys**

* Access your account settings dashboard to configure your API keys.
* Input your Novita AI authentication credentials into the Hugging Face platform.

  <Frame>
    <img alt=" Configure API Keys in Hugging Face" />
  </Frame>

### **Step 2: Choose Inference API Modes**

* Custom Key Mode: Calls are sent directly to the inference provider, utilizing your own API key.
* HF-Routed Mode: In this mode, no provider token is required. Charges are applied to your Hugging Face account instead of the provider's account.

  <Frame>
    <img alt="Choose Inference API Modes" />
  </Frame>

### **Step 3: Explore Compatible Providers on Model Pages**

* Model pages display third-party inference providers compatible with the selected model (the ones that are compatible with the current model, sorted by user preference).

  <Frame>
    <img alt=" Explore Compatible Providers on Model Pages in Hugging Face" />
  </Frame>

## **Using Huggingface\_hub from Python by the Client SDKs**

### **Step 1: Install** [**Huggingface\_hub**](https://github.com/huggingface/huggingface_hub)

```python theme={"system"}
pip install huggingface_hub
```

### **Step 2: Call model API in Python**

```python theme={"system"}
from huggingface_hub import InferenceClient


client = InferenceClient(
    provider="novita",
    api_key="xxxxxxxxxxxxxxxxxxxxxxxx", # optional, required from 2nd calling, get from https://novita.ai/settings/key-management
)

# an example question
messages = [
    dict(
        role="user",
        content='Sally (a girl) has 3 brothers. Each brother has 2 sisters. How many sisters does Sally have?',
    ),
]
completion = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-R1",
    messages=messages,
    max_tokens=512,
)

print(completion.choices[0].message)
```

## **Using Huggingface\_hub from JS by the Client SDKs**

```json theme={"system"}
import { HfInference } from "@huggingface/inference";

const client = new HfInference("xxxxxxxxxxxxxxxxxxxxxxxx");

const chatCompletion = await client.chatCompletion({
    model: "deepseek-ai/DeepSeek-R1",
    messages: [
        {
            role: "user",
            content: "What is the capital of France?"
        }
    ],
    provider: "novita",
    max_tokens: 500
});

console.log(chatCompletion.choices[0].message)
```


# Introduction
Source: https://novita.ai/docs/guides/introduction



Novita provides simple, reliable, and cost-effective cloud infrastructure for running AI models. We empower developers with scalable, production-ready model inference so they can focus on building AI applications.

<CardGroup>
  <Card title="Quickstart" icon="toolbox" href="/guides/quickstart">
    Set up your account and get started.
  </Card>

  <Card title="Model APIs" icon="box" href="/guides/model-apis-overview">
    Ship top AI models with a simple API.
  </Card>

  <Card title="GPUs" icon="microchip" href="/guides/gpus-overview">
    Need help running your own models? Get dedicated GPUs.
  </Card>

  <Card title="Agent Sandbox" icon="box" href="https://novita.ai/docs/guides/sandbox-overview">
    Securely run AI-generated code with full isolation and seamless agent integration.
  </Card>
</CardGroup>


# Run Kohya_SS GUI on Novita AI
Source: https://novita.ai/docs/guides/kohya_ss-gui

Transform Your Stable Diffusion Experience with Kohya_SS GUI on Novita AI. 

Kohya\_SS GUI offers a user-friendly Gradio interface for Kohya's Stable Diffusion trainers. It has strong Linux support through community installations, with limited but possible macOS compatibility. Combining Novita AI with Kohya\_SS GUI streamlines AI model training workflows, removing hardware limitations and creating an optimized environment for diffusion model fine-tuning.

This guide will show you how to deploy and run Kohya\_SS GUI on Novita AI's platform.

## How to Run Kohya\_ss: GUI on Novita AI

Step 1: Access GPU Instance Control Panel

* Navigate to the `GPU menu` in the top navigation bar.
* Click `Get Started` to enter the GPU Instance control interface.

<Frame>
  ### &#x20; <img alt="images/Step1AccessGPUInstanceControlPanel.jpg" />
</Frame>

Step 2: Select Kohya\_ss:GUI Template

* Locate and select the `Kohya_ss:GUI` official template.
* Click `Deploy` button under the 4090 GPU card option to enter the instance creation page.

<Frame>
  ### &#x20; <img alt="images/Step2SelectKohya_ssGUITemplate.png" />
</Frame>

Step 3: Configure Disk Parameters and Review Configuration Settings

* On the left panel, adjust the disk settings as needed:
  * Set appropriate system disk size;
  * Configure local disk capacity based on your storage needs.
* Check the right panel for configuration options:
  * Verify image settings are correct;
  * Confirm startup commands are properly configured;
  * Ensure ports and environment variables meet your requirements.
* Confirm all settings are correct and then click the `Next` button to advance to the final confirmation page.

<Frame>
  ### &#x20; <img alt="images/Step3ConfigureDiskParametersandReviewConfigurationSettings.png" />
</Frame>

Step 4: Proceed to Confirmation and Deploy Your Instance

* Review the complete instance configuration summary.
* Verify the cost details displayed on this page.
* Click `Deploy` to initiate the deployment process.

<Frame>
  ### &#x20; <img alt="images/Step4ProceedtoConfirmationandDeployYourInstance.png" />
</Frame>

Step 5: Wait as the System Creates Your Instance

<Frame>
  ### &#x20; <img alt="images/Step5WaitastheSystemCreatesYourInstance.jpg" />
</Frame>

Step 6: Monitor Deployment Progress and Track Image Download

* After deployment, the system will automatically redirect you to the instance management page.
* Your new instance will display `Pulling` status while downloading the image.
* After clicking the arrow icon next to your instance name, the instance details panel will be expanded with the image download progress in real-time.
* Once image downloading completes, instance will change status from `Pulling` to `Running`.

<Frame>
  ### &#x20; <img alt="images/Step6MonitorDeploymentProgressandTrackImageDownload.png" />
</Frame>

Step 7: Check Instance Logs

* Click the `Logs` button on your instance and select `Instance Logs` from the available options.
* Observe the Kohya\_ss service startup process in the logs and wait for confirmation that all services have loaded successfully.

<Frame>
  ### &#x20; <img alt="images/Step7CheckInstanceLogs.png" />
</Frame>

Step 8: Connect to Your Instance

* Close the logs view when ready and click the `Connect` button to view connection options.
* View various connection methods: SSH, TCP, and HTTP of your instance.
* For Kohya\_SS GUI access, focus on the HTTP connection details. Therefore, in the Connection Options section, click `Connect to HTTP Service` and access to a new browser tab or window.

<Frame>
  ### &#x20; <img alt="images/Step8-1ConnecttoYourInstance.png" />
</Frame>

<Frame>
  <img alt="images/Step8-2ConnecttoYourInstance.png" />
</Frame>

Step 9: Begin Using Your Instance

* Allow a few moments for the web interface to fully load and get ready to run Kohya\_ss:GUI on Novita AI.

<Frame>
  <img alt="images/Step9BeginUsingYourInstance.png" />
</Frame>


# LangChain
Source: https://novita.ai/docs/guides/langchain

Integrate Novita AI with LangChain to build intelligent, language model-driven applications. Learn setup, API usage, and function calling workflows.

This guide will walk you through the process of integrating Novita AI with LangChain. You’ll be able to use Novita AI’s powerful language models with LangChain’s robust tools for building language model-driven applications.

## What is LangChain?

LangChain is a framework for developing applications powered by language models. It enables applications that:

* **Are context-aware**: LangChain connects a language model to sources of context (such as prompt instructions, few-shot examples, content to ground its response in, etc.).
* **Reason**: LangChain allows language models to reason—whether it’s determining how to answer based on provided context or deciding what actions to take.

With LangChain, you can build complex workflows, enhance model behavior with external knowledge, and create intelligent systems that can interact dynamically with users and data sources.

## Prerequisites

Before you start, make sure you have the following:

* **Novita AI LLM API Key**:
  * Visit [Novita AI’s website](https://novita.ai/) and create an account.
  * After logging in, go to the [**Key Management**](https://novita.ai/settings/key-management) page to generate your **API Key**. This key is required to connect Novita AI’s models to LangChain.

    <Frame>
      ![Novita AI key management](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/dify-1.png)
    </Frame>
* A basic understanding of Node.js, JavaScript, and how to use environment variables.

## Integration

### Step 1: Set the API Key

For most environments, set the environment variable `NOVITA_API_KEY` as follows:

```bash theme={"system"}
export NOVITA_API_KEY="your-api-key"
```

Make sure to replace `your-api-key` with the actual key you got from Novita AI.

### Step 2: Install the Required Packages

To integrate Novita AI with LangChain, you need to install the `@langchain-community` package, which includes the Novita AI integration.

Choose one of the following commands to install the necessary packages:

**Using npm:**

```bash theme={"system"}
npm install @langchain/community @langchain/core
```

**Using yarn:**

```bash theme={"system"}
yarn add @langchain/community @langchain/core
```

**Using pnpm:**

```bash theme={"system"}
pnpm add @langchain/community @langchain/core
```

### Step 3: Instantiate the Novita AI Model

Once you’ve installed the necessary packages, you can instantiate the Novita AI model using the `ChatNovitaAI` class.

Here’s an example that demonstrates how to do that:

```javascript theme={"system"}
import { ChatNovitaAI } from "@langchain/community/chat_models/novita";

const llm = new ChatNovitaAI({
  model: "deepseek/deepseek-r1", // You can choose the model you want to use
  temperature: 0, // Optional: Controls randomness. 0 is deterministic.
  // other parameters can be set here...
});
```

### Step 4: Invoke the Model for Chat Completion

Once the model is instantiated, you can use it to generate chat completions by invoking it with a message.

Here's an example of how to send a message and get a response:

```javascript theme={"system"}
const aiMsg = await llm.invoke([
  {
    role: "system",
    content: "You are a helpful assistant that translates English to French. Translate the user sentence.",
  },
  {
    role: "human",
    content: "I love programming.",
  },
]);

console.log(aiMsg.content); // The model’s response will be printed here
```

### Step 5: Chain Model with Prompt Templates

LangChain allows you to create powerful workflows by chaining models together with prompt templates. This can be especially useful when you want to reuse the same format for multiple inputs.

Here’s an example where we chain the Novita AI model with a custom prompt template for translating between languages:

```javascript theme={"system"}
import { ChatPromptTemplate } from "@langchain/core/prompts";

// Create a template for translating languages
const prompt = ChatPromptTemplate.fromMessages([
  [
    "system",
    "You are a helpful assistant that translates {input_language} to {output_language}.",
  ],
  ["human", "{input}"],
]);

// Chain the prompt with the model
const chain = prompt.pipe(llm);

// Invoke the chain with inputs for translation
const result = await chain.invoke({
  input_language: "English",
  output_language: "German",
  input: "I love programming.",
});

console.log(result.content); // The translated text will be printed here
```

### Step 6: Customize the Workflow

You can modify the temperature, add more messages, or tweak other parameters depending on your use case. LangChain is highly flexible, allowing you to design complex interactions by chaining multiple prompts, adding conditional logic, or working with different models.

## Function Calling with Novita AI and LangChain

To implement function calling (or tool usage) with Novita AI's LLM API, LangChain can serve as a convenient framework. In this example, we’ll create a simple math application that allows the model to perform addition and multiplication operations via function calls.

💡 While this guide uses LangChain for convenience, implementing function calling doesn’t require any specific framework. The key is designing the right prompts to make the model understand and correctly invoke functions. LangChain is used here simply to streamline the implementation.

### Prerequisites

First, install the required packages:

```bash theme={"system"}
pip install langchain-openai python-dotenv
```

### Setting Up the Environment

Create a `.env` file in your project root and add your Novita AI API key:

```
NOVITA_API_KEY=your_api_key_here
```

### Implementation Steps

1. **Define the Tools**

First, let’s create two simple mathematical tools using LangChain's `@tool` decorator:

```python theme={"system"}
from langchain_core.tools import tool

@tool
def multiply(x: float, y: float) -> float:
    """Multiply two numbers together."""
    return x * y

@tool
def add(x: int, y: int) -> int:
    """Add two numbers."""
    return x + y

tools = [multiply, add]
```

2. **Create the Tool Execution Function**

Next, implement a function to execute the tools:

```python theme={"system"}
from typing import Any, Dict, Optional, TypedDict
from langchain_core.runnables import RunnableConfig

class ToolCallRequest(TypedDict):
    name: str
    arguments: Dict[str, Any]

def invoke_tool(
    tool_call_request: ToolCallRequest, 
    config: Optional[RunnableConfig] = None
):
    """Execute the specified tool with given arguments."""
    tool_name_to_tool = {tool.name: tool for tool in tools}
    name = tool_call_request["name"]
    requested_tool = tool_name_to_tool[name]
    return requested_tool.invoke(tool_call_request["arguments"], config=config)
```

3. **Set Up the LangChain Pipeline**

Create a chain that uses Novita AI's LLM to select and prepare tool calls:

```python theme={"system"}
from langchain_openai import ChatOpenAI
from langchain_core.output_parsers import JsonOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.tools import render_text_description
import os

def create_chain():
    """Create a chain that uses the specified LLM model to select and prepare tool calls."""
    model = ChatOpenAI(
        model="meta-llama/llama-3.3-70b-instruct",
        api_key=os.getenv("NOVITA_API_KEY"),
        base_url="https://api.novita.ai/openai",
    )
    
    rendered_tools = render_text_description(tools)
    system_prompt = f"""\
    You are an assistant that has access to the following set of tools. 
    Here are the names and descriptions for each tool:

    {rendered_tools}

    Given the user input, return the name and input of the tool to use. 
    Return your response as a JSON blob with 'name' and 'arguments' keys.

    The `arguments` should be a dictionary, with keys corresponding 
    to the argument names and the values corresponding to the requested values.
    """

    prompt = ChatPromptTemplate.from_messages(
        [("system", system_prompt), ("user", "{input}")]
    )

    return prompt | model | JsonOutputParser()
```

4. **Create the Main Processing Function**

Implement the main function that processes mathematical queries:

```python theme={"system"}
def process_math_query(query: str):
    """Process a mathematical query by using an LLM to select the appropriate tool and execute it."""
    chain = create_chain()
    message = chain.invoke({"input": query})
    result = invoke_tool(message, config=None)
    return message, result
```

5. **Usage Example**

Here’s how to use the implementation:

```python theme={"system"}
if __name__ == "__main__":
    message, result = process_math_query(
        "meta-llama/llama-3.3-70b-instruct", 
        "what's 3 plus 1132"
    )
    print(result)  # Output: 1135
```


# Langflow
Source: https://novita.ai/docs/guides/langflow

Six steps to achieve Novita AI's LLM API integration with Langflow, enabling faster application deployment and simplified workflows.

The integration of Langflow and Novita AI creates a powerful development environment that streamlines the creation of multi-agent and RAG applications. This combination leverages Langflow's intuitive visual flow builder for rapid prototyping while enabling seamless workflow design and testing capabilities. Novita AI enhances this ecosystem with its advanced Model APIs, featuring industry-leading language models including Llama, DeepSeek, and Mistral.

This step-by-step guide will help you access Novita AI LLM API on Langflow and start building AI-powered applications.

## **Accessing Novita AI LLM API on Langflow**

### Step 1: **Expand the "Models" Tag**

* Find and expand the "Models" section on Langflow’s sidebar.

  <Frame>
    <img alt="Expand the “Models” Tag on Langflow" />
  </Frame>

### **Step 2: Drag Novita AI to Your Canvas**

* Select and position the "Novita AI "component from the sidebar onto the Langflow canvas area.

  <Frame>
    <img alt="Drag Novita AI to Your Canvas on Langflow" />
  </Frame>

### **Step 3: Create a Global Variable for the Novita AI API Key**

* Set up Langflow authentication instantly by adding your Novita AI API Key as a global variable.

  <Frame>
    <img alt="Create a Global Variable for the Novita AI API Key on Langflow" />
  </Frame>

### Step 4: **Get your Novita AI API Key**

* Generate Your API Keys Instantly on the [Key Management page](https://novita.ai/settings/key-management).

### Step 5: **Select a Model**

* Choose from Novita AI's powerful language models: DeepSeek, Llama, and Mistral and then select the perfect AI model for your project needs.

  <Frame>
    <img alt="Select a Model on Langflow" />
  </Frame>

### **Step 6: Start Building Your AI App**

* Create advanced AI functionality by connecting Novita AI components to your Langflow workflow system.


# Langfuse
Source: https://novita.ai/docs/guides/langfuse

Step-by-step guide to set up Langfuse with Novita AI to develop, monitor, evaluate, and debug AI applications.

With Langfuse, your team can collaboratively debug, analyze, and iterate on their LLM applications built with Novita AI. Its fully integrated features streamline the development workflow, enhancing efficiency and accelerating progress.

This guide shows you how to integrate Novita AI with Langfuse. Novita AI's API endpoints for chat, language and code are fully compatible with OpenAI's API. This allows us to use the Langfuse OpenAI drop-in replacement to trace all parts of your application.

# Prerequisites

Before you begin, make sure you have the following:

* Novita AI LLM API Key:
  * Visit Novita AI’s website to create an account.
  * Log in and go to the Key Management page to generate your API Key, which is essential for integrating Novita AI’s models with Langfuse.

    <Frame>
      <img alt="" />
    </Frame>
* Langfuse Account:
  * Sign up for a Langfuse account on the official [Langfuse](https://langfuse.com)website to start building powerful AI applications.

# Integration Steps

## Step 1: Install Dependencies

Ensure you have installed all the required Python packages:

```shell theme={"system"}
pip install openai langfuse
```

## Step 2: Set Up Environment Variables

```python theme={"system"}
import os

# Get keys for your project from the project settings page
# https://cloud.langfuse.com

os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-..." # DOCS EXAMPLE KEYS
os.environ["LANGFUSE_SECRET_KEY"] = "sk-..." # DOCS EXAMPLE KEYS
os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com" # 🇪🇺 EU region
# os.environ["LANGFUSE_HOST"] = "https://us.cloud.langfuse.com" # 🇺🇸 US region


# Get your Novita AI API key from the project settings page
os.environ["NOVITA_API_KEY"] = "..."
```

## Step 3: Langfuse OpenAI drop-in Replacement

In this step we use the native [OpenAI drop-in replacement](https://langfuse.com/docs/integrations/openai/python/get-started) by importing `from langfuse.openai import openai`.

To start using Novita AI with OpenAI's client libraries, pass in your Novita AI API key to the `api_key` option, and change the `base_url` to [`https://api.novita.ai/openai:`](https://api.novita.ai/openai)

```python theme={"system"}
# instead of import openai:
from langfuse.openai import openai

client = openai.OpenAI(
  api_key=os.environ.get("NOVITA_API_KEY"),
  base_url="https://api.novita.ai/openai",
)
```

**Note:** The OpenAI drop-in replacement is fully compatible with the [Low-Level Langfuse Python SDKs](https://langfuse.com/docs/sdk/python/low-level-sdk) and [`@observe() decorator`](https://langfuse.com/docs/sdk/python/decorators) to trace all parts of your application.

## Step 4: Run An Example

The following code cell shows how to use the traced OpenAI client to call Novita AI's chat model. All API calls will be seamlessly traced by Langfuse.

```python theme={"system"}
client = openai.OpenAI(
  api_key=os.environ.get("NOVITA_API_KEY"),
  base_url="https://api.novita.ai/openai",
)

response = client.chat.completions.create(
  model="meta-llama/llama-3.1-70b-instruct",
  messages=[
    {"role": "system", "content": "Act like you are a helpful assistant."},
    {"role": "user", "content": "What are the famous attractions in San Francisco?"},
  ]
)

print(response.choices[0].message.content)

San Francisco, one of the most iconic cities in the world, is home to a plethora of famous attractions that cater to all interests and ages. Here are some of the most popular attractions in San Francisco:

1. **Golden Gate Bridge**: An engineering marvel and a symbol of San Francisco, the Golden Gate Bridge is a must-visit attraction. Take a walk or bike ride across the bridge for spectacular views of the city and the Bay.
2. **Alcatraz Island**: Explore the infamous former prison turned national park, which once housed notorious inmates like Al Capone. Take a ferry to the island and enjoy a guided tour of the prison and its surroundings.
3. **Fisherman's Wharf**: A bustling waterfront district, Fisherman's Wharf is famous for its seafood restaurants, street performers, and stunning views of the Bay Bridge and Alcatraz Island. Don't miss the sea lions at Pier 39!
4. **Chinatown**: San Francisco's Chinatown is one of the largest and oldest in the United States. Explore the colorful streets, try some authentic Chinese cuisine, and shop for unique souvenirs.
5. **Golden Gate Park**: A sprawling urban park that's home to several attractions, including the de Young Museum, the California Academy of Sciences, and the Japanese Tea Garden.
6. **Cable Cars**: A classic San Francisco experience, the cable cars offer a fun and historic way to explore the city. Take a ride on the Powell-Mason line to Fisherman's Wharf, or the Powell-Hyde line to Lombard Street.
7. **Lombard Street**: Known as the "crookedest street in the world," Lombard Street is a scenic and winding road that offers stunning views of the city.
8. **Union Square**: A vibrant public square in the heart of the city, Union Square is surrounded by shopping, dining, and entertainment options. Catch a show at the historic Curran Theatre or take a stroll through the square.
9. **The Painted Ladies**: A row of colorful Victorian houses on Alamo Square, the Painted Ladies are a iconic symbol of San Francisco's architecture. Take a photo in front of these stunning homes.
10. **The Exploratorium**: A museum of science, art, and human perception, the Exploratorium is a great place to learn and have fun. With interactive exhibits and stunning views of the Bay, it's a must-visit for families and science enthusiasts.
11. **Pier 39**: A popular shopping and dining destination, Pier 39 offers stunning views of the Bay Bridge, Alcatraz Island, and the sea lions that call the pier home.
12. **The de Young Museum**: A fine arts museum located in Golden Gate Park, the de Young Museum features a diverse collection of art and cultural exhibitions from around the world.

These are just a few of the many famous attractions in San Francisco. Whether you're interested in history, culture, science, or entertainment, San Francisco has something for everyone.
```

## Step 5: See Traces in Langfuse

After running the example model call, you can view the traces in Langfuse. These traces provide detailed information about your Novita AI API calls, including:

* Request parameters (model, messages, temperature, etc.)
* Response content
* Token usage statistics
* Latency metrics

[Public example trace link in Langfuse](https://cloud.langfuse.com/project/cm7ua5l6e05wlad07qr6ce2wn/traces/039cc8b2-dba0-479f-9cd6-63672bc08c71?timestamp=2025-03-06T02%3A15%3A15.184Z).


# LiteLLM
Source: https://novita.ai/docs/guides/litellm

Supercharge Your AI Applications with Novita AI and LiteLLM.

LiteLLM is an open-source Python library and proxy server that provides access, spend tracking, and fallbacks to over 100 LLMs through a unified interface in the OpenAI format. By leveraging Novita AI's cutting-edge models, the integration with LiteLLM empowers your AI applications with seamless model switching, dependable fallbacks, and intelligent request routing—all through a standardized completion API that ensures compatibility across multiple providers.

This guide will show you how to quickly get started with integrating Novita AI and LiteLLM, enabling you to set up this powerful combination and streamline your workflow with ease.

## **How to Integrate Novita AI with LiteLLM**

### Step 1: Install LiteLLM

* Install the LiteLLM library using pip to create a unified interface for working with different language models.

```bash theme={"system"}
pip install litellm
```

### Step 2: Set Up Your API Credentials

* Log in to [the key management page](https://novita.ai/settings/key-management) in Novita AI and click `Add New Key`to generate your API key.

  <img alt="Visitthekeymanagementpageandselect Add New Keytogenerateyour AP Ikey Pn" />

### Step 3: Structure Your Basic API Call

* Create a completion request to Novita AI's models through LiteLLM's standardized interface.

```python theme={"system"}
from litellm import completion
import os

## set ENV variables. Visit https://novita.ai/settings/key-management to get your API key
os.environ["NOVITA_API_KEY"] = "novita-api-key"

response = completion(
  model="novita/deepseek/deepseek-r1",
  messages=[{ "content": "Hello, how are you?","role": "user"}]
)
```

### Step 4: Implement Streaming for Better User Experience

* Enable streaming mode for more interactive applications or when handling longer responses.

```python theme={"system"}
from litellm import completion
import os

## set ENV variables. Visit https://novita.ai/settings/key-management to get your API key
os.environ["NOVITA_API_KEY"] = "novita_api_key"

response = completion(
  model="novita/deepseek/deepseek-r1",
  messages = [{ "content": "Hello, how are you?","role": "user"}],
  stream=True,
)
```


# LlamaIndex
Source: https://novita.ai/docs/guides/llamaindex

Effortlessly integrate Novita AI with LlamaIndex to build intelligent, data-powered applications.

Designed for optimal indexing and retrieval, LlamaIndex excels in delivering high efficiency for applications requiring precise and fast data access. By combining [Novita AI](https://novita.ai/) with LlamaIndex, you will unlock key benefits such as superior data retrieval accuracy, unmatched scalability, and cost-effective performance.

This guide will walk you through how to use LlamaIndex with Novita AI based on the OpenAl APl, offering smarter, scalable, and highly efficient AI solutions that drive innovation and deliver exceptional results for developers.

## **How to Integrate Novita AI API with LlamaIndex**

Step 1: Visit [Model Library](https://novita.ai/llm-api) on Novita AI and select a model of interest.

<Frame>
  <img alt="images/Step1VisitModelLibraryonNovitaAIandselectamodelofinterest.png" />
</Frame>

Step 2: Navigate to the demo page of the chosen model and click the `Code` button on the right.

<Frame>
  <img alt="images/Step2NavigatetothedemopageofthechosenmodelandclicktheCodebuttonontheright.png" />
</Frame>

Step 3: Copy the model’s name and make a note of it.

<Frame>
  <img alt="images/Step3Copythemodel’snameandmakeanoteofit.png" />
</Frame>

Step 4: [Log in ](https://novita.ai/user/login)to the Novita platform.

<Frame>
  <img alt="images/Step4LogintotheNovitaplatform.png" />
</Frame>

Step 5: After logging in, go to the platform’s [settings page](https://novita.ai/settings).

<Frame>
  <img alt="images/Step5Afterloggingin,gototheplatform’ssettingspage.png" />
</Frame>

Step 6: Create a new [API key](https://novita.ai/settings/key-management) and copy it for service authentication.

<Frame>
  <img alt="images/Step6CreateanewAPIkeyandcopyitforserviceauthentication.png" />
</Frame>

Step 7: Install `llama_index` and related Python libraries by running:

<Frame>
  <img alt="images/Step7Installllama_indexandrelatedPythonlibrariesbyrunning.png" />
</Frame>

Step 8: Write Python code and set the model name and API key as parameters in the NovitaAI class.

<Frame>
  <img alt="images/Step8WritePythoncodeandsetthemodelnameandAPIkeyasparametersintheNovitaAIclass.png" />
</Frame>

Step 9: Run the code to get the output.

<Frame>
  <img alt="images/Step9Runthecodetogettheoutput.png" />
</Frame>

For more examples, refer to the documentation: [llama\_index/llama-index-integrations/llms/llama-index-llms-novita at main · run-llama/llama\_index](https://github.com/run-llama/llama_index/tree/main/llama-index-integrations/llms/llama-index-llms-novita).


# Anthropic SDK Compatibility
Source: https://novita.ai/docs/guides/llm-anthropic-compatibility



Novita AI provides a compatibility API that allows you to use the Anthropic SDK with Novita AI models. This is useful if you are already using the Anthropic SDK and want to switch to Novita AI models.

## Supported Models

Currently, only the following models are compatible with the Anthropic SDK:

<AnthropicCompatibilityModels />

## Quick Start Guide

This guide demonstrates how to use the Anthropic SDK with the Novita AI models step by step.

### 1. Install the Anthropic SDK

<CodeGroup>
  ```bash Python icon="python" theme={"system"}
  pip install anthropic
  ```

  ```bash TypeScript icon="js" theme={"system"}
  npm install @anthropic-ai/sdk
  ```
</CodeGroup>

### 2. Initialize the Client

The Anthropic SDKs are designed to pull the API key and base URL from the environmental variables: `ANTHROPIC_API_KEY` and `ANTHROPIC_BASE_URL`. Also, you can supply the parameters to the Anthropic client when initializing it.

<Tip>
  You can view and manage your API keys on the [settings page](https://novita.ai/settings/key-management?utm_source=getstarted).
</Tip>

* Using Environment Variables

<CodeGroup>
  ```bash Bash icon="terminal" theme={"system"}
  export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
  export ANTHROPIC_API_KEY="<YOUR_NOVITA_API_KEY>"
  ```
</CodeGroup>

* Set the parameters while initializing the Anthropic client

<CodeGroup>
  ```python Python icon="python" theme={"system"}
  import anthropic

  client = anthropic.Anthropic(
      base_url="https://api.novita.ai/anthropic",
      api_key="<YOUR_NOVITA_API_KEY>",
      # Rewrite header
      default_headers={
          "Content-Type": "application/json",
          "Authorization": "Bearer <YOUR_NOVITA_API_KEY>",
      }
  )
  ```

  ```typescript TypeScript icon="js" theme={"system"}
  import Anthropic from "@anthropic-ai/sdk";

  const anthropic = new Anthropic({
      baseURL: "https://api.novita.ai/anthropic",
      apiKey: "<YOUR_NOVITA_API_KEY>",
      // Rewrite header
      defaultHeaders: {
        "Content-Type": "application/json",
        Authorization: `Bearer <YOUR_NOVITA_API_KEY>`,
      }
  });
  ```
</CodeGroup>

### 3. Call the API

<CodeGroup>
  ```python Python icon="python" theme={"system"}
  import anthropic

  # Initialize the client, if you already set `ANTHROPIC_BASE_URL` and `ANTHROPIC_API_KEY` 
  # in the environment variables, you can omit the `api_key` and `base_url` parameters.
  client = anthropic.Anthropic(
      base_url="https://api.novita.ai/anthropic",
      api_key="<YOUR_NOVITA_API_KEY>",
      # Rewrite header
      default_headers={
          "Content-Type": "application/json",
          "Authorization": "Bearer <YOUR_NOVITA_API_KEY>",
      }
  )

  message = client.messages.create(
      model="moonshotai/kimi-k2-instruct",
      max_tokens=1000,
      temperature=1,
      system=[
          {
              "type": "text",
              "text": "You are a world-class poet. Respond only with short poems."
          }
      ],
      messages=[
          {
              "role": "user",
              "content": [
                  {
                      "type": "text",
                      "text": "Why is the ocean salty?"
                  }
              ]
          }
      ]
  )

  print(message.content)
  ```

  ```typescript TypeScript icon="js" theme={"system"}
  import Anthropic from "@anthropic-ai/sdk";

  // Initialize the client, if you already set `ANTHROPIC_BASE_URL` and `ANTHROPIC_API_KEY` 
  // in the environment variables, you can omit the `baseURL` and `apiKey` parameters.
  const anthropic = new Anthropic({
      baseURL: "https://api.novita.ai/anthropic",
      apiKey: "<YOUR_NOVITA_API_KEY>",
      // Rewrite header
      defaultHeaders: {
        "Content-Type": "application/json",
        Authorization: `Bearer <YOUR_NOVITA_API_KEY>`,
      }
  });

  const msg = await anthropic.messages.create({
    model: "moonshotai/kimi-k2-instruct",
    max_tokens: 1000,
    temperature: 1,
    system="You are a world-class poet. Respond only with short poems.",
    messages: [
      {
        role: "user",
        content: [
          {
            type: "text",
            text: "Why is the ocean salty?"
          }
        ]
      }
    ]
  });

  console.log(msg);
  ```
</CodeGroup>


# Large Language Models
Source: https://novita.ai/docs/guides/llm-api



## Model Capabilities

Large Language Models (LLMs) are types of AI model built using deep learning and natural language processing techniques. After being trained on massive amounts of text data, they can understand, generate, and process human language. LLMs have the following main capabilities:

* **Text Generation**

  LLMs can generate logically coherent content based on context and adjust output style as needed.
* **Language Understanding**

  LLMs can accurately understand the meaning of input text and support context-aware conversation.
* **Text Translation**

  LLMs are capable of cross-lingual understanding and generation, enabling translation between different languages.
* **Knowledge-based Q\&A**

  With extensive knowledge basis, LLMs can answer questions across domains such as culture, science, and history.
* **Code Understanding & Generation**

  LLMs can understand and generate code (Python, Java, C++ and so on), detect code errors, and offer suggestions.
* **Text Classification & Summarization**

  LLMs can understand complex sentences, categorize and extract information, and summarize key points.

## Model Selection

On the [LLM Service Page](https://novita.ai/models), you can browse the list of supported models, learn model basics and pricing. Click on a specific model, and you can open its detail page for an online demo. After trying different models with your task, you can compare and choose the most suitable one.

## API Integration

Novita AI provides fast, reliable APIs for open-source models, combining the ease and reliability of top-tier LLM APIs with the flexibility and cost-efficiency of open source LLMs.

* [ChatCompletion](https://platform.openai.com/docs/guides/text-generation/chat-completions-api): Supports both streaming and non-streaming modes.
* [Completion](https://platform.openai.com/docs/guides/text-generation/completions-api): Also supports streaming and non-streaming modes.

If you're already using OpenAI's `ChatCompletion` or `Completion` API, simply set your base URL to: api.novita.ai/openai , get and set your API key, update the model name as needed to start using LLM services.

<Tip>
  For how to get API key, refer to the [API Key Management](/api-reference/basic-authentication).
</Tip>

## Code Examples

### Python

<CodeGroup>
  ```python ChatCompletion theme={"system"}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.novita.ai/openai",
      api_key="<Your API Key>",
  )

  model = "deepseek/deepseek-r1"
  stream = True  # or False
  max_tokens = 512

  chat_completion_res = client.chat.completions.create(
      model=model,
      messages=[
          {
              "role": "system",
              "content": "you are a professional AI helper.",
          },
          {
              "role": "user",
              "content": "Where can the example of GPU provided by novita ai be adapted?",
          }
      ],
      stream=stream,
      max_tokens=max_tokens,
  )

  if stream:
      for chunk in chat_completion_res:
          print(chunk.choices[0].delta.content or "", end="")
  else:
      print(chat_completion_res.choices[0].message.content)
  ```

  ```python Completion theme={"system"}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.novita.ai/openai",
      api_key="<Your API Key>",
  )

  model = "deepseek/deepseek-r1"
  stream = True  # or False
  max_tokens = 512

  completion_res = client.completions.create(
      model=model,
      prompt="Where can the example of GPU provided by novita ai be adapted?",
      stream=stream,
      max_tokens=max_tokens,
  )

  if stream:
      for chunk in completion_res:
          print(chunk.choices[0].text or "", end="")
  else:
      print(completion_res.choices[0].text)
  ```
</CodeGroup>

### Curl

<CodeGroup>
  ```bash ChatCompletion theme={"system"}
  export API_KEY="<Your API Key>"

  curl "https://api.novita.ai/openai/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${API_KEY}" \
    -d '{
      "model": "deepseek/deepseek-r1",
      "messages": [
          {
              "role": "system",
              "content": "you are a professional AI helper."
          },
         {
              "role": "user",
              "content": "Where can the example of GPU provided by novita ai be adapted?"
          }
      ],
      "max_tokens": 512
  }'
  ```

  ```bash Completion theme={"system"}
  export API_KEY="<Your API Key>"

  curl "https://api.novita.ai/openai/v1/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${API_KEY}" \
    -d '{
      "model": "deepseek/deepseek-r1",
      "prompt": "Where can the example of GPU provided by novita ai be adapted?",
      "max_tokens": 512
  }'
  ```
</CodeGroup>

## Key Parameters

### Base Parameters

`model`: The target LLM. See the full list on the [LLM Service Page](https://novita.ai/models).

### Messages

> ChatCompletion Only

`messages`: Inputs and outputs when interacting with LLM. Each message belongs to one character. Messages can help you get better outputs, you can try different methods to get better results.

* `content`: message content.
* `role`: Define the speaker:
  * `system`: Set the AI's role, telling model its role or behavior.
  * `user`: The user's input.
  * `assistant`: The AI's response. Users can give examples of output in advance, telling model how to answer current request.
* `name` (optional): separating message writers with same role.

### Prompt

> ChatCompletion Only

`prompt`: Instruction text for generating a completion written by user to LLM to tell the model their task clearly.

### Output Control

Different combination of parameters can help the model to generate more satisfying content.

**Diversity of Text**

> 'temperature' and 'top\_p' can control the diversity of generated text, we advice you to set only one of them. The bigger the value you set, The more diverse the text will be.  The smaller the value you set, The more accurate the text will be.

* `temperature`: Controls randomness. Higher = more creative.
* `top_p`: Nucleus sampling. Controls cumulative probability.
* `top_k`: Limits candidate token count.

**Repetition Penalties**

* `presence_penalty`: Controls repeated tokens of the texts. If one token has already existed in the text, penalty will come, this results in more token in the text.
* `frequency_penalty`: Control token frequency of the texts. Every time the same token exist in the text, penalty will come, which results in less same token in the future in the text.
* `repetition_penalty`: Penalizes or encourages repetition.

### Output Limits

* `max_tokens`: Max tokens in one response. Content after this value in the text will be truncated.
* `stream`: Whether to use streaming. For those with long outputs, we advice you to use streaming mode to prevent timeout error:
  * `true`: Streamed, partial results as they are generated.
  * `false`: Full result after processing.
* `stop`: Strings that will terminate generation when encountered.


# Batch Inference
Source: https://novita.ai/docs/guides/llm-batch-api



The Batch API for Large Language Models enables asynchronous processing of numerous inference requests and is fully compatible with the OpenAI API standard.

The Batch API is a cost-effective solution when immediate inference results are unnecessary. It provides a higher rate limits than online calls, ensuring results are delivered within a reasonable timeframe of 48 hours.

This API is ideal for:

* Conducting evaluations and data analysis.
* Classifying extensive datasets.
* Generating document summaries in an offline mode.

Supported Models:

<BatchApiModels />

## Quick Start

### 1. Preparing Batch Files

The Batch API uses .jsonl format files as input, with each line representing the details of an API inference request. Available endpoints include `/v1/chat/completions` and `/v1/completions`.

<Warning>
  Set the `endpoint` parameter to `/v1/chat/completions` or `/v1/completions` for OpenAI API compatibility.
</Warning>

Each request must include a unique `custom_id` to locate inference results in the output file after batch completion. Parameters in the `body` field of each line are sent as actual inference request parameters to the endpoint.

<Warning>
  All requests within a single batch JSONL file must target the same model. Do not mix requests for different models in one batch.
</Warning>

Below is an example input file containing 2 requests:

```JSON theme={"system"}
{"custom_id": "request-1", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "user", "content": "Hello, world!"}], "max_tokens": 400}}
{"custom_id": "request-2", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}
```

### 2. Upload Batch Input File

Upload the batch input file to ensure it can be accurately referenced when creating a batch. Use the Files API to upload your .jsonl file and set the purpose to `batch`. Note that the file will be retained for 15 days.

<Tip>
  For how to get API key, refer to the [API Key Management](/api-reference/basic-authentication).
</Tip>

Code Example

**Python**

```python theme={"system"}
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

batch_input_file = client.files.create(
    file=open("batch_input.jsonl", "rb"),
    purpose="batch",
)

print(batch_input_file)
```

**Curl**

```bash theme={"system"}
export API_KEY="<Your API Key>"

curl --request POST \
  --url https://api.novita.ai/openai/v1/files \
  --header 'Authorization: Bearer ${API_KEY}' \
  --form 'file=@"/your/batch_input.jsonl"' \
  --form 'purpose="batch"'
```

Sample response upon successful file upload:

```
{
    "id": "file_d2co***as73c0cjd0",
    "object": "file",
    "bytes": 238,
    "filename": "batch_input.jsonl",
    "created_at": 1754894162,
    "purpose": "batch",
    "metadata": {
        "total_requests": 2
    }
}
```

### 3. Creating a Batch

Once the input file is successfully uploaded, you can initiate a batch using the ID of the uploaded File object. The completion window is fixed at `48h` and is currently non-adjustable.

Code Example

**Python**

```python theme={"system"}
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

batch = client.batches.create(
  input_file_id="file_d2cor0es1cas73c0cj60",
  endpoint="/v1/chat/completions",
  completion_window="48h"
)
print(batch)
```

**Curl**

```bash theme={"system"}
export API_KEY="<Your API Key>"

curl --request POST \
  --url https://api.novita.ai/openai/v1/batches \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}' \
  --data '{
      "input_file_id": "file_d2co***as73c0cjd0",
      "endpoint": "/v1/chat/completions",
      "completion_window": "48h"
  }'
```

This request will yield a Batch object that includes metadata about your batch, as illustrated in the example below:

```JSON theme={"system"}
{
    "id": "batch_d2cq***73a68lu0",
    "object": "batch",
    "endpoint": "/v1/chat/completions",
    "input_file_id": "file_d2co***as73c0cjd0",
    "output_file_id": "",
    "error_file_id": "",
    "completion_window": "48h",
    "in_progress_at": null,
    "expires_at": null,
    "finalizing_at": null,
    "completed_at": null,
    "failed_at": null,
    "expired_at": null,
    "cancelling_at": null,
    "cancelled_at": null,
    "status": "validating",
    "errors": "",
    "version": 0,
    "created_at": "2025-08-11T16:31:52.949816948+08:00",
    "updated_at": null,
    "created_by": "8f242aa1-f725-4a67-8***9-cb68025e0976",
    "created_by_key_id": "key_cc19f96c***e7390644a37da21",
    "remark": "",
    "total": 0,
    "completed": 0,
    "failed": 0,
    "metadata": null,
    "request_counts": {
        "total": 0,
        "completed": 0,
        "failed": 0
    }
}
```

### 4. Check the Status of a Batch

You can check a batch's status at any time to receive the latest batch information.

The status enumeration values of the Batch object are as follows:

<table>
  <thead>
    <tr>
      <th>Status</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>VALIDATING</td>
      <td>The input file is being validated before the batch can begin</td>
    </tr>

    <tr>
      <td>PROGRESS</td>
      <td>Batch is in progress</td>
    </tr>

    <tr>
      <td>COMPLETED</td>
      <td>Batch processing completed successfully</td>
    </tr>

    <tr>
      <td>FAILED</td>
      <td>Batch processing failed</td>
    </tr>

    <tr>
      <td>EXPIRED</td>
      <td>Batch exceeded deadline</td>
    </tr>

    <tr>
      <td>CANCELLING</td>
      <td>Batch is being cancelled</td>
    </tr>

    <tr>
      <td>CANCELLED</td>
      <td>Batch was cancelled</td>
    </tr>
  </tbody>
</table>

Code Example

**Python**

```python theme={"system"}
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)
batch = client.batches.retrieve("batch_d2cq***73a68lu0")
print(batch)
```

**Curl**

```bash theme={"system"}
export API_KEY="<Your API Key>"

curl --request GET \
  --url https://api.novita.ai/openai/v1/batches/{batch_id} \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}'
```

### 5. Retrieve the Results

Once the batch inference is complete, you can download the result output file using the `output_file_id` field from the Batch object.

The result output file will be deleted 30 days after the batch inference concludes, so please retrieve it promptly via the interface.

Code Example

**Python**

```python theme={"system"}
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

content = client.files.content("example-250811-1")
print(content.read())
```

**Curl**

```bash theme={"system"}
export API_KEY="<Your API Key>"

curl --request GET \
  --url https://api.novita.ai/openai/v1/files/{file_id}/content \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}'
```

The response returns the raw file content. For batch output files, each line contains a response like this:

```json theme={"system"}
{
  "custom_id": "request-2589",
  "error": null,
  "id": "batch_req_task_d2c",
  "response": {
    "body": {
      "id": "29e1432c-edfb-44a4-b531-c23c600abfae",
      "object": "chat.completion",
      "created": 1754902266,
      "model": "deepseek-test",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "Hello! 👋 How can I assist you today? 😊"
          },
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 5,
        "completion_tokens": 13,
        "total_tokens": 18
      }
    },
    "request_id": "request-2589",
    "status_code": 200
  }
}
```

## Instructions

### Limitations

1. Each batch can contain up to 50,000 requests.<br />
2. The maximum input file size per batch is 100MB.

### Error Handling

Errors encountered during batch processing are recorded in a separate error file, accessible via the error\_file\_id field. Common error codes include:

<table>
  <thead>
    <tr>
      <th>Error Code</th>
      <th>Description</th>
      <th>Solution</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>400</td>
      <td>Invalid request format</td>
      <td>Check JSONL syntax and required fields</td>
    </tr>

    <tr>
      <td>401</td>
      <td>Authentication failed</td>
      <td>Verify API key</td>
    </tr>

    <tr>
      <td>404</td>
      <td>Batch not found</td>
      <td>Check batch ID</td>
    </tr>

    <tr>
      <td>429</td>
      <td>Rate limit exceeded</td>
      <td>Reduce request frequency</td>
    </tr>

    <tr>
      <td>500</td>
      <td>Server error</td>
      <td>Contact us</td>
    </tr>
  </tbody>
</table>

### Batch Expiration

Batches not completed within 48 hours will transition to an EXPIRED state. Unfinished requests will be canceled, while completed requests will be provided through an output file. You only pay for tokens consumed by completed requests. The batch makes every effort to complete within 48 hours.

## All Batch API

1. [Create batch](/api-reference/model-apis-llm-create-batch)
2. [Retrieve batch](/api-reference/model-apis-llm-retrieve-batch)
3. [Cancel batch](/api-reference/model-apis-llm-cancel-batch)
4. [List batch](/api-reference/model-apis-llm-list-batches)
5. [Upload file](/api-reference/model-apis-llm-upload-batch-input-file)
6. [List files](/api-reference/model-apis-llm-list-files)
7. [Retrieve file](/api-reference/model-apis-llm-query-file)
8. [Delete file](/api-reference/model-apis-llm-delete-file)
9. [Retrieve file content](/api-reference/model-apis-llm-retrieve-file-content)


# Dedicated Endpoint User Manual
Source: https://novita.ai/docs/guides/llm-dedicated-endpoint



## 1 Quickstart

### 1.1 Accessing Novita API Keys

* Account Registration:

1. Visit the official Novita website;
2. Click the "Log In" button located in the top-right corner;
3. Complete the user registration process.

* API Key Generation:

After successful registration, navigate to the [API key management page](https://novita.ai/settings/key-management?utm_source=getstarted). Generate and retrieve your API keys from this dashboard.

### 1.2 Creating Your First Dedicated Endpoint Instance

To create your first Dedicated Endpoint, first navigate to [Dedicated Endpoint](https://novita.ai/dedicated-endpoint), where you'll find two options: "LLM Dedicated Endpoints" and "Image Dedicated Endpoints" below the title. Click on "LLM Dedicated Endpoints" and then look for "High cost performance" section, where you will find the green "Create a new endpoint" button, click on it and you'll be redirected to [LLM Dedicated Endpoint](https://novita.ai/models-console/llm-dedicated-endpoints). Click either "+ New Endpoint" aligned with "Getting Started with Deployments" or "Get started" under "Create a new deployment". By now your Dedicated Endpoint creation journey formally begins:

1. After entering your Endpoint name, you'll see the "model" section below. For more information about this section, you can visit [**1.3**](https://novita.ai/docs/guides/llm-DE#1.3-Quick-Deployment-of-HuggingFace-Models) about them;
2. After successfully selecting base model and adding LoRA, you can choose hardware specifications and GPU quantity next, if you have any questions about this process, you can visit [**1.4**](https://novita.ai/docs/guides/llm-DE#1.4-Hardware-and-GPU-Configuration) for more information;
3. After selecting your most suitable GPU and quantity, you'll enter autoscaling section, since this part is actually more complex, we've provided a detailed [**1.5**](https://novita.ai/docs/guides/llm-DE#1.5-Autoscaling-Configuration) part for you to visit;
4. Eventually, you'll enter the last part of the whole process: setting your inference framework. Again we have an independent section for you to visit for more information: (**1.6.**)\[[https://novita.ai/docs/guides/llm-DE#1.6-Inference-Framework-Configuration](https://novita.ai/docs/guides/llm-DE#1.6-Inference-Framework-Configuration)]

And that's the complete process for creating your first Dedicated Endpoint. Enjoy using the service!

### 1.3 Quick Deployment of HuggingFace Models

After entering your desired model name, you'll see the Models module. Here's how to configure it:

1. To use models we provide for you for your Dedicated Endpoint, you need to get HuggingFace access token. Click Integrated-this link to log into HuggingFace;
2. Obtain your access token and then enter the token in the field below the "this link" button. This grants you access to private repositories and gated models;
3. Browse and select your preferred model from the available options;
4. If you want, you can also add the LoRA adapter by using the "+ add LoRA adapter" button at the bottom of the Models section. Enter the HuggingFace repository name for your desired LoRA adapter. For more details on LoRA adapters, refer to section [**2.3**](https://novita.ai/docs/guides/llm-DE#2.3-Best-Practices-in-LoRA).

<Tip>
  While choosing model, You may notice a "Gated" label next to your choice, and this is completely normal!

  * GATED models on HuggingFace are restricted-access models, including Meta's LLaMA series, Mistral commercial license models and Medical and financial domain models
  * To access GATED models, log into your HuggingFace account, navigate to the model page (e.g., meta-llama) where you need to click "Access request" or "Request access" and provide usage description and accept terms of use. After doing all these things, you can just wait for approval before loading the model
</Tip>

### 1.4 Hardware and GPU Configuration

After selecting your model, you can configure your preferred hardware specifications and GPU count. At Novita, We are able to provide you with three different kinds of GPUs: H100 (High-performance enterprise GPU), H200 (Latest generation enterprise GPU) and RTX4090 (Cost-effective consumer GPU). you can choose to have 1,2 or 4 GPUs of one type. Feel free to combine any GPU type with any supported quantity to match your model requirements. But be careful! you are only allowed to use 8 GPUs in total. If you want to use more, you can purchase Enterprise Solution from our sales. After upgrading, you can adjust maximum GPU count in your account interface.

If you wonder which GPU and how many of them you should choose, we suggest you consider these factors:

* Model size - Larger models require more powerful/multiple GPUs;
* Performance needs - H100/H200 for high-performance, RTX4090 for cost-efficiency;
* Budget constraints - Balance performance requirements with costs.

### 1.5 Autoscaling Configuration

After configuring your hardware and GPU count, you'll reach the autoscaling module. In this part, if you choose the default settings, the autoscaling is enabled with minimum replicas as 1 and maximum replicas as 2. We do suggest you to turn on autoscaling, as it enables cost optimization, assures high performance and is resource-efficient. But of course, you can choose to turn off the autoscaling mode, by doing which your initial replica will be a fixed 1.

Under the autoscaling, you can adjust your Cooldown period (with default number of 300 seconds), you can adjust it to any time as long as it's longer than 120 seconds.

<Tip>
  If you are not very familiar with some terms written above, don't worry! We do have some explanations below:

  * Replica\
    An independent service instance that increases maximum supported QPS (queries per second). For example, if you have 2 GPUs with  min replicas as 1 and max replicas as 2, then the model will always run with ≥1 replica (2 GPUs) and can scale up to 2 replicas (4 GPUs total) during high traffic
  * Conditions for Minimum Replicas\
    Set to 0: Endpoint enters sleep mode during idle periods (cost-saving)\
    Set to >0: Maintains at least that many active replicas continuously
  * Conditions for Maximum Replicas\
    Defines the upper limit of replicas for handling traffic growth\
    System limit: Maximum 10 replicas
  * Cooldown Period\
    Delay before scaling down replicas, which can prevent premature resource release during temporary traffic drops.
</Tip>

### 1.6 Inference Framework Configuration

If you are reading this part, congratulations! You're just one step away from successfully deploying your Dedicated Endpoint. At this stage, you'll configure the inference framework settings.

Here you can choose your own engine with two choices: vLLM and SGLang. If your base model is a LLM and you want it to do tasks like text generation, completion and chat applications, we suggest choosing vLLM, which is optimized for Large Language Models (LLMs). If your base model is a Multimodal model or a non-LLM one and you want it to do tasks related to Vision or specialized AI applications, we suggest choosing SGLang, which has versatile framework for diverse model types.

After choosing your engine type, there'll be default engine version with the latest. If you want, you can also select older versions. --max-model-len controls context length, you'll be able to use model's default configuration when you left this blank empty. --max-num-seqs sets the number of sequences per iteration, affecting throughput and resource utilization. If you want to add more engine parameters, you can write them in Additional Arguments, which can fine-tune engine behavior for specific requirements.

## 2 Model Management

### 2.1 Supported Models and their capabilities

Up till now, there are five models supporting Dedicated Endpoints in Novita without being **gated** (see the tip in [1.3](https://novita.ai/docs/guides/llm-DE#1.3-Quick-Deployment-of-HuggingFace-Models) if you don't know what gate means):

| Model name                                | vision | reasoning | function-calling | structured output | context size | tensor type |
| ----------------------------------------- | ------ | --------- | ---------------- | ----------------- | ------------ | ----------- |
| deepseek/deepseek-r1-0528-qwen3-8b        | no     | yes       | no               | no                | 128000       | BF16        |
| meta-llama/llama-4-scout-17b-16e-instruct | yes    | no        | yes              | no                | 131072       | BF16        |
| deepseek/deepseek-r1-distill-llama-8b     | no     | yes       | no               | yes               | 32000        | BF16        |
| qwen/qwen3-8b-fp8                         | no     | yes       | no               | no                | 128000       | FP8         |
| qwen/qwen3-4b-fp8                         | no     | yes       | no               | no                | 128000       | FP8         |

there are six models supporting Dedicated Endpoints in Novita being gated:

| Model name                                   | vision | reasoning | function-calling | structured output | context size | tensor type |
| :------------------------------------------- | :----- | :-------- | :--------------- | :---------------- | :----------- | :---------- |
| meta-llama/llama-3.1-8b-instruct             | no     | no        | no               | no                | 16384        | FP8         |
| meta-llama/llama-3.3-70b-instruct            | no     | no        | yes              | yes               | 131072       | BF16        |
| meta-llama/llama-3.2-3b-instruct             | no     | no        | yes              | no                | 32768        | BF16        |
| novita/inflatebot-mn-12B-mag-mell-r1-awq-fp8 | yes    | no        | yes              | yes               | 32000        | FP8         |
| novita/sao10k-l3-8b-stheno-v3.2-awq-fp8      | no     | no        | no               | no                | 8192         | FP8         |
| deepseek/deepseek-v3-0324                    | no     | no        | yes              | no                | 163840       | FP8         |

### 2.2 Custom Upload (LoRA Adapters)

LoRA (Low-Rank Adaptation of LLMs) is a popular and lightweight training technique that dramatically reduces trainable parameters.

Core Mechanism of LoRA:

* **Parameter Insertion**: Adds minimal new weights to pre-trained models
* **Selective Training**: Only trains new parameters while keeping original weights frozen
* **Inference Integration**: Updated low-rank weights are merged with frozen base model weights

Key Advantages of LoRA:

* **Faster Training**: Significantly accelerated training process
* **Lower Memory Usage**: Dramatically reduced memory consumption
* **Compact Models**: Generates smaller weight files (only hundreds of MB)
* **Easy Sharing**: Simplified storage and distribution
  For more details, you can visit [LoRAs in Novita](https://novita.ai/docs/api-reference/model-apis-list-training-task)

Here at Novita, we not only support adding LoRA with PEFT or HuggingFace LoRA formats for fine-tuning models, but also allows Multi-Model Mounting, Hot-Switching Capabilities and adapter ensemble. So through our proprietary optimization technology, you can deploy and serve multiple LoRA models on a single endpoint using just one GPU. This simplifies operational workflows, maximizes resource utilization efficiency, and delivers greater flexibility and superior performance when customizing models—while supporting the loading and processing of image assets. Achieve efficient deployment without compromising top-tier inference quality.

### 2.3 Best Practices in LoRA

Follow these detailed steps to add LoRA adapters to your certain Dedicated Endpoint:

1. In the Dedicated Endpoints creation Models module, locate "+ Add LoRA adapter" at the bottom (separate from "Base Model"). Click to begin adapter configuration;
2. Enter the adapter's Hugging Face model ID. One base model can support multiple LoRA adapters, all adapters are deployed directly from Hugging Face Hub;
3. Once base model is selected, "+Add LoRA adapter" button becomes active. Click to open the LoRA adapter configuration modal;
4. If you succeeded in adding LoRA adapter, the plus button will change from gray to blue  However, if you see the message: "LoRA adapter does not match base model" , you may need to add your LoRA adapter again;
5. After successfully adding your LoRA adapter, you can test Your Deployment. You can see a new interface called "My New LoRA endpoint". If you want to test your adapter, you can go to "Playground" page for testing. You can use the highlighted dropdown menu to seamlessly switch between adapter models and base models for experimentation and comparison.

That's it! You've successfully deployed a LoRA adapter on your certain dedicated endpoint and tested it in the Playground. You're now ready to explore advanced multi-adapter configurations or integrate your model into production applications.

## 3. Private Endpoint Deployment

### 3.1 Private Endpoint Status Monitoring

Access the ​​"My Models - Dedicated Endpoints"​​ page, where all dedicated endpoint model deployment tasks are displayed. Click ​​Dedicated Endpoints → Model Name​​ to enter the model details page, which shows deployment configuration information and endpoint status. There are five possible status indicators:

* ​​Running​​ (In Service): The endpoint is fully operational, having completed initialization/version upgrade/scaling, and is ready to process inference requests—indicating a successful deployment.
* ​​Pending​​ (Cold Start): Resources and models are being initialized; the endpoint cannot accept requests yet (no available workers).
* ​​Rolling​​ (Version Updating): Configuration or model version is being updated. ​​
* Terminating​​ (Pausing): The endpoint is in the process of shutting down. ​​
* Terminated​​ (Stopped): The endpoint has been terminated, with min/max replicas set to 0,

GPU instances released, and billing halted. ​​Status Indicators & Actions​​:

* ​​Green Button​​: Endpoint is ​​Running​​ (active and serving requests). ​
* Yellow Button​​: Endpoint is in ​​Pending​​ (cold start) phase. ​​
* Cycling Symbol​​: Endpoint is ​​Rolling​​ (updating). ​​
* Red Button​​: Endpoint is either ​​Terminating​​ (shutting down) or ​​Terminated​​ (fully stopped).

Suggested status:

| combination of stutus    | situations                                                        |
| ------------------------ | ----------------------------------------------------------------- |
| Running                  | Able to accept reasoning requirement                              |
| Pending/Rolling→ Running | Restore available status automatically after changing deployments |
| Terminating→ Terminated  | Release resources, stop billing, support restart                  |

### **3.2 Endpoint Status Management Operations**

When your ​**​**Dedicated Endpoint​​ is in the ​**​**Running​​ state, you will see a ​**​**"Terminate"​​ button aligned with the Dedicated Endpoint name on the right side of the screen. Clicking this button will stop the endpoint. To restart it, simply click the ​**​**"Restart"​​ button located below the Dedicated Endpoint name.

<Note>
  ​**​Important Notes​**​:

  * ​​Deletion is not allowed​​ while the Dedicated Endpoint is in the ​**​**Running​​ state.
  * If you need to delete the model, first set the Dedicated Endpoint to a ​​stopped​​ state, then click ​**​**"Update"​​ followed by ​**​**"Delete"​​ to remove it.
</Note>

## 4. Commercial Capabilities

### 4.1 Dedicated Endpoint Billing Rules & Report Export

Your ​Dedicated Endpoints billing on the Novita platform follows this pricing logic:\
​​Total Cost = Number of GPUs × Duration (hours) × Price per GPU-hour​​

**​​Key Billing Details​​**

1. ​**​Duration Calculation​**​:
   * Measured in seconds by the backend system (configured at 1-second granularity).
   * ​Billed hourly​​ (rounded to the nearest hour).
   * Starts when the Dedicated Endpoint enters ​Running​​ status and ends when it stops (includes state transitions like scaling updates).
2. ​**​GPU Pricing​**​:
   * Pricing varies by ​GPU type​​ .
   * ​Dynamic scaling supported: The number of GPUs (2/4/8) is adjusted automatically based on workload, with Novita’s autoscaling system reporting real-time values.
   * If you want to learn more about it, you can visit our [pricing page](https://novita.ai/pricing) and click on "GPUs" to see more.
3. ​**​Usage Reporting​**​:
   * Data is reported ​​per minute​​ (one data point every minute).

For full pricing specifications, visit: [Novita Pricing - LLMs Dedicated Endpoints](https://novita.ai/pricing).

​​**Billing Statements & Export​​**

Access your Dedicated Endpoints usage reports at [Novita Billing Details](https://novita.ai/billing/details), where your report includes:

* Billing cycle dates
* Product category (LLM Dedicated Endpoints)
* Cost breakdown by DE (including ​Endpoints ID​​, GPU count, and price per GPU-second)

​​To export your report​​, just Click ​"LLM Dedicated Endpoints → Export"​​ to generate and download a copy.


# DeepSeek-OCR Usage
Source: https://novita.ai/docs/guides/llm-deepseek-ocr



## Overview

DeepSeek-OCR is designed for document recognition and image-to-text scenarios, pushing the limits of visual and textual compression. The model can render long texts into highly compressed images, achieving an OCR accuracy of 97% at a lossless compression ratio of 10x and around 60% accuracy at 20x compression.

<Note>
  This model currently supports only single-turn, independent recognition tasks. It does not support multi-turn conversations. Only one image can be uploaded per request, and it is strongly recommended to use preset prompts for optimal performance.
</Note>

## Recommended Preset Prompts

```bash theme={"system"}
# Convert the document contents to markdown format
<|grounding|>Convert the document to markdown.

# Perform text recognition on this image
<|grounding|>OCR this image.

# Extract all text without layout consideration
Free OCR.

# Parse any figures or tables in the document
Parse the figure.

# Provide a detailed description of the image content
Describe this image in detail.

# Locate the position of <|ref|>xxxx<|/ref|> in the image
Locate <|ref|>xxxx<|/ref|> in the image.
```

## Usage Example

This example uses the `<|grounding|>OCR this image.` preset prompt to perform image text recognition.

```python theme={"system"}
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    api_key="<Your API Key>",
)

response = client.chat.completions.create(
    model="deepseek/deepseek-ocr",
    messages=[
      {
        "role": "user",
        "content": [
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/image.png"
            }
          },
          {
            "type": "text",
            "text": "<|grounding|>OCR this image."
          }
        ]
      }
    ],
    stream=False,
    max_tokens=4096
)

content = response.choices[0].message.content

print(content)
```

Example input image:

<Frame>
  <img alt="OCR Example Image" />
</Frame>

Example output:

```
<|/ref|><|det|>[[37, 48, 279, 140]]<|/det|>
<|ref|>Deploy open-source and specialized models<|/ref|><|det|>[[42, 48, 857, 133]]<|/det|>
<|ref|>smarterandfasterwithsimpleApls.Accessthe<|/ref|><|det|>[[44, 185, 902, 246]]<|/det|>
<|ref|>latest chat, code, image, audio, video models and<|/ref|><|det|>[[41, 291, 945, 370]]<|/det|>
<|ref|>more,ready for production with built-in<|/ref|><|det|>[[40, 407, 756, 488]]<|/det|>
<|ref|>scalability.<|/ref|><|det|>[[39, 515, 232, 606]]<|/det|>
<|ref|>Explore<|/ref|><|det|>[[87, 813, 266, 879]]<|/det|>
<|ref|>Models<|/ref|><|det|>[[289, 816, 432, 878]]<|/det|>
```


# Function Calling
Source: https://novita.ai/docs/guides/llm-function-calling



`Function Calling` empowers AI models to interact with external tools and APIs, enabling them to perform specific actions and access real-time information. This capability extends the functionality of AI models beyond simple text generation, allowing for more dynamic and practical applications.

## Supported Models

The following models support `Function Calling`:

<FunctionCallingModels />

## Quick Start Guide

This guide demonstrates how to use Function Calling to retrieve current weather information for a user's specified location.  We will walk through a complete Python code example.

For the specific API format of Function Calling, please refer to the API reference [Create Chat Completion](/api-reference/model-apis-llm-create-chat-completion).

### 1. Initialize the Client

First, you need to initialize the client with your Novita API key.

```python theme={"system"}
from openai import OpenAI
import json

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    # Get the Novita AI API Key from: https://novita.ai/settings/key-management.
    api_key="<YOUR Novita AI API Key>",
)

model = "deepseek/deepseek_v3"
```

### 2. Define the Function to Be Called

Next, define the Python function that the model can call. In this example, it's a function to get weather information.

```python theme={"system"}
# Example function to simulate fetching weather data.
def get_weather(location):
    """Retrieves the current weather for a given location."""
    print("Calling get_weather function with location: ", location)
    # In a real application, you would call an external weather API here.
    # This is a simplified example returning hardcoded data.
    return json.dumps({"location": location, "temperature": "60 degrees Fahrenheit"})
```

### 3. Construct the API Request with Tools and User Message

Now, create the API request to the Novita endpoint. This request includes the `tools` parameter, defining the functions the model can use, and the user's message.

```python theme={"system"}
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get weather of an location, the user shoud supply a location first",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    }
                },
                "required": ["location"]
            },
        }
    },
]

messages = [
    {
        "role": "user",
        "content": "What is the weather in San Francisco?"
    }
]

# Let's send the request and print the response.
response = client.chat.completions.create(
    model=model,
    messages=messages,
    tools=tools,
)

# Please check if the response contains tool calls if in production.
tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.model_dump())
```

**Output:**

```js theme={"system"}
{'id': '0', 'function': {'arguments': '{"location": "San Francisco, CA"}', 'name': 'get_weather'}, 'type': 'function'}
```

### 4. Respond with the Function Call Result and Get the Final Answer

The next step is to process the function call, execute the `get_weather` function, and send the result back to the model to generate the final response to the user.

```python theme={"system"}
# Ensure tool_call is defined from the previous step
if tool_call:
    # Extend conversation history with the assistant's tool call message
    messages.append(response.choices[0].message)

    function_name = tool_call.function.name
    if function_name == "get_weather":
        function_args = json.loads(tool_call.function.arguments)
        # Execute the function and get the response
        function_response = get_weather(
            location=function_args.get("location"))
        # Append the function response to the messages
        messages.append(
            {
                "tool_call_id": tool_call.id,
                "role": "tool",
                "content": function_response,
            }
        )

    # Get the final response from the model, now with the function result
    answer_response = client.chat.completions.create(
        model=model,
        messages=messages,
        # Note: Do not include tools parameter here.
    )
    print(answer_response.choices[0].message)
```

**Output:**

```
ChatCompletionMessage(content="The weather in San Francisco, CA is currently **60 degrees Fahrenheit**. For more detailed information, such as specific conditions (e.g., sunny, cloudy, rainy), you might want to check a local weather app or website. Let me know if you'd like help with anything else!", refusal=None, role='assistant', function_call=None, tool_calls=None)
```

### The Complete Code

```python theme={"system"}
from openai import OpenAI
import json

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    # Get the Novita AI API Key from: https://novita.ai/settings/key-management.
    api_key="<YOUR Novita AI API Key>",
)

model = "deepseek/deepseek_v3"

# Example function to simulate fetching weather data.
def get_weather(location):
    """Retrieves the current weather for a given location."""
    print("Calling get_weather function with location: ", location)
    # In a real application, you would call an external weather API here.
    # This is a simplified example returning hardcoded data.
    return json.dumps({"location": location, "temperature": "60 degrees Fahrenheit"})

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get weather of an location, the user shoud supply a location first",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    }
                },
                "required": ["location"]
            },
        }
    },
]

messages = [
    {
        "role": "user",
        "content": "What is the weather in San Francisco?"
    }
]

# Let's send the request and print the response.
response = client.chat.completions.create(
    model=model,
    messages=messages,
    tools=tools,
)

# Please check if the response contains tool calls if in production.
tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.model_dump())

# Ensure tool_call is defined from the previous step
if tool_call:
    # Extend conversation history with the assistant's tool call message
    messages.append(response.choices[0].message)

    function_name = tool_call.function.name
    if function_name == "get_weather":
        function_args = json.loads(tool_call.function.arguments)
        # Execute the function and get the response
        function_response = get_weather(
            location=function_args.get("location"))
        # Append the function response to the messages
        messages.append(
            {
                "tool_call_id": tool_call.id,
                "role": "tool",
                "content": function_response,
            }
        )

    # Get the final response from the model, now with the function result
    answer_response = client.chat.completions.create(
        model=model,
        messages=messages,
        # Note: Do not include tools parameter here
    )
    print(answer_response.choices[0].message)
```


# Interleaved Thinking Supporty
Source: https://novita.ai/docs/guides/llm-interleaved-thinking



> **Last Updated**: 2025-12-03 <br />
> **Status**: Supported (OpenAI-Compatible)

## 1. Overview

**Interleaved Thinking** is an advanced reasoning framework that enables models to perform explicit reasoning steps between tool calls.

Models with Interleaved Thinking can:

* Reflect on the current environment and tool outputs
* Decide the next action based on updated reasoning
* Maintain a continuous reasoning chain across multiple tool invocations
* Provide transparent, inspectable multi-step thinking through `reasoning_details` or `reasoning_content`

This capability transforms traditional function-calling into **agent-level tool use**, making complex workflows more accurate, reliable, and context-aware.

Novita fully supports Interleaved Thinking for all models that natively expose reasoning streams (e.g., MiniMax-M2 and other OpenAI-compatible reasoning models).

## 2. Key Concepts

### 2.1 Interleaving

Instead of executing a single reasoning phase followed by a tool call, the model performs:

```BASH theme={"system"}
Reason → Tool Call → Observe → Reason → Tool Call → ...
```

This allows the model to adjust its strategy dynamically based on previous tool outputs.

### 2.2 Reasoning Details (`reasoning_details`)

For some models, the content of the model's thinking will be returned in the form of a separate structure:

```JSON theme={"system"}
"reasoning_details": [
  {
    "type": "reasoning.text",
    "format": "openai-responses-v1",
    "text": "Model’s step-by-step reasoning..."
  }
]
```

For such models, Novita supports returning this field in both streaming and non-streaming modes.

### 2.3 Conversation Memory Requirement

To maintain reasoning continuity: You **must append the model’s full response** including `reasoning_details`, `tool_calls`, and `content` to subsequent `messages`.

Failing to preserve the chain may result in:

* Incorrect tool use
* Lost reasoning context
* Repeated or circular tool calls
* Reduced reliability

This requirement mirrors OpenAI’s reasoning APIs.

## 3. API Behavior

### 3.1 Request Format

No changes are required on the user side.
Interleaved Thinking works with the standard OpenAI-compatible Chat Completions API.

### 3.2 Response Format

The model may return the following fields:

* `reasoning_content`: original thinking content
* `reasoning_details`: structured reasoning segments, this field is optioanl
* `tool_calls`: tool invocation plan
* `content`: natural language output

These extend the standard OpenAI format.

## 4. Example Request (MiniMax-M2)

```JSON theme={"system"}
{
  "model": "minimax/minimax-m2",
  "messages": [
    {
      "role": "user",
      "content": "How's the weather in San Francisco?"
    },
    {
      "role": "assistant",
      "name": "MiniMax AI",
      "content": "",
      "tool_calls": [
        {
          "id": "call_function_asqvfevfc8af_1",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"location\": \"San Francisco, US\"}"
          }
        }
      ],
      "reasoning_details": [
        {
          "type": "reasoning.text",
          "id": "reasoning-text-1",
          "format": "openai-responses-v1",
          "index": 0,
          "text": "The user is asking about the weather in San Francisco..."
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_function_asqvfevfc8af_1",
      "content": "24℃, sunny"
    }
  ],
  "stream": true,
  "reasoning_split": true,
  "max_tokens": 1024,
  "temperature": 0.7,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get weather for a specific location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": { "type": "string" }
          },
          "required": ["location"]
        }
      }
    }
  ]
}
```

## 5. Example Response (Non-Streaming)

```JSON theme={"system"}
{
  "id": "07a4dedfdb1498b045498dfd42497639",
  "object": "chat.completion",
  "created": 1764303147,
  "model": "MiniMax",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "",
        "name": "MiniMax",
        "tool_calls": [
          {
            "index": 0,
            "id": "call_function_9w7wq1j9zmpl_1",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"ShangHai\"}"
            }
          }
        ],
        "reasoning_content": "The user asked for Shanghai weather...",
        "reasoning_details": [
          {
            "type": "reasoning.text",
            "text": "The user is asking about the weather in Shanghai...",
            "id": "reasoning-text-1",
            "format": "openai-responses-v1",
            "index": 0
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}
```

## 6. Streaming Response Example

```JSON theme={"system"}
{
  "id": "664c5ad870c1888fbcbd267d9829e354",
  "object": "chat.completion.chunk",
  "created": 1764303504,
  "model": "minimax-m2",
  "choices": [
    {
      "index": 0,
      "delta": {
        "role": "assistant",
        "reasoning_content": "...\n\nThe user has specifically asked...",
        "reasoning_details": [
          {
            "type": "reasoning.text",
            "text": ".\n\nThe user has specifically asked...",
            "id": "reasoning-text-1",
            "format": "openai-responses-v1",
            "index": 0
          }
        ]
      },
      "finish_reason": null
    }
  ]
}
```

## 7. Developer Notes

### 7.1 Models That Support Interleaved Thinking

All models exposing `reasoning_details` through OpenAI-compatible APIs, including:

* MiniMax-M2
* (Upcoming) Novita Reasoning Series
* Other reasoning-enabled partner models

### 7.2 Pricing

Billing is based on reasoning tokens, following the model’s pricing rules.
`reasoning_details` will increase token usage.

### 7.3 Error Handling

You may encounter:

* Missing tool parameters
* Recursive or repeated tool calls
* Incorrect assumptions in the reasoning phase

Ensure your application validates tool arguments and handles model errors gracefully.

## 8. Best Practices

**✓ Always include full model messages in the next request**

Include:

* `content`
* `tool_calls`
* `reasoning_details`

**✓ Enable streaming for long-chain reasoning**

Streaming allows the client to:

* Monitor the reasoning process
* Detect incorrect tool plans early
* Provide faster user feedback

**✓ Combine with server-side state machines for stability**

For production systems, we recommend pairing Interleaved Thinking with deterministic guardrails, e.g.:

* Parameter validators
* Execution sandbox
* Maximum recursion safeguards

## 9. Summary

Interleaved Thinking significantly enhances multi-step reasoning and tool-use reliability:

* Transparent and inspectable step-wise reasoning
* Adaptive planning between tool invocations
* Stronger context retention across long workflows
* Fully compatible with OpenAI-style Chat Completions API

Novita will continue expanding support for advanced reasoning models, bringing agent-level intelligence to the API layer.


# LLM Monitoring
Source: https://novita.ai/docs/guides/llm-monitor

Description of your new file.

Novita AI provides comprehensive monitoring metrics for the usage of large language model (LLM) APIs. These metrics help you gain deep insights into the availability and performance of your LLM API requests.

You can view the monitoring metrics on the [LLM Monitoring Page](https://novita.ai/models-console/llm-metrics).

## Metric Descriptions

<Note>
  All metrics are broken down by **model** and sampled at the **minute level**. However, depending on your selected time interval, samples may not be shown for every minute. In such cases, values will be averaged across the selected time range.
</Note>

* **Requests Per Minute (RPM)**

Displays the number of API requests sent per minute. This helps you understand usage patterns and the level of API concurrency.

* **Request Success Rate**

Shows the percentage of successful API responses per minute (non-5xx status codes), reflecting the API's availability.

* **Average Token Count per Request**

Displays the average number of input and output tokens per request per minute, which helps you monitor token consumption patterns.

* **End-to-End (E2E) Latency**

Shows the total time required for the model to generate a full response in each request per minute. Metrics include the 99th percentile, 95th percentile, and average latency.

* **Time to First Token (TTFT)**

<Note>
  Only tracked for streaming requests where stream=true.
</Note>

Displays the time it takes to process the prompt and generate the first output token in each request per minute. Includes the 99th percentile, 95th percentile, and average latency.

* **Time Per Output Token (TPOT)**

<Note>
  Only tracked for streaming requests where stream=true.
</Note>

Displays the average time between consecutive output tokens in each request per minute. Includes the 99th percentile, 95th percentile, and average latency.


# Interactive Playground
Source: https://novita.ai/docs/guides/llm-playgrounds



To help users better understand and test the behavior of large language models, **Novita** provides a flexible interactive playground. Users can fine-tune a series of parameters to precisely control the model's generation logic, content style, and response structure, enabling more targeted output.

## Response Format

Users can choose between two modes:

* **Custom JSON Output Structure**: Define a JSON Schema to guide the model in generating output that follows a predefined format, ideal for structured tasks or API integration scenarios.
* **Free-form Generation**: Allow the model to freely organize answers based on context, suitable for open-ended Q\&A and creative writing applications.

## System Prompt

By setting a system prompt, users can define the model's "persona" and behavioral context. For example, if you set the prompt as “You are a professional travel planner,” the model will respond from that perspective, enhancing consistency and contextual coherence.

## Parameter Configuration

The playground supports the adjustment of the following core parameters:

* **max\_tokens**: Sets the maximum number of tokens the model can generate. Lower values improve response speed, while higher values are suitable for complex, lengthy outputs.
* **temperature**: Controls the creativity and randomness of the output. Higher values lead to more diverse and imaginative responses, while lower values yield more conservative and deterministic outputs, ideal for precise tasks.
* **top\_p (nucleus sampling)**: Dynamically adjusts the token sampling range per step to improve diversity and fluency. Recommended to use alongside temperature.
* **top\_k**: Limits the model to select from the top K highest probability tokens at each step, which enhances efficiency and reduces noise.
* **min\_p**: An alternative to top\_p and top\_k, used to filter out tokens with probabilities below a certain threshold, suitable for accuracy-critical tasks.
* **presence\_penalty**: Encourages the model to introduce new topics in its output. Positive values increase the likelihood of expanding to new content.
* **frequency\_penalty**: Suppresses the generation of repeated tokens. Positive values reduce repetition and help maintain originality.
* **repetition\_penalty**: Further reduces the risk of loops or repetitive prompts, enhancing output robustness.

## Usage Recommendations

* **For Creative Writing**: Increase temperature, top\_p, and presence\_penalty to encourage diverse and imaginative outputs.
* **For Structured Tasks and Tool Invocation**: Use a fixed JSON schema with lower temperature and top\_k to ensure consistent and reliable outputs.
* **For Testing Interactions**: Compare different parameter combinations to observe changes in generation style, information density, and contextual understanding, aiding in faster prompt iteration.

***

To replicate the behavior from the playground in API calls, refer to the corresponding parameter documentation in the platform guide.


# Prompt Cache
Source: https://novita.ai/docs/guides/llm-prompt-cache



Prompt Cache is a cost-optimization feature provided by the Novita inference engine.

When a request matches a previous Prompt, the system returns a cached result and charges only a minimal cache token fee — significantly reducing cost and improving response latency.

## 1. Benefits

With Prompt Cache enabled, you gain:

* **Lower Cost**

  Repeated Prompts no longer require full inference. Only minimal cache token fees are charged.

* **Lower Latency**

  Cached results are returned instantly without running the model.

* **Higher Throughput**

  In high-QPS scenarios, Prompt Cache reduces compute load and improves overall system capacity.

* **Transparent to Your Application**

  no additional logic or system changes are required.

## 2. Supported Models

Several serverless open-source models currently support prompt cache billing, including:

<PromptCacheModels />

For pricing details regarding the prompt cache feature of supported models, please refer to: [https://novita.ai/pricing](https://novita.ai/pricing) (see "Cache" section).

## 3. Use Cases

Prompt Cache is highly effective in workloads with **frequent repeated Prompts**, including but not limited to:

* **Template-based Generation**
  * Fixed-format summaries
  * Template-driven rewriting
  * Prompts reused across tasks
* **Text Classification & Field Extraction**
  * Content type classification
  * Tag or key information extraction
* **Content Moderation**
  * Review of comments, ads, or titles
  * Many moderation prompts repeat across users and time
* **Repeated System Prompts in Chat Applications**
  * Chatbot persona definitions
  * Global conversation rules
  * Background information reused across multiple turns
* **Workflow / Assistant-style Prompts**
  * SQL generation assistants
  * Code repair assistants
  * Summary assistants with fixed output formats

These scenarios naturally achieve high cache hit rates, reducing inference cost significantly.

## 4. Response Examples

<Note>
  When the cache is hit, no inference is performed, resulting in significantly lower cost and faster responses.
</Note>

If the model supports prompt caching, your API calls require no modifications. Below is a sample response when hitting the cached result:

```JSON theme={"system"}
{
    "prompt_tokens": 3295,
    "completion_tokens": 137,
    "total_tokens": 3432,
    "prompt_tokens_details":
    {
        "audio_tokens": 0,
        "cached_tokens": 448,
        "cache_creation_Prompt_tokens": 0,
        "cache_read_Prompt_tokens": 0
    }
}
```


# Rate limits
Source: https://novita.ai/docs/guides/llm-rate-limits



Rate limits control how frequently users can make requests to our LLM API within specific time periods. Understanding and working within these limits is essential for optimal API usage.

## 1. Understanding Rate Limits

### What are Rate Limits?

Rate limits restrict the number of API requests that can be made within defined time periods. They help:

* Prevent API abuse and misuse;
* Ensure fair resource distribution among users;
* Maintain consistent API performance and reliability;
* Protect the stability of our services.

### Default Rate Limits

Each account has a default rate limit for model calls, measured in RPM (requests per model per minute) and TPM (tokens per model per minute). Rate limits vary by account tier, as outlined in the tables below.

<table>
  <thead>
    <tr>
      <th>Tier</th>
      <th>How to reach</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>T1</td>
      <td>Monthly top-ups did not exceed \$50 in any of the last 3 calendar months.</td>
    </tr>

    <tr>
      <td>T2</td>
      <td>Monthly top-ups were at least \$50 but did not exceed \$500 in any of the last 3 calendar months.</td>
    </tr>

    <tr>
      <td>T3</td>
      <td>Monthly top-ups were at least \$500 but did not exceed \$3,000 in any of the last 3 calendar months.</td>
    </tr>

    <tr>
      <td>T4</td>
      <td>Monthly top-ups were at least \$3,000 but did not exceed \$10,000 in any of the last 3 calendar months.</td>
    </tr>

    <tr>
      <td>T5</td>
      <td>Monthly top-ups were at least \$10,000 in at least one of the last 3 calendar months.</td>
    </tr>
  </tbody>
</table>

<Tip>The last 3 calendar months refers to the current month and the two months before it.</Tip>

Default Rate Limit by Tier (RPM / TPM):

<DynamicRPMList />

## 2. Handling Rate Limits

### How to Monitor Rate Limits?

When you exceed the rate limit, the API will return:

* HTTP Status Code: 429 (Too Many Requests);
* A rate limit exceeded message in the response body.

### Best Practices

To avoid hitting rate limits:

1. Implement request throttling in your application;
2. Add exponential backoff for retries;
3. Monitor your API usage patterns.

### When You Hit Rate Limits

If you receive a 429 error, you can:

1. **Retry Later**: Wait a short period before retrying your request;
2. **Optimize Requests**: Reduce request frequency;
3. **Rate Limits Increase**: For higher rate limits, you can:
   * <a href="https://discord.gg/YyPRAzwp7P">Contact us through Discord</a>
   * or <a href="https://meet.brevo.com/novita-ai/contact-sales">Book a call with our sales team</a>

***

**If you have any questions, [please reach out to us on Discord](https://discord.gg/YyPRAzwp7P).**


# Reasoning Models
Source: https://novita.ai/docs/guides/llm-reasoning



## Overview

Reasoning models are advanced language models optimized for complex problem-solving tasks. By generating detailed reasoning steps (chain-of-thought), they improve the accuracy of answers in analytical scenarios.

### Typical Use Cases

* **Complex Problem Solving**: Suitable for tasks requiring step-by-step logic, such as math or scientific reasoning.
* **Decision Support Systems**: Helps explain the logic behind conclusions by providing detailed reasoning processes.
* **Education and Training**: Assists learners in understanding complex concepts by presenting derivation processes clearly.

***

## Installation & Setup

Before using reasoning models, make sure the latest OpenAI SDK is installed:

```bash theme={"system"}
pip install -U openai
```

***

## API Usage

Use the `/chat/completions` endpoint to invoke reasoning models.

### Request Parameters

* `max_tokens`: Sets the maximum number of tokens the model can return.
* `temperature`: Recommended between 0.5 and 0.7 (suggested: 0.6) to balance creativity and logic.
* `top_p`: Recommended value is 0.95.

***

### Example Code

#### Streaming Response

```python theme={"system"}
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.novita.ai/openai")
messages = [
    {"role": "user", "content": "Explain Newton's Second Law."}
]

response = client.chat.completions.create(
    model="deepseek/deepseek-r1",
    messages=messages,
    stream=True,
    max_tokens=4096
)

content = ""
reasoning_content = ""
for chunk in response:
    if chunk.choices[0].delta.content:
        content += chunk.choices[0].delta.content
    if chunk.choices[0].delta.reasoning_content:
        reasoning_content += chunk.choices[0].delta.reasoning_content

print("Final Answer:", content)
print("Reasoning Steps:", reasoning_content)
```

#### Non-Streaming Response

```python theme={"system"}
response = client.chat.completions.create(
    model="deepseek/deepseek-r1",
    messages=[
        {"role": "user", "content": "What is the greenhouse effect? How can it be mitigated?"}
    ],
    stream=False,
    max_tokens=4096
)

content = response.choices[0].message.content
reasoning_content = response.choices[0].message.reasoning_content

print("Final Answer:", content)
print("Reasoning Steps:", reasoning_content)
```

***

## Context Management

Reasoning outputs are not automatically carried over to the next round of dialogue. You must manually maintain the message history:

```python theme={"system"}
messages.append({"role": "assistant", "content": content})
messages.append({"role": "user", "content": "Please continue explaining the solution."})
```

***

## Supported Models

The following reasoning models are currently supported on the Novita platform:

<ReasoningModels />

***

## Billing

* Billing is based on the number of tokens for both input and output.
* Please refer to each model's pricing page for specific billing rules and token conversion details.

***

## Notes & Best Practices

* Avoid placing reasoning instructions in the `system` message. Instead, make the intent explicit in the `user` message.
* For mathematical tasks, clearly instruct the model, e.g., “Please reason step by step and provide a final answer.”
* To prevent the model from skipping reasoning steps, consider asking for a newline before the final answer.


#    Recommended Models
Source: https://novita.ai/docs/guides/llm-recommended



A list of recommended open models for common use cases.

## Which open models should I use?

Actually, there’s no single right answer! Here’s a curated list based on Novita internal testing, community feedback, and external benchmarks. We recommend using it as a starting point, and we will update it regularly as new models emerge.

<Note>
  * Model sizes are marked as Small, Medium, or Large
  * For best latency, use small or medium models. For best quality, use large models or fine-tune medium or small models.
  * You can explore all models in the Novita Model Library
</Note>

| **Use Cases**                       | **Recommended Models**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Code generation & reasoning**     | [**Deepseek-r1-0528**](https://novita.ai/models/llm/deepseek-deepseek-r1-0528), [**Deepseek-v3-0324**](https://novita.ai/models/llm/deepseek-deepseek-v3-0324),[**Qwen3-Coder-480B-A35B-Instruct**](https://novita.ai/models/llm/qwen-qwen3-coder-480b-a35b-instruct)[**,Qwen3-235B-A22B-Instruct-2507**](https://novita.ai/models/llm/qwen-qwen3-235b-a22b-instruct-2507)\_(Large)                               \_[**Kimi-K2-Instruct**](https://novita.ai/models/llm/moonshotai-kimi-k2-instruct)[**,GLM-4.5**](https://novita.ai/models/llm/zai-org-glm-4.5)(Medium) |
| **General reasoning & planning**    | [**Deepseek-r1-0528**](https://novita.ai/models/llm/deepseek-deepseek-r1-0528), [**Deepseek-v3-0324**](https://novita.ai/models/llm/deepseek-deepseek-v3-0324) *(Large)*<br />[**Qwen-2.5-72b-instruct**](https://novita.ai/models/llm/qwen-qwen-2.5-72b-instruct), [**Llama-3.3-70b-instruct**](https://novita.ai/models/llm/meta-llama-llama-3.3-70b-instruct) *(Medium)*                                                                                                                                                                                              |
| **Function calling & tool use**     | [**Qwen3-235b-a22b-fp8**](https://novita.ai/models/llm/qwen-qwen3-235b-a22b-fp8) *(Large)*<br />**Qwen 3 Family Models** *(Large/Medium/Small)*                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **Long context & summarization**    | [**Llama-4-maverick-17b-128e-instruct-fp8**](https://novita.ai/models/llm/meta-llama-llama-4-maverick-17b-128e-instruct-fp8) *(Large)*<br />[**Llama-4-scout-17b-16e-instruct**](https://novita.ai/models/llm/meta-llama-llama-4-scout-17b-16e-instruct) *(Medium)*                                                                                                                                                                                                                                                                                                      |
| **Vision & document understanding** | [**Llama-4-maverick-17b-128e-instruct-fp8**](https://novita.ai/models/llm/meta-llama-llama-4-maverick-17b-128e-instruct-fp8) *(Large)*<br />[**Qwen2.5-vl-72b-instruct**](https://novita.ai/models/llm/qwen-qwen2.5-vl-72b-instruct), [**Llama-4-scout-17b-16e-instruct**](https://novita.ai/models/llm/meta-llama-llama-4-scout-17b-16e-instruct) *(Medium)*                                                                                                                                                                                                            |
| **Low-latency NLU & extraction**    | [**Llama-3.1-8b-instruct**](https://novita.ai/models/llm/meta-llama-llama-3.1-8b-instruct), [**Llama-3.2-3b-instruct**](https://novita.ai/models/llm/meta-llama-llama-3.2-3b-instruct), [**Llama-3.2-1b-instruct**](https://novita.ai/models/llm/meta-llama-llama-3.2-1b-instruct), [**Qwen3-8b-fp8**](https://novita.ai/models/llm/qwen-qwen3-8b-fp8) *(Small)*                                                                                                                                                                                                         |

*Last updated: August 1, 2025*


# Structured Outputs
Source: https://novita.ai/docs/guides/llm-structured-outputs



`Structured Outputs` enables the model to generate responses that adhere to your supplied [JSON Schema](https://json-schema.org/specification).

## Supported Models

The following models support `Structured Outputs`:

<StructuredOutputsModels />

## Quick Start Guide

This guide demonstrates how to use `Structured Outputs` ability to generate the JSON response via `json_schema` response format. We will walk through a complete Python code example.

### 1. Initialize the Client

First, you need to initialize the client with your Novita API key.

```python theme={"system"}
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    # Get the Novita AI API Key from: https://novita.ai/settings/key-management.
    api_key="<YOUR Novita AI API Key>",
)

# Go to the [Models](https://novita.ai/models) page to see the models that support `Structured Outputs`.
model = "mistralai/mistral-7b-instruct"
```

### 2. Define the JSON schema

This example creates a schema for extracting expense information from the user's input.

```python theme={"system"}

# Define system prompt for expense tracking.
system_prompt = """You are an expense tracking assistant. 
Extract expense information from the user's input and format it according to the provided schema."""

# Define JSON schema for structured response.
response_format = {
    "type": "json_schema",
    "json_schema": {
        "name": "expense_tracking_schema",
        "schema": {
            "type": "object",
            "properties": {
                "expenses": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "description": {
                                "type": "string",
                                "description": "Description of the expense"
                            },
                            "amount": {
                                "type": "number",
                                "description": "Amount spent in dollars"
                            },
                            "date": {
                                "type": "string",
                                "description": "When the expense occurred"
                            },
                            "category": {
                                "type": "string",
                                "description": "Category of expense (e.g., food, office, travel)"
                            }
                        },
                        "required": [
                            "description",
                            "amount"
                        ]
                    }
                },
                "total": {
                    "type": "number",
                    "description": "Total amount of all expenses"
                }
            },
            "required": [
                "expenses",
                "total"
            ],
        },
    },
}
```

### 3. Request chat completion API

Now, make the chat completion request to the Novita endpoint.

This request includes the `response_format` parameter, defining the JSON schema we defined in the previous step.

```python theme={"system"}
chat_completion = client.chat.completions.create(
    model=model,
    messages=[
        {
            "role": "system",
            "content": system_prompt,
        },
        {
            "role": "user",
            "content": """I spent $120 on dinner at an Italian restaurant last Friday with my colleagues.
Also bought office supplies for $45 on Monday.""",
        },
    ],
    max_tokens=1024,
    temperature=0.8,
    stream=False,
    response_format=response_format,
)

response_content = chat_completion.choices[0].message.content

# Parse and prettify the JSON
try:
    json_response = json.loads(response_content)
    prettified_json = json.dumps(json_response, indent=2)
    print(prettified_json)
except json.JSONDecodeError:
    print("Could not parse response as JSON. Raw response:")
    print(response_content)
```

**Output:**

```json theme={"system"}
{
  "expenses": [
    {
      "date": "2023-03-17",
      "description": "Dinner at Italian restaurant",
      "amount": 120,
      "category": "Food & Dining"
    },
    {
      "date": "2023-03-13",
      "description": "Office supplies",
      "amount": 45,
      "category": "Office Supplies"
    }
  ],
  "total": 165
}
```

### The Complete Code

```python theme={"system"}
from openai import OpenAI
import json

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    # Get the Novita AI API Key from: https://novita.ai/settings/key-management.
    api_key="<YOUR Novita AI API Key>",
)

# Go to the [Models](https://novita.ai/models) page to see the models that support `Structured Outputs`.
model = "mistralai/mistral-7b-instruct"

# Example of using JSON Schema for structured output
# This example creates a schema for extracting expense information

# Define system prompt for expense tracking
system_prompt = """You are an expense tracking assistant. 
Extract expense information from the user's input and format it according to the provided schema."""

# Define JSON schema for structured response
response_format = {
    "type": "json_schema",
    "json_schema": {
        "name": "expense_tracking_schema",
        "schema": {
            "type": "object",
            "properties": {
                "expenses": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "description": {
                                "type": "string",
                                "description": "Description of the expense"
                            },
                            "amount": {
                                "type": "number",
                                "description": "Amount spent in dollars"
                            },
                            "date": {
                                "type": "string",
                                "description": "When the expense occurred"
                            },
                            "category": {
                                "type": "string",
                                "description": "Category of expense (e.g., food, office, travel)"
                            }
                        },
                        "required": [
                            "description",
                            "amount"
                        ]
                    }
                },
                "total": {
                    "type": "number",
                    "description": "Total amount of all expenses"
                }
            },
            "required": [
                "expenses",
                "total"
            ],
        },
    },
}

chat_completion = client.chat.completions.create(
    model=model,
    messages=[
        {
            "role": "system",
            "content": system_prompt,
        },
        {
            "role": "user",
            "content": """I spent $120 on dinner at an Italian restaurant last Friday with my colleagues.
Also bought office supplies for $45 on Monday.""",
        },
    ],
    max_tokens=1024,
    temperature=0.8,
    stream=False,
    response_format=response_format,
)

response_content = chat_completion.choices[0].message.content

# Parse and prettify the JSON
try:
    json_response = json.loads(response_content)
    prettified_json = json.dumps(json_response, indent=2)
    print(prettified_json)
except json.JSONDecodeError:
    print("Could not parse response as JSON. Raw response:")
    print(response_content)
```


# Vision Language Models
Source: https://novita.ai/docs/guides/llm-vision



## Overview

Vision-Language Models (VLMs) are a type of multimodal foundation model capable of processing both image and text inputs. These models understand visual content in conjunction with language instructions, and generate high-quality responses based on the combined context. They are widely used in scenarios involving image recognition, content interpretation, and intelligent visual Q\&A.

### Typical Use Cases

* **Image Recognition and Description**: Automatically identifies objects, colors, scenes, and spatial relationships in images, and generates natural language descriptions.
* **Multimodal Understanding**: Combines image input and contextual text for multi-turn dialogue and task completion.
* **Visual Question Answering**: Acts as an advanced OCR tool by recognizing and interpreting text embedded in images.
* **Emerging Applications**: Ideal for use in intelligent vision assistants, robot perception, AR interfaces, and more.

***

## API Usage Guide

To invoke a Vision-Language Model, use the `/chat/completions` endpoint with both image and text inputs.

### Image Detail Parameter

Use the `detail` field to control image resolution. The following modes are available:

* `high`: High resolution, preserves more detail—ideal for precision tasks.
* `low`: Low resolution, faster response—suitable for real-time usage.
* `auto`: Automatically selects the appropriate mode.

***

### Example Message Format

#### Image via URL

```json theme={"system"}
{
  "role": "user",
  "content": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.png",
        "detail": "high"
      }
    },
    {
      "type": "text",
      "text": "Please describe the scene in the image."
    }
  ]
}
```

#### Image via Base64

```json theme={"system"}
{
  "role": "user",
  "content": [
    {
      "type": "image_url",
      "image_url": {
        "url": "data:image/jpeg;base64,{base64_image}",
        "detail": "low"
      }
    },
    {
      "type": "text",
      "text": "What text is present in the image?"
    }
  ]
}
```

***

### Python Code: Encode Image to Base64

```python theme={"system"}
import base64
from PIL import Image
import io

def image_to_base64(image_path):
    with Image.open(image_path) as img:
        buffered = io.BytesIO()
        img.save(buffered, format="JPEG")
        return base64.b64encode(buffered.getvalue()).decode('utf-8')

base64_image = image_to_base64("path/to/your/image.jpg")
```

***

## Multi-Image Input

The API supports sending multiple images alongside text input. For best results, we recommend sending no more than two images per request.

```json theme={"system"}
{
  "role": "user",
  "content": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image1.png"
      }
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "data:image/jpeg;base64,{base64_image}"
      }
    },
    {
      "type": "text",
      "text": "Compare the common features of these two images."
    }
  ]
}
```

***

## Supported Models

The following Vision-Language Models are currently supported on the Novita platform:

<VisionModels />

Visit the [Model Hub](https://novita.ai/models-console/library) for a complete and up-to-date list of available models.

***

## Billing

Image input is tokenized and counted toward billing together with text.

* Each model uses a different image-to-token conversion method.
* Refer to each model’s pricing page for detailed billing and token policy.

***

## API Call Examples

### Single Image Description

```python theme={"system"}
from openai import OpenAI

client = OpenAI(api_key="YOUR_KEY", base_url="https://api.novita.ai/openai")

response = client.chat.completions.create(
    model="qwen/qwen2.5-vl-72b-instruct",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/cityscape.jpg"
                    }
                },
                {
                    "type": "text",
                    "text": "Describe the main buildings in the image."
                }
            ]
        }
    ],
    stream=True
)

for chunk in response:
    print(chunk.choices[0].delta.content or "", end="", flush=True)
```

### Multi-Image Comparison

```python theme={"system"}
response = client.chat.completions.create(
    model="qwen/qwen2.5-vl-72b-instruct",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/product1.jpg"
                    }
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/product2.jpg"
                    }
                },
                {
                    "type": "text",
                    "text": "Please compare the key differences between these two products."
                }
            ]
        }
    ],
    stream=True
)

for chunk in response:
    print(chunk.choices[0].delta.content or "", end="", flush=True)
```

***

## Notes & Troubleshooting

* Image resolution and clarity significantly affect model performance. Use high-quality sources where possible.
* Base64-encoded images should ideally be under 1MB to avoid timeouts or errors.
* For detailed usage, [book a call with our sales team](https://meet.brevo.com/novita-ai/contact-sales) or contact support if needed.


# LobeChat
Source: https://novita.ai/docs/guides/lobechat

Integrate Novita AI with LobeChat to build advanced AI apps with multimodal capabilities, enhanced privacy, and customizable features.

With the **Novita AI & LobeChat integration**, you gain seamless access to Novita AI’s comprehensive suite of LLM models, including Llama, DeepSeek, and more. This integration enables you to create and deploy advanced AI applications tailored to your needs. Whether it’s customer service, content creation, or personal assistance, LobeChat, and Novita AI provide the tools to build intelligent, dynamic, and privacy-focused AI solutions.

This guide will walk you through integrating Novita AI’s LLMs with the LobeChat platform, enabling you to deploy AI applications with advanced capabilities like multimodal interaction, context-aware reasoning, and extensible plugins.

## **What Is LobeChat?**

LobeChat is an open-source, modern UI/Framework designed for ChatGPT and other LLMs. It simplifies the development of AI chat applications by supporting speech synthesis, multi-modal inputs, and an extensible plugin ecosystem. With LobeChat, you can deploy your private chat application using models like OpenAI’s ChatGPT, Claude, Gemini, or Novita AI’s LLMs in just one click.

## **Prerequisites**

Before you begin, ensure you have the following:

* **Novita AI LLM API Key**:
  * Visit [Novita AI’s website](https://novita.ai/) and create an account.
  * After logging in, go to the [**Key Management**](https://novita.ai/settings/key-management) page to generate your **API Key**. This key is required to connect Novita AI’s models to LobeChat.

    <Frame>
      ![Novita AI key management](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/dify-1.png)
    </Frame>
* **LobeChat Account**
  * Sign up for a LobeChat account at [LobeChat](https://lobechat.com).

## **Integration Steps**

### **Step 1: Connect Novita AI to LobeChat**

<Frame>
  <img alt="Connect Novita AI to LobeChat" />
</Frame>

To connect Novita AI’s models with LobeChat:

* Log in to your **LobeChat account** and access the [**Settings**](https://lobechat.com/settings/common).
* Navigate to the **AI Service Provider** tab.
* Scroll down to find the **Novita AI** section and expand it.
* Paste your **Novita AI API Key** into the provided field and click **Save**.

### **Step 2:** Select a Novita AI Model

Once the API Key is configured, you can select a Novita AI LLM model to power your AI application:

<Frame>
  <img alt="Choose a Novita AI Model" />
</Frame>

### Step 3: Launch Your First Chat

Begin your conversation with Novita AI LLM on LobeChat.


# LoLLMS WebUI
Source: https://novita.ai/docs/guides/lollmswebui

Easily integrate Novita AI with LoLLMS WebUI to enhance your productivity and simplify complex tasks.

LoLLMS WebUI, a centralized platform designed for effortless interaction with Large Language Models (LLMs) and multimodal AI systems, offers an intuitive interface to unlock the full potential of AI. The integration between Novita AI and LoLLMS WebUI will unleash transformative power,enabling you to simplify complex tasks, find answers, and explore new possibilities effortlessly.

By combining Novita AI with LoLLMS, you'll gain access to cutting-edge AI capabilities, making it your ultimate assistant for enhanced productivity. This guide provides a step-by-step walkthrough to help you maximize the benefits of this powerful integration.

## How to Leverage Novita AI with LoLLMS WebUI

You can find the GitHub repository of LoLLMS WebUI here: [ParisNeo/lollms-webui](https://github.com/ParisNeo/lollms-webui).

### Obtain Your Novita AI API Key

1. [Log in](https://novita.ai/user/login) to your Novita AI account.
2. Navigate to [the Key Management page](https://novita.ai/settings/key-management).
3. Generate a new API Key and copy it.

### Install LoLLMS WebUI

1. Automatic Installation:
   * Download the installation script from [the scripts folder](https://github.com/ParisNeo/lollms-webui/tree/main/scripts) and run it:
     * `lollms_installer.bat` for Windows.
     * `lollms_installer.sh` for Linux.
     * `lollms_installer_macos.sh` for Mac.
2. Manual Installation:
   * Ensure Python 3.11 is installed. Check your version with `python --version`.
   * If needed, download Python 3.11 from [Python.org](https://www.python.org/downloads/release/python-3118/).

Step 1: Clone the Repository

```bash theme={"system"}
git clone --recursive https://github.com/ParisNeo/lollms-webui.git
cd lollms-webui
git submodule update --init --recursive
```

Step 2: Create and Activate a Virtual Environment

* Create a Virtual Environment:

```bash theme={"system"}
python -m venv venv
```

* Activate the Virtual Environment:
  * On Windows:

    ```bash theme={"system"}
    .\venv\Scripts\activate
    ```
  * On Linux/Mac:

    ```bash theme={"system"}
    source venv/bin/activate
    ```

Step 3: Install Requirements

```bash theme={"system"}
pip install -r requirements.txt
pip install -e ./lollms_core
```

Step 4: Create global\_paths\_cfg.yaml

```bash theme={"system"}
mkdir -p $HOME/.lollms_personal_data

cat > global_paths_cfg.yaml << EOL
lollms_path: $(pwd)/lollms_core/lollms
lollms_personal_path: $HOME/.lollms_personal_data
EOL
```

### Configure Novita AI in LoLLMS WebUI

1. Install Novita AI Binding

* Set environment variables for Novita AI binding. For example:

  * On Windows:

  ```bash theme={"system"}
  set NOVITA_AI_API_KEY="your_api_key_here"
  set NOVITA_AI_MODEL_NAME="your_model_name_here"
  ```

  * On Linux/Mac:

  ```bash theme={"system"}
  export NOVITA_AI_API_KEY="your_api_key_here"
  export NOVITA_AI_MODEL_NAME="your_model_name_here"
  ```
* Run the script to finalize the setup:

  ```bash theme={"system"}
  python zoos/bindings_zoo/novita_ai/__init__.py
  ```

2. Run the Server

```bash theme={"system"}
python app.py
```

3. Use Novita AI in LoLLMS WebUI

* Open your browser and navigate to [http://localhost:9600](http://localhost:9600) (or the port shown in the terminal).
* Select Novita AI from the available bindings.
* Enter your Novita AI API key.
* Select your desired Novita AI model.

[******Here is an application: Vibe Coding Using Novita AI Bindings and Services on LoLLMS WebUI.******](https://www.youtube.com/watch?v=jyFaP4zTM9g)


# Low Balance Alert
Source: https://novita.ai/docs/guides/low-balance-alert



To prevent service interruption due to insufficient balance, you can enable a low balance alert.

Once set, if your account balance drops below your designated threshold, the system will notify you via **Email** or **Inbox** to ensure continuous service.

<Note>
  The alert will be sent at most once per day (from 00:00 to 24:00 UTC+0), and notifications will stop once your balance rises above the set threshold.
</Note>

## How to Set Up

1. Go to the [Low Balance Alert page](https://novita.ai/billing/balance-warning) and click "Add Alerts".

2. In the pop-up dialog, enter your desired warning amount, enable the "Active" status, and click "Confirm".

* The warning amount must be between \$1 and \$1,000.
* The interval between amounts with an active warning status must be at least \$5.


# A Brief Introduction to Clip Skip
Source: https://novita.ai/docs/guides/model-apis-clip-skip



Clip Skip is a feature that literally skips part of the image generation process, resulting in slightly different outputs. This also leads to faster image rendering.

### But why would anyone want to skip a part of the diffusion process?

A typical Stable Diffusion 1.5 base model image goes through 12 "clip" layers, which represent levels of refinement. The early layers are very broad, while the later layers produce images that are clearer and more specific. In the case of some base models, especially those based on Danbooru tags, trial and error has shown that skipping certain layers can lead to better images, as the broad clip layers may introduce unwanted noise. You can literally skip layers, saving GPU time and achieving better art.

If you want a picture of "a cow", you might not care about the subcategories of "cow" that the text model might have. Especially since these can vary in quality. So if you want "a cow", you might not want "an Aberdeen Angus bull". (The full post is at the bottom of this page.)

You can think of CLIP Skip as a setting for "how accurate you want the text model to be". You can test it out and see that each clip stage adds more definition in terms of description. For example, if you have a detailed prompt about a young man standing in a field, with lower clip stages you’d get an image of "a man standing", while deeper stages would yield "a young man standing" or "a young man standing in a forest", and so on. CLIP Skip becomes particularly effective when using models that are structured in a specific way, where the "1girl" tag can break down into many sub-tags connected to that main tag.

### Do I need it?

It’s a minor optimization recommended only for hardcore, quality-obsessed enthusiasts. If you’re working on anime or semi-realism, it’s worth a try.

### Limitations

**How many layers to skip**

Generally speaking, skipping 1 or 2 layers can yield good results. However, skipping more than 2 layers may produce images that appear to have low guidance.

**Inconsistent compatibility**

Clip Skip has become one of those "wear your seatbelt" kinds of safe defaults, where many people prefer to set it and forget it. This approach isn’t wise. The feature can also yield unpredictable results when used with other technologies, such as LoRAs and Textual Inversions. Missing layers where layers are expected can degrade the image quality or have no effect at all.

It’s often faster to simply try it out than to compare results. Just make sure you also lock the seed, guidance, concept, and sampler to accurately assess the differences.


# Configure Custom AWS S3 Bucket
Source: https://novita.ai/docs/guides/model-apis-configure-custom-s3-bucket



By default, Novita AI temporarily stores output results in our private S3 bucket and returns the results to the user through a temporary authorized S3 link.

However, you can set up a **Custom S3 Bucket** to allow us to save the results in your own bucket. Please follow the steps below to enable this.

## 1. Configure S3 Bucket Policy

First, change your S3 Bucket Policy configuration to the following format (replace `${BucketName}` with your bucket name):

```json theme={"system"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "CanonicalUser": "e98cde8d11ec7c03ac08688f1a933b08b0f0f7746b21c4f2e7b2c8202cc0532f"
      },
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl"
      ],
      "Resource": "arn:aws:s3:::${BucketName}/*"
    }
  ]
}
```

## 2. Enable Custom Storage in V3 APIs

For V3 API endpoints, Novita AI provides the `custom_storage` parameter in the request body, allowing you to configure your custom S3 bucket for storing generated images.

Here's an example using the `txt2img` API endpoint:

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/txt2img' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
  "extra": {
    "response_image_type": "jpeg",
    "custom_storage": {
      "aws_s3": {
        "region": "us-east-2",
        "bucket": "test_bucket",
        "path": "/"
      }
    }
  },
  "request": {
    "prompt": "a cute dog",
    "model_name": "realisticVisionV51_v51VAE_94301.safetensors",
    "negative_prompt": "",
    "width": 512,
    "height": 384,
    "image_num": 2,
    "steps": 20,
    "seed": 123,
    "clip_skip": 1,
    "sampler_name": "Euler a",
    "guidance_scale": 7.5
  }
}'
```


# Upload Custom LoRA Models
Source: https://novita.ai/docs/guides/model-apis-custom-model



<Tip>
  * Currently, the Model Upload feature only supports LoRA models, with a limit of 5 uploads per user. We plan to gradually lift these restrictions in the future;
  * The Model Upload feature is temporarily available free of charge. However, we may introduce a fee for this service in the future. Please stay tuned for future announcements;
  * If you have any questions, please contact our customer service or technical team through the [Discord Channel](https://discord.gg/YyPRAzwp7P).
</Tip>

Please follow the steps below to upload your custom LoRA models.

1. Log in to your account and go to the [Model Management Page](https://novita.ai/models-console/model-management).

2. Click the `Upload Model` button to upload your models.

3. Upload the LoRA model and fill in the form. Please note that the model name cannot be modified after submission.

4. After the model is uploaded successfully, you can use the model from the model list.

**For example:**

<Tip>
  In the following example, the LoRA model name `test_sd_name_in_api.safetensors` can be found in the `MODEL NAME IN API` column in your private model list.
</Tip>

```bash theme={"system"}
curl --location --request POST 'https://api.novita.ai/v3/async/txt2img' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{API Key}}' \
--data-raw '{
    "model_name": "AnythingV5_v5PrtRE.safetensors",
    "width": 512,
    "height": 768,
    "prompt": "a body stood high, behind him, looking down.",
    "negative_prompt": "",
    "sampler_name": "DPM++ 2S a Karras",
    "guidance_scale": 7.5,
    "steps": 30,
    "image_num": 1,
    "clip_skip": 0,
    "seed": -1,
    "loras": [
        {"model_name":"test_sd_name_in_api.safetensors", "strength":0.7}
    ]
}'
```


# How to subscribe to Dedicated Endpoints?
Source: https://novita.ai/docs/guides/model-apis-dedicated-endpoints



**Generally, subscribing to **Dedicated Endpoints** involves the following steps.**

* Applying for **Dedicated Endpoints** access;
* Starting a **Dedicated Endpoints** subscription;
* Waiting for the **Dedicated Endpoints** to be `Actived`.

## 1. Applying for Dedicated Endpoints access.

<Tip>Please skip this step if you already have access.</Tip>

Go to the [Dedicated Endpoint Pricing Page](https://novita.ai/pricing?utm_source=getstarted#dedicated_endpoints).

Choose the plan you want to subscribe to, click **"Contact Sales"**, and fill out the application form. After the Novita AI team reviews your request, you will receive a notification from us confirming that your request has been approved.

## 2. Starting a Dedicated Endpoints subscription.

Once the request is approved, you can subscribe the **Dedicated Endpoints** on the [Pricing Page](https://novita.ai/pricing?utm_source=getstarted#dedicated_endpoints).

<Tip>
  * You need to add a `Payment Method` if you haven't already done so.
  * Don't forget to input the `Coupon Code` if you have one.
</Tip>

The **Dedicated Endpoints** will be created after the payment is completed.

## 3. Waiting Dedicated Endpoints to be `Actived`.

Once you've subscribed the **Dedicated Endpoints**, they will enter the `Deploying` status, and you can access them from the [Dedicated Endpoints Setting Page](https://novita.ai/models-console/dedicated-endpoints).

Upon activation of the **Dedicated Endpoints**, you'll receive an email notification confirming that the service is now `Actived` and ready to use.

The billing cycle for **Dedicated Endpoints** is monthly and begins immediately upon the service entering the `Actived` status. And the next monthly billing will be automatically deducted from your credit account.

## 4. Make a request with Dedicated Endpoints resources.

For **Dedicated Endpoints**, we have added a request body parameter `extra.enterprise_plan` to allow you to enable the **Dedicated Endpoints**. Please refer to the code below.

```bash theme={"system"}
curl --location 'https://api.novita.ai/v3/async/txt2img' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
  "extra": {
    "response_image_type": "jpeg",
    "enterprise_plan": {
      "enabled": true
    }
  },
  "request": {
    "model_name": "sdxlUnstableDiffusers_v11_216694.safetensors",
    "prompt": "Luxury suite design, Spacious suite area, Luxuriously plush large bed, Refined office desk, Carefully selected furniture for the luxurious suite, High-end and opulent decor, Private office and lounge area, Comfortably luxurious office chair, Amenities for luxury travelers, Premium bedding and linens, Uniquely designed lighting fixtures, Luxurious suite curtain design, Private work corner, Luxurious amenities, Lavish lounge area, Sophisticated indoor plant, decorations, Exquisite luxury design, Exclusive services for the luxury suite, Luxury color scheme. Exclusive furniture for the luxury suite, a bedroom with a large bed and a desk",
    "negative_prompt": "(badhandv4:1.2),(worst quality:2),(low quality:2),(normal quality:2),lowres,bad anatomy,bad hands,((monochrome)),((grayscale)) watermark,moles, easynegative ng_deepnegative_v1_75t, (oversized head:2), (big head:2), (deformed face:1.5),( blurry face:2), bad eyes, irregular eyes, asymmetric eyes, ugly, teeth, (navel:0.9), artefact, jpg artefact, blurry face, blurry, blurred, pixelated, bad eyes, crossed eyes, blurry eyes",
    "width": 512,
    "height": 512,
    "image_num": 1,
    "steps": 20,
    "seed": 123,
    "clip_skip": 1,
    "guidance_scale": 7.5,
    "sampler_name": "Euler a"
  }
}'
```

<Tip>If you encounter any questions, [please reach out to us on Discord](https://discord.gg/YyPRAzwp7P).</Tip>


# Overview
Source: https://novita.ai/docs/guides/model-apis-overview



Novita AI deploys state-of-the-art open-source models. Use our APIs to access them out of the box!

<CardGroup>
  <Card title="Try Novita's LLM Playground" icon="box" href="https://novita.ai/model-api/product/llm-api/playground?utm_source=docs-guides">
    Test prompts, explore our models, and compare results instantly, no coding required.
  </Card>

  <Card title="Integrate with open-source LLM APIs" icon="box" href="/guides/llm-api">
    Get started with Novita's OpenAI-compatible APIs.
  </Card>

  <Card title="Explore our Image, Audio and Video Generation Models" icon="box" href="https://novita.ai/model-api/playground?utm_source=docs-guides">
    Try the Image, Audio and Video Generation Models in the Playground.
  </Card>

  <Card title="Integrate with Image, Audio and Video Generation APIs" icon="box" href="/api-reference/model-apis-introduction">
    Explore our API references.
  </Card>
</CardGroup>


# Rate limits
Source: https://novita.ai/docs/guides/model-apis-rate-limits



## 1. Understanding Rate Limits

Rate limiting refers to the rules that govern how frequently a user’s API may access our platform services within a given time window. Its goals are:

* **Prevent API abuse and misuse:** By setting an upper bound on request frequency, we limit abnormal or unintended traffic.
* **Ensure fair resource allocation:** We prevent a small number of users from monopolizing system resources, so everyone can access the service on equal terms.
* **Maintain API performance and reliability:** By smoothing out traffic spikes, we stabilize response times and reduce failure rates due to overload, improving overall service quality.
* **Protect system stability:** Rate limits help absorb sudden bursts of traffic, preventing high-concurrency spikes from overwhelming our infrastructure.

## 2. Rate Limiting Metrics

For our image and video models, we use two primary rate-limiting metrics:

* **IPM (Images Per Minute):** The number of images an image model is allowed to generate per minute.
* **RPM (Requests Per Minute):** The number of API requests a video model is allowed to handle per minute.

## 3. Default Rate Limits

For different models, our platform applies differentiated rate-limiting strategies based on each model’s computational resource consumption.

### **IPM**

The IPM (Images Per Minute) limit controls the number of images that can be generated per minute. The default IPM values for each model are listed in the table below.

| Resource/Service                | Model API            | User Default Settings |
| :------------------------------ | :------------------- | :-------------------- |
| Text to Image                   | `txt2img_v3`         | 20                    |
| Image to Image                  | `img2img_v3`         | 10                    |
| Remove Background               | `remove_background`  | 10                    |
| Replace Background              | `replace_background` | 10                    |
| Remove Text                     | `remove_text`        | 10                    |
| Inpainting                      | `inpainting`         | 10                    |
| Cleanup                         | `cleanup`            | 10                    |
| Merge Face                      | `merge_face`         | 10                    |
| FLUX.1 \[schnell] Text to Image | `flux-1-schnell`     | 10                    |
| Upscale                         | `upscale_v3`         | 20                    |

### **RPM**

The RPM (Requests Per Minute) limit controls the number of API requests allowed per minute. The default RPM values for each model are provided in the table below.

| Resource/Service          | Model API            | User Default Settings |
| :------------------------ | :------------------- | :-------------------- |
| Video Merge Face          | `video_merge_face`   | 10                    |
| Text to Video             | `txt2video`          | 2                     |
| Image to Video            | `img2video`          | 2                     |
| Wan 2.1 Text to Video     | `wan_txt_to_video`   | 20                    |
| Wan 2.1 Image to Video    | `wan i2v`            | 20                    |
| Hunyuan Video Fast        | `hunyuan_video_fast` | 20                    |
| KLING V1.6 Image to Video | `Kling i2v`          | 20                    |
| KLING V1.6 Text to Video  | `Kling t2v`          | 20                    |
| Minimax Video-01          | `Minimax`            | 20                    |

## 4. Handling Rate Limits

### How to Monitor Rate Limits?

If your API requests exceed the allowed rate, the API will return:

* **HTTP Status Code:** 429 Too Many Requests
* **Response Body:** A message indicating that the rate limit has been exceeded.

### Best Practices

**To avoid triggering rate limits, you can:**

* **Implement client-side request throttling:** Respect the platform’s rate limits by controlling your application’s request rate, ensuring you don’t send too many calls in a short period.
* **Use exponential backoff on retries:** When you receive a rate-limit response (e.g., HTTP 429), wait progressively longer between retry attempts instead of retrying immediately, reducing load on the service.
* **Monitor your API usage:** Continuously track and log your request counts, frequencies, and any error responses so you can adjust your usage patterns proactively.

### When You Hit Rate Limits

**If you receive an HTTP 429 ("Too Many Requests") response, you can:**

* **Retry later:** Wait a short period before sending your request again.
* **Optimize your requests:** Reduce the frequency of calls to stay within the platform’s rate limits.
* **Request a higher rate limit:** If you require a higher rate limit, please fill out the contact form at the [Quotas\&Limits](https://novita.ai/quota-limits/image)  to get in touch with us.


# A Brief Introduction to Sampler
Source: https://novita.ai/docs/guides/model-apis-sampler



Stable Diffusion Art. (n.d.). Samplers. Retrieved from [https://stable-diffusion-art.com/samplers/.](https://stable-diffusion-art.com/samplers/)

Many sampling methods are available in Novita AI, including Euler a, Heun, and DDIM. What are samplers? How do they work? What are the differences between them? Which one should you use? You will find the answers in this article.

<Frame>
  <img />
</Frame>

To produce an image, Stable Diffusion first generates a completely random image in the latent space. The noise predictor then estimates the noise of the image, which is subsequently subtracted from the image. This process is repeated multiple times, resulting in a clean image.

This denoising process is called sampling because Stable Diffusion generates a new sample image at each step. The method used in sampling is referred to as the `sampler` or `sampling method`.

Sampling is just one part of the Stable Diffusion model. Read the article "How Does Stable Diffusion Work?" if you want to understand the entire model.

Below is a sampling process in action. The sampler gradually produces cleaner and cleaner images.

<Frame>
  <img />
</Frame>

While the framework is the same, there are many different ways to carry out this denoising process. It is often a trade-off between speed and accuracy.

### Samplers Overview

As of this writing, there are 19 samplers available in Novita AI, and this number seems to be growing over time. What are the differences?

<Frame>
  <img />
</Frame>

You will learn about them in the later part of this article. The technical details can be overwhelming, so I will include a bird's-eye view in this section to help you get a general idea of what they are.

#### Old-School ODE Solvers

Let’s start with the easier ones. Some of the samplers on the list were invented more than a hundred years ago. They are old-school solvers for ordinary differential equations (ODE).

* Euler – The simplest possible solver.
* Heun – A more accurate but slower version of Euler.
* LMS (Linear Multi-Step Method) – Same speed as Euler but supposedly more accurate.

#### Ancestral Samplers

Do you notice that some sampler names have a single letter "a"?

* Euler a
* DPM2 a
* DPM++ 2S a
* DPM++ 2S a Karras

These are ancestral samplers. An ancestral sampler adds noise to the image at each sampling step. They are stochastic samplers because the sampling outcome contains some randomness.

Be aware that many other samplers are also stochastic, even if their names do not include an "a".

The drawback of using an ancestral sampler is that the image may not converge. Compare the images generated using Euler a and Euler below.

Euler a does not converge. (sampling steps 2–40)

<Frame>
  <img />
</Frame>

Euler converges. (sampling steps 2-40)

<Frame>
  <img />
</Frame>

Images generated with Euler a do not converge at high sampling steps, while images from Euler converge well.

For reproducibility, it is desirable to have the image converge. If you want to generate slight variations, you should use a variational seed.

#### Karras Noise Schedule

The samplers labeled "Karras" use the noise schedule recommended in the [Karras article](https://arxiv.org/abs/2206.00364). If you look closely, you will see that the noise step sizes are smaller near the end. This adjustment improves the quality of the images.

#### DDIM and PLMS

DDIM (Denoising Diffusion Implicit Model) and PLMS (Pseudo Linear Multi-Step Method) were the samplers included with the original Stable Diffusion v1. DDIM is one of the first samplers designed for diffusion models, while PLMS is a newer and faster alternative to DDIM. They are generally considered outdated and are not widely used anymore.

#### DPM and DPM++

DPM (Diffusion Probabilistic Model Solver) and DPM++ are new samplers designed for diffusion models released in 2022. They represent a family of solvers with similar architecture.

DPM and DPM2 are similar, with DPM2 being second-order (more accurate but slower).

DPM++ is an improvement over DPM.

DPM adaptive adjusts the step size adaptively. It can be slow since it doesn’t guarantee completion within the specified number of sampling steps.

#### UniPC

UniPC (Unified Predictor-Corrector) is a new sampler released in 2023. Inspired by the predictor-corrector method in ODE solvers, it can achieve high-quality image generation in 5-10 steps.

### How to Pick a Sampler

In this section, I will provide some objective comparisons to help you decide.

#### Image Convergence

In this section, I will generate the same image using different samplers with up to 40 sampling steps. The last image at the 40th step will be used as a reference for evaluating how quickly the sampling converges, with the Euler method serving as the benchmark.

> Euler, DDIM, PLMS, LMS Karras and Heun

First, let’s look at Euler, DDIM, PLMS, LMS Karras, and Heun as a group since they represent old-school ODE solvers or original diffusion solvers. DDIM converges at about the same number of steps as Euler but with more variations due to the injection of random noise during its sampling steps.

<Frame>
  <img />
</Frame>

PLMS did not perform well in this test.

LMS Karras seems to have difficulty converging and stabilizes at a higher baseline.

Heun converges faster but is twice as slow since it is a second-order method. Therefore, we should compare Heun at 30 steps with Euler at 15 steps, for example.

> Ancestral Samplers

If a stable, reproducible image is your goal, you should avoid using ancestral samplers, as they all fail to converge.

<Frame>
  <img />
</Frame>

> DPM and DPM2

DPM fast did not converge well. DPM2 and DPM2 Karras performs better than Euler but again in the expense of being two times slower.

DPM adaptive performs deceptively well because it uses its own adaptive sampling steps. It can be very slow.

<Frame>
  <img />
</Frame>

> DPM++ solvers

DPM++ SDE and DPM++ SDE Karras suffer the same shortcoming as ancestral samplers. They not only don’t converge, but the images also fluctuate significantly as the number of steps changes.

DPM++ 2M and DPM++ 2M Karras perform well. The Karras variant converges faster when the number of steps is high enough.

<Frame>
  <img />
</Frame>

> UniPC

UniPC converges a bit slower than Euler, but not too bad.

<Frame>
  <img />
</Frame>

#### Speed

<Frame>
  <img />
</Frame>

Although DPM adaptive performs well in convergence, it is also the slowest.

You may have noticed the rest of the rendering times fall into two groups, with the first group taking about the same time (about 1x), and the other group taking about twice as long (about 2x). This reflects the order of the solvers. 2nd order solvers, although more accurate, need to evaluate the denoising U-Net twice. So they are 2x slower.

#### Quality

Of course, speed and convergence mean nothing if the images look crappy.

**Final images**

Let’s first look at samples of the image.

<Frame>
  <img />
</Frame>

DPM++ fast failed pretty badly. Ancestral samples did not converge to the image that other samplers converged to.

Ancestral samplers tend to converge to an image of a kitten, while the deterministic ones tend to converge to a cat. There are no correct answers as long as they look good to you.

Perceptual quality
An image can still look good even if it hasn’t converged. Let’s look at how quickly each sampler can produce a high-quality image.

You will see perceptual quality measured with BRISQUE (Blind/Referenceless Image Spatial Quality Evaluator). It measures the quality of natural images.

DDIM is doing surprisingly well here, capable of producing the highest quality image within the group in as few as 8 steps.

### So… which one is the best?

Here are my recommendations:

1. If you want to use something fast, converging, new, and with decent quality, excellent choices are

* DPM++ 2M Karras with 20 – 30 steps
* UniPC with 20-30 steps.

2. If you want good quality images and don’t care about convergence, good choices are

* DPM++ SDE Karras with 10-15 steps (Note: This is a slower sampler)
* DDIM with 10-15 steps.

3. Avoid using any ancestral samplers if you prefer stable, reproducible images.

4. Euler and Heun are fine choices if you prefer something simple. Reduce the number of steps for Heun to save time.


# SDKs for Model APIs
Source: https://novita.ai/docs/guides/model-apis-sdks



Novita AI provides official SDKs to help you easily integrate our services into your applications.

## JavaScript SDK

### Installation

Install our JavaScript SDK using `npm`:

```bash theme={"system"}
npm i novita-sdk
```

### Quick Start

Visit [https://github.com/novitalabs/javascript-sdk](https://github.com/novitalabs/javascript-sdk) for a quick start.

## Python SDK

### Installation

Install our Python SDK using `pip`:

```bash theme={"system"}
pip install novita-client
```

### Quick Start

Visit [https://github.com/novitalabs/python-sdk](https://github.com/novitalabs/python-sdk) for a quick start.


# Training Image Caption Guidance
Source: https://novita.ai/docs/guides/model-apis-training-guidance



### Preparation

Depending on how and what you are training, you may need to crop the photos to a specific width and height. Other types of training may categorize images into various sizes and do not require cropping. Look into what is required for the training method you are using, the model you are training, and the program you are using to train your model.

### Captioning – General Notes

#### Avoid Automated Captioning

* BLIP and deepbooru are exciting, but it is still a bit early for them.

* BLIP and deepbooru struggle with context and relative importance.

* It is faster to manually caption than to fix mistakes made by BLIP or deepbooru and still have to manually caption.

#### Caption in the Same Manner You Prompt

* Captioning and prompting are related.

* Recognize how you typically prompt. Do you use verbose sentences? Short descriptions? Vague or detailed prompts?

* Caption in a similar style and verbosity to how you usually prompt.

#### Follow a Set Structure per Concept

* Following a structure will benefit the learning process.

* You might have one structure for photographs and another for illustrations. However, try to avoid mixing and matching structures when captioning a single dataset.

#### Captions are Like Variables You Can Use in Your Prompts

Everything you describe in a caption can be thought of as a variable that you can manipulate in your prompt. This has two implications:

1. You want to describe as many details as possible about anything that isn’t the concept you are trying to implicitly teach. In other words, describe everything that you want to become a variable. For example, if you are teaching a specific face but want to be able to change the hair color, you should describe the hair color in each image so that "hair color" becomes one of your variables.

2. You don’t want to describe anything (beyond a class-level description) that you want to be implicitly taught. In other words, the thing you are trying to teach shouldn’t become a variable. For example, if you are teaching a specific face, you should not describe it as having a big nose. You don’t want the nose size to be variable because then it isn’t that specific face anymore. However, you can still caption "face" if you want, which provides context to the model you are training. This does have some implications described in the following point.

#### Leveraging Classes as Tags

* There are two concepts here.

1. Using generic class tags will bias that entire class toward your training data. This may or may not be desired depending on your goals.

2. Using generic class tags provides context to the learning process. Conceptually, it is easier to learn what a "face" is when the model already has a reasonable approximation of "face".

* If you want to bias the entire class of your model toward your training images, use broad class tags rather than specific ones. For example, if you want to teach your model that every man should look like Brad Pitt, your captions should contain the tag "man" but should not be more specific than that. This influences your model to produce a Brad Pitt-looking man whenever you use the word "man" in your prompt. This also allows your model to draw on and leverage what it already knows about the concept of "man" while it is training.

* If you want to reduce the impact of your training on the entire class, include specific tags and de-emphasize class tags. For example, if you want to teach your model that only "ohwxman" should look like Brad Pitt, and you don't want every "man" to look like Brad Pitt, you would not use "man" as a tag, only tagging it with "ohwxman". This reduces the impact of your training images on the tag "man" and strongly associates your training images with "ohwxman". Your model will draw on what it knows about "ohwxman", which is practically nothing (see note), thus building up knowledge almost solely from your training images, creating a very strong association.

* **Note:** This is simplified for the sake of understanding. This would actually be tokenized into two tokens, "ohwx" and "man", but these tokens would be strongly correlated for training purposes, which should still reduce the impact on the overall class of "man" compared to training with "man" as a token in the caption. The mathematics involved is quite complex and well beyond the scope of this document.

#### Consistent Captioning

* Use consistent captions across all of your training. This will help you consistently invoke your concept when prompting.

* Using inconsistent tags across your dataset will make the concept you are trying to teach harder for the model to grasp, as you are essentially forcing it to learn both the concept and the different phrasings for that concept. It’s much better to have it just learn the concept under a single term.

* For example, you probably don’t want to have both "legs raised in air" and "raised legs" if you are trying to teach a single concept of a person with their legs up in the air. You want to be able to consistently invoke this pose in your prompt, so choose one way to caption it.

#### Avoid Repetition

* Try to avoid repetition wherever possible. Similar to prompting, repeating words increases the weighting of those words.

* For example, if we repeat the word "background" too much, we may have three tags that say "background" (e.g., simple background, white background, lamp in background). Even though we want the background to have low weight, we have unintentionally increased the weighting significantly. It would be better to combine these or reword them (e.g., simple white background with a lamp).

#### Take Note of Ordering

* Again, just like with prompting, order matters for the relative weighting of tags.

* Having a specific structure or order that you generally use for captions can help you maintain the relative weightings of tags between images in your dataset, which should benefit the training process.

* Having a standardized ordering makes the whole captioning process faster as you become familiar with captioning in that structure.

#### Use Your Model's Existing Knowledge to Your Advantage

* Your model already produces decent results and reasonably understands what you are prompting. Take advantage of that by captioning with words that already work well in your prompts.

* You want to use descriptive words, but if you use words that are too obscure or niche, you likely can't leverage much of the existing knowledge. For example, you could say "sarcastic" or "mordacious". The model has some idea of what "sarcastic" conveys, but it likely has no clue what "mordacious" means.

* You can also look at this from the opposite perspective. If you were trying to teach the concept of "mordacious", you might have a dataset full of images that convey "sarcastic" and caption them with both the tags "sarcastic" and "mordacious" side by side (so that they are close in relative weighting).

### Captioning – Structure

This is mainly for people or characters, so it might not be quite as applicable to something like fantasy landscapes, but perhaps it can provide some inspiration.

#### General Format

#### Loose Associations

* This is where we put any final loose associations we have with the image.

* This could be anything that pops up in our head, usually “feelings” that we feel when looking at the image or concepts we feel are portrayed, really anything goes here as long as it exists in the image.

* Keep in mind this is for loose associations. If the image is very obviously portraying some feeling, we may want it tagged closer to the start of the caption for higher weighting.

* For example: happy, sad, joyous, hopeful, lonely, sombre

#### FULL EXAMPLE OF A SINGLE IMAGE

This is an example of how we would caption a single image we picked off of safebooru. We will assume that I want to train the style of this image and associate it with the tag "ohwxStyle", and we will assume that we have many images in this style within our dataset.

Sample Image: [https://safebooru.org/index.php?page=post\&s=view\&id=3887414](https://safebooru.org/index.php?page=post\&s=view\&id=3887414)

* Globals: ohwxStyle

* Type or Perspective Of a: anime, drawing, of a young woman, full body shot, from side

* Action words: sitting, looking at viewer, smiling, head tilt, holding a phone, eyes closed

* Subject description: short brown hair, pale pink dress with dark edges, stuffed animal in lap, brown slippers

* Notable details: sunlight through windows as lighting source

* Background or location: brown couch, red patterned fabric on couch, wooden floor, white water-stained paint on walls, refrigerator in background, coffee machine sitting on a countertop, table in front of couch, bananas and coffee pot on table, white board on wall, clock on wall, stuffed animal chicken on floor

* Loose associations: dreary environment

All together: ohwxStyle, anime, drawing, of a young woman, full body shot, from side, sitting, looking at viewer, smiling, head tilt, holding a phone, eyes closed, short brown hair, pale pink dress with dark edges, stuffed animal in lap, brown slippers, sunlight through windows as lighting source, brown couch, red patterned fabric on couch, wooden floor, white water-stained paint on walls, refrigerator in background, coffee machine sitting on a countertop, table in front of couch, bananas and coffee pot on table, white board on wall, clock on wall, stuffed animal chicken on floor, dreary environment


# API V2 to V3 Migration Guide
Source: https://novita.ai/docs/guides/model-apis-v2-to-v3-migration



## Text to Image

### Request Body Parameter Mapping

<table>
  <thead>
    <tr>
      <th>V2</th>
      <th>V3</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**extra**<span>object</span></td>
      <td>**extra**<span>object</span></td>

      <td />
    </tr>

    <tr>
      <td>enable\_nsfw\_detection<br /><span>boolean</span></td>
      <td>enable\_nsfw\_detection<br /><span>boolean</span></td>

      <td />
    </tr>

    <tr>
      <td>nsfw\_detection\_level<br /><span>Enum: `0, 1, 2`</span></td>
      <td>nsfw\_detection\_level<br /><span>Enum: `0, 1, 2`</span></td>

      <td />
    </tr>

    <tr>
      <td>enable\_progress\_info</td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>response\_image\_type<br /><span>Enum: `png`, `jpeg`</span></td>
      <td>response\_image\_type<br /><span>Enum: `png, webp, jpeg`</span></td>
      <td>V3 adds support for `webp`image format</td>
    </tr>

    <tr>
      <td />

      <td>**request**<span>object</span></td>
      <td><span>New Field</span><br />All image generation parameters must be passed via the `request`in V3</td>
    </tr>

    <tr>
      <td>**prompt**<span>string</span><br />\<lora:\$sd\_name:\$weight></td>
      <td>prompt<span>string</span></td>
      <td>Moved Inside</td>
    </tr>

    <tr>
      <td />

      <td>loras<span>object\[]</span></td>
      <td><span>Moved Inside</span><br />**Migrate LoRA usage: From **`prompt`** to **`request.loras`** parameter**</td>
    </tr>

    <tr>
      <td />

      <td>model\_name<span>string</span></td>
      <td><span>New Field</span><br />Name of lora, retrieve the corresponding sd\_name\_in\_api value by invoking the [Get Model API](https://novita.ai/docs/api-reference/model-apis-get-model) endpoint with filter.types=lora as the query parameter.</td>
    </tr>

    <tr>
      <td />

      <td>strength<span>number(float32)</span></td>
      <td><span>New Field</span><br />The strength value of lora. The larger the value, the more biased the effect is towards lora, Range \[0, 1]</td>
    </tr>

    <tr>
      <td>**negative\_prompt**<span>string</span></td>
      <td>negative\_prompt<span>string</span></td>
      <td>Moved Inside</td>
    </tr>

    <tr>
      <td>**sampler\_name**<span>string</span></td>
      <td>sampler\_name<span>string</span></td>
      <td>Moved Inside</td>
    </tr>

    <tr>
      <td>**batch\_size**<span>integer</span></td>
      <td>image\_num<span>integer</span></td>
      <td><span>Changed</span><br /> `num_images` **→** `request.image_num`</td>
    </tr>

    <tr>
      <td>**n\_iter**</td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>**steps**<span>string</span></td>
      <td>steps<span>string</span></td>
      <td>Moved Inside</td>
    </tr>

    <tr>
      <td>**cfg\_scale**<span>integer</span></td>
      <td>guidance\_scale<br /><span>number(float32)</span></td>
      <td><span>Changed</span><br /> `cfg_scale`**→** `request.guidance_scale`</td>
    </tr>

    <tr>
      <td>**seed**<span>integer</span></td>
      <td>seed<span>integer</span></td>
      <td>Moved Inside</td>
    </tr>

    <tr>
      <td>**height**<span>integer</span></td>
      <td>height<span>integer</span></td>
      <td><span>Moved Inside</span><br />Range Change: \[128, 2048].</td>
    </tr>

    <tr>
      <td>**width**<span>integer</span></td>
      <td>width<span>integer</span></td>
      <td><span>Moved Inside</span><br />Range Change: \[128, 2048].</td>
    </tr>

    <tr>
      <td>**model\_name**<span>string</span></td>
      <td>model\_name<span>string</span></td>
      <td><span>Moved Inside</span><br />This parameter specifies the name of the model checkpoint. Retrieve the corresponding sd\_name value by invoking the [Query Model](https://novita.ai/docs/api-reference/model-apis-get-model) API with filter.types=checkpoint as the query parameter.</td>
    </tr>

    <tr>
      <td>**restore\_faces**<span>bool</span></td>
      <td>restore\_faces<span>bool</span></td>
      <td>Moved Inside</td>
    </tr>

    <tr>
      <td>**restore\_faces\_model**</td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>**sd\_vae**<span>string</span></td>
      <td>sd\_vae<span>string</span></td>
      <td>Moved Inside</td>
    </tr>

    <tr>
      <td>**clip\_skip**<span>integer</span></td>
      <td>clip\_skip<span>integer</span></td>
      <td>Moved Inside</td>
    </tr>

    <tr>
      <td>**enable\_hr**<span>boolean</span></td>
      <td>hires\_fix<span>object</span></td>
      <td><span>Changed</span><br /> `enable_hr`**→** `request.hires_fix`</td>
    </tr>

    <tr>
      <td>**hr\_upscaler**<br /><span>Enum:<br /> `Latent`, `ESRGAN_4x`, `R-ESRGAN 4x+`, `R-ESRGAN 4x+ Anime6B`</span></td>
      <td>upscaler<br /><span>Enum: `RealESRGAN_x4plus_anime_6B`, `RealESRNet_x4plus,Latent`</span></td>
      <td><span>Changed</span><br /> `hr_upscaler`**→**`request.hires_fix.upscaler`</td>
    </tr>

    <tr>
      <td>**hr\_scale**<span>number</span></td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>**hr\_resize\_x**<span>integer</span></td>
      <td>target\_width<span>integer</span></td>
      <td><span>Changed</span><br /> `hr_resize_x`**→** `request.hires_fix.target_width`</td>
    </tr>

    <tr>
      <td>**hr\_resize\_y**<span>integer</span></td>
      <td>target\_height<span>integer</span></td>
      <td><span>Changed</span><br /> `hr_resize_y`**→** `request.hires_fix.target_height`</td>
    </tr>

    <tr>
      <td>**img\_expire\_ttl**<span>integer</span></td>

      <td />

      <td><span>Deprecated</span><br />Default 3600s</td>
    </tr>

    <tr>
      <td>**sd\_refiner**<span>object</span></td>
      <td>refiner<span>object</span></td>
      <td><span>Changed</span><br /> `sd_refiner`**→** `request.refiner`</td>
    </tr>

    <tr>
      <td>checkpoint<span>string</span></td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>switch\_at<br /><span>number(float32)</span></td>
      <td>switch\_at<br /><span>number(float32)</span></td>
      <td><span>Changed</span><br /> `sd_refiner.switch_at`**→** `request.refiner.switch_at`</td>
    </tr>

    <tr>
      <td>**controlnet\_units**<span>object\[]</span></td>

      <td />

      <td><span>Deprecated</span><br /><span>`img2img` Only</span></td>
    </tr>
  </tbody>
</table>

### Response Parameter Mapping

<table>
  <thead>
    <tr>
      <th>V2</th>
      <th>V3</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**code**</td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>**msg**</td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>**data**</td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>task\_id</td>
      <td>**task\_id**</td>
      <td><span>Changed</span><br /> `data.task_id`**→** `task_id`</td>
    </tr>

    <tr>
      <td>warn</td>

      <td />

      <td>Deprecated</td>
    </tr>
  </tbody>
</table>

### Example

<CardGroup>
  <Card title="Text to Image V2">
    * Request

    ```bash theme={"system"}
    curl --location "https://api.novita.ai/v2/txt2img" \
    --header "Authorization: Bearer {{API Key}}" \
    --header "Content-Type: application/json" \
    --data '{
      "extra": {
        "enable_nsfw_detection": false,
        "nsfw_detection_level": 0,
        "response_image_type": "jpeg"
      },
      "prompt": "(masterpiece, best quality, ultra-detailed:1.3), <lora:AnimeStyle_XL_v1_AutoRunMech_103883:0.8>, 1girl, mecha armor, futuristic city background, glowing neon lights, dynamic pose, cyberpunk style, intricate mechanical details, (floating holographic interface:1.2), sparkling blue eyes, wind-blown hair, (steam and energy particles:1.1), cinematic lighting",
      "negative_prompt":"(worst quality, low quality:1.4), (deformed, distorted:1.3), disfigured, blurry, bad anatomy, extra limbs, (mutated hands:1.2), (text, watermark:1.5), 
    overexposed, underexposed, (cartoonish:1.2), (simplistic background:1.3), 
    grainy, (traditional drawing:1.2), (realistic:1.4), (noisy:1.3)",
      "sampler_name":"DPM++ 2M Karras",
      "batch_size": 1,
      "n_iter": 1,
      "steps": 25,
      "cfg_scale": 7,
      "seed": 65531,
      "height": 512,
      "width": 512,
      "model_name": "sd_xl_base_1.0.safetensors",
      "restore_faces": false,
      "restore_faces_model": "",
      "sd_vae": "",
      "clip_skip": 1,
      "enable_hr": true,
      "hr_upscaler": "Latent",
      "hr_scale": 2,
      "hr_resize_x": 1024,
      "hr_resize_y": 1024,
      "img_expire_ttl": 3600
    }'
    ```

    * Response

    ```
    {
      "code": 0,
      "msg": "",
      "data": {
        "task_id": "12905b6a-d436-4010-b199-d800130c0aab"
      }
    }
    ```
  </Card>

  <Card title="Text to Image V3">
    * Reqeust

    ```bash theme={"system"}
    curl --location 'https://api.novita.ai/v3/async/txt2img' \
    --header 'Authorization: Bearer {{API Key}}' \
    --header 'Content-Type: application/json' \
    --data '{
        "extra": {
            "enable_nsfw_detection": false,
            "nsfw_detection_level": 0,
            "response_image_type": "jpeg"
        },
        "request": {
          "prompt": "(masterpiece, best quality, ultra-detailed:1.3), 1girl, mecha armor, futuristic city background, glowing neon lights, dynamic pose, cyberpunk style, intricate mechanical details,(floating holographic interface:1.2), sparkling blue eyes, wind-blown hair, (steam and energy particles:1.1), cinematic lighting",
          "negative_prompt": "(worst quality, low quality:1.4), (deformed, distorted:1.3), disfigured,blurry, bad anatomy, extra limbs, (mutated hands:1.2), (text, watermark:1.5),overexposed, underexposed,(cartoonish:1.2), (simplistic background:1.3), grainy, (traditional drawing:1.2),(realistic:1.4), (noisy:1.3)",
            "model_name": "sd_xl_base_1.0.safetensors",
            "width": 512,
            "height": 512,
            "image_num": 1,
            "steps": 25,
            "seed": 65531,
            "restore_faces": false,
            "clip_skip": 1,
            "sampler_name":"DPM++ 2M Karras",
            "guidance_scale": 7,
            "hires_fix": {
                "target_width": 1024,
                "target_height": 1024,
                "strength": 0.8,
                "upscaler": "Latent"
            },
            "loras": [
              {
                "model_name": "AnimeStyle_XL_v1_AutoRunMech_103883",
                "strength": 0.8
              }
            ]
        }
    }'
    ```

    * Repspone

    ```bash theme={"system"}
    {
      "task_id":"0696ce57-22df-4a89-9efc-80c386a82dbd"
    }
    ```
  </Card>
</CardGroup>

## Image to Image

### Request Body Parameter Mapping

<table>
  <thead>
    <tr>
      <th>V2</th>
      <th>V3</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**extra**<span>object</span></td>
      <td>**extra**<span>object</span></td>

      <td />
    </tr>

    <tr>
      <td>enable\_nsfw\_detection<br /><span>boolean</span></td>
      <td>enable\_nsfw\_detection<br /><span>boolean</span></td>

      <td />
    </tr>

    <tr>
      <td>nsfw\_detection\_level<br /><span>Enum: `0, 1, 2`</span></td>
      <td>nsfw\_detection\_level<br /><span>Enum: `0, 1, 2`</span></td>

      <td />
    </tr>

    <tr>
      <td>enable\_progress\_info</td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>response\_image\_type<br /><span>Enum: `png`, `jpeg`</span></td>
      <td>response\_image\_type<br /><span>Enum: `png, webp, jpeg`</span></td>
      <td>V3 adds support for `webp`image format</td>
    </tr>

    <tr>
      <td />

      <td>**request**<span>object</span></td>
      <td><span>New field</span><br />All image generation parameters must be passed via the `request`in V3</td>
    </tr>

    <tr>
      <td>**prompt**<span>string</span><br />\<lora:\$sd\_name:\$weight></td>
      <td>prompt<span>string</span></td>
      <td>Moved Inside</td>
    </tr>

    <tr>
      <td />

      <td>loras<span>object\[]</span></td>
      <td><span>Moved Inside</span><br />**Migrate LoRA usage: From **`prompt`** to **`request.loras`** parameter**</td>
    </tr>

    <tr>
      <td />

      <td>model\_name<span>string</span></td>
      <td><span>New Field</span><br />Name of lora, retrieve the corresponding sd\_name\_in\_api value by invoking the [Get Model API](https://novita.ai/docs/api-reference/model-apis-get-model) endpoint with filter.types=lora as the query parameter.</td>
    </tr>

    <tr>
      <td />

      <td>strength<br /><span>number(float32)</span></td>
      <td><span>New Field</span><br />The strength value of lora. The larger the value, the more biased the effect is towards lora, Range \[0, 1]</td>
    </tr>

    <tr>
      <td>**negative\_prompt**<span>string</span></td>
      <td>negative\_prompt<br /><span>string</span></td>
      <td>Moved Inside</td>
    </tr>

    <tr>
      <td>**sampler\_name**<span>string</span></td>
      <td>sampler\_name<span>string</span></td>
      <td>Moved Inside</td>
    </tr>

    <tr>
      <td>**batch\_size**<span>integer</span></td>
      <td>image\_num<span>integer</span></td>
      <td><span>Changed</span><br /> `batch_size`**→** `request.image_num`</td>
    </tr>

    <tr>
      <td>**n\_iter**<span>integer</span></td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>**steps**<span>string</span></td>
      <td>steps<span>string</span></td>
      <td>Moved Inside</td>
    </tr>

    <tr>
      <td>**cfg\_scale**<span>integer</span></td>
      <td>guidance\_scale<br /><span>number(float32)</span></td>
      <td><span>Changed</span><br /> `cfg_scale`**→** `request.guidance_scale`</td>
    </tr>

    <tr>
      <td>**seed**<span>integer</span></td>
      <td>seed<span>integer</span></td>
      <td>Moved Inside</td>
    </tr>

    <tr>
      <td>**height**<span>integer</span></td>
      <td>height<span>integer</span></td>
      <td><span>Moved Inside</span><br />Range Change: \[128, 2048].</td>
    </tr>

    <tr>
      <td>**width**<span>integer</span></td>
      <td>width<span>integer</span></td>
      <td><span>Moved Inside</span><br />Range Change: \[128, 2048].</td>
    </tr>

    <tr>
      <td>**model\_name**<span>string</span></td>
      <td>model\_name<span>string</span></td>
      <td><span>Moved Inside</span><br />This parameter specifies the name of the model checkpoint. Retrieve the corresponding sd\_name value by invoking the [Query Model](https://novita.ai/docs/api-reference/model-apis-get-model) API with filter.types=checkpoint as the query parameter.</td>
    </tr>

    <tr>
      <td>**init\_images**<span>string\[]</span></td>
      <td>image\_base64<span>string</span></td>
      <td><span>Changed</span><br /> `init_images`**→** `request.image_base64`</td>
    </tr>

    <tr>
      <td>**denoising\_strength**<br /><span>number(float)</span></td>
      <td>strength<br /><span>number(float)</span></td>
      <td><span>Changed</span><br /> `denoising_strength`**→** `request.strength`</td>
    </tr>

    <tr>
      <td>**restore\_faces**<span>bool</span></td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>**sd\_vae**<span>string</span></td>
      <td>sd\_vae<span>string</span></td>
      <td>Moved Inside</td>
    </tr>

    <tr>
      <td>**clip\_skip**<span>integer</span></td>
      <td>clip\_skip<span>integer</span></td>
      <td>Moved Inside</td>
    </tr>

    <tr>
      <td>**mask**<span>string</span></td>

      <td />

      <td><span>Deprecated</span><br />Recommendation: Use V3 Inpainting API</td>
    </tr>

    <tr>
      <td>**mask\_blur**<span>integer</span></td>

      <td />

      <td><span>Deprecated</span><br />Recommendation: Use V3 Inpainting API</td>
    </tr>

    <tr>
      <td>**resize\_mode**<span>integer</span></td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>**image\_cfg\_scale**<span>integer</span></td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>**inpainting\_fill**<span>integer</span></td>

      <td />

      <td><span>Deprecated</span><br />Recommendation: Use V3 Inpainting API</td>
    </tr>

    <tr>
      <td>**inpaint\_full\_res**<span>integer</span></td>

      <td />

      <td><span>Deprecated</span><br />Recommendation: Use V3 Inpainting API</td>
    </tr>

    <tr>
      <td>**inpaint\_full\_res\_padding**<br /><span>integer</span></td>

      <td />

      <td><span>Deprecated</span><br />Recommendation: Use V3 Inpainting API</td>
    </tr>

    <tr>
      <td>**inpainting\_mask\_invert**<br /><span>integer</span></td>

      <td />

      <td><span>Deprecated</span><br />Recommendation: Use V3 Inpainting API</td>
    </tr>

    <tr>
      <td>**initial\_noise\_multiplier**<br /><span>number(float32)</span></td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>**img\_expire\_ttl**<span>integer</span></td>

      <td />

      <td><span>Deprecated</span><br />Default 3600s</td>
    </tr>

    <tr>
      <td>**sd\_refiner**<span>object</span></td>
      <td>refiner<span>object</span></td>
      <td><span>Changed</span><br /> `sd_refiner`**→** `request.refiner`</td>
    </tr>

    <tr>
      <td>checkpoint</td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>switch\_at<br /><span>number(float32)</span></td>
      <td>switch\_at<br /><span>number(float32)</span></td>
      <td>Moved Inside</td>
    </tr>

    <tr>
      <td />

      <td>controlnet<span>object</span></td>
      <td><span>New Field</span></td>
    </tr>

    <tr>
      <td>**controlnet\_units**<span>object\[]</span></td>
      <td>units<span>object\[]</span></td>
      <td><span>Changed</span><br /> `controlnet_units`**→** `request.controlnet.units`</td>
    </tr>

    <tr>
      <td>model<span>string</span></td>
      <td>model\_name<br /><span>string</span></td>
      <td><span>Changed</span><br /> `controlnet_units.model`**→** <br />`request.controlnet.units.model_name`</td>
    </tr>

    <tr>
      <td>weight<span>number</span></td>
      <td>strength<br /><span>number(float32)</span></td>
      <td><span>Changed</span><br /> `controlnet_units.weight`**→** <br />`request.controlnet.units.strength`</td>
    </tr>

    <tr>
      <td>input\_image<span>string</span></td>
      <td>image\_base64<br /><span>string</span></td>
      <td><span>Changed</span><br /> `controlnet_units.input_image`**→** <br />`request.controlnet.units.image_base64`</td>
    </tr>

    <tr>
      <td>module<span>string,Enum</span></td>
      <td>preprocessor<br /><span>string,Enum</span></td>
      <td><span>Changed</span><br />`controlnet_units.module`**→** <br />`request.controlnet.units.preprocessor`</td>
    </tr>

    <tr>
      <td>control\_mode</td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>mask</td>

      <td />

      <td><span>Deprecated</span><br />Recommendation: Use V3 Inpainting API</td>
    </tr>

    <tr>
      <td>resize\_mode</td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>processor\_res</td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>threshold\_a</td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>threshold\_b</td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>guidance\_start<br /><span>number(float32)</span></td>
      <td>guidance\_start<br /><span>number(float32)</span></td>
      <td>Moved Inside</td>
    </tr>

    <tr>
      <td>guidance\_end<br /><span>number(float32)</span></td>
      <td>guidance\_end<br /><span>number(float32)</span></td>
      <td>Moved Inside</td>
    </tr>

    <tr>
      <td>pixel\_perfect</td>

      <td />

      <td>Deprecated</td>
    </tr>
  </tbody>
</table>

### Response Parameter Mapping

<table>
  <thead>
    <tr>
      <th>V2</th>
      <th>V3</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>code</td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>msg</td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>data</td>

      <td />

      <td>Deprecated</td>
    </tr>

    <tr>
      <td>task\_id</td>
      <td>**task\_id**</td>
      <td><span>Changed</span><br /> `data.task_id`**→** `task_id`</td>
    </tr>

    <tr>
      <td>warn</td>

      <td />

      <td>Deprecated</td>
    </tr>
  </tbody>
</table>

### Example

<CardGroup>
  <Card title="Image to Image V2">
    * Request

    ```
    curl --request POST \
      --url https://api.novita.ai/v2/img2img \
      --header 'Authorization: <authorization>' \
      --header 'Content-Type: application/json' \
      --data '{
      "extra": {
        "enable_nsfw_detection": false,
        "nsfw_detection_level": 0,
        "response_image_type": "png"
      },
      "prompt": "realistic, photograph, (masterpiece), 8k quality, (detailed eyes:1.2), (highest quality:1.1), highly detailed, majestic, top quality, best quality, newest, ai-generated, (intricate details:1.1), extremely beautiful, elegant, majestic, immersive background+, (detailed face, perfect face), In the heart of a vibrant garden, a girl with red hair and brown eyes sits in contemplation of the nature around her.",
      "negative_prompt": "(worst quality:1.5), (low quality:1.5), (normal quality:1.5), anime, cartoon, painting, drawing, illustration, manga, sketch, nudity, young, child, hairband, headband, horns, lowres, bad anatomy, bad hands, multiple eyebrow, (cropped), extra limb, missing limbs, deformed hands, long neck, long body, long torso, (bad hands), signature, username, artist name, conjoined fingers, deformed fingers, ugly eyes, imperfect eyes, skewed eyes, unnatural face, unnatural body, error, grain, jpeg artifacts",
      "sampler_name":"DPM++ 2M Karras",
      "batch_size": 1,
      "n_iter": 1,
      "steps": 25,
      "cfg_scale": 7.5,
      "seed": 765824,
      "height": 768,
      "width": 512,
      "model_name": "cyberrealistic_v31_62396.safetensors",
      "init_images": [
        "<IMAGE_BASE64>"
      ],
      "denoising_strength": 0.8,
      "restore_faces": false,
      "clip_skip": 1,
      "img_expire_ttl": 3600,
      "controlnet_units": {
        "model": "control_v11p_sd15_lineart",
        "weight": 1,
        "input_image": "<IMAGE_BASE64>",
        "module": "lineart",
        "guidance_start": 0,
        "guidance_end": 1
      }
    }'
    ```

    * Response

    ```
    {
      "code": 0,
      "msg": "",
      "data": {
        "task_id": "a1b0d99b-2ef0-4b20-8eeb-c641ae84ed45"
      }
    }
    ```
  </Card>

  <Card title="Image to Image V3">
    * Request

    ```
    curl --request POST \
      --url https://api.novita.ai/v3/async/img2img \
      --header 'Authorization: <authorization>' \
      --header 'Content-Type: <content-type>' \
      --data '{
      "extra": {
        "enable_nsfw_detection": false,
        "nsfw_detection_level": 0,
        "response_image_type": "png"
      },
      "request": {
        "prompt": "realistic, photograph, (masterpiece), 8k quality, (detailed eyes:1.2), (highest quality:1.1), highly detailed, majestic, top quality, best quality, newest, ai-generated, (intricate details:1.1), extremely beautiful, elegant, majestic, immersive background+, (detailed face, perfect face), In the heart of a vibrant garden, a girl with red hair and brown eyes sits in contemplation of the nature around her.",
        "negative_prompt": "(worst quality:1.5), (low quality:1.5), (normal quality:1.5), anime, cartoon, painting, drawing, illustration, manga, sketch, nudity, young, child, hairband, headband, horns, lowres, bad anatomy, bad hands, multiple eyebrow, (cropped), extra limb, missing limbs, deformed hands, long neck, long body, long torso, (bad hands), signature, username, artist name, conjoined fingers, deformed fingers, ugly eyes, imperfect eyes, skewed eyes, unnatural face, unnatural body, error, grain, jpeg artifacts",
        "sampler_name": "DPM++ 2M Karras",
        "image_num": 1,
        "steps": 25,
        "guidance_scale": 7.5,
        "seed": 765824,
        "height": 768,
        "width": 512,
        "model_name": "cyberrealistic_v31_62396.safetensors",
            "image_base64": "<IMAGE_BASE64>",
        "strength": 0.8,
        "clip_skip": 1,
        "controlnet": {
          "units": [
            {
              "model_name": "control_v11p_sd15_lineart",
              "strength": 1,
              "image_base64": "<IMAGE_BASE64>",
              "preprocessor": "lineart",
              "guidance_start": 0,
              "guidance_end": 1
            }
          ]
        }
      }
    }'
    ```

    * Response

    ```bash theme={"system"}
    {
      "task_id": "9490dde7-cd28-493e-9db0-8a38a65bf5e6"
    }
    ```
  </Card>
</CardGroup>


# What's the Variational Autoencoder VAE?
Source: https://novita.ai/docs/guides/model-apis-vae



### Introduction to Autoencoders

Autoencoders are a class of neural networks primarily used for unsupervised learning and dimensionality reduction. The fundamental idea behind autoencoders is to encode input data into a lower-dimensional representation and then decode it back to the original data, aiming to minimize the reconstruction error. The basic architecture of an autoencoder consists of two main components: the encoder and the decoder.

* **Encoder**: The encoder is responsible for transforming the input data into a compressed or latent representation. It typically consists of one or more layers of neurons that progressively reduce the dimensions of the input.

* **Decoder**: The decoder, on the other hand, takes the compressed representation produced by the encoder and attempts to reconstruct the original input data. Like the encoder, it often consists of one or more layers, but in reverse order, gradually increasing the dimensions.

<Frame>
  <img />
</Frame>

### Variational Autoencoders (VAEs) Overview

Variational Autoencoders (VAEs) address some of the limitations of traditional autoencoders by introducing a probabilistic approach to encoding and decoding. The motivation behind VAEs lies in their ability to generate new data samples by sampling from a learned distribution in the latent space, rather than from a fixed latent vector as was the case with vanilla autoencoders. This makes them suitable for generative tasks.

* **Probabilistic Nature**: Unlike deterministic autoencoders, VAEs model the latent space as a probability distribution. This produces a probability distribution function over the input encodings instead of just a single fixed vector, allowing for a more nuanced representation of uncertainty in the data. The decoder then samples from this probability distribution.

* **Role of Latent Space**: The latent space in VAEs serves as a continuous, structured representation of the input data. Since it is continuous by design, this allows for easy interpolation. Each point in the latent space corresponds to a potential output, enabling smooth transitions between different data points and ensuring that points closer in the latent space lead to similar generations.

The concept can be elucidated through a straightforward example, as presented below. Encoders within a neural network are tasked with acquiring a representation of input images in the form of a vector. This vector encapsulates various features such as a subject’s smile, hair color, gender, age, etc., denoted as a vector similar to \[0.4, 0.03, 0.032, …]. In this illustration, the focus is narrowed to a singular latent representation, specifically the attribute of a "smile".

Autoencoders vs VAEs - Sciforce MediumIn the context of Vanilla Autoencoders (AE), the smile feature is encapsulated as a fixed, deterministic value. In contrast, Variational Autoencoders (VAEs) are deliberately crafted to encapsulate this feature as a probabilistic distribution. This design choice facilitates the introduction of variability in generated images by enabling the sampling of values from the specified probability distribution.

<Frame>
  <img />
</Frame>

In summary, VAEs go beyond mere data reconstruction; they generate new samples and provide a probabilistic framework for understanding latent representations. The inclusion of probabilistic elements in the model’s architecture sets VAEs apart from traditional autoencoders. Compared to traditional autoencoders, VAEs offer a richer understanding of the data distribution, making them particularly powerful for generative tasks.


# LLM API Metrics
Source: https://novita.ai/docs/guides/observability-llm-api-metrics



Novita AI provides comprehensive monitoring metrics for your LLM API usage. These metrics give you insights into the availability and performance of your LLM API requests.

You can access these metrics through the [LLM Metrics Console](https://novita.ai/model-api/console/llm-metrics).

## Available Metrics

<Tip>
  All the following metrics are **dimensioned by model**, and sampled on a **per-minute basis**, but depending on the interval you select, the sampling points may not be displayed per minute. In such cases, the sampling points within that time interval will be averaged before being displayed.
</Tip>

**Request Per Minute (RPM)**

Shows the number of API requests made per minute, helping you understand usage patterns and API concurrency levels.

**Request Success Rate**

Shows the percentage of successful API responses (non-5xx status codes) made per minute, indicating API availability.

**Average Token Count Per Request**

Shows the average number of input and output tokens per request made per minute, useful for understanding token consumption patterns.

**End-to-end (E2E) Latency**

Shows the overall time it takes for the model to generate the full response for requests made per minute. Includes 99th percentile, 95th percentile, and average latency metrics.

**Time to First Token (TTFT)**

<Tip>
  This metric is only tracked for streaming requests with the `stream=true` parameter is enabled.
</Tip>

Shows the time required to process the prompt and generate the first output token for requests made per minute. Includes 99th percentile, 95th percentile, and average latency metrics.

**Time Per Output Token (TPOT)**

<Tip>
  This metric is only tracked for streaming requests when the `stream=true` parameter is enabled.
</Tip>

Shows the average time between consecutive output tokens for requests made per minute. Includes 99th percentile, 95th percentile, and average latency metrics.


# OpenAI Agents SDK
Source: https://novita.ai/docs/guides/openai-agents-sdk

Seamlessly integrate Novita AI with OpenAI Agents SDK for building multi-agent workflows.

The [OpenAI Agents SDK](https://github.com/openai/openai-agents-python) is a lightweight yet powerful framework for building multi-agent workflows. And the SDK is compatible with any model providers that support the OpenAI Chat Completions API format.

This guide will walk you through how to use Novita LLM API with OpenAI Agents SDK.

## Get Started

1. Set up your Python environment and install the Agents SDK.

```bash theme={"system"}
python -m venv env
source env/bin/activate
pip install openai-agents==0.0.7
```

2. Set up your Novita API key.

Go to [Key Management](https://novita.ai/settings/key-management?utm_source=getstarted) and create a new API key.

## Hello world example

<Warning>
  If running this, ensure you set the NOVITA\_API\_KEY and MODEL\_NAME environment variables.
</Warning>

```python theme={"system"}
import os
from openai import AsyncOpenAI
from agents import (
    Agent,
    Runner,
    set_default_openai_api,
    set_default_openai_client,
    set_tracing_disabled,
)

BASE_URL = "https://api.novita.ai/openai"
API_KEY = os.getenv("NOVITA_API_KEY")
MODEL_NAME = os.getenv("MODEL_NAME")

# Because Novita not support the responses API so we use the chat completions API instead.
set_default_openai_api("chat_completions")
set_default_openai_client(AsyncOpenAI(base_url=BASE_URL, api_key=API_KEY))
# Disable tracing for this example
# Refer to https://openai.github.io/openai-agents-python/tracing/#external-tracing-processors-list to use the custom spans.
set_tracing_disabled(disabled=True)

agent = Agent(name="Assistant",
              instructions="You are a helpful assistant", model=MODEL_NAME)

result = Runner.run_sync(
    agent, "Write a haiku about recursion in programming.")
print(result.final_output)

# Code within the code,
# Functions calling themselves,
# Infinite loop's dance.
```

## Handoffs example

<Warning>
  If running this, ensure you set the NOVITA\_API\_KEY and MODEL\_NAME environment variables.
</Warning>

```python theme={"system"}
import os
import asyncio
from openai import AsyncOpenAI
from agents import (
    Agent,
    Runner,
    set_default_openai_api,
    set_default_openai_client,
    set_tracing_disabled,
)

BASE_URL = "https://api.novita.ai/openai"
API_KEY = os.getenv("NOVITA_API_KEY")
MODEL_NAME = os.getenv("MODEL_NAME")

# Because Novita not support the responses API so we use the chat completions API instead.
set_default_openai_api("chat_completions")
set_default_openai_client(AsyncOpenAI(base_url=BASE_URL, api_key=API_KEY))
# Disable tracing for this example
# Refer to https://openai.github.io/openai-agents-python/tracing/#external-tracing-processors-list to use the custom spans.
set_tracing_disabled(disabled=True)

spanish_agent = Agent(
    name="Spanish agent",
    instructions="You only speak Spanish.",
    model=MODEL_NAME,
)

english_agent = Agent(
    name="English agent",
    instructions="You only speak English",
    model=MODEL_NAME,
)

triage_agent = Agent(
    name="Triage agent",
    instructions="Handoff to the appropriate agent based on the language of the request.",
    handoffs=[spanish_agent, english_agent],
    model=MODEL_NAME,
)


async def main():
    result = await Runner.run(triage_agent, input="Hola, ¿cómo estás?")
    print(result.final_output)
    # ¡Hola! Estoy bien, gracias por preguntar. ¿Y tú, cómo estás?


if __name__ == "__main__":
    asyncio.run(main())
```

## Functions example

<Warning>
  If running this, ensure you set the NOVITA\_API\_KEY and MODEL\_NAME environment variables.
</Warning>

```python theme={"system"}
import os
import asyncio
from openai import AsyncOpenAI
from agents import (
    Agent,
    Runner,
    set_default_openai_api,
    set_default_openai_client,
    set_tracing_disabled,
    function_tool,
)

BASE_URL = "https://api.novita.ai/openai"
API_KEY = os.getenv("NOVITA_API_KEY")
MODEL_NAME = os.getenv("MODEL_NAME")

# Because Novita not support the responses API so we use the chat completions API instead.
set_default_openai_api("chat_completions")
set_default_openai_client(AsyncOpenAI(base_url=BASE_URL, api_key=API_KEY))
# Disable tracing for this example
# Refer to https://openai.github.io/openai-agents-python/tracing/#external-tracing-processors-list to use the custom spans.
set_tracing_disabled(disabled=True)

@function_tool
def get_weather(city: str) -> str:
    return f"The weather in {city} is sunny."

agent = Agent(
    name="Hello world",
    instructions="You are a helpful agent.",
    tools=[get_weather],
    model=MODEL_NAME,
)

async def main():
    result = await Runner.run(agent, input="What's the weather in Tokyo?")
    print(result.final_output)
    # The weather in Tokyo is sunny.

if __name__ == "__main__":
    asyncio.run(main())
```


# OWL
Source: https://novita.ai/docs/guides/owl

Optimize Your Workflow with Novita AI and OWL.

OWL is an open-source framework for multi-agent collaboration that specializes in real-world task automation, built on the CAMEL-AI Foundation. By integrating with various AI models, OWL combines dynamic agent interactions with powerful toolkits for online search, browser automation, document processing, and code execution. This framework enables more natural, efficient, and robust task automation across diverse domains, delivering actionable insights tailored to your specific needs.

This guide will enable you to seamlessly integrate Novita AI with OWL and elevate your AI-driven processes for faster, smarter outcomes.

## **How to Integrate Novita AI with RAGFlow**

### **Step 1: Pre-Configuration Setup**

1. **Access the API Endpoint**

* Use the official API endpoint: [https://api.novita.ai/openai](https://api.novita.ai/openai).

2. **Create an API Key**

* Visit the [key management page](https://novita.ai/settings/key-management) and select `Add New Key` to generate your API key.

  <img alt="Visitthekeymanagementpageandselect Add New Keytogenerateyour AP Ikey Pn" />
* Keep your API key safe.
  * **Note:** API keys are securely encrypted on the server. If you lose it, you’ll need to delete the old key and create a new one.

    <img alt="Keepyour AP Ikeysafe 1 Pn" />

    <img alt="Keepyour AP Ikeysafe 2 Pn" />

3. **Identify the Model ID**

* meta-llama/llama-4-scout-17b-16e-instruct

### **Step 2: Install OWL**

* To begin, download and install OWL by following the step-by-step instructions on the Github: [https://github.com/camel-ai/owl](https://github.com/camel-ai/owl).

### **Step 3: Configure OWL**

* Prepare OWL for use by setting up environment variables and adding your API key. Run the following commands in your terminal:

```bash theme={"system"}
cd owl
cp .env_template .env
```

* Start OWL and specify your task by executing:

```bash theme={"system"}
python examples/run_novita_ai.py
```

<img alt="Step3 Configure OWL Pn" />

### **Step 4: View Results**

1. **Terminal Output**

* Once launched, OWL will display the execution results directly in the terminal window.

  <img alt="Terminal Output 1 Pn" />

  <img alt="Terminal Output 2 Pn" />

2. **Web Interface**

* For a more intuitive experience, use OWL’s web-based interface. Launch it by running:

```bash theme={"system"}
cd owl
python webapp.py
```

<img alt="Web Interface 1 Pn" />

<img alt="Web Interface 2 Pn" />

* Steps to use the Web UI:
  * Select `run_novita_ai` from the left-hand menu and go to the `Environment Variable Management` tab on the right and input your `NOVITA_API_KEY`.

    <img alt="Stepstousethe Web UI 1 Pn" />
  * Click `Run` to execute your task.

    <img alt="Stepstousethe Web UI 2 Pn" />
  * To perform a new task, update the input field and click `Run` again.

    <img alt="Stepstousethe Web UI 3 Pn" />

    <img alt="Stepstousethe Web UI 4 Pn" />
  * Results will be displayed in the terminal, or a new file will be generated in the root directory, depending on the task.

    <img alt="Stepstousethe Web UI 5 Pn" />
  * Alternatively, you can directly input your desired task into the content box and click the `Run` button to execute it.

    <img alt="Stepstousethe Web UI 6 Pn" />


# Page Assist
Source: https://novita.ai/docs/guides/pageassist

Elevate Your Browsing Experience with Novita AI and Page Assist Integration.

Page Assist offers a seamless browser extension that integrates AI capabilities directly into your web interactions. By combining Novita AI with Page Assist, you can unlock a powerful AI-enhanced browsing experience that enhances productivity and insight generation.

This guide will walk you through the process of deploying and running Page Assist with Novita AI to supercharge your web interactions.

## **How to Integrate Novita AI with Page Assist**

You can find the GitHub repository of Page Assist here: [n4ze3m/page-assist](https://github.com/n4ze3m/page-assist).

### Step 1: Prepare Your Environment

* Install Bun or npm: Follow the installation guide for [<u>Bun</u>](https://bun.sh/) or use npm as an alternative.

### Step 2: Clone Page Assist Repository

1. Open your terminal and run:

```bash theme={"system"}
git clone https://github.com/n4ze3m/page-assist.git
cd page-assist
```

2. Install dependencies using Bun or npm:

```bash theme={"system"}
bun install
```

### Step 3: Build Page Assist Extension

* Build the extension for Chrome (default):

```bash theme={"system"}
bun run build
```

* For Firefox, use:

```bash theme={"system"}
bun build:firefox
```

### Step 4: Load the Extension

1. For Chrome:
   * Navigate to `chrome://extensions`.
   * Enable Developer Mode.
   * Click `Load unpacked` and select the `build/chrome-xxx` (e.g. `build/chrome-mv3`) directory.
2. For Firefox:
   * Go to `about:addons`.
   * Click `Extensions` tab.
   * Click `Manage Your Extensions`.
   * Select `Load Temporary Add-on` and choose the `manifest.json` file from in the `build/firefox-xxx` (e.g. `build/firefox-mv3`) directory.

### Step 5: Configure Novita AI as OpenAI API Compatible Endpoint

1. Obtain Your Novita AI API Key:
   * [Log in](https://novita.ai/user/login) to your Novita AI account.
   * Navigate to [the Key Management page](https://novita.ai/settings/key-management).
   * Generate a new API Key and copy it.
2. Set Up Novita AI Endpoint:

   * In your Page Assist Settings, enter `Open Compatible API` to add provider.

   <Frame>
     <img alt="Inyour Page Assist Settings,enter Open Compatible AP Itoaddprovider Jpe" />
   </Frame>

   * Choose Novita from the `Custom list`, and use your API key for authentication.

   <Frame>
     <img alt="Choose Novitafromthe Customlist,anduseyour AP Ikeyforauthentication Jpe" />
   </Frame>

### Step 6: Choose your Model and Test Page Assist with Novita AI

* Choose your model from the model list provided by Novita AI.

<Frame>
  <img alt="Chooseyourmodelfromthemodellistprovidedby Novita AI Jpe" />
</Frame>

* Interact with your Novita AI model by asking questions or analyzing web content.

<Frame>
  <img alt="Interactwithyour Novita A Imodelbyaskingquestionsoranalyzingwebcontent Jpe" />
</Frame>


# Payment Methods
Source: https://novita.ai/docs/guides/payment-methods



Novita AI uses **Stripe** for all payment processing.

<Tip>All your payment information is securely stored by Stripe, and we <u>do not store</u> any payment information.</Tip>

You can manually top up a specified amount of credit, which must be greater than \$10. Additionally, you can enable the [Automatic Top-Up](/guides/auto-top-up), which will automatically add credit if your balance falls below a specified threshold.

<Frame>
  <img />
</Frame>


# Portkey
Source: https://novita.ai/docs/guides/portkey

Streamline AI development by using Portkey AI Gateway with Novita AI for fast, secure, and reliable performance.

Portkey AI Gateway transforms how developers work with AI models like Novita AI, providing a unified interface for seamless access to multiple language models with fast, secure, and reliable routing. This integration simplifies AI development and improves application performance.

This guide will walk you through setting up Portkey AI Gateway and then integrating Novita AI API with Portkey.

## How to Set Up Portkey AI Gateway

Setting up Portkey AI Gateway is simple and efficient, requiring just three key steps: configuring the gateway, sending your first request, and optimizing routing and guardrails for seamless performance.

### Step 1: Setup your AI Gateway

To run the gateway locally, ensure Node.js and npm are installed on your system. Once ready, execute the following command:

```jason theme={"system"}
npx @portkey-ai/gateway
```

After the gateway starts, two key URLs will be displayed:

* The Gateway: `http://localhost:8787/v1`
* The Gateway Console: `http://localhost:8787/public/`

### Step 2: Make your first request

Begin by installing the Portkey AI Python library:

```python theme={"system"}
pip install -qU portkey-ai
```

Next, execute the following Python code to send your first request:

```python theme={"system"}
from portkey_ai import Portkey

# OpenAI compatible client
client = Portkey(
    provider="openai", # or 'anthropic', 'bedrock', 'groq', etc
    Authorization="sk-***" # the provider API key
)

# Make a request through your AI Gateway
client.chat.completions.create(
    messages=[{"role": "user", "content": "What's the weather like?"}],
    model="gpt-4o-mini"
)
```

Effortlessly monitor all your local logs in one centralized location using the Gateway Console at: `http://localhost:8787/public/`.

### Step 3: Routing & Guardrails

Portkey AI Gateway enables you to configure routing rules, add reliability features, and enforce guardrails. Below is an example configuration:

```python theme={"system"}
config = {
  "retry": {"attempts": 5},

  "output_guardrails": [{
    "default.contains": {"operator": "none", "words": ["Apple"]},
    "deny": True
  }]
}

# Attach the config to the client
client = client.with_options(config=config)

client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Reply randomly with Apple or Bat"}]
)

# In this example, the guardrail denies all replies containing "Apple", so the response would always be "Bat". The retry configuration would attempt the request up to 5 times before giving up.
```

<Frame>
  <img alt="" />
</Frame>

## How to Integrate Novita AI API with Portkey

To access the Novita AI API via the Portkey AI Gateway, follow these steps:

### Step 1: Install the Portkey SDK

Integrate the Portkey SDK into your application to seamlessly interact with Novita AI’s API through Portkey’s gateway.

**Node.JS**

```jason theme={"system"}
npm install --save portkey-ai
```

**Python**

```python theme={"system"}
pip install portkey-ai
```

### Step 2: Initialize Portkey with the Virtual Key

To integrate Novita AI with Portkey, retrieve your LLM API key from[ Novita AI ](https://novita.ai/settings/key-management)and add it to Portkey to generate the virtual key.

**Node.JS SDK**

```jason theme={"system"}
import Portkey from 'portkey-ai'

const portkey = new Portkey({
  apiKey: "PORTKEY_API_KEY",  // Replace with your Portkey API key
  virtualKey: "VIRTUAL_KEY"   // Replace with your virtual key for Novita AI
})
```

**Python SDK**

```python theme={"system"}
from portkey_ai import Portkey

portkey = Portkey(
    api_key="PORTKEY_API_KEY",  # Replace with your Portkey API key
    virtual_key="VIRTUAL_KEY"   # Replace with your virtual key for Novita AI
)
```

### Step 3: Invoke Chat Completions with Novita AI

Utilize the Portkey instance to send requests to Novita AI. If necessary, you can override the virtual key directly within the API call.

**Node.JS SDK**

```jason theme={"system"}
const chatCompletion = await portkey.chat.completions.create({
  messages: [{ role: 'user', content: 'Say this is a test' }],
  model: 'Nous-Hermes-2-Mixtral-8x7B-DPO'
});

console.log(chatCompletion.choices);
```

**Python SDK**

```python theme={"system"}
completion = portkey.chat.completions.create(
    messages= [{ "role": 'user', "content": 'Say this is a test' }],
    model= 'reka-core'
)

print(completion)
```


# null
Source: https://novita.ai/docs/guides/quickstart



Novita AI is the go-to inference platform for AI developers seeking a low-cost, reliable, and simple solution for shipping AI models. This is a quickstart guide to help you set up your account and get started.

<Tip>
  If you have questions, please check our [FAQs](/guides/faq) first or [reach out to our support team on Discord](https://discord.gg/YyPRAzwp7P).
</Tip>

## 1. Log into [novita.ai](https://novita.ai/user/login?utm_source=getstarted)

You can log in using Google or GitHub authentication, and a new account will be automatically created on your first login. You can also [sign up using your email address](https://novita.ai/user/register?utm_source=getstarted).

## 2. Manage API Key

Novita AI authenticates API access using Bearer authentication with an API Key in the request header, e.g., "Authorization: Bearer \{API Key}".

If you need to access APIs, you can go to [Key Management](https://novita.ai/settings/key-management?utm_source=getstarted) setting page to create or manage your API keys.

## 3. Maintain sufficient credit balance in your account

We offer new users a voucher with some credit to try our products. To add more credit, please visit [Billing and Payments](https://novita.ai/billing?utm_source=getstarted) and follow the guide on [Payment Methods](/guides/payment-methods).

Also, to avoid any interruption to your service, please ensure your account has sufficient credit balance, and [Setup Automatic Top-up](/guides/auto-top-up) is a recommended practice.


# Advanced Features
Source: https://novita.ai/docs/guides/sandbox-agent-runtime-advanced



This document covers advanced features and best practices for Novita Agent Runtime.

***

## Table of Contents

* [Configuration File Reference](#configuration-file-reference)
* [Environment Variables Management](#environment-variables-management)
* [Streaming Responses](#streaming-responses)
* [Version Management](#version-management)
* [Health Checks](#health-checks)
* [Multi-turn Conversations](#multi-turn-conversations)
* [Example Projects](#example-projects)

***

## Configuration File Reference

### .novita-agent.yaml Structure

The `.novita-agent.yaml` configuration file uses Kubernetes-style YAML format:

```yaml theme={"system"}
apiVersion: v1
kind: Agent
metadata:
  name: my-agent              # Agent name (must consist of lowercase letters, numbers, and hyphens only)
  version: 1.0.0              # Agent version (semantic versioning)
  author: dev@example.com     # Author email (required)
  description: My AI Agent    # Agent description (optional)
  created: '2025-10-23T10:30:00Z'  # Creation time (auto-generated)

spec:
  entrypoint: app.py          # Python entry file (must be .py file)
  
  # Environment variables configuration (optional)
  envVars:
    MODEL_NAME: deepseek/deepseek-v3-0324
    TEMPERATURE: '0.7'
  
  # Runtime configuration (optional, applied to the built sandbox template)
  runtime:
    timeout: 300              # Startup timeout in seconds (1-3600, default 300)
    memory_limit: 1Gi         # Memory limit (supports "512Mi", "1Gi", etc.)
    cpu_limit: '1'            # CPU limit (supports "1", "1000m", etc.)

# Status field (maintained by the system, should not be modified manually by users)
status:
  phase: deployed             # Current phase: pending/building/deployed/failed
  agent_id: agent-xxxxx       # Agent ID (auto-generated after deployment)
  last_deployed: '2025-10-23T10:35:00Z'  # Last deployment time
  build_id: build_xyz789      # Build ID (auto-generated after deployment)
```

### Modifying Configuration

#### Modifying CPU and Memory Settings

Modify resource configuration under `spec.runtime` in `.novita-agent.yaml`:

```yaml theme={"system"}
spec:
  runtime:
    # CPU configuration
    cpu_limit: '2'        # 2 CPU cores
    # Memory configuration
    memory_limit: 2Gi     # 2 GB memory
```

#### Modifying Environment Variables

The `spec.envVars` in `.novita-agent.yaml` is only used for the CLI's `agent invoke` command and will not be passed to the deployed sandbox template.

Modify environment variables under `spec.envVars` in `.novita-agent.yaml`:

```yaml theme={"system"}
spec:
  envVars:
    # LLM configuration
    MODEL_NAME: deepseek/deepseek-v3-0324
    TEMPERATURE: '0.7'
```

**Note**:

* ⚠️ **Do not store sensitive information** (such as API Keys) in `.novita-agent.yaml`
* You can also pass environment variables via the `--env` parameter when running the `agent invoke` command

#### Redeploy to Apply Configuration Changes

After modifying resource specifications in `.novita-agent.yaml`, redeploy is required:

```bash theme={"system"}
# Redeploy (creates a new version)
npx novita-sandbox-cli agent launch
```

***

## Environment Variables Management

There are several ways to pass environment variables to Agents running in sandbox instances:

### Method 1: Define in Configuration File (CLI invocation only)

Define environment variables under `spec.envVars` in `.novita-agent.yaml`:

```yaml theme={"system"}
spec:
  envVars:
    MODEL_NAME: deepseek/deepseek-v3-0324
    TEMPERATURE: '0.7'
```

### Method 2: Pass Dynamically via SDK

When invoking an Agent using the SDK's `invoke_agent_runtime` method, pass them dynamically via the `envVars` parameter:

```python theme={"system"}
import os
from novita_sandbox.agent_runtime import AgentRuntimeClient

client = AgentRuntimeClient(api_key=os.getenv("NOVITA_API_KEY"))

response = await client.invoke_agent_runtime(
    agentId="agent-xxxxx",
    payload=payload,
    envVars={
        # Read sensitive information from environment variables
        "NOVITA_API_KEY": os.getenv("NOVITA_API_KEY"),
        "DATABASE_PASSWORD": os.getenv("DATABASE_PASSWORD"),
        
        # Or pass directly
        "MODEL_NAME": "deepseek/deepseek-v3-0324",
        "TEMPERATURE": "0.7"
    }
)
```

***

## Streaming Responses

### Implementing Streaming with Synchronous Generators

Use Python generators to implement streaming responses:

```python theme={"system"}
from novita_sandbox.agent_runtime import AgentRuntimeApp

app = AgentRuntimeApp()

@app.entrypoint
def streaming_agent(request: dict):
    """Synchronous streaming response"""
    prompt = request.get("prompt", "")

    # Use generator to return chunks
    for i, chunk in enumerate(generate_response(prompt)):
        yield {
            "chunk": chunk,
            "type": "content",
            "index": i
        }
    # Send end marker
    yield {"chunk": "", "type": "end"}

```

### Implementing Streaming with Async Generators

Use Python async generators:

```python theme={"system"}
import asyncio

@app.entrypoint
async def async_streaming_agent(request: dict):
    """Async streaming response"""
    prompt = request.get("prompt", "")

    async for chunk in async_generate_response(prompt):
        yield {
            "chunk": chunk,
            "type": "content"
        }
    yield {"chunk": "", "type": "end"}

```

### LangChain Streaming Response Example

Complete example using LangChain for streaming responses:

```python theme={"system"}
import os
from langchain_openai import ChatOpenAI
from langchain.callbacks.base import BaseCallbackHandler
from novita_sandbox.agent_runtime import AgentRuntimeApp

app = AgentRuntimeApp()

class StreamingHandler(BaseCallbackHandler):
    """Streaming callback handler"""
    def __init__(self):
        self.tokens = []
    
    def on_llm_new_token(self, token: str, **kwargs):
        self.tokens.append(token)

@app.entrypoint
def langchain_streaming_agent(request: dict):
    """LangChain streaming response"""
    prompt = request.get("prompt", "")

    # Create streaming-enabled LLM
    llm = ChatOpenAI(
        api_key=os.getenv("NOVITA_API_KEY"),
        streaming=True
    )
    
    # Stream invocation
    for chunk in llm.stream(prompt):
        if chunk.content:
            yield {
                "chunk": chunk.content,
                "type": "content"
            }
    yield {"chunk": "", "type": "end"}
```

### Invoking a Streaming Agent

Invoke a streaming Agent using the SDK:

```python theme={"system"}
import asyncio
import json
import os
from novita_sandbox.agent_runtime import AgentRuntimeClient

async def call_streaming_agent():
    client = AgentRuntimeClient(api_key=os.getenv("NOVITA_API_KEY"))
    
    payload = json.dumps({
        "prompt": "Tell me a story"
    }).encode()
    
    response = await client.invoke_agent_runtime(
        agentId="agent-xxxxx",
        payload=payload
    )
    
    # Process streaming response
    print("Streaming response:")
    print(response)
```

***

## Version Management

### Deploying a New Agent Version

Modify the version number and deploy a new version:

```bash theme={"system"}
# Modify version number
npx novita-sandbox-cli agent configure --agent-version 1.1.0

# Deploy new version
npx novita-sandbox-cli agent launch
```

After successful deployment, a new `agent_id` is generated. Each deployment generates a unique `agent_id` that corresponds to a specific version.

***

## Health Checks

### Default Health Check Endpoint

AgentRuntimeApp automatically provides a `/ping` health check endpoint:

```python theme={"system"}
from novita_sandbox.agent_runtime import AgentRuntimeApp

app = AgentRuntimeApp()

# Default health check automatically responds with {"status": "Healthy"}
```

### Custom Health Checks

Use the `@app.ping` decorator to customize health check logic:

```python theme={"system"}
@app.ping
def custom_health_check():
    """Custom health check"""
    # Check dependent services
    db_ok = check_database_connection()
    llm_ok = check_llm_service()
    
    if db_ok and llm_ok:
        return {"status": "Healthy"}
    elif db_ok or llm_ok:
        return {"status": "HealthyBusy"}  # Partially available
    else:
        return {"status": "Unhealthy"}  # Unavailable

def check_database_connection():
    """Check database connection"""
    try:
        # Simulate database check
        return True
    except:
        return False

def check_llm_service():
    """Check LLM service"""
    try:
        # Simulate LLM service check
        return True
    except:
        return False
```

### Supported Health Check Statuses

Agents can return the following health statuses:

| Status        | Description                                                | HTTP Status Code |
| ------------- | ---------------------------------------------------------- | ---------------- |
| `Healthy`     | Agent is fully available                                   | 200              |
| `HealthyBusy` | Agent is partially available (e.g., processing heavy load) | 200              |
| `Unhealthy`   | Agent is unavailable                                       | 503              |

***

## Multi-turn Conversations

### Using Session ID for Multi-turn Conversations

Use the `runtimeSessionId` parameter to route multiple requests to the same sandbox instance:

```python theme={"system"}
import uuid
import json
import os
from novita_sandbox.agent_runtime import AgentRuntimeClient

async def multi_turn_conversation():
    runtime_session_id = str(uuid.uuid4())
    client = AgentRuntimeClient(api_key=os.getenv("NOVITA_API_KEY"))
    agent_id = "agent-xxxxx"
    
    # First turn
    response1 = await client.invoke_agent_runtime(
        agentId=agent_id,
        payload=json.dumps({"prompt": "Hello, my name is John"}).encode(),
        runtimeSessionId=runtime_session_id,
    )
    print(f"AI: {response1}")
    
    # Second turn (sent to the same sandbox instance, Agent remembers the context)
    response2 = await client.invoke_agent_runtime(
        agentId=agent_id,
        payload=json.dumps({"prompt": "What's my name?"}).encode(),
        runtimeSessionId=runtime_session_id,
    )
    print(f"AI: {response2}")  # Should answer "John"
```

***

## Example Projects

We provide a complete example project based on LangGraph, demonstrating how to build real AI applications with Novita Agent Runtime.

### Project Repository

🔗 [https://github.com/novitalabs/Novita-CollabHub/tree/main/examples/agent-runtime/agentic-frameworks/langgraph](https://github.com/novitalabs/Novita-CollabHub/tree/main/examples/agent-runtime/agentic-frameworks/langgraph)


# Agent Framework Integration Guide
Source: https://novita.ai/docs/guides/sandbox-agent-runtime-frameworks



This document shows you how to integrate agents built with various AI frameworks into Novita Agent Runtime.

We provide integration examples for popular AI Agent frameworks:

* [LangGraph](#langgraph) - Build complex multi-step Agent workflows
* [OpenAI Agents SDK](#openai-agents-sdk) - OpenAI's official Agent framework
* [Microsoft AutoGen](#microsoft-autogen) - Microsoft's multi-Agent conversation framework
* [Google ADK](#google-adk) - Google Agent Development Kit

***

## Core Integration Pattern

All framework integrations follow this core pattern:

```python theme={"system"}
from novita_sandbox.agent_runtime import AgentRuntimeApp

# 1. Create Agent Runtime application instance
app = AgentRuntimeApp()

# 2. Initialize your Agent framework

# 3. Define entry point with decorator
@app.entrypoint
def agent_invocation(request: dict) -> dict:
    """
    Args:
        request: Request data, typically contains fields like prompt
    Returns:
        Response data dictionary
    """
    prompt = request.get("prompt", "")
    
    # Call your Agent framework
    result = your_agent.run(prompt)
    
    return {"result": result}

# 4. Run the application
if __name__ == "__main__":
    app.run()
```

***

## LangGraph

LangGraph is the official framework from LangChain for building stateful, multi-step Agent applications.

### Example Code

For the complete example project, see [here](https://github.com/novitalabs/Novita-CollabHub/tree/main/examples/agent-runtime/agentic-frameworks/langgraph)

```python theme={"system"}
from langchain_community.chat_models import ChatOpenAI
from typing_extensions import TypedDict
from typing import Annotated
from langgraph.graph import StateGraph, START
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition

# Import Novita Agent Runtime
from novita_sandbox.agent_runtime import AgentRuntimeApp

app = AgentRuntimeApp()

# Define state
class State(TypedDict):
    messages: Annotated[list, add_messages]

# Initialize LLM
llm = ChatOpenAI(model="gpt-4")

# Define tools
def get_weather(location: str) -> str:
    """Get weather information for a specified location"""
    return f"The weather in {location} is sunny, 23°C"

tools = [get_weather]
llm_with_tools = llm.bind_tools(tools)

# Define node function
def chatbot(state: State):
    return {"messages": [llm_with_tools.invoke(state["messages"])]}

# Build graph
graph_builder = StateGraph(State)
graph_builder.add_node("chatbot", chatbot)
graph_builder.add_node("tools", ToolNode(tools=tools))
graph_builder.add_conditional_edges(
    "chatbot",
    tools_condition,
)
graph_builder.add_edge("tools", "chatbot")
graph_builder.add_edge(START, "chatbot")

graph = graph_builder.compile()

# Define entry point
@app.entrypoint
def agent_invocation(request: dict) -> dict:
    """LangGraph Agent entry point"""
    prompt = request.get("prompt", "Hello!")
    
    # Invoke LangGraph
    result = graph.invoke({
        "messages": [{"role": "user", "content": prompt}]
    })
    
    # Extract the last message
    final_message = result['messages'][-1].content
    
    return {"result": final_message}

if __name__ == "__main__":
    app.run()
```

***

## OpenAI Agents SDK

OpenAI Agents SDK is the official toolkit from OpenAI for building AI Agents.

### Example Code

For the complete example project, see [here](https://github.com/novitalabs/Novita-CollabHub/tree/main/examples/agent-runtime/agentic-frameworks/openai-agents-sdk)

```python theme={"system"}
import os
from novita_sandbox.agent_runtime import AgentRuntimeApp
from openai import AsyncOpenAI

# Create application
app = AgentRuntimeApp()

# Define tool function
def get_weather(city: str) -> str:
    """Get city weather (simulated)"""
    weather_data = {
        "Beijing": "Sunny, 15°C",
        "Shanghai": "Cloudy, 20°C",
        "Shenzhen": "Light rain, 25°C",
    }
    return weather_data.get(city, f"{city}: Sunny, 23°C")

# Tool definition
TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get weather information for a specified city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name, e.g. 'Beijing', 'Shanghai'"
                    }
                },
                "required": ["city"]
            }
        }
    }
]

# Agent core logic
async def run_agent(query: str) -> str:
    """Run OpenAI Agent (supports function calling)"""
    client = AsyncOpenAI(
        base_url=os.getenv("OPENAI_API_BASE"),
        api_key=os.getenv("NOVITA_API_KEY"),
    )
    
    messages = [
        {"role": "system", "content": "You are a helpful AI assistant that can query weather."},
        {"role": "user", "content": query}
    ]
    
    # First call
    response = await client.chat.completions.create(
        model=os.getenv("MODEL_NAME", "deepseek/deepseek-v3.1-terminus"),
        messages=messages,
        tools=TOOLS,
        tool_choice="auto"
    )
    
    response_message = response.choices[0].message
    
    # If tool call is needed
    if response_message.tool_calls:
        messages.append(response_message)
        
        for tool_call in response_message.tool_calls:
            function_args = eval(tool_call.function.arguments)
            function_response = get_weather(**function_args)
            
            messages.append({
                "tool_call_id": tool_call.id,
                "role": "tool",
                "name": "get_weather",
                "content": function_response
            })
        
        # Second call to get final response
        final_response = await client.chat.completions.create(
            model=os.getenv("MODEL_NAME", "deepseek/deepseek-v3.1-terminus"),
            messages=messages
        )
        return final_response.choices[0].message.content
    
    return response_message.content

# Novita Agent Runtime entry point
@app.entrypoint
async def agent_invocation(request: dict) -> dict:
    """Entry point function"""
    prompt = request.get("prompt", "Hello!")
    result = await run_agent(prompt)
    return {"result": result}

# Start application
if __name__ == "__main__":
    app.run()
```

***

## Microsoft AutoGen

AutoGen is a multi-Agent conversation framework developed by Microsoft that supports multi-Agent collaboration and conversations, capable of working independently or with humans.

### Example Code

For the complete example project, see [here](https://github.com/novitalabs/Novita-CollabHub/tree/main/examples/agent-runtime/agentic-frameworks/autogen)

```python theme={"system"}
import os
from novita_sandbox.agent_runtime import AgentRuntimeApp
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.messages import TextMessage
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_core.models import ModelFamily, ModelInfo

# Create application
app = AgentRuntimeApp()

# Define tool function
async def get_weather(city: str) -> str:
    """Get weather for a specified city"""
    weather_data = {
        "Beijing": "Sunny, 15°C",
        "Shanghai": "Cloudy, 20°C",
        "Shenzhen": "Light rain, 25°C",
    }
    return weather_data.get(city, f"{city}: Sunny, 23°C")

# Create AutoGen Agent
def create_agent():
    """Create AutoGen Agent"""
    model_client = OpenAIChatCompletionClient(
        base_url=os.getenv("OPENAI_BASE_URL", "https://api.novita.ai/v3/openai"),
        model=os.getenv("MODEL_NAME", "deepseek/deepseek-v3.1-terminus"),
        api_key=os.getenv("OPENAI_API_KEY"),
        model_info=ModelInfo(
            vision=False,
            function_calling=True,
            json_output=True,
            family=ModelFamily.UNKNOWN,
        ),
    )
    
    agent = AssistantAgent(
        name="assistant",
        model_client=model_client,
        tools=[get_weather],
        system_message="You are a helpful AI assistant that can query weather information.",
        reflect_on_tool_use=True,
    )
    
    return agent

# Run Agent
async def run_agent(prompt: str) -> str:
    """Run AutoGen Agent"""
    agent = create_agent()
    
    # Create user message
    message = TextMessage(content=prompt, source="user")
    
    # Run Agent
    response_message = await agent.on_messages([message])
    
    # Extract response content
    if response_message and hasattr(response_message, 'chat_message'):
        return response_message.chat_message.content
    
    return str(response_message)

# Novita Agent Runtime entry point
@app.entrypoint
async def agent_invocation(request: dict):
    """Entry point function"""
    prompt = request.get("prompt", "Hello!")
    result = await run_agent(prompt)
    return {"result": result}

# Start application
if __name__ == "__main__":
    app.run()
```

***

## Google ADK

Google Agent Development Kit (ADK) is Google's toolkit for Agent development.

### Complete Example

For the complete example project, see [here](https://github.com/novitalabs/Novita-CollabHub/tree/main/examples/agent-runtime/agentic-frameworks/google-adk)

```python theme={"system"}
import os
import uuid
import asyncio
from google.adk.agents import LlmAgent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.adk.tools import google_search
from google.genai import types
from novita_sandbox.agent_runtime import AgentRuntimeApp

# Create application
app = AgentRuntimeApp()

APP_NAME = "google_search_agent"

# Create Google ADK Agent
root_agent = LlmAgent(
    model=os.getenv("GEMINI_MODEL", "gemini-2.0-flash"), 
    name=APP_NAME,
    instruction="I can answer your questions by searching the internet. Ask me anything!",
    tools=[google_search]
)

# Create Session service and Runner
session_service = InMemorySessionService()
runner = Runner(
    agent=root_agent, 
    app_name=APP_NAME, 
    session_service=session_service
)

# Run Agent
async def run_agent(query: str) -> str:
    """Run Google ADK Agent"""
    user_id = "user_default"
    session_id = str(uuid.uuid4())
    
    # Create Session
    await session_service.create_session(
        app_name=APP_NAME, 
        user_id=user_id, 
        session_id=session_id
    )
    
    # Create user message
    user_content = types.Content(
        role='user', 
        parts=[types.Part(text=query)]
    )
    
    # Run Agent
    result = ""
    async for event in runner.run_async(
        user_id=user_id, 
        session_id=session_id, 
        new_message=user_content
    ):
        if event.is_final_response() and event.content and event.content.parts:
            result = event.content.parts[0].text
    
    return result

# Novita Agent Runtime entry point
@app.entrypoint
def agent_invocation(request: dict):
    """Entry point function"""
    prompt = request.get("prompt", "Hello!")
    result = asyncio.run(run_agent(prompt))
    return {"result": result}

# Start application
if __name__ == "__main__":
    app.run()
```


# Installation
Source: https://novita.ai/docs/guides/sandbox-agent-runtime-installation



This feature is currently in **beta**. You need to install the beta versions of both the Novita Sandbox Python SDK and the CLI tool:

***

## Install Python SDK with pip

Use the `--pre` flag to install the latest beta version:

```bash theme={"system"}
pip install --pre novita-sandbox
```

***

## Install Node.js CLI

### Option 1: Run with npx (Recommended)

Install the beta CLI locally in your project directory using `npm`, then run it with `npx`. This avoids polluting your global environment with the beta version.

```bash theme={"system"}
# Install the latest beta version CLI
npm install novita-sandbox-cli@beta

# First, complete authentication
npx novita-sandbox-cli auth login

# Run agent configure command to configure your Agent
npx novita-sandbox-cli agent configure
```

### Option 2: Global Installation

If you use the CLI frequently, you can install it globally:

```bash theme={"system"}
# Install the latest beta version
npm install -g novita-sandbox-cli@beta
```

After installation, you can use the command directly:

```bash theme={"system"}
novita-sandbox-cli agent configure
```


# Overview
Source: https://novita.ai/docs/guides/sandbox-agent-runtime-introduction



## What is Novita Agent Runtime?

Novita Agent Runtime is a lightweight framework for deploying AI Agents that enables you to **deploy AI Agents quickly and cost-effectively**.

No need to worry about infrastructure configuration, container orchestration, service exposure, or other complex details—just focus on developing your Agent's business logic.

***

## Core Components

Novita Agent Runtime is included in the Novita Sandbox SDK and CLI tools:

| Component              | Description                                                                                                 |
| ---------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Novita Sandbox SDK** | Provides decorator-based APIs to expose your Agent as a standard HTTP service, and methods to invoke Agents |
| **Novita Sandbox CLI** | One-click configuration and deployment of Agents to the Novita Agent Sandbox ecosystem                      |

***

## Deployment Workflow

The complete deployment and usage workflow consists of three steps:

### Step 1: Develop and Integrate Your Agent

Integrate the SDK into your Agent code by adding decorators:

```python theme={"system"}
from novita_sandbox.agent_runtime import AgentRuntimeApp

app = AgentRuntimeApp()

@app.entrypoint
def my_agent(request: dict):
    # Agent business logic
    return {"result": "..."}
```

### Step 2: Configure and Deploy

Use the CLI tool to configure and deploy to the cloud:

```bash theme={"system"}
# Configure Agent
novita-sandbox-cli agent configure

# Deploy to cloud
novita-sandbox-cli agent launch
```

* Generates `Dockerfile` and `.novita-agent.yaml` configuration files
* Builds sandbox template and uploads it
* Generates Agent ID (format: `agent_<name>_v<version>`)

### Step 3: Invoke Agent

After successful deployment, you can invoke your Agent via CLI or SDK:

**Option 1: Quick test with CLI**

```bash theme={"system"}
novita-sandbox-cli agent invoke "Hello, Agent!"
```

**Option 2: Invoke via SDK in your application**

```python theme={"system"}
import json
from novita_sandbox.agent_runtime import AgentRuntimeClient

client = AgentRuntimeClient(api_key="your-api-key")

# Prepare request data (converted to a JSON string and encoded as bytes)
payload = json.dumps({"prompt": "Hello, Agent!"}).encode()

response = await client.invoke_agent_runtime(
    agentId="agent-xxxxx",
    payload=payload
)
```

**Agent invocation execution flow**:

* Creates an isolated sandbox instance from the sandbox template
* Executes the Agent in an isolated environment
* Returns the processed result

***

## Key Benefits

SDK:

* ✅ **Minimal Changes**: Just modify a few lines of code with decorators
* ✅ **Framework Agnostic**: Supports LangChain, LangGraph, CrewAI, and other popular AI frameworks
* ✅ **Streaming Support**: Native streaming responses for real-time LLM generation scenarios
* ✅ **Health Checks**: Built-in health check endpoint with customizable health status

CLI:

* ✅ **Smart Detection**: Auto-detects project structure, entry files, and dependency management files
* ✅ **Auto Build**: Automatically generates Dockerfile and project configuration
* ✅ **Version Management**: Supports multiple versions coexisting with independent deployments
* ✅ **Quick Testing**: Built-in invoke command for rapid deployment verification

Runtime:

* ✅ **Environment Isolation**: Each sandbox instance runs independently without interference
* ✅ **Session Persistence**: Multiple invocations to the same sandbox instance, supporting multi-turn interactive Agents
* ✅ **Secure Sandbox**: Securely isolated sandbox environment with restricted filesystem access


# Quick Start
Source: https://novita.ai/docs/guides/sandbox-agent-runtime-quick-start



This guide will help you **develop, deploy, and invoke your first Agent in 5 minutes**.

***

## Table of Contents

* [Overview](#overview)
* [Prerequisites](#prerequisites)
* [Step 1: Integrate SDK into Your Agent](#step-1-integrate-sdk-into-your-agent)
* [Step 2: Generate Configuration Files with CLI](#step-2-generate-configuration-files-with-cli)
* [Step 3: Deploy to Novita with One-Click](#step-3-deploy-to-novita-with-one-click)
* [Step 4: Invoke Agent via CLI or SDK](#step-4-invoke-agent-via-cli-or-sdk)
* [FAQ](#faq)

***

## Overview

The complete workflow consists of 4 steps:

1. ✅ **Integrate SDK** - Add decorators to your Agent code
2. ✅ **Configure Agent** - Generate configuration files using CLI
3. ✅ **Deploy Agent** - One-click deployment to the cloud
4. ✅ **Invoke Agent** - Call your Agent using SDK or CLI

***

## Prerequisites

Ensure you have the following prerequisites:

* ✅ Python 3.9+ and Node.js 20+ installed
* ✅ Beta version Python SDK and Node.js CLI installed (see [Installation Guide](/guides/sandbox-agent-runtime-installation))
* ✅ Novita AI API Key obtained (from the [Console](https://novita.ai/settings/key-management))
* ✅ [Docker](https://www.docker.com/products/docker-desktop/) installed

***

## Step 1: Integrate SDK into Your Agent

### 1.1 Create Agent Code

Create `app.py` in your project directory:

```python theme={"system"}
from novita_sandbox.agent_runtime import AgentRuntimeApp

# Create Agent Runtime application instance
app = AgentRuntimeApp()

# Define Agent entry point with decorator
@app.entrypoint
def my_agent(request: dict) -> dict:
    """
    Agent entry function
    
    Args:
        request: Request data, which typically contains fields like prompt
        
    Returns:
        Response data dictionary
    """
    prompt = request.get("prompt", "")
    
    # Agent business logic
    # You can call LLMs, use Agent frameworks, or implement any custom logic here
    result = f"Received message: {prompt}"
    
    return {"result": result}

# Local run entry point
if __name__ == "__main__":
    app.run()
```

### 1.2 Prepare Dependencies File

Ensure your project root has a `requirements.txt` file with the required dependencies:

```txt theme={"system"}
novita-sandbox>=1.1.0b1
# Your other dependencies...
```

### 1.3 Local Testing

Test locally before deployment:

```bash theme={"system"}
# Start the Agent service
python app.py
```

In another terminal, test the endpoints:

```bash theme={"system"}
# Test health check
curl http://localhost:8080/ping

# Test Agent invocation
curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello, Agent!"}'
```

**Expected output**:

Health check should return:

```json theme={"system"}
{"status": "Healthy"}
```

Agent invocation should return:

```json theme={"system"}
{"result": "Received message: Hello, Agent!"}
```

***

## Step 2: Generate Configuration Files with CLI

Use CLI to interactively configure your Agent:

```bash theme={"system"}
# Make sure environment variables are configured
export NOVITA_API_KEY=your-novita-api-key

# Run configuration command
npx novita-sandbox-cli agent configure
```

Follow the CLI prompts to configure the required information. When complete, the CLI will generate the following files in your project directory:

* `novita.Dockerfile` - Docker build file
* `.dockerignore` - Docker ignore file
* `.novita-agent.yaml` - Agent configuration file

***

## Step 3: Deploy to Novita AI with One-click

> ⚠️ **Important**: After successful deployment, an `agent_id` will be generated. This is the unique identifier for invoking your Agent—make sure to save it.

### 3.1 Deploy Command

Deploy with one-click using CLI:

```bash theme={"system"}
npx novita-sandbox-cli agent launch
```

### 3.2 View Deployment Results

After successful deployment, the `.novita-agent.yaml` file will update the `status` field:

```yaml theme={"system"}
status:
  phase: deployed
  agent_id: agent-xxxx  # ⭐ This is your Agent's unique identifier
  last_deployed: '2025-10-23T10:35:00Z'
  build_id: build_xyz789
```

**Record the `agent_id`—you'll need it for subsequent invocations.**

***

## Step 4: Invoke Agent via CLI or SDK

### Option 1: Quick Test with CLI

Quickly test your Agent using CLI:

```bash theme={"system"}
npx novita-sandbox-cli agent invoke "Hello, Agent!"
```

**Note**: The CLI automatically reads the Agent ID from the `status.agent_id` field in `.novita-agent.yaml`.

**Expected output**:

```json theme={"system"}
{"result": "Received message: Hello, Agent!"}
```

### Option 2: SDK Invocation (Recommended for Production)

Use the SDK to invoke your Agent in backend services:

#### Example Code

```python theme={"system"}
import asyncio
import json
import os
from novita_sandbox.agent_runtime import AgentRuntimeClient
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Create Agent Runtime client
client = AgentRuntimeClient(
    api_key=os.getenv("NOVITA_API_KEY")
)

async def main():
    # Get from status.agent_id in .novita-agent.yaml after deployment
    agent_id = "agent-xxxx"
    
    # Prepare request data
    payload = json.dumps({
        "prompt": "Hello, Agent! Tell me something about AI."
    }).encode()
    
    # Invoke Agent
    print(f"🚀 Invoking agent: {agent_id}")
    response = await client.invoke_agent_runtime(
        agentId=agent_id,
        payload=payload,
        timeout=300
    )
    
    print(f"✅ Response: {response}")

if __name__ == "__main__":
    asyncio.run(main())
```

***

## FAQ

### Q1: How do I get the Agent ID?

After successful deployment, the Agent ID is saved in the `status.agent_id` field of the `.novita-agent.yaml` file:

```yaml theme={"system"}
status:
  agent_id: agent-xxxxx  # Here
```

### Q2: What if deployment fails?

1. **Check dependencies file**: Ensure `requirements.txt` contains all dependencies
2. **View detailed logs**: Use the `--verbose` flag
3. **Check network connection**: Ensure you can access the Novita AI Sandbox domain (e.g., `sandbox.novita.ai`)
4. **Verify API Key**: Confirm `NOVITA_API_KEY` is correct

```bash theme={"system"}
# Show detailed logs
npx novita-sandbox-cli agent launch --verbose
```

### Q3: How do I update a deployed Agent?

Modify your code and redeploy:

```bash theme={"system"}
# Option 1: Create new version (Recommended)
npx novita-sandbox-cli agent configure --agent-version 1.1.0
npx novita-sandbox-cli agent launch

# Option 2: Update existing version
npx novita-sandbox-cli agent launch --update-existing
```

### Q4: Works locally but fails after deployment?

**Possible causes**:

1. Environment variables not passed to sandbox instance
2. Dependency package version inconsistencies
3. File path issues

**Solution**:

Pass environment variables to the sandbox instance via the `envVars` parameter:

```python theme={"system"}
response = await client.invoke_agent_runtime(
    agentId=agent_id,
    payload=payload,
    envVars={
        "NOVITA_API_KEY": os.getenv("NOVITA_API_KEY"),
        "MODEL_NAME": "deepseek/deepseek-v3-0324"
    }
)
```


# Auto Pause and Resume
Source: https://novita.ai/docs/guides/sandbox-auto-persistence



<SandboxBetaVersionWarning />

When the sandbox instance is not currently needed but you need to be able to resume it at any time later, you can refer to the [documentation](/guides/sandbox-persistence) to manually pause and resume sandbox instances.

The **"Auto Pause and Resume"** feature allows your sandbox instance to automatically pause after [timeout](/guides/sandbox-lifecycle) and resume when needed. When you attempt to perform operations (such as executing commands, running code, or file operations) on a paused sandbox, it will automatically resume without manual intervention.

## Enable Auto Pause

You can enable the auto pause feature by setting the `auto_pause` parameter to `true` when creating a sandbox instance. The sandbox instance will automatically pause after timeout and can be resumed later.

<Warning>
  Note: The resumed sandbox instance will still have the auto pause feature enabled and will automatically pause again after timeout.
</Warning>

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter';

  const sandbox = await Sandbox.create(
      {
          timeoutMs: 5_000,
          autoPause: true
      },
  );
  console.log('Sandbox created', sandbox.sandboxId)

  console.log('Waiting for 10 seconds...')
  await new Promise(resolve => setTimeout(resolve, 10000));

  const resumedSandbox = await Sandbox.connect(sandbox.sandboxId)
  console.log('Sandbox resumed', resumedSandbox.sandboxId)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.core import Sandbox
  import time

  sandbox = Sandbox.create(
      timeout=5,
      auto_pause=True,
  )
  print('Sandbox created', sandbox.sandbox_id)

  print('Waiting for 10 seconds...')
  time.sleep(10)

  resumed_sandbox = Sandbox.connect(sandbox.sandbox_id)
  print('Sandbox resumed', resumed_sandbox.sandbox_id)

  sandbox.kill()
  ```
</CodeGroup>

## Enable Auto Resume

You can enable the auto resume feature by setting the `auto_resume` key in `metadata` to `true` when creating a sandbox instance. Once enabled, when you attempt to operate on a paused sandbox (such as executing commands, running code, file operations, etc.), the sandbox will automatically resume.

<Warning>
  Note: The default timeout for the resumed sandbox is 5 minutes. You can update the sandbox timeout using the `setTimeout` or `set_timeout` method.
</Warning>

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter';

  const sandbox = await Sandbox.create(
      {
          metadata:{"auto_resume": "true"}
      }
  );
  console.log('Sandbox created', sandbox.sandboxId)

  await sandbox.betaPause()
  console.log('Sandbox paused', sandbox.sandboxId)

  const result = await sandbox.commands.run('ls -al')
  console.log('Command result', result)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.core import Sandbox

  sandbox = Sandbox.create(
      metadata={
          "auto_resume": "true",
      }
  )
  print('Sandbox created', sandbox.sandbox_id)

  sandbox.beta_pause()
  print('Sandbox paused', sandbox.sandbox_id)

  result = sandbox.commands.run('ls -al')
  print('Command result', result)

  sandbox.kill()
  ```
</CodeGroup>


# Installing CLI
Source: https://novita.ai/docs/guides/sandbox-cli



Novita Agent Sandbox CLI is a command line tool that allows you to list, kill running <Link href="/guides/sandbox-lifecycle">sandboxes</Link>, and manage <Link href="/guides/sandbox-template">sandbox templates</Link>.

## Installation

You can install the CLI globally using npm:

```bash Bash icon="terminal" theme={"system"}
npm i -g novita-sandbox-cli
```

Additionally, some new advanced features will be first released in the **Beta versions** of CLI tool, which you can install using the following methods. If you encounter any issues during use of these Beta features, please feel free to <Link href="https://meetings-na2.hubspot.com/junyu">contact us</Link>.

## Install Beta CLI

```bash Bash icon="terminal" theme={"system"}
npm i -g novita-sandbox-cli@beta
```


# Authentication in CLI
Source: https://novita.ai/docs/guides/sandbox-cli-auth



Before using the CLI, you must first authenticate. Run the following command to sign in into to your Novita account:

<Tip>
  After executing the command below, a third-party authorization page will open in your browser (with URL format `https://novita.ai/oauth/authorize?xxx`). Follow the instructions to complete the subsequent authorization steps.
</Tip>

```bash Bash icon="terminal" theme={"system"}
novita-sandbox-cli auth login
```


# List sandboxes
Source: https://novita.ai/docs/guides/sandbox-cli-list-sandboxes



<SandboxCliConfigHint />

### List all running sandboxes

To list all running sandboxes, use the following command:

```bash Bash icon="terminal" theme={"system"}
novita-sandbox-cli sandbox list
```

### Filter by state

To filter the sandboxes by their state you can specify the `--state` flag, which can either be "**running**", "**paused**" or both.

```bash Bash icon="terminal" theme={"system"}
novita-sandbox-cli sandbox list --state running,paused
```

This will return all sandboxes, both running and paused.

### Filter by metadata

To filter the sandboxes by their metadata, use the `--metadata` flag.

```bash Bash icon="terminal" theme={"system"}
novita-sandbox-cli sandbox list --metadata key1=value1,key2=value2
```

### List limit

To limit the amount of sandboxes returned by the command, use the `--limit` flag.

```bash Bash icon="terminal" theme={"system"}
novita-sandbox-cli sandbox list --limit 10
```

By default, the command will return all sandboxes.


# Shutdown running sandboxes
Source: https://novita.ai/docs/guides/sandbox-cli-shutdown-sandboxes



You can shutdown single or all running sandboxes with the CLI.

<SandboxCliConfigHint />

## Shutdown single sandbox

To shutdown a single sandbox, run the following command:

```bash Bash icon="terminal" theme={"system"}
novita-sandbox-cli sandbox kill <sandbox-id>
```

## Shutdown all sandboxes

To shutdown all running sandboxes, run the following command:

```bash Bash icon="terminal" theme={"system"}
novita-sandbox-cli sandbox kill --all
```


# Create sandbox and connect to terminal
Source: https://novita.ai/docs/guides/sandbox-cli-spawn-sandbox



<SandboxCliConfigHint />

With the following command, you can use the command line tool to start a sandbox and connect to the terminal.

```bash Bash icon="terminal" theme={"system"}
novita-sandbox-cli sandbox create <template-id>
```


# Sandbox Clone
Source: https://novita.ai/docs/guides/sandbox-clone



<SandboxBetaVersionWarning />

The **"Sandbox Clone"** feature allows you to duplicate a running or paused sandbox instance. The cloned sandbox maintains the same <u>file system and memory state</u> as the original sandbox.

<Warning>
  If you clone a running sandbox, the sandbox being cloned will be briefly suspended. During this period, the sandbox instance will be unavailable, and the suspension time is close to the time required to <Link href="/guides/sandbox-persistence#pausing-sandbox">pause a sandbox</Link>.
</Warning>

**Parameter Description:**

* `count`: Specifies how many sandbox instances to clone. The minimum value is 1, and the maximum is determined by the concurrent running sandbox instance limit (see [Quota Limit](/guides/sandbox-quota-limit)).
* `strict`: Specifies whether to strictly clone according to the number specified in the `count` parameter. The default value is false. When set to true, if the number of successfully cloned instances is less than `count`, a clone failure error will be returned, and other successfully created sandboxes will also be cleaned up. When set to false, the actual number of successfully cloned sandbox instances will be returned.
* `timeout`(`timeoutMs`): Specifies the timeout for cloning sandbox instances. If this parameter is not specified, when the parent sandbox is running, it inherits the parent sandbox's timeout configuration; but when the parent sandbox is in a paused state, the default value of 5min is used.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox';

  const sandbox = await Sandbox.create();
  console.log('Sandbox created', sandbox.sandboxId)

  const sbxClones = await Sandbox.clone(sandbox.sandboxId, 
      {
          count: 2,
          strict: false,
          timeoutMs: 100_000
      }
  );
  console.log('Sandbox clones created', sbxClones.map(sbxClone => sbxClone.sandboxId))

  await sandbox.kill()
  for (const sbxClone of sbxClones) {
      await sbxClone.kill()
  }
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.core import Sandbox

  sandbox = Sandbox.create()
  print('Sandbox created', sandbox.sandbox_id)

  sbxClones = Sandbox.clone(
      sandbox.sandbox_id, 
      count=2, 
      strict=False, 
      timeout=60
  )
  print('Sandbox clones created', [sbxClone.sandbox_id for sbxClone in sbxClones])

  sandbox.kill()
  for sbxClone in sbxClones:
      sbxClone.kill()
  ```
</CodeGroup>

Additionally, you can also use the [Novita Sandbox CLI](/guides/sandbox-cli) to clone a specified sandbox instance:

```bash Bash icon="terminal" theme={"system"}
# novita-sandbox-cli sandbox clone [sandboxID] -c [count] -s [strict] -t [timeout]
novita-sandbox-cli sandbox clone 0r0efkbfwzfp9p7qpc1c -c 2
```


# Running commands in sandbox
Source: https://novita.ai/docs/guides/sandbox-commands



<SandboxConfigHint />

You can run terminal commands inside the sandbox using the `commands.run()` method.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()

  const result = await sandbox.commands.run('ls -l')
  console.log(result)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()

  result = sandbox.commands.run('ls -l')
  print(result)

  sandbox.kill()
  ```
</CodeGroup>


# Running commands in background
Source: https://novita.ai/docs/guides/sandbox-commands-background



<SandboxConfigHint />

To run commands in background, pass the `background` option to the `commands.run()` method. This will return immediately and the command will continue to run in the sandbox.
You can then later kill the command using the `commands.kill()` method.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()

  // Start the command in the background
  const command = await sandbox.commands.run('echo hello; sleep 10; echo world', {
    background: true,
    onStdout: (data) => {
      console.log(data)
    },
  })

  // Kill the command
  await command.kill()

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()

  # Start the command in the background
  command = sandbox.commands.run('echo hello; sleep 10; echo world', background=True)

  # Get stdout and stderr from the command running in the background.
  # You can run this code in a separate thread or use command.wait() to wait for the command to finish.
  for stdout, stderr, _ in command:
      if stdout:
          print(stdout)
      if stderr:
          print(stderr)

  # Kill the command
  command.kill()

  sandbox.kill()
  ```
</CodeGroup>


# Streaming command output
Source: https://novita.ai/docs/guides/sandbox-commands-streaming



<SandboxConfigHint />

To stream command output as it is being executed, pass the `onStdout`, `onStderr` callbacks to the `commands.run()` method in JavaScript
or the `on_stdout`, `on_stderr` callbacks to the `commands.run()` method in Python.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()
  const result = await sandbox.commands.run('echo hello; sleep 1; echo world', {
    onStdout: (data) => {
      console.log(data)
    },
    onStderr: (data) => {
      console.log(data)
    },
  })

  console.log(result)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()

  result = sandbox.commands.run('echo hello; sleep 1; echo world',
                                on_stdout=lambda data: print(data),
                                on_stderr=lambda data: print(data))

  print(result)

  sandbox.kill()
  ```
</CodeGroup>


# Connect to running sandbox
Source: https://novita.ai/docs/guides/sandbox-connect



If you have a running sandbox, you can connect to it using the `Sandbox.connect()` method and then start controlling it with our SDK.

This is useful if you want to, for example, reuse the same sandbox instance for the same user after a short period of inactivity.

<SandboxConfigHint />

## 1. Get the sandbox ID

To connect to a running sandbox, you first need to retrieve its ID. You can do this by calling the `Sandbox.list()` method.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from "novita-sandbox/code-interpreter"

  // Get all running sandboxes
  const runningSandboxesPaginator = await Sandbox.list({
    query: {
      state: ["running"],
    },
  })

  const runningSandboxes = await runningSandboxesPaginator.nextItems()
  if (runningSandboxes.length === 0) {
    throw new Error("No running sandboxes found")
  }
  const runningSandboxId = runningSandboxes[0].sandboxId

  console.log(`got a running sandbox: ${runningSandboxId}`)
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox, SandboxQuery, SandboxState

  sandbox = Sandbox.create()

  # Get all running sandboxes
  running_sandboxes_paginator = Sandbox.list(query=SandboxQuery(state=[SandboxState.RUNNING]))

  running_sandboxes = running_sandboxes_paginator.next_items()
  if len(running_sandboxes) == 0:
    raise Exception("No running sandboxes found")
  running_sandbox_id = running_sandboxes[0].sandbox_id

  # got a running sandbox.
  print("got a running sandbox: ", running_sandbox_id)

  sandbox.kill()
  ```
</CodeGroup>

## 2. Connect to the sandbox

Now that you have the sandbox ID, you can connect to the sandbox using the `Sandbox.connect()` method.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from "novita-sandbox/code-interpreter"

  // Get all running sandboxes
  const runningSandboxesPaginator = await Sandbox.list({
    query: {
      state: ["running"],
    },
  })

  const runningSandboxes = await runningSandboxesPaginator.nextItems()
  if (runningSandboxes.length === 0) {
    throw new Error("No running sandboxes found")
  }
  const runningSandboxId = runningSandboxes[0].sandboxId

  // connect to the sandbox.
  const sandbox = await Sandbox.connect(runningSandboxId)
  console.log("connected to sandbox: ", sandbox.sandboxId)

  // Now you can use the sandbox as usual
  // ...
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox, SandboxQuery, SandboxState

  sandbox = Sandbox.create()

  # Get all running sandboxes.
  running_sandboxes_paginator = Sandbox.list(query=SandboxQuery(state=[SandboxState.RUNNING]))

  running_sandboxes = running_sandboxes_paginator.next_items()
  if len(running_sandboxes) == 0:
    raise Exception("No running sandboxes found")
  running_sandbox_id = running_sandboxes[0].sandbox_id

  # connect to the sandbox.
  sandbox = Sandbox.connect(running_sandbox_id)
  print("got a running sandbox: ", sandbox.sandbox_id)

  # Now you can use the sandbox as usual
  # ...

  sandbox.kill()
  ```
</CodeGroup>


# Agent Sandbox Console
Source: https://novita.ai/docs/guides/sandbox-console



Agent Sandbox console helps you view and manage sandboxes, templates, and usage statistics.

## Sandbox Management

* Display the list of currently running sandboxes.
* Support searching for a sandbox by ID.
* Support filtering sandboxes by creation time, template, vCPUs, memory, etc.

<Frame>
  <img alt="Sandbox Management" />
</Frame>

## Template Management

* Display the list of available templates, including official templates provided by Novita official and your [custom templates](/guides/sandbox-template).
* Support searching for a template by ID.
* Support filtering templates by visibility (public, private, or all), vCPUs, and memory.

<Frame>
  <img alt="Sandbox Management" />
</Frame>

## Usage Statistics

Console provides daily resource usage and cost analysis to help you monitor your consumption and optimize your usage.

* **vCPU Hours**
  * Display the total vCPU usage time for all sandboxes on the current day (unit: hours).
  * This data can be accurate to the second, and can be used to evaluate the current computing resource usage.

* **Memory Hours**
  * Display the total memory usage time for all sandboxes on the current day (unit: GB·hours).
  * The system calculates the memory allocation and usage time for each sandbox during runtime.

* **Usage Costs**
  * Display the total cost of resources on the current day (unit: USD).
  * Includes the total cost of all vCPUs and memory. The storage space and templates are currently free to use.

<Tip>
  - All resources are billed by the second, and displayed in daily granularity.
  - The chart shows the trend of the past 30 days, which can be used to monitor the trend of usage changes.
  - This data may not include the latest usage, which may be slightly different from the bill. The final settlement is based on the <Link href="https://novita.ai/billing/details">billing details</Link> page.
</Tip>

<Frame>
  <img alt="Sandbox Management" />
</Frame>


# E2B SDK Compatibility
Source: https://novita.ai/docs/guides/sandbox-e2b-compatible



Novita Agent Sandbox provides a compatibility API that allows you to use the E2B SDK and CLI. This is useful if you are already using the E2B SDK and CLI and want to switch to Novita Agent Sandbox. However, we recommend using the Novita [Agent Sandbox SDK](/guides/sandbox-sdk-and-cli) to access all features.

## Installation

### Code Interpreter SDK

<CodeGroup>
  ```bash JavaScript & TypeScript icon="terminal" theme={"system"}
  npm i @e2b/code-interpreter@beta
  ```

  ```bash Python icon="terminal" theme={"system"}
  pip install e2b-code-interpreter==1.2.0b5
  ```
</CodeGroup>

### Core SDK

<CodeGroup>
  ```bash JavaScript & TypeScript icon="terminal" theme={"system"}
  npm i e2b@beta
  ```

  ```bash Python icon="terminal" theme={"system"}
  pip install e2b==1.2.0b6
  ```
</CodeGroup>

### Desktop SDK

<CodeGroup>
  ```bash JavaScript & TypeScript icon="terminal" theme={"system"}
  npm i @e2b/desktop@beta
  ```

  ```bash Python icon="terminal" theme={"system"}
  pip install e2b-desktop==1.7.1b1
  ```
</CodeGroup>

### CLI

<CodeGroup>
  ```bash Bash icon="terminal" theme={"system"}
  npm i -g @e2b/cli@v1.9.2
  ```
</CodeGroup>

## Setup Configuration

You need to set the following environment variables in your project to use the E2B SDK and CLI with Novita Agent Sandbox.

```bash Bash icon="terminal" theme={"system"}
export E2B_DOMAIN=sandbox.novita.ai
export E2B_API_KEY="<Your Novita AI API Key>"
```

## Examples

Below is an example showing how to create a sandbox through the SDK and run specified commands using E2B SDK.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from '@e2b/code-interpreter'
  // or import { Sandbox } from 'e2b'
  // or import { Sandbox } from '@e2b/desktop'

  const sbx = await Sandbox.create()
  const execution = await sbx.commands.run('ls -l')
  console.log(execution)

  await sbx.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from e2b_code_interpreter import Sandbox
  # or from e2b import Sandbox
  # or from e2b_desktop import Sandbox

  sbx = Sandbox.create()
  execution = sbx.commands.run('ls -l')
  print(execution)

  sbx.kill()
  ```
</CodeGroup>

Below is an example showing how to use the E2B CLI with Novita Agent Sandbox.

<CodeGroup>
  ```bash Bash icon="terminal" theme={"system"}
  export E2B_DOMAIN=sandbox.novita.ai
  # Authentication in CLI
  e2b auth login

  # Start sandbox and connect to terminal
  e2b sandbox spawn <template-id>

  # List sandboxes
  e2b sandbox list

  # Shutdown running sandboxes
  e2b sandbox kill <sandbox-id>
  ```
</CodeGroup>


# Environment variables
Source: https://novita.ai/docs/guides/sandbox-environment-variables



This page covers how to set and use environment variables in a sandbox, and default environment variables inside the sandbox.

<SandboxConfigHint />

## Setting environment variables

There are 3 ways to set environment variables in a sandbox:

* [Global environment variables when creating the sandbox](#1-global-environment-variables).
* [When running code in the sandbox](#2-setting-environment-variables-when-running-code).
* [When running commands in the sandbox](#3-setting-environment-variables-when-running-commands).

### 1. Global environment variables

You can set global environment variables when creating a sandbox.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create({
    envs: {
      MY_VAR: 'my_value',
    },
  })

  const result = await sandbox.commands.run("echo $MY_VAR")

  console.log(result)

  // Output example:
  // { exitCode: 0, error: undefined, stdout: 'my_value\n', stderr: '' }

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create(
    envs={
      'MY_VAR': 'my_value',
    },
  )

  result = sandbox.commands.run("echo $MY_VAR")

  print(result)

  # Output example:
  # { exitCode: 0, error: undefined, stdout: '123\n', stderr: '' }

  sandbox.kill()
  ```
</CodeGroup>

### 2. Setting environment variables when running code

You can set environment variables for specific code execution call in the sandbox.

<Note>
  If you had a global environment variable with the same name, it will be overridden.
</Note>

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()

  const result = await sandbox.runCode('import os; print(os.environ.get("MY_VAR"))', {
    envs: {
      MY_VAR: 'my_value',
    },
  })
  console.log(result.logs)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()
  result = sandbox.run_code(
      'import os; print(os.environ.get("MY_VAR"))',
      envs={
          'MY_VAR': 'my_value'
      }
  )

  print(result)

  sandbox.kill()
  ```
</CodeGroup>

### 3. Setting environment variables when running commands

You can set environment variables for specific command execution in the sandbox.

<Note>
  If you had a global environment variable with the same name, it will be overridden.
</Note>

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()

  const result = await sandbox.commands.run('echo $MY_VAR', {
    envs: {
      MY_VAR: '123',
    },
  })

  console.log(result)

  // Output example:
  // { exitCode: 0, error: undefined, stdout: '123\n', stderr: '' }

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()
  result = sandbox.commands.run(
      'echo $MY_VAR',
      envs={
          'MY_VAR': '123'
      }
  )

  print(result)

  # Output example:
  # CommandResult(stderr='', stdout='123\n', exit_code=0, error='')

  sandbox.kill()
  ```
</CodeGroup>


# Overview
Source: https://novita.ai/docs/guides/sandbox-filesystem



Each sandbox has a completely isolated filesystem. Currently, we provide fixed 5 GB storage space for sandboxes.

Next, we will demonstrate how to operate the sandbox filesystem using the SDK, including:

* [Read & write files](/guides/sandbox-filesystem-read-write)
* [Watch sandbox directory for changes](/guides/sandbox-filesystem-watch)
* [Upload data to sandbox](/guides/sandbox-filesystem-upload)
* [Download data from sandbox](/guides/sandbox-filesystem-download)


# Download data from sandbox
Source: https://novita.ai/docs/guides/sandbox-filesystem-download



You can download data from the sandbox using the `files.read()` method.

<SandboxConfigHint />

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import fs from 'fs'
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()

  // Create a file in the sandbox for testing
  const filePathInSandbox = '/tmp/test-file'
  await sandbox.files.write(filePathInSandbox, "test-file-content")

  // Read file from sandbox
  const content = await sandbox.files.read(filePathInSandbox)

  // Write file to local filesystem
  const localFilePath = './local-test-file'
  fs.writeFileSync(localFilePath, content)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()

  # Create a file in the sandbox for testing
  file_path_in_sandbox = '/tmp/test-file'
  sandbox.files.write(file_path_in_sandbox, "test-file-content")

  # Read file from sandbox
  content = sandbox.files.read(file_path_in_sandbox)

  # Write file to local filesystem
  local_file_path = './local-test-file'
  with open(local_file_path, 'w') as file:
    file.write(content)

  sandbox.kill()
  ```
</CodeGroup>


# Read & write files
Source: https://novita.ai/docs/guides/sandbox-filesystem-read-write



<SandboxConfigHint />

## Reading files

You can read files from the sandbox filesystem using the `files.read()` method.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()

  // Create a file in the sandbox for testing
  const filePathInSandbox = '/tmp/test-file'
  await sandbox.files.write(filePathInSandbox, "test-file-content")

  const fileContent = await sandbox.files.read(filePathInSandbox)
  console.log(fileContent)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()

  file_path_in_sandbox = '/tmp/test-file'
  sandbox.files.write(file_path_in_sandbox, "test-file-content")

  file_content = sandbox.files.read(file_path_in_sandbox)
  print(file_content)

  sandbox.kill()
  ```
</CodeGroup>

## Writing single files

You can write single files to the sandbox filesystem using the `files.write()` method.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()

  const filePathInSandbox = '/tmp/test-file'

  const result = await sandbox.files.write(filePathInSandbox, "test-file-content")
  console.log(result)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()

  file_path_in_sandbox = '/tmp/test-file'
  result = sandbox.files.write(file_path_in_sandbox, "test-file-content")
  print(result)

  sandbox.kill()
  ```
</CodeGroup>

## Writing multiple files

You can also write multiple files to the sandbox filesystem using the `files.write()` method.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()

  const result = await sandbox.files.write([
      { path: '/tmp/test-file-1', data: 'file content 1' },
      { path: '/tmp/test-file-2', data: 'file content 2' }
  ])

  console.log(result)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()

  result = sandbox.files.write_files([
      { "path": "/tmp/test-file-1", "data": "file content 1" },
      { "path": "/tmp/test-file-2", "data": "file content 2" }
  ])
  print(result)

  sandbox.kill()
  ```
</CodeGroup>


# Upload data to sandbox
Source: https://novita.ai/docs/guides/sandbox-filesystem-upload



You can upload data to the sandbox using the `files.write()` method.

<SandboxConfigHint />

## Upload single file

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import fs from 'fs'
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()

  // Read file from local filesystem
  const localFilePath = '../local-test-file'
  const content = fs.readFileSync(localFilePath, 'utf8')

  // Upload file to sandbox
  const filePathInSandbox = '/tmp/test-file'
  const result = await sandbox.files.write(filePathInSandbox, content)
  console.log(result)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()

  local_file_path = '../local-test-file'
  with open(local_file_path, "rb") as file:
    file_path_in_sandbox = '/tmp/test-file'
    result = sandbox.files.write(file_path_in_sandbox, file)
    print(result)

  sandbox.kill()
  ```
</CodeGroup>

## Upload directory / multiple files

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import fs from 'fs'
  import path from 'path'

  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()

  const readDirectoryFiles = (directoryPath) => {
    const files = fs.readdirSync(directoryPath);

    const filesArray = files
      .filter(file => {
        const fullPath = path.join(directoryPath, file);
        return fs.statSync(fullPath).isFile();
      })
      .map(file => {
        const filePath = path.join(directoryPath, file);
      
        return {
          path: filePath,
          data: fs.readFileSync(filePath, 'utf8')
        };
      });

    return filesArray;
  };

  const localDirectoryPath = '../local-test-dir'
  const files = readDirectoryFiles(localDirectoryPath);
  console.log(files); 

  files.forEach(file => {
    file.path = file.path.replace('../local-test-dir', '/tmp')
  })

  const result = await sandbox.files.write(files)
  console.log(result)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  import os
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()

  def read_directory_files(directory_path):
      files = []

      for filename in os.listdir(directory_path):
          file_path = os.path.join(directory_path, filename)
          
          if os.path.isfile(file_path):
              with open(file_path, "rb") as file:
                  files.append({
                      'path': file_path,
                      'data': file.read()
                  })
      return files

  local_directory_path = '../local-test-dir'
  files = read_directory_files(local_directory_path)
  print(files)

  for file in files:
      file['path'] = file['path'].replace('../local-test-dir', '/tmp')

  result = sandbox.files.write_files(files)
  print(result)

  sandbox.kill()
  ```
</CodeGroup>


# Watch sandbox directory for changes
Source: https://novita.ai/docs/guides/sandbox-filesystem-watch



You can watch a directory for changes using the `files.watchDir()` method in JavaScript and `files.watch_dir()` method in Python.

<Note>
  Since events are tracked asynchronously, their delivery may be delayed.
  It's recommended not to collect or close watcher immediately after making a change.
</Note>

<SandboxConfigHint />

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox, FilesystemEventType } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()
  const dirname = '/tmp'

  // Start watching directory for changes
  const handle = await sandbox.files.watchDir(dirname, async (event) => {
    console.log(`got event: ${event.type} - ${event.name}`)
    if (event.type === FilesystemEventType.WRITE) {
      console.log(`wrote to file ${event.name}`)
    }
  })

  // Trigger file write event
  await sandbox.files.write(`${dirname}/test-file`, 'test-file-content')

  // Stop watching directory for changes
  handle.stop()

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox, FilesystemEventType

  sandbox = Sandbox.create()
  dirname = '/tmp'

  # Watch directory for changes
  handle = sandbox.files.watch_dir(dirname)
  # Trigger file write event
  sandbox.files.write(f"{dirname}/test-file", "test-file-content")

  # Retrieve the latest new events since the last `get_new_events()` call
  events = handle.get_new_events()
  for event in events:
    print(f"got event: {event.type} - {event.name}")
    if event.type == FilesystemEventType.WRITE:
      print(f"wrote to file {event.name}")

  # Stop watching directory for changes
  handle.stop()

  sandbox.kill()
  ```
</CodeGroup>

## Recursive Watching

You can enable recursive watching using the parameter `recursive`.

<Note>
  When rapidly creating new folders (e.g., deeply nested path of folders), events other than `CREATE` might not be emitted. To avoid this behavior, create the required folder structure in advance.
</Note>

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox, FilesystemEventType } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()
  const dirname = '/tmp'

  // Start watching directory for changes
  const handle = await sandbox.files.watchDir(dirname, async (event) => {
    console.log(`got event: ${event.type} - ${event.name}`)
    if (event.type === FilesystemEventType.WRITE) {
      console.log(`wrote to file ${event.name}`)
    }
  }, {
    recursive: true
  })

  // Trigger file write event
  await sandbox.files.write(`${dirname}/test-folder/test-file`, 'test-file-content')

  // Stop watching directory for changes
  handle.stop()

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox, FilesystemEventType

  sandbox = Sandbox.create()
  dirname = '/tmp'

  # Watch directory for changes
  handle = sandbox.files.watch_dir(dirname, recursive=True)
  # Trigger file write event
  sandbox.files.write(f"{dirname}/test-folder/test-file", "test-file-content")

  # Retrieve the latest new events since the last `get_new_events()` call
  events = handle.get_new_events()
  for event in events:
    print(f"got event: {event.type} - {event.name}")
    if event.type == FilesystemEventType.WRITE:
      print(f"wrote to file {event.name}")

  # Stop watching directory for changes
  handle.stop()

  sandbox.kill()
  ```
</CodeGroup>


# Idle Timeout
Source: https://novita.ai/docs/guides/sandbox-idle-timeout



<SandboxBetaVersionWarning />

We can set a timeout for each sandbox (refer to [Lifecycle Management](/guides/sandbox-lifecycle)). When the sandbox running time reaches the timeout, the sandbox will be automatically killed. However, in some scenarios, we cannot determine the expected running time of the sandbox, but we want the sandbox to be automatically killed when not in use to save costs. In this case, you can use the **"Idle Timeout"** feature.

When creating a sandbox, we can set the `idle_timeout` parameter in metadata (unit: seconds, minimum is 60) to enable the **"Idle Timeout"** feature. Once enabled, when the system detects that the sandbox has no operations (executing commands, running code, file operations, etc.) within the specified time range, the system will kill the sandbox instance. Otherwise, the sandbox will continue to run until it reaches the maximum time limit for sandbox operation (currently default is 3600 seconds).

Please refer to the following example:

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter';

  const sandbox = await Sandbox.create(
      {
          metadata: { "idle_timeout": "60" }
      }
  );
  console.log('Sandbox created', sandbox.sandboxId)

  const result = await sandbox.commands.run('ls -al')
  console.log('Command result', result)

  await new Promise(resolve => setTimeout(resolve, 90000));

  const isRunning = await sandbox.isRunning()
  console.log('Sandbox is running', isRunning)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.core import Sandbox
  import time

  sandbox = Sandbox.create(
      metadata={"idle_timeout": "60"}  # Minimum time is 60s, you can customize it
  )
  print('Sandbox created', sandbox.sandbox_id)

  result = sandbox.commands.run('ls -al')
  print('Command result', result)

  print('Waiting for 90 seconds...')
  time.sleep(90)

  is_running = sandbox.is_running()
  print('Sandbox is running', is_running)

  sandbox.kill()
  ```
</CodeGroup>


# BrowserUse Integration with Novita Agent Sandbox
Source: https://novita.ai/docs/guides/sandbox-integrations-browser-use



[BrowserUse](https://github.com/browser-use/browser-use) is a powerful AI browser agent. Combined with the secure isolated environment provided by Novita Agent Sandbox, you can build high-concurrency, multi-task browser AI agents.

This document provides detailed instructions on how to run BrowserUse projects based on Novita Agent Sandbox service.

The document uses the `browser-chromium` sandbox template released by Novita. If you want to create your own template based on this or view more complete example code, please refer to [here](https://github.com/novitalabs/Novita-CollabHub/tree/main/examples/browser-use).

### 1. Get Novita API Key

<SetupApiKeyGuide />

### 2. Configure Environment Variables

Before getting started, you need to configure the necessary environment variables:

```bash Bash icon="terminal" highlight={1,2} theme={"system"}
export E2B_DOMAIN=sandbox.novita.ai
export NOVITA_API_KEY="<Your Novita AI API Key>"
export LLM_API_KEY="<Your Novita AI API Key>"
export LLM_BASE_URL=https://api.novita.ai/openai
export LLM_MODEL="<Your LLM Model ID>"
```

### 3. Install Dependencies

Install the required Python packages:

```bash Python icon="terminal" theme={"system"}
pip install browser-use
pip install e2b-code-interpreter
```

### 4. Example Code

```python agent.py icon="python" theme={"system"}
import asyncio
import os
import time

from browser_use import Agent, BrowserSession
from browser_use.llm import ChatOpenAI
from novita_sandbox.code_interpreter import Sandbox

async def screenshot(agent: Agent):
  # Screenshot function
  print("Taking screenshot...")
  page = await agent.browser_session.get_current_page()
  screenshot_bytes = await page.screenshot(full_page=True, type='png')
  # screenshot method returns the binary data of the image, we should save it as a PNG file
  screenshots_dir = os.path.join(".", "screenshots")
  os.makedirs(screenshots_dir, exist_ok=True)
  screenshot_path = os.path.join(screenshots_dir, f"{time.time()}.png")
  with open(screenshot_path, "wb") as f:
    f.write(screenshot_bytes)
  print(f"Screenshot saved to {screenshot_path}")

async def main():
    # Create E2B sandbox instance
    sandbox = Sandbox(
        timeout=600,  # Timeout in seconds
        template="browser-chromium",  # This template contains chromium browser and exposes port 9223 for remote connection
    )
    
    try:
        # Get Chrome debug port address from sandbox
        host = sandbox.get_host(9223) # Get sandbox port 9223 address
        cdp_url = f"https://{host}"
        print(f"Chrome Debug Protocol URL: {cdp_url}")

        # Create BrowserUse session
        browser_session = BrowserSession(cdp_url=cdp_url)
        await browser_session.start()
        print("BrowserUse session created successfully")
        
        # Create AI Agent
        agent = Agent(
            task="Go to hackernews and find the top 3 stories",
            llm=ChatOpenAI(
                api_key=os.getenv("LLM_API_KEY"),
                base_url=os.getenv("LLM_BASE_URL"),
                model=os.getenv("LLM_MODEL"),
                temperature=1
            ),
            browser_session=browser_session,
        )
        
        # Run Agent task
        print("Starting Agent task execution...")
        await agent.run(
            on_step_end=screenshot, # Take screenshot after each step
        )
        
        # Close browser session
        await browser_session.close()
        print("Task execution completed")
        
    finally:
        # Clean up sandbox resources
        sandbox.kill()
        print("Sandbox resources cleaned up")

if __name__ == "__main__":
    asyncio.run(main())
```

### 5. Run the Agent

After Installing the dependencies and setting up the environment variables, you can run the example code. You can see the output in the terminal as below if everything goes well. Browser-use is running tasks in the remote browser inside your sandbox.

<img alt="Output" />

It will generate screenshots like below:

<img alt="screenshot1" />

<img alt="screenshot2" />

To run a more complete demo, please refer to [here](https://github.com/novitalabs/Novita-CollabHub/tree/main/examples/browser-use).


# Computer use with E2B Desktop
Source: https://novita.ai/docs/guides/sandbox-integrations-e2b-desktop



[E2B Desktop](https://github.com/e2b-dev/desktop) is an open-source secure virtual desktop framework specifically engineered for developing Computer Use Agents. This solution provides a comprehensive, isolated desktop environment that enables AI agents to securely interact with desktop applications through controlled virtualization.

This document will provide detailed instructions on how to run this project based on Novita Agent sandbox service.

### 1. Get Novita API Key

<SetupApiKeyGuide />

### 2. Environment Configuration

Before you start using the service, you need to configure the necessary environment variables:

```bash Bash icon="terminal" highlight={1} theme={"system"}
export E2B_DOMAIN=sandbox.novita.ai
export E2B_API_KEY=<Your API key obtained in the previous step>
```

Running example:

<img alt="Setup Environment Variables" />

### 3. SDK Installation

Select the appropriate installation method corresponding to your development environment and programming language:

<CodeGroup>
  ```bash JavaScript & TypeScript icon="terminal"  theme={"system"}
  npm i @e2b/desktop@2.0.1
  ```

  ```bash Python icon="terminal" theme={"system"}
  pip install e2b-desktop==2.0.1
  ```
</CodeGroup>

### 4. Implementation Examples

#### Get Virtual Desktop Stream VNC URL

The following implementation demonstrates the instantiation of a virtual desktop environment and the retrieval of VNC access endpoints for remote desktop interaction:

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  // demo.ts implementation
  import { Sandbox } from '@e2b/desktop'

  // Initialize virtual desktop sandbox instance
  const desktop = await Sandbox.create()

  // Activate desktop streaming service
  await desktop.stream.start()

  // Retrieve interactive VNC endpoint URL
  const url = desktop.stream.getUrl()
  console.log(url)

  // Expected output format:
  // Browser-accessible URL for interactive virtual desktop session. Suitable for application integration.
  // https://6080-ik0n7lc3j0dvqd4jxy6g7.sandbox.novita.ai/vnc.html?autoconnect=true&resize=scale

  // Retrieve read-only VNC endpoint URL (interaction disabled)
  const urlDisabledInteraction = desktop.stream.getUrl({ viewOnly: true })
  console.log(urlDisabledInteraction)
  // Expected output format:
  // Browser-accessible URL for view-only virtual desktop session (non-interactive mode). Suitable for monitoring applications.
  // https://6080-ik0n7lc3j0dvqd4jxy6g7.sandbox.novita.ai/vnc.html?autoconnect=true&view_only=true&resize=scale

  // Keep the program running
  console.log("Desktop stream started, press Ctrl+C to stop the program...")
  const interval = setInterval(() => {}, 1000)

  // Register interrupt signal handlers for resource cleanup
  let isCleaning = false
  const cleanup = async () => {
      if (isCleaning) return
      isCleaning = true
      
      console.log("\nProgram interrupted, cleaning up resources...")
      clearInterval(interval)
      try {
          await desktop.stream.stop() // Terminate streaming service
          await desktop.kill()        // Deallocate sandbox instance
      } catch (err) {
          console.error("Error cleaning up resources:", err)
      }
      process.exit(0)
  }

  process.on('SIGINT', cleanup)
  process.on('SIGTERM', cleanup)
  ```

  ```python Python icon="python" theme={"system"}
  # demo.py implementation
  from e2b_desktop import Sandbox

  # Initialize virtual desktop sandbox instance
  desktop = Sandbox.create()

  # Activate desktop streaming service
  desktop.stream.start()

  # Retrieve interactive VNC endpoint URL
  url = desktop.stream.get_url()
  print(url)
  # Expected output format:
  # Browser-accessible URL for interactive virtual desktop session. Suitable for application integration.
  # https://6080-ik0n7lc3j0dvqd4jxy6g7.sandbox.novita.ai/vnc.html?autoconnect=true&resize=scale

  # Retrieve read-only VNC endpoint URL (interaction disabled)
  url_readonly = desktop.stream.get_url(view_only=True)
  print(url_readonly)
  # Expected output format:
  # Browser-accessible URL for view-only virtual desktop session (non-interactive mode). Suitable for monitoring applications.
  # https://6080-ik0n7lc3j0dvqd4jxy6g7.sandbox.novita.ai/vnc.html?autoconnect=true&view_only=true&resize=scale

  # Implement keyboard interrupt handling for graceful shutdown
  try:
      print("Desktop stream started, press Ctrl+C to stop the program...")
      import time
      while True:
          time.sleep(0.1)
  except KeyboardInterrupt:
      print("\nProgram interrupted, cleaning up resources...")

  # Execute resource deallocation procedures
  desktop.stream.stop()  # Terminate streaming service
  desktop.kill()        # Deallocate sandbox instance
  ```
</CodeGroup>

Running example:

<img alt="Run Example" />

Access virtual desktop stream VNC URL:

<img alt="Desktop Streaming" />

Additional implementation examples and advanced use cases are available in the <Link href="https://github.com/e2b-dev/desktop/tree/main/examples">official E2B Desktop repository</Link>.


# Internet access
Source: https://novita.ai/docs/guides/sandbox-internet-access



Every sandbox has access to the internet and can be reached by a public URL.

<SandboxConfigHint />

## Sandbox public URL

Every sandbox has a public URL that can be used to access running services inside the sandbox.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()

  // You need to always pass a port number to get the host
  const host = sandbox.getHost(3000)
  console.log(`https://${host}`)

  // Example output:
  // https://3000-idpw1qdrbcciscn2r8lw7-82b888ba.sandbox.novita.ai

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()

  # You need to always pass a port number to get the host
  host = sandbox.get_host(3000)
  print(f'https://{host}')

  # Example output:
  # https://3000-i9y92beaqiyor8x3josfy-82b888ba.sandbox.novita.ai

  sandbox.kill()
  ```
</CodeGroup>

The first leftmost part of the host is the port number we passed to the method.

## Connecting to a server running inside the sandbox

You can start a server inside the sandbox and connect to it using the approach above.

In this example we will start a simple HTTP server that listens on port 3000 and responds with the content of the directory where the server is started.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()

  // Start a simple HTTP server inside the sandbox.
  const commandHandle = await sandbox.commands.run('python -m http.server 3000', { background: true })
  const host = sandbox.getHost(3000)
  const url = `https://${host}`
  console.log('Server started at:', url)

  // Fetch data from the server inside the sandbox.
  const response = await fetch(url);
  const data = await response.text();
  console.log('Response from server inside sandbox:', data);

  // Kill the server process inside the sandbox.
  await commandHandle.kill()

  // Example output:
  // Server started at: https://3000-ibbw4zmqp38s77v1vbykj-d0b9e1e2.sandbox.novita.ai
  // Response from server inside sandbox: <!DOCTYPE HTML>
  // <html lang="en">
  // <head>
  // <meta charset="utf-8">
  // <title>Directory listing for /</title>
  // </head>
  // <body>
  // <h1>Directory listing for /</h1>
  // <hr>
  // <ul>
  // <li><a href=".bash_logout">.bash_logout</a></li>
  // <li><a href=".bashrc">.bashrc</a></li>
  // <li><a href=".profile">.profile</a></li>
  // </ul>
  // <hr>
  // </body>
  // </html>

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()

  # Start a simple HTTP server inside the sandbox.
  command_handle = sandbox.commands.run("python -m http.server 3000", background=True)
  host = sandbox.get_host(3000)
  url = f"https://{host}"
  print('Server started at:', url)

  # Fetch data from the server inside the sandbox.
  response = sandbox.commands.run(f"curl {url}")
  data = response.stdout
  print("Response from server inside sandbox:", data)

  # Kill the server process inside the sandbox.
  command_handle.kill()

  # Example output:
  # Server started at: https://3000-i0iq56w6786bz91034h8l-82b888ba.sandbox.novita.ai
  # Response from server inside sandbox: <!DOCTYPE HTML>
  # <html lang="en">
  # <head>
  # <meta charset="utf-8">
  # <title>Directory listing for /</title>
  # </head>
  # <body>
  # <h1>Directory listing for /</h1>
  # <hr>
  # <ul>
  # <li><a href=".bash_logout">.bash_logout</a></li>
  # <li><a href=".bashrc">.bashrc</a></li>
  # <li><a href=".profile">.profile</a></li>
  # </ul>
  # <hr>
  # </body>
  # </html>

  sandbox.kill()
  ```
</CodeGroup>


# Learn more
Source: https://novita.ai/docs/guides/sandbox-learn-more



After reading the [quick start guide](/guides/sandbox-your-first-agent-sandbox), you should have a basic understanding of how to create and use Novita Agent Sandbox through the SDK. To access more advanced features, you can refer to the [detailed tutorial](/guides/sandbox-lifecycle).

Additionally, you can manage sandboxes and templates through the [CLI](/guides/sandbox-cli).


# Sandbox Lifecycle
Source: https://novita.ai/docs/guides/sandbox-lifecycle



When you start the sandbox, it stays alive for 5 minutes by default but you can change it by passing the `timeout` parameter.
After the time passes, the sandbox will be automatically shutdown.

<SandboxConfigHint />

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  // Create sandbox with and keep it running for 60 seconds.
  const sandbox = await Sandbox.create({
    timeoutMs: 60_000, // The units are milliseconds.
  })

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  # Create sandbox with and keep it running for 60 seconds.
  sandbox = Sandbox.create(
    timeout=60, # The units are seconds.
  )

  sandbox.kill()
  ```
</CodeGroup>

## Change sandbox timeout during runtime

You can change the sandbox timeout when it's running by calling the the `setTimeout` method in JavaScript or `set_timeout` method in Python.

When you call the set timeout method, the sandbox timeout will be reset to the new value that you specified.

This can be useful if you want to extend the sandbox lifetime when it's already running.
You can for example start with a sandbox with 1 minute timeout and then periodically call set timout every time user interacts with it in your app.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  // Create sandbox with and keep it running for 60 seconds.
  const sandbox = await Sandbox.create({ timeoutMs: 60_000 })

  // Change the sandbox timeout to 30 seconds.
  // The new timeout will be 30 seconds from now.
  await sandbox.setTimeout(30_000)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  # Create sandbox with and keep it running for 60 seconds.
  sandbox = Sandbox.create(timeout=60)

  # Change the sandbox timeout to 30 seconds.
  # The new timeout will be 30 seconds from now.
  sandbox.set_timeout(30)

  sandbox.kill()
  ```
</CodeGroup>

## Retrieve sandbox information

You can retrieve sandbox information like sandbox ID, template, metadata, started at/end at date by calling the `getInfo` method in JavaScript or `get_info` method in Python.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  // Create sandbox with and keep it running for 60 seconds.
  const sandbox = await Sandbox.create({ timeoutMs: 60_000 })

  // Retrieve sandbox information.
  const info = await sandbox.getInfo()

  console.log(info)

  // Output example:
  // {
  //   sandboxId: 'i8kktl6jolbramfm8cp3k-a402f90a',
  //   templateId: '23j9hy90m6r461w7nkrn',
  //   name: 'code-interpreter-v1',
  //   metadata: {},
  //   envdVersion: '0.2.0',
  //   envdAccessToken: undefined,
  //   startedAt: 2025-06-30T06:46:36.096Z,
  //   endAt: 2025-06-30T07:16:36.096Z
  // }

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  # Create sandbox with and keep it running for 60 seconds.
  sandbox = Sandbox.create(timeout=60)

  # Retrieve sandbox information.
  info = sandbox.get_info()

  print(info)

  sandbox.kill()
  ```
</CodeGroup>

## Shutdown sandbox

You can shutdown the sandbox any time even before the timeout is up by calling the `kill` method.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  // Create sandbox with and keep it running for 60 seconds.
  const sandbox = await Sandbox.create({ timeoutMs: 60_000 })

  // Shutdown the sandbox immediately.
  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  # Create sandbox with and keep it running for 60 seconds.
  sandbox = Sandbox.create(timeout=60)

  # Shutdown the sandbox immediately.
  sandbox.kill()
  ```
</CodeGroup>


# List sandboxes
Source: https://novita.ai/docs/guides/sandbox-list



You can list sandboxes using the `Sandbox.list()` method.

<SandboxConfigHint />

<Note>
  Once you have information about running sandbox, you can [connect](/guides/sandbox-connect) to it using the `Sandbox.connect()` method.
</Note>

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  // Create a sandbox.
  const sandbox = await Sandbox.create({
    metadata: {
      name: 'My Sandbox',
    },
  })

  // List all running sandboxes.
  const runningSandboxesPaginator = await Sandbox.list({
    query: {
      state: ["running"],
    },
  })

  const runningSandboxes = await runningSandboxesPaginator.nextItems()
  const runningSandbox = runningSandboxes[0]

  console.log('Running sandbox metadata:', runningSandbox.metadata)
  console.log('Running sandbox id:', runningSandbox.sandboxId)
  console.log('Running sandbox started at:', runningSandbox.startedAt)
  console.log('Running sandbox template id:', runningSandbox.templateId)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox, SandboxQuery, SandboxState

  sandbox = Sandbox.create(
    metadata= {
      'name': 'My Sandbox',
    },
  )

  # List all running sandboxes.
  running_sandboxes_paginator = Sandbox.list(
    query=SandboxQuery(
      state=[SandboxState.RUNNING],
    ),
  )

  running_sandboxes = running_sandboxes_paginator.next_items()

  running_sandbox = running_sandboxes[0]
  print('Running sandbox metadata:', running_sandbox.metadata)
  print('Running sandbox id:', running_sandbox.sandbox_id)
  print('Running sandbox started at:', running_sandbox.started_at)
  print('Running sandbox template id:', running_sandbox.template_id)

  sandbox.kill()
  ```
</CodeGroup>

## Filtering sandboxes

You can filter sandboxes by specifying <Link href="/guides/sandbox-metadata">Metadata</Link> key value pairs.
Specifying multiple key value pairs will return sandboxes that match all of them.

This can be useful when you have a large number of sandboxes and want to find only specific ones. The filtering is performed on the server.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  // Create a sandbox with metadata.
  const sandbox = await Sandbox.create({
    metadata: {
      env: 'dev',
      app: 'my-app',
      userId: '123',
    },
  })

  // List all running sandboxes that has `userId` key with value `123` and `env` key with value `dev`.
  const runningSandboxesPaginator = await Sandbox.list({
    query: {
      metadata: { userId: '123', env: 'dev' },
    },
  })

  const runningSandboxes = await runningSandboxesPaginator.nextItems()
  for (const runningSandbox of runningSandboxes) {
    console.log(`list running sandbox (${runningSandbox.sandboxId}) metadata:`, runningSandbox.metadata)
  }

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox, SandboxQuery

  # Create sandbox with metadata.
  sandbox = Sandbox.create(
      metadata={
          "env": "dev",
          "app": "my-app",
          "user_id": "123",
      },
  )

  # List all running sandboxes that has `user_id` key with value `123` and `env` key with value `dev`.
  paginator = Sandbox.list(
      query=SandboxQuery(
          metadata={
              "user_id": "123",
              "env": "dev",
          }
      ),
  )

  sandbox.kill()
  ```
</CodeGroup>

### Listing sandboxes

The `Sandbox.list()` method now supports pagination. In the [advanced pagination](#advanced-pagination) section, you can find more information about pagination techniques using the updated method.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js"  theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()

  const paginator = Sandbox.list()

  // Get the first page of sandboxes (running and paused)
  const firstPage = await paginator.nextItems()
  if (paginator.hasNext) {
      // Get the next page of sandboxes
      const nextPage = await paginator.nextItems()
  }

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()

  # List all sandboxes (running and paused)
  paginator = Sandbox.list()

  firstPage = paginator.next_items()
  if paginator.has_next:
      nextPage = paginator.next_items()

  sandbox.kill()
  ```
</CodeGroup>

### Filtering sandboxes

Filter sandboxes by their current state. The state parameter can contain either "**running**" for running sandboxes or "**paused**" for paused sandboxes, or both.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()

  // List all sandboxes that are running or paused.
  const paginator = Sandbox.list({
    query: {
      state: ['running', 'paused'],
    },
  })

  const sandboxes = await paginator.nextItems()

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox, SandboxQuery, SandboxState

  sandbox = Sandbox.create()

  # List all sandboxes that are running or paused.
  paginator = Sandbox.list(
      query=SandboxQuery(
          state=[SandboxState.RUNNING, SandboxState.PAUSED],
      ),
  )

  # Get the first page of sandboxes (running and paused)
  sandboxes = paginator.next_items()

  sandbox.kill()
  ```
</CodeGroup>

Filter sandboxes by the metadata key value pairs specified during Sandbox creation.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  // Create sandbox with metadata.
  const sandbox = await Sandbox.create({
    metadata: {
      env: 'dev',
      app: 'my-app',
      userId: '123',
    },
  })

  // List all sandboxes that has `userId` key with value `123` and `env` key with value `dev`.
  const paginator = Sandbox.list({
    query: {
      metadata: { userId: '123', env: 'dev' },
    },
  })

  const sandboxes = await paginator.nextItems()

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox, SandboxQuery

  # Create sandbox with metadata.
  sandbox = Sandbox.create(
      metadata={
          "env": "dev",
          "app": "my-app",
          "user_id": "123",
      },
  )

  # List all sandboxes that has `userId` key with value `123` and `env` key with value `dev`.
  paginator = Sandbox.list(
      query=SandboxQuery(
          metadata={
              "user_id": "123",
              "env": "dev",
          }
      ),
  )

  sandboxes = paginator.next_items()

  sandbox.kill()
  ```
</CodeGroup>

### Advanced pagination

For more granular pagination, you can set custom per-page item limit (default and maximum is **1000**) and specify an offset parameter (`nextToken` or `next_token`) to start paginating from.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()

  const paginator = Sandbox.list({
    limit: 1000,
    // nextToken: '<base64-encoded-token>',
  })

  // Fetch the next page
  await paginator.nextItems()

  // Additional paginator properties
  // Whether there is a next page
  console.log("paginator.hasNext: ", paginator.hasNext)

  // Next page token
  console.log("paginator.nextToken: ", paginator.nextToken)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()

  paginator = Sandbox.list(
      limit=1000,
      # next_token='<base64-encoded-token>',
  )

  # Fetch the next page
  paginator.next_items()

  # Whether there is a next page
  print("paginator.has_next: ", paginator.has_next)

  # Next page offset parameter
  print("paginator.next_token: ", paginator.next_token)

  sandbox.kill()
  ```
</CodeGroup>

You can fetch all pages by looping through the paginator while checking if there is a next page (using `hasNext` or `has_next` property) and fetching until there are no more pages left to fetch:

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox, SandboxInfo } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()

  const paginator = Sandbox.list()

  const sandboxes: SandboxInfo[] = []
  while (paginator.hasNext) {
    const items = await paginator.nextItems()
    sandboxes.push(...items)
  }

  for (const sandbox of sandboxes) {
    console.log(`list sandbox (${sandbox.sandboxId})`)
  }

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox, SandboxInfo

  sandbox = Sandbox.create()

  paginator = Sandbox.list()

  # Get all sandboxes
  sandboxes: list[SandboxInfo] = []
  while paginator.has_next:
      items = paginator.next_items()
      sandboxes.extend(items)

  sandbox.kill()
  ```
</CodeGroup>


# Sandbox Metadata
Source: https://novita.ai/docs/guides/sandbox-metadata



Metadata is a way to attach arbitrary key-value pairs for a sandbox.

This is useful in various scenarios, for example:

* Associate a sandbox with a user session.
* Store custom user data for a sandbox like API keys.
* Associate a sandbox with a user ID and [connect to it later](/guides/sandbox-connect).

You specify metadata when creating a sandbox and can access it later through listing running sandboxes with `Sandbox.list()` method.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  // Create sandbox with metadata.
  const sandbox = await Sandbox.create({
    metadata: {
      userId: '123',
    },
  })

  // List running sandboxes and access metadata.
  const runningSandboxesPaginator = await Sandbox.list({
    query: {
      state: ["running"],
    },
  })

  const runningSandboxes = await runningSandboxesPaginator.nextItems()

  console.log("runningSandboxes[0].metadata: ", runningSandboxes[0].metadata)

  // Example output:
  // { userId: '123' }

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox, SandboxQuery, SandboxState

  # Create sandbox with metadata.
  sandbox = Sandbox.create(
    metadata={
      'userId': '123',
    },
  )

  # List running sandboxes and access metadata.
  running_sandboxes_paginator = Sandbox.list(
    query=SandboxQuery(
      state=[SandboxState.RUNNING],
    ),
  )
  running_sandboxes = running_sandboxes_paginator.next_items()

  print(running_sandboxes[0].metadata)

  # Example output:
  # { userId: '123' }

  sandbox.kill()
  ```
</CodeGroup>

## Filtering sandboxes by metadata

You can also filter sandboxes by metadata, you can find more about it [here](/guides/sandbox-list#filtering-sandboxes).


# Sandbox Metrics
Source: https://novita.ai/docs/guides/sandbox-metrics



The sandbox metrics allows you to get information about the sandbox's CPU and memory usage.

<SandboxConfigHint />

## Getting sandbox metrics

Getting the metrics of a sandbox returns an array of timestamped metrics containing CPU and memory usage information.
The metrics are collected at the start of the sandbox, then every 2 seconds, and finally right before the sandbox is deleted.

### Getting sandbox metrics using the SDKs

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()
  console.log('Sandbox created', sandbox.sandboxId)

  let metrics = await sandbox.getMetrics()

  // You can also get the metrics by sandbox ID:
  // const metrics = await Sandbox.getMetrics(sbx.sandboxId)

  while (metrics && metrics.length <= 1) {
      console.log('Waiting for metrics...')
      await new Promise(resolve => setTimeout(resolve, 1000))
      metrics = await sandbox.getMetrics()
  }

  console.log('Sandbox metrics:', metrics)

  // Example output:
  // Sandbox metrics: [
  //   {
  //     cpuCount: 2,
  //     cpuUsedPct: 17.85,
  //     memTotalMiB: 987,
  //     memUsedMiB: 245,
  //     timestamp: '2025-06-30T06:49:15.243Z'
  //   },
  //   {
  //     cpuCount: 2,
  //     cpuUsedPct: 0.4,
  //     memTotalMiB: 987,
  //     memUsedMiB: 246,
  //     timestamp: '2025-06-30T06:49:20.237Z'
  //   }
  // ]

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox
  import time

  sandbox = Sandbox.create()
  print('Sandbox created', sandbox.sandbox_id)

  metrics = sandbox.get_metrics()

  # You can also get the metrics by sandbox ID:
  # metrics = Sandbox.get_metrics(sbx.sandbox_id)

  while len(metrics) <= 1:
      print('Waiting for metrics...')
      time.sleep(1)
      metrics = sandbox.get_metrics()

  print('Sandbox metrics', metrics)

  # Example output:
  # Sandbox metrics [SandboxMetrics(timestamp=datetime.datetime(2025, 6, 30, 6, 51, 13, 169230, tzinfo=tzutc()), cpu_used_pct=17.87, cpu_count=2, mem_used_mib=245, mem_total_mib=987), SandboxMetrics(timestamp=datetime.datetime(2025, 6, 30, 6, 51, 18, 165258, tzinfo=tzutc()), cpu_used_pct=0.4, cpu_count=2, mem_used_mib=246, mem_total_mib=987)]

  sandbox.kill()
  ```
</CodeGroup>

### Getting sandbox metrics using the CLI

```bash Bash icon="terminal" theme={"system"}
novita-sandbox-cli sandbox metrics <sandbox_id>
```

## Limitations

* It may take a second or more to get the metrics after the sandbox is created. Until the logs are collected from the sandbox, you will get an empty array.


# Mount object storage bucket in sandbox
Source: https://novita.ai/docs/guides/sandbox-mount-cloudstorage



Each sandbox instance is provisioned with 20GB of ephemeral system disk storage by default for temporary data operations. <u>Upon sandbox termination or timeout, all data within this storage space is automatically purged</u>. Consequently, persistent data requiring long-term retention should be stored in external cloud storage services.

<Tip>
  Sandbox storage allocation specifications are subject to modification. Consult the [Pricing](/guides/sandbox-pricing) documentation for current resource allocations and associated costs.
</Tip>

Object Storage represents a highly scalable, durable, and cost-efficient cloud storage architecture offered by major cloud service providers. Within sandbox environments, object storage can be accessed through two primary methodologies: direct programmatic interaction via cloud provider SDKs or CLI utilities, or through FUSE (Filesystem in Userspace) implementations that present object storage buckets as standard POSIX-compliant filesystem mounts.

<Tip>
  [FUSE (Filesystem in Userspace)](https://www.kernel.org/doc/html/next/filesystems/fuse.html) is a kernel module and userspace library that enables the implementation of fully functional filesystems in userspace applications. This framework provides an abstraction layer that presents remote cloud storage services as standard filesystem hierarchies, enabling transparent file operations through conventional POSIX interfaces.
</Tip>

This documentation provides comprehensive guidance for integrating object storage buckets from leading cloud service providers into sandbox environments through filesystem mounting techniques.

<Warning>
  FUSE-based object storage mounts introduce significant I/O performance overhead due to network latency and protocol translation layers. Applications with stringent performance requirements should avoid this approach. Furthermore, FUSE filesystem operations lack atomicity guarantees inherent to native object storage APIs, creating potential race conditions where local filesystem operations may succeed while corresponding remote operations fail, resulting in data inconsistency.

  This mounting approach is optimal for read-heavy workloads with infrequent write operations and relaxed performance constraints. For performance-critical applications or frequent write patterns, direct integration using cloud provider SDKs or native REST APIs is strongly recommended.
</Warning>

<SandboxConfigHint />

## Amazon S3

Amazon S3 buckets can be mounted as POSIX-compliant filesystems using [s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse), a FUSE-based filesystem implementation that provides S3 bucket access through standard file operations.

The s3fs-fuse package can be integrated during [sandbox template](/guides/sandbox-template) creation by incorporating installation commands in the `novita.Dockerfile`, or installed dynamically within active sandbox instances for ad-hoc requirements.

The following `novita.Dockerfile` demonstrates the integration of s3fs-fuse during template building:

<CodeGroup>
  ```dockerfile novita.Dockerfile icon="docker" theme={"system"}
  # Compatible with Debian-based distributions
  FROM ubuntu:latest

  # Critical: s3fs versions below 1.93 contain known mounting issues. Ensure version compatibility.
  RUN DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y s3fs
  ```
</CodeGroup>

The following implementation demonstrates programmatic S3 bucket mounting within sandbox environments using s3fs-fuse:

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox'

  const TEMPLATE_ID = process.env.NOVITA_TEMPLATE_ID
  const AWS_ACCESS_KEY_ID = process.env.AWS_ACCESS_KEY_ID
  const AWS_SECRET_ACCESS_KEY = process.env.AWS_SECRET_ACCESS_KEY
  const AWS_BUCKET_NAME = process.env.AWS_BUCKET_NAME
  if (!TEMPLATE_ID || !AWS_ACCESS_KEY_ID || !AWS_SECRET_ACCESS_KEY || !AWS_BUCKET_NAME) {
      throw new Error('Required environment variables not configured: NOVITA_TEMPLATE_ID, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_BUCKET_NAME')
  }

  const MOUNT_DIRECTORY = "/mnt/s3-bucket"

  const sandbox = await Sandbox.create(TEMPLATE_ID)

  // Initialize mount point directory structure
  await sandbox.files.makeDir(MOUNT_DIRECTORY)

  // Configure s3fs credentials using standard credential file location
  // s3fs-fuse reads AWS credentials from /root/.passwd-s3fs by default
  await sandbox.files.write('/root/.passwd-s3fs', `${AWS_ACCESS_KEY_ID}:${AWS_SECRET_ACCESS_KEY}`)

  // Enforce secure credential file permissions (owner read-only)
  await sandbox.commands.run('sudo chmod 600 /root/.passwd-s3fs')

  // Execute S3 bucket mount operation with optimized parameters
  // Configuration parameters:
  // - allow_other: Enable cross-user filesystem access
  // - endpoint: Specify AWS regional endpoint for optimal latency
  // Reference: https://manpages.ubuntu.com/manpages/noble/en/man1/s3fs.1.html
  const mountOptions = 'allow_other,endpoint=us-east-1'
  await sandbox.commands.run(`sudo s3fs ${AWS_BUCKET_NAME} ${MOUNT_DIRECTORY} -o ${mountOptions}`)

  // Validate mount functionality with write operation
  await sandbox.files.write(`${MOUNT_DIRECTORY}/test-file.txt`, 'test-file-content')

  // Verify mount integrity through read operation
  const content = await sandbox.files.read(`${MOUNT_DIRECTORY}/test-file.txt`)
  console.log(content)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  import os
  from novita_sandbox.core import Sandbox

  TEMPLATE_ID = os.environ.get("NOVITA_TEMPLATE_ID")
  AWS_ACCESS_KEY_ID = os.environ.get("AWS_ACCESS_KEY_ID")
  AWS_SECRET_ACCESS_KEY = os.environ.get("AWS_SECRET_ACCESS_KEY")
  AWS_BUCKET_NAME = os.environ.get("AWS_BUCKET_NAME")
  if not TEMPLATE_ID or not AWS_ACCESS_KEY_ID or not AWS_SECRET_ACCESS_KEY or not AWS_BUCKET_NAME:
      raise ValueError("Required environment variables not configured: NOVITA_TEMPLATE_ID, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_BUCKET_NAME")

  MOUNT_DIRECTORY = "/mnt/s3-bucket"

  sandbox = Sandbox.create(TEMPLATE_ID)

  # Initialize mount point directory structure
  sandbox.files.make_dir(MOUNT_DIRECTORY)

  # Configure s3fs credentials using standard credential file location
  # s3fs-fuse reads AWS credentials from /root/.passwd-s3fs by default
  # Custom credential paths require explicit specification via -o passwd_file parameter
  sandbox.files.write("/root/.passwd-s3fs", f"{AWS_ACCESS_KEY_ID}:{AWS_SECRET_ACCESS_KEY}")

  # Enforce secure credential file permissions (owner read-only)
  sandbox.commands.run("sudo chmod 600 /root/.passwd-s3fs")

  # Execute S3 bucket mount operation with optimized parameters
  # Configuration parameters:
  # - allow_other: Enable cross-user filesystem access
  # - endpoint: Specify AWS regional endpoint for optimal latency
  # Reference: https://manpages.ubuntu.com/manpages/noble/en/man1/s3fs.1.html
  mount_options = "allow_other,endpoint=cn-north-1"
  sandbox.commands.run(f"sudo s3fs {AWS_BUCKET_NAME} {MOUNT_DIRECTORY} -o {mount_options}")

  # Validate mount functionality with write operation
  write_result = sandbox.files.write(f"{MOUNT_DIRECTORY}/test-file.txt", "test-file-content")

  # Verify mount integrity through read operation
  content = sandbox.files.read(f"{MOUNT_DIRECTORY}/test-file.txt")
  print("File content:", content)

  sandbox.kill()
  ```
</CodeGroup>


# Overview
Source: https://novita.ai/docs/guides/sandbox-overview



**Agent Sandbox** is a next-generation runtime infrastructure specifically designed for AI Agents, providing a secure and isolated cloud sandbox environment for executing AI-generated code.

## Features

* **Secure**. Sandboxes have system-level isolation capabilities, ensuring the security of data and execution environment within the sandbox.
* **Fast startup**. Startup time is less than 200ms, with support for large-scale concurrent creation, suitable for AI application scenarios with high concurrency requirements.
* **Multi-language execution support**. Supports running code in multiple programming languages including Python, JavaScript, TypeScript, C++, and more.
* **[Quick pause and resume](/guides/sandbox-persistence)**. Pause the sandbox at any time and resume when needed, with filesystem and process state fully restored.
* **[Background execution](/guides/sandbox-commands-background)**. Supports background task execution and suitable for scenarios that require waiting for results.
* **Easy integration**. Seamlessly integrates with popular AI Agent frameworks and tools.

## Scenarios

* AI data analysis and visualization;
* Code execution environment for Code Agents;
* Computer Use Agent.

Contact our <Link href="https://meet.brevo.com/novita-ai/contact-sales">solution engineers</Link> to learn how to integrate Agent Sandbox into your business.

## Pricing

Agent Sandbox provides per-second billing for CPU and RAM. Storage — encompassing templates, sandbox snapshots, and template snapshots — is now subject to daily charges. See the [pricing page](/guides/sandbox-pricing) for more details.

## Getting Started

You can start and manage your Agent Sandboxes through SDK or CLI. For details, please refer to [quick start page](/guides/sandbox-your-first-agent-sandbox).


# Sandbox Persistence
Source: https://novita.ai/docs/guides/sandbox-persistence



The sandbox persistence allows you to pause your sandbox and resume it later from the same state it was in when you paused it.

This includes not only state of the sandbox's filesystem but also the sandbox's memory. This means all running processes, loaded variables, data, etc.

<SandboxConfigHint />

<Warning>
  Please note:

  * It takes about 4 seconds per 1 GB RAM to pause the sandbox.
  * It takes about 1 second to resume the sandbox.
  * Sandbox can be used up to 30 days.\
    After 30 days from the initial sandbox create call, the data may be deleted and you will not be able to resume it. Attempting to resume a sandbox that was deleted or does not exist will result in the NotFoundError in the JavaScript SDK or the NotFoundException in the Python SDK.
</Warning>

## Pausing sandbox

When you pause a sandbox, both the sandbox's <Link href="/guides/sandbox-filesystem">filesystem</Link> and memory state will be saved. This includes all the files in the sandbox's filesystem and all the running processes, loaded variables, data, etc.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()
  console.log('Sandbox created', sandbox.sandboxId)

  // Pause the sandbox.
  // You can save the sandbox ID in your database
  // to resume the sandbox later
  const result = await sandbox.betaPause()
  console.log('Sandbox paused', sandbox.sandboxId, result)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()
  print('Sandbox created', sandbox.sandbox_id)

  # You can save the sandbox ID in your database
  # to resume the sandbox later
  sandbox.beta_pause()
  print('Sandbox paused', sandbox.sandbox_id)

  sandbox.kill()
  ```
</CodeGroup>

## Resuming sandbox

When you resume a sandbox, it will be in the same state it was in when you paused it.
This means that all the files in the sandbox's filesystem will be restored and all the running processes, loaded variables, data, etc. will be restored.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()
  console.log('Sandbox created', sandbox.sandboxId)

  // Pause the sandbox.
  // You can save the sandbox ID in your database
  // to resume the sandbox later
  const result = await sandbox.betaPause()
  console.log('Sandbox paused', sandbox.sandboxId, result)

  // Resume the sandbox from the same state.
  const resumedSandbox = await sandbox.connect()
  console.log('Sandbox resumed', resumedSandbox.sandboxId)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()
  print('Sandbox created', sandbox.sandbox_id)

  # Pause the sandbox.
  # You can save the sandbox ID in your database
  # to resume the sandbox later
  sandbox.beta_pause()
  print('Sandbox paused', sandbox.sandbox_id)

  # Resume the sandbox from the same state.
  connectedSandbox = sandbox.connect()
  print('Sandbox resumed', connectedSandbox.sandbox_id)

  sandbox.kill()
  ```
</CodeGroup>

## Listing paused sandboxes

You can list all paused sandboxes by calling the `Sandbox.list` method and supplying the `state` query parameter.
More information about using the method can be found in [List Sandboxes](/guides/sandbox-list).

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox, SandboxInfo } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()

  // List all paused sandboxes.
  const paginator = Sandbox.list({ query: { state: ['paused'] } })

  // Get all paused sandboxes.
  const sandboxes: SandboxInfo[] = []
  while (paginator.hasNext) {
    const items = await paginator.nextItems()
    sandboxes.push(...items)
  }

  console.log('all paused sandboxes', sandboxes)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox, SandboxQuery, SandboxState, SandboxInfo

  sandbox = Sandbox.create()

  sandbox.beta_pause()
  print('Sandbox paused', sandbox.sandbox_id)

  # List all paused sandboxes.
  paginator = Sandbox.list(query=SandboxQuery(state=[SandboxState.PAUSED]))

  # Get all paused sandboxes.
  sandboxes: list[SandboxInfo] = []
  while paginator.has_next:
    items = paginator.next_items()
    sandboxes.extend(items)

  print('all paused sandboxes', sandboxes)

  sandbox.kill()
  ```
</CodeGroup>

## Removing paused sandboxes

You can remove paused sandboxes by calling the `kill` method on the sandbox instance.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()
  console.log('Sandbox created', sandbox.sandboxId)

  // Pause the sandbox.
  await sandbox.betaPause()

  // Kill the paused sandbox.
  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()

  # Pause the sandbox.
  sandbox.beta_pause()

  # Kill the paused sandbox.
  sandbox.kill()
  ```
</CodeGroup>

## Sandbox's timeout

When you resume a sandbox, the sandbox's timeout is reset to the default timeout of a sandbox - 5 minutes.

You can pass a custom timeout to the `Sandbox.connect()` method like this:

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()

  const connectedSandbox = await Sandbox.connect(sandbox.sandboxId, { timeoutMs: 60 * 1000 })
  console.log('Sandbox connected', connectedSandbox.sandboxId)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()

  connectedSandbox = Sandbox.connect(sandbox.sandbox_id, timeout=60) # 60 seconds
  print('Sandbox connected', connectedSandbox.sandbox_id)

  sandbox.kill()
  ```
</CodeGroup>

## Network

If you have a service (for example a server) running inside your sandbox and you pause the sandbox, the service won't be accessible from the outside and all the clients will be disconnected.
If you resume the sandbox, the service will be accessible again but you need to connect clients again.


# Pricing
Source: https://novita.ai/docs/guides/sandbox-pricing



Agent Sandbox supports independent billing for CPU and RAM (memory) by the second, with on-demand usage and flexible billing.

## Billing Items

<table>
  <thead>
    <tr>
      <th>Billing Item</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>CPU</td>
      <td>Billed based on the number of vCPU cores used and usage duration (accurate to the second). Current pricing can be found on the [here](https://novita.ai/pricing?sandbox=1). No billing occurs after the Sandbox is stopped.</td>
    </tr>

    <tr>
      <td>RAM (memory)</td>
      <td>Billed based on allocated memory capacity and usage duration (accurate to the second). Current pricing can be found on the [here](https://novita.ai/pricing?sandbox=1). No billing occurs after the Sandbox is stopped.</td>
    </tr>

    <tr>
      <td><Link href="/guides/sandbox-filesystem">Storage</Link></td>
      <td>Current pricing can be found on the [here](https://novita.ai/pricing?sandbox=1).</td>
    </tr>

    <tr>
      <td><Link href="/guides/sandbox-template">Templates</Link></td>
      <td>Currently free.</td>
    </tr>
  </tbody>
</table>

## Pricing

* **CPU**

<table>
  <thead>
    <tr>
      <th>vCPUs (cores)</th>
      <th>Unit Price</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>1</td>
      <td>\$0.0000098/s</td>
    </tr>

    <tr>
      <td>2</td>
      <td>\$0.0000196/s</td>
    </tr>

    <tr>
      <td>3</td>
      <td>\$0.0000294/s</td>
    </tr>

    <tr>
      <td>4</td>
      <td>\$0.0000392/s</td>
    </tr>

    <tr>
      <td>5</td>
      <td>\$0.000049/s</td>
    </tr>

    <tr>
      <td>6</td>
      <td>\$0.0000588/s</td>
    </tr>

    <tr>
      <td>7</td>
      <td>\$0.0000686/s</td>
    </tr>

    <tr>
      <td>8</td>
      <td>\$0.0000784/s</td>
    </tr>
  </tbody>
</table>

* **RAM (memory)**

<table>
  <thead>
    <tr>
      <th>Memory (MiB)</th>
      <th>Unit Price</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Valid values: multiples of 512 MiB, from 512 MiB to 8192 MiB</td>
      <td>\$0.0000032/GiB/s</td>
    </tr>

    <tr>
      <td>512 MiB</td>
      <td>\$0.0000016/s</td>
    </tr>

    <tr>
      <td>1 GiB</td>
      <td>\$0.0000032/s</td>
    </tr>

    <tr>
      <td>2 GiB</td>
      <td>\$0.0000064/s</td>
    </tr>
  </tbody>
</table>

* **Storage**

<table>
  <thead>
    <tr>
      <th>Memory (MiB)</th>
      <th>Unit Price</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Each account includes 60 GB of free storage. Usage beyond this limit is billed on a pay-as-you-go basis.</td>
      <td>\$0.00009/GB/h</td>
    </tr>
  </tbody>
</table>

## Get Bills

You can view and export Agent Sandbox bills in <u>"Billing - Billing Details - Usage-based Billing"</u>.

* Go to the <Link href="https://novita.ai/billing/details">billing details page</Link>;
* Select the "Usage-based Billing" tab on the right, then click the "Agent Sandbox" secondary tab below;
* You can set the "Time Range" and "Group By" filters;
* You can click "Export" button after querying to export bill data as an .xlsx file.

## Overdue Payment Notice

If the account's available balance (including available balance and voucher balance) is less than the bill to be paid, the account is considered overdue. Overdue payments will result in sandboxes being terminated and data loss, affecting your service. During usage, please ensure sufficient account balance. After overdue, the system will send relevant notification emails, please recharge promptly.

You can confirm account balance and vouchers on the <Link href="https://novita.ai/billing">payments</Link> page, recharge as needed.

<Warning>
  To avoid overdue payments affecting your service, it is recommended that you set up <Link href="https://novita.ai/billing/balance-warning">low balance alerts</Link>. When your account balance is less than the alert threshold you set, an notification email will be sent.
</Warning>

The specific **overdue payment impacts** are as follows:

* Unable to start new sandboxes.
* Running sandboxes will be terminated.


# Quota Limit
Source: https://novita.ai/docs/guides/sandbox-quota-limit



Currently, each user allows to create a maximum of **<u>100</u>** concurrent sandboxes by default. The quota can be adjusted based on your requirements after our evaluation.

If you need a higher quota, please <Link href="https://meet.brevo.com/novita-ai/contact-sales">contact our support team</Link>.

## Agent Sandbox CPU and Memory Ratio Restrictions

When creating an Agent sandbox template, the system enforces constraints on the ratio between **CPU** and **memory**. These restrictions are designed to ensure the stability and resource efficiency of Agent sandboxes, and to avoid operational issues caused by unreasonable resource allocation.

### CPU Restrictions

* Supported CPU specification range: **1‒8 vCPU**
* Only integer values for CPU count are supported, such as: `1`, `2`, `4`, `8 vCPU`

### Memory Restrictions

* Maximum memory limit: **8192 MiB (8 GiB)**
* Memory must be an integer multiple of **512 MiB**, e.g.: `512 MiB`, `1024 MiB`, `2048 MiB`, etc.

### Ratio Rules

| Item          | Restriction Requirement | Description                                                                   |
| :------------ | :---------------------- | :---------------------------------------------------------------------------- |
| Minimum Ratio | 1:0.5 (CPU:Memory)      | Each 1 vCPU requires at least: 0.5 × 1024 = **512 MiB** memory                |
| Maximum Ratio | 1:4 (CPU:Memory)        | Each 1 vCPU can allocate up to: 4 × 1024 = **4096 MiB** memory                |
| Memory Step   | 512 MiB increments      | Memory must be a multiple of 512 MiB, e.g.: 512 MiB, 1024 MiB, 1536 MiB, etc. |

### Example Overview

| CPU Spec | Minimum Memory   | Maximum Value by Ratio | Actual Maximum Selectable |
| :------- | :--------------- | :--------------------- | :------------------------ |
| 1 vCPU   | 512 MiB          | 4096 MiB (4 GiB)       | 4096 MiB (4 GiB)          |
| 2 vCPU   | 1024 MiB (1 GiB) | 8192 MiB (8 GiB)       | 8192 MiB (8 GiB)          |
| 4 vCPU   | 2048 MiB (2 GiB) | 16384 MiB (16 GiB)     | 8192 MiB (8 GiB)          |
| 8 vCPU   | 4096 MiB (4 GiB) | 32768 MiB (32 GiB)     | 8192 MiB (8 GiB)          |

### Notes

* The above rules are only effective **when creating the <Link href="/guides/sandbox-template">sandbox template</Link>**. Sandboxes launched from this template will inherit its specifications.
* The memory upper limit is **8192 MiB (8 GiB)** by default; even if the calculated ratio exceeds this value, the actual selectable memory cannot surpass this limit.
* If the configuration is out of range, the system will prompt an error and the user needs to select again.
* It is recommended to reasonably choose the CPU to memory ratio according to your workload, to avoid OOM (out-of-memory) errors due to insufficient resources or wasting resources due to overallocation.


# Installing SDKs & CLI
Source: https://novita.ai/docs/guides/sandbox-sdk-and-cli



Novita Agent Sandbox provides official stable SDKs (currently supporting Python and JavaScript & TypeScript) as well as accompanying command-line tools to help you easily integrate sandbox capabilities into your business. Below are the installation methods for these components.

## Install Stable SDK

<CodeGroup>
  ```bash JavaScript & TypeScript icon="terminal" theme={"system"}
  npm i novita-sandbox
  ```

  ```bash Python icon="terminal" theme={"system"}
  pip install novita-sandbox
  ```
</CodeGroup>

## Install Stable CLI

<CodeGroup>
  ```bash Bash icon="terminal" theme={"system"}
  npm i -g novita-sandbox-cli
  ```
</CodeGroup>

Additionally, some new advanced features will be first released in the **Beta** versions of the SDK and CLI tools, which you can install using the following methods. After thorough validation, the Beta versions of the SDK and CLI tools will be regularly synchronized and updated to the stable version. If you encounter any issues during use, please feel free to <Link href="https://meetings-na2.hubspot.com/junyu">contact us</Link>.

## Install Beta SDK

<CodeGroup>
  ```bash JavaScript & TypeScript icon="terminal" theme={"system"}
  npm i novita-sandbox@beta
  ```

  ```bash Python icon="terminal" theme={"system"}
  pip install --pre novita-sandbox
  ```
</CodeGroup>

## Install Beta CLI

<CodeGroup>
  ```bash Bash icon="terminal" theme={"system"}
  npm i -g novita-sandbox-cli@beta
  ```
</CodeGroup>


# Sandbox Templates
Source: https://novita.ai/docs/guides/sandbox-template



Sandbox templates allow you to customize the sandbox environment to your needs.

<Tip>
  Novita Agent Sandbox service has built-in public templates for out-of-the-box use. You can find these public templates in the <Link href="https://novita.ai/sandbox-console/template">console</Link>.
</Tip>

<SandboxCliConfigHint />

To create a sandbox template, you specify the `novita.Dockerfile`. We then take this Dockerfile and create a new sandbox template from it and give you back a template ID.

You can then use this template ID to create a new sandbox with the SDK based on the template you created.

## How to create custom sandbox

**Steps**

1. [Install CLI](#1-install-cli)
2. [Initialize sandbox template](#2-initialize-sandbox-template)
3. [Customize `novita.Dockerfile`](#3-customize-novita-dockerfile)
4. [Build your sandbox template](#4-build-your-sandbox-template)
5. [Start your custom sandbox](#5-start-your-custom-sandbox)

### 1. Install CLI

Please refer to the <Link href="/guides/sandbox-cli">tutorial</Link> for installation and complete <Link href="/guides/sandbox-cli-auth">authentication</Link>.

### 2. Initialize sandbox template

The following command will create a basic `novita.Dockerfile` in the current directory.

<CodeGroup>
  ```bash Bash icon="terminal" theme={"system"}
  novita-sandbox-cli template init
  ```
</CodeGroup>

### 3. Customize `novita.Dockerfile`

Now you can customize your sandbox template by editing the `novita.Dockerfile` file.

<CodeGroup title="novita.Dockerfile">
  ```dockerfile novita.Dockerfile icon="docker" theme={"system"}
  # Make sure to use this base image
  FROM novitalabs/code-interpreter:latest

  # Install some Python packages
  RUN pip install cowsay
  ```
</CodeGroup>

### 4. Build your sandbox template

Now you can build your sandbox template. We'll use Docker and the CLI.
What is going to happen is that CLI will call Docker to build the image and then push it to the Novita cloud.
Then we convert the Docker image to a micro VM that can be then launched as a sandbox with our SDK.

<CodeGroup>
  ```bash Bash icon="terminal" theme={"system"}
  novita-sandbox-cli template build -c "/root/.jupyter/start-up.sh"
  ```
</CodeGroup>

This process will take a moment. In the end, you'll see your template ID that you'll need to use to create a sandbox with the SDK.

### 5. Start your custom sandbox

Now you can use the template ID to create a sandbox with the SDK.

<SandboxConfigHint />

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  // Your template ID from the previous step
  const templateID = 'id-of-your-template'

  // Pass the template ID to the `Sandbox.create` method
  const sandbox = await Sandbox.create(templateID)

  // The template installed cowsay, so we can use it
  const result = await sandbox.runCode(`
  import cowsay
  cowsay.say('Hello!')`)

  console.log(result)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  # Your template ID from the previous step
  template_id = 'id-of-your-template'

  # Pass the template ID to the `Sandbox.create` method
  sandbox = Sandbox.create(template_id)

  # The template installed cowsay, so we can use it
  result = sandbox.run_code("""
  import cowsay
  cowsay.say('Hello!')""")

  print(result)

  sandbox.kill()
  ```
</CodeGroup>

## How it works

Every time you are building a sandbox template, we create a container based on the `novita.Dockerfile` file you create in the process.
We extract the container's filesystem, do provisioning and configuration (e.g. installing required dependencies), and start a sandbox.

Then, these steps happen:

1. We take the running sandbox.
2. (Only if you specified the [start command](/guides/sandbox-template-start-cmd), otherwise this step is skipped) Execute the start command.
3. Wait for readiness (by default 20 seconds if start command is specified, otherwise immediately ready). Readiness check can be configured using [ready command](/guides/sandbox-template-ready-cmd).
4. Snapshot the sandbox and make it ready for you to spawn it with the SDK.

We call this sandbox snapshot a *sandbox template*.

<Note title="Sandbox Snapshot">
  Snapshots are saved running sandboxes. We serialize and save the whole sandbox's filesystem together with all the running processes in a way that can be loaded later.

  This allows us to load the sandbox in a few hundred milliseconds any time later with all the processes already running and the filesystem exactly as it was.
</Note>


# Customize sandbox CPU & RAM
Source: https://novita.ai/docs/guides/sandbox-template-customize-cpu-ram



You can customize the CPU and RAM of your sandbox template via CLI.

<SandboxCliConfigHint />

You need to create a <Link href="/guides/sandbox-template">sandbox template</Link> first.

During the build step, you can specify the CPU and RAM of your sandbox template.

The following command will create a sandbox template with 2 vCPUs and 2GB RAM.

```bash Bash icon="terminal" theme={"system"}
novita-sandbox-cli template build -c "/root/.jupyter/start-up.sh" --cpu-count 2 --memory-mb 2048
```

## Through Configuration File

You can also specify the vCPU and RAM specifications for the sandbox template in the `novita.toml` file in the same directory where you run the `novita-sandbox-cli template build` command.

```toml Toml icon="gear" theme={"system"}
template_id = "0r0efkbfwzfp9p7qpc1c"
dockerfile = "novita.Dockerfile"
template_name = "my-agent-sandbox"
ready_cmd = "<your-ready-command>"
# Specify sandbox template vCPU and RAM specifications as 2 vCPUs and 2GB RAM
cpu_count = 2
memory_mb = 2_048
```


# Start Command
Source: https://novita.ai/docs/guides/sandbox-template-start-cmd



The start command allows you to specify a command that will be **already running** when you spawn your custom sandbox.
This way, you can for example have running servers or seeded databases inside the sandbox that are already fully ready when you spawn the sandbox using the SDK and with zero waiting time for your users during the runtime.

The idea behind the start command feature is to lower the wait times for your users and have everything ready for your users when you spawn your sandbox.

You can see how it works [here](/guides/sandbox-template#how-it-works).

<SandboxCliConfigHint />

## How to add start command

When you are building a sandbox template you can specify the start command by using the `-c` option:

```bash Bash icon="terminal" theme={"system"}
novita-sandbox-cli template build -c "<your-start-command>"
```

When you spawn the custom sandbox you built, the start command will be already running if there was no error when we tried to execute it.

### Sandbox template config

You can specify the start command also inside the `novita.toml` in the same directory where you run `novita-sandbox-cli template build`.

```toml Toml icon="gear" theme={"system"}
template_id = "0r0efkbfwzfp9p7qpc1c"
dockerfile = "novita.Dockerfile"
template_name = "my-agent-sandbox"
start_cmd = "<your-start-command>"
```

## Logs

You can retrieve the start command's logs using the CLI during runtime.

<Note>
  These logs are the logs from the start command during the build phase.
</Note>

<SandboxConfigHint />

```bash Bash icon="terminal" theme={"system"}
novita-sandbox-cli sandbox logs <sandbox-id>
```


# Version Management
Source: https://novita.ai/docs/guides/sandbox-template-version-management



<SandboxBetaVersionWarning />

For the same sandbox template, each time it is built, the system will add a new version number (buildID), and the sandbox template will use the latest built version by default. In some scenarios, if you find that a newly built version has errors and need to rollback to a previous version, you can use the Novita Sandbox CLI to manage the versions of the sandbox template.

## View All Versions of a Sandbox Template

```bash Bash icon="terminal" theme={"system"}
# novita-sandbox-cli template version [templateID]
novita-sandbox-cli tpl version lovhlhmzeq6q0yh3lu9a
# Example output:
# Sandbox template versions
# Build ID Is Default Build  RAM MiB  VCPUs  Start  Cmd  Status    Created At             Finished At
# f15e442a-a825-4881-9bd8-ad70a96af372  true              1024     2      /root/.jupyter/start-up.sh  Uploaded  8/25/2025, 5:53:04 PM  8/25/2025, 5:55:43 PM
# f9e12c5a-8934-4b13-b574-2f7c211adba1  false             1024     2                                  Uploaded  8/25/2025, 4:52:30 PM  8/25/2025, 4:56:43 PM
```

## Rollback to a Specific Version

```bash Bash icon="terminal" theme={"system"}
# novita-sandbox-cli template version [templateID] -r [buildID]
novita-sandbox-cli tpl version lovhlhmzeq6q0yh3lu9a -r f9e12c5a-8934-4b13-b574-2f7c211adba1
```


# Create Your First Agent Sandbox
Source: https://novita.ai/docs/guides/sandbox-your-first-agent-sandbox



## Create an Account

If you don't have a Novita account, you need to <Link href="https://novita.ai/user/register">sign up</Link> first. For details, please refer to <Link href="/guides/quickstart">Quickstart guide</Link>.

## Create API Key

Go to the Novita <Link href="https://novita.ai/settings/key-management">Key Management page</Link>, you can create an API key and save the API key value for use in subsequent steps.

## Install SDK

You can install the SDK by executing the following commands.

<CodeGroup>
  ```bash JavaScript & TypeScript SDK icon="terminal" theme={"system"}
  npm i novita-sandbox
  ```

  ```bash Python SDK icon="terminal" theme={"system"}
  pip install novita-sandbox
  ```
</CodeGroup>

## Configure Environment Variables

Create a `.env` file in your project folder (if it doesn't exist), and configure the API key and API domain address.

<Warning>
  For JavaScript and TypeScript projects, you need to import the `dotenv/config` package in your project; for Python projects, you need to import the `dotenv` library in your project and call the `load_dotenv` method to load environment variables.
  For details, please refer to the [example](#use-sdk-to-start-agent-sandbox).
</Warning>

```bash .env icon="terminal" highlight={2} theme={"system"}
NOVITA_API_KEY=sk_*** # Novita API key obtained from previous steps
```

Or you can configure the API key and API domain address by setting environment variables in your terminal.

```bash Bash icon="terminal" highlight={2} theme={"system"}
export NOVITA_API_KEY=sk_*** # Novita API key obtained from previous steps
```

## Use SDK to Start Agent Sandbox

Below is a simple example showing how to create a sandbox through the SDK and run specified commands.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  // index.ts
  import 'dotenv/config'
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  // The .env file should be located in the project root directory
  // dotenv/config will automatically look for .env in the current working directory
  // Or 
  // You can set the environment variable in the command line
  // export NOVITA_API_KEY=sk_***

  const sandbox = await Sandbox.create()
  const execution = await sandbox.runCode('print("hello world")')
  console.log(execution.logs)

  const files = await sandbox.files.list('/tmp')
  console.log(files)

  // Close sandbox when no longer needed
  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  # main.py
  from dotenv import load_dotenv
  from novita_sandbox.code_interpreter import Sandbox


  # The .env file should be located in the project root directory
  # dotenv will automatically look for .env in the current working directory
  load_dotenv()

  # Or 
  # You can set the environment variable in the command line
  # export NOVITA_API_KEY=sk_***

  sandbox = Sandbox.create()
  execution = sandbox.run_code("print('hello world')")
  print(execution.logs)

  files = sandbox.files.list("/")
  print(files)

  # Close sandbox when no longer needed
  sandbox.kill()
  ```
</CodeGroup>

Execute the following commands to run the above code.

<CodeGroup>
  ```bash index.ts icon="terminal" theme={"system"}
  npx tsx ./index.ts
  ```

  ```bash main.py icon="terminal" theme={"system"}
  python main.py
  ```
</CodeGroup>


# Overview
Source: https://novita.ai/docs/guides/serverless-gpus-overview



The GPU elastic container product designed specifically for **AI inference**. You only need to specify the container image address and make slight configurations according to your business scenarios to quickly deploy an AI inference service.

## Features

* With the capability of **elastic scaling**, it automatically scales up during peak business traffic and scales down during low traffic periods, ensuring service stability while saving costs as much as possible;
* Built-in efficient **load balancing** ensures that request loads are evenly distributed to each GPU container instance;
* Billing is **accurate to the second**, charging only for the actual running time of the GPU container instances;
* Through technologies such as GPU container instance reservation, image preheating, and high-performance hardware, it can achieve **second-level cold-start**, easily handling traffic peaks;
* Complete **log panel** supports querying real-time log streams, helping you quickly identify and resolve potential issues.

## Terminology

* **Container Image Address**: Refers to the Docker container image address, currently supporting **"public image"** and **"private image"**.
* **Serverless Endpoint**: Represents a GPU elastic container instance. It includes components such as **worker**, **load balancer**, and **elastic scaler**.
* **Worker**: A GPU container instance used by the serverless endpoint to handle specific requests. One Worker corresponds to one GPU container instance.
* **Scale Policy**: Used to control the logic of automatically scaling up during traffic peaks and scaling down during low traffic periods.
* **Health Check Path**: The built-in load balancer performs health checks through this path, determining whether to forward requests to the Worker based on whether the returned status code is `200`.


# Serverless Pricing
Source: https://novita.ai/docs/guides/serverless-gpus-pricing



## Pricing Items

* **Computing Resources**: On-Demand. For Serverless, you pay for the actual computing resources consumed; no charge is incurred for unused resources.
* **Container Disk**: On-Demand. A certain amount of free capacity is supported. Charges will apply to any usage beyond the free allowance, based on capacity and duration.
* **Volume Disk**: On-Demand. A certain amount of free capacity is supported. Charges will apply to any usage beyond the free allowance, based on capacity and duration.
* **Network Volume**: On-Demand. Charged separately based on capacity and duration of use.

## Pricing Method

Charges are calculated based on the GPU specifications configured when creating the Serverless Endpoint, according to the runtime duration of the Workers.

**The billing formula is as follows:**

<u>Serverless Endpoint Cost</u> = Total cost generated by all Workers running on that Endpoint;

<u>Worker Cost</u> = Worker Running Duration (time in running state, in seconds) \* Worker Unit Price (in \$/second).

### Details

* The Worker unit price is determined by the GPU specifications assigned to that Worker. And you can check the pricing on the <a href="https://novita.ai/gpus-console/serverless">Serverless GPUs Console</a>.

<Frame>
  <img />
</Frame>

* If a Worker is configured with multiple GPUs, the unit price of that Worker will change; the final unit price on the configuration page shall prevail.

<Frame>
  <img />
</Frame>

* Also, after creating a Serverless Endpoint, the actual pricing can be checked on the Serverless Endpoint management page.

<Frame>
  <img />
</Frame>

## Account Delinquency Policy

### Handling of Delinquent Accounts

After your account becomes delinquent (insufficient credits in both account balance and vouchers), the platform will send you notifications and suspend the services. The specific impacts are as follows:

* Creation of new Serverless Endpoints is not supported;
* Only "viewing" or "deleting" of existing Serverless Endpoints is supported, modifications are not allowed, wherein:
  * Workers in running state will no longer accept new requests, but Workers currently processing requests will continue to run until all existing requests are completed;
  * Running Workers will be automatically released after processing existing requests;
  * Eventually, the number of Workers in the Serverless Endpoint will scale down to 0, and no new Workers will be created.

### Service Restoration

When your account returns to a non-delinquent status, existing Serverless Endpoints will automatically scale up according to their configurations and resume service.


# Create Async Serverless Endpoint
Source: https://novita.ai/docs/guides/serverless-gpus-quickstart-create-async-endpoint



If you don't have a Novita account, you need to <Link href="https://novita.ai/user/register">sign up</Link> first. For details, please refer to <Link href="/guides/quickstart">Quickstart guide</Link>.

This article uses the deployment of **runpod/worker-comfyui:5.5.0-flux1-dev** as an example to demonstrate how to create an Async Serverless Endpoint.

## 1. Prepare Container Image

You need to package your runtime environment into a Docker image and upload it to an image repository in advance. Both public and private image repositories are supported (credentials required for private repositories).

* You can upload your image to Docker Hub. The platform currently provides an [image warm-up service](https://novita.ai/gpus-console/image) for this site.

This example uses the `runpod/worker-comfyui:5.5.0-flux1-dev` model image. When using the worker-comfyui image, please configure S3-related settings such as BUCKET\_ENDPOINT\_URL. These settings ensure that images and videos generated by the async serverless endpoint are uploaded to your S3 bucket.

## 2. Select Instance Specification

Currently, Async Serverless Endpoint supports the following GPU instance types:

* RTX 4090 24GB
* H100 SXM 80GB

For additional requirements, please [contact us](mailto:support@novita.ai).

## 3. Create Cloud Storage (Optional)

If you need shared or persistent storage, you can create cloud storage on the [storage management page](https://novita.ai/gpus-console/storage), and mount this storage when creating an instance. For more details, see [Manage Cloud Storage](https://novita.ai/docs/guides/gpu-instance-quickstart-manage-network-volume).

## 4. Create Endpoint

1. Go to the [Async Serverless GPUs](https://novita.ai/gpus-console/serverless) page, choose an instance type, and click "Create Endpoint".
2. Complete the Endpoint parameter configuration:

* **Endpoint Name**: Used to uniquely identify the endpoint; it will be part of the URL when creating jobs. The system will generate a random default name; you may customize it but using the default name is recommended.
* **Worker Configuration**

<table>
  <thead>
    <tr>
      <th>Configuration Item</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Min Worker Count</td>
      <td>The minimum number of worker instances to keep for the endpoint. Setting a higher minimum helps reduce cold start time. If set to 0, there will be no idle workers when there are no requests, which may increase response time for incoming requests. For latency-sensitive scenarios, use 0 with caution.</td>
    </tr>

    <tr>
      <td>Max Worker Count</td>
      <td>The maximum number of worker instances that the endpoint can scale up to. When request volume increases, the platform automatically increases workers up to this maximum. This limit helps control costs.</td>
    </tr>

    <tr>
      <td>Idle Timeout (seconds)</td>
      <td>When a worker is about to be released due to autoscaling down, the platform will keep the worker alive for the specified idle timeout period to be able to react quickly to new requests. Note that you will be charged for the worker during this period.</td>
    </tr>

    <tr>
      <td>Max Concurrent Requests</td>
      <td>The maximum number of concurrent requests handled by a single worker. If this is exceeded, requests will be routed to other workers. If all workers are fully occupied, excess requests will be queued until execution is possible.</td>
    </tr>

    <tr>
      <td>GPUs / Worker</td>
      <td>Number of GPU cards allocated to each worker.</td>
    </tr>

    <tr>
      <td>CUDA Version</td>
      <td>Specify the CUDA version supported for the worker.</td>
    </tr>
  </tbody>
</table>

* **Type**:
  * Select the Endpoint type: choose Async (asynchronous).
* **Elastic Policy**:
  * Queue request policy: The number of Workers is automatically scaled according to the number of queued requests. By default, each Worker can only process one job at a time. You need to specify the maximum number of requests supported by each Worker.
* **Image Configuration**:
  * Image address: The address of the image to deploy, e.g., `runpod/worker-comfyui:5.5.0-flux1-dev`.
  * Image repository credentials: If using a private image, provide access credentials so the image can be pulled. You can create credentials at the [security credentials management page](https://novita.ai/gpu-instance/console/settings).
  * HTTP Port: The HTTP port to expose on the Worker.
  * Container start command: The command to run when the container starts.
* **Storage Configuration**:
  * System disk: System disk size per Worker instance.
  * Cloud storage: Select your cloud storage if you wish to mount it. For details, see [Manage Cloud Storage](https://novita.ai/docs/guides/gpu-instance-quickstart-manage-network-volume).
* **Other**:

  * Health check path: This parameter is currently not enabled.
  * Environment variables: Set necessary environment variables for the service. These will be initialized automatically when the Worker starts. For example:
    * `BUCKET_ENDPOINT_URL=https://<your-bucket-name>s3.<aws-region>.amazonaws.com`
    * `BUCKET_ACCESS_KEY_ID=AKIASVYYYN6L4S6TTTTTT`
    * `BUCKET_SECRET_ACCESS_KEY=maVz2OwY98UUUUUUGjMsmR/Yo8/Zzw0qWMMMMMMM`

  When using the worker-comfyui image, **it is highly recommended to configure S3 BUCKET settings so that the output images are uploaded to S3**.

3. Review pricing, then click "Deploy with One Click".

## 5. Access the Service

1. In [Async Serverless GPUs](https://novita.ai/gpus-console/serverless), find the newly created Endpoint and ensure its status is "Running".
2. Ensure that at least one Worker in the Endpoint is running.
3. Ensure you have the corresponding api key for authentication. The Endpoint creator and the api key owner must belong to the same team.

### 5.1 Create a Job and Retrieve Output via Curl

Below is an example showing an actual use of the worker-comfyui worker . Replace `0f43a6867e05fddd` in the URL with your real endpointName, and replace `sk_xxxx` in the example with your actual user api key.

<Note>
  The maximum job size accepted by Async Serverless Endpoint is 4 MiB.
</Note>

```bash theme={"system"}
curl -X POST https://async.novita.ai/v1/0f43a6867e05fddd/run \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_xxxx' \
  -d '{
    "input": {
        "workflow": {
            "8": {
                "inputs": {
                    "samples": [
                        "31",
                        0
                    ],
                    "vae": [
                        "39",
                        0
                    ]
                },
                "class_type": "VAEDecode",
                "_meta": {
                    "title": "VAE Decode"
                }
            },
            "9": {
                "inputs": {
                    "filename_prefix": "ComfyUI",
                    "images": [
                        "8",
                        0
                    ]
                },
                "class_type": "SaveImage",
                "_meta": {
                    "title": "Save Image"
                }
            },
            "27": {
                "inputs": {
                    "width": 1024,
                    "height": 1024,
                    "batch_size": 1
                },
                "class_type": "EmptySD3LatentImage",
                "_meta": {
                    "title": "Empty Latent Image (SD3)"
                }
            },
            "31": {
                "inputs": {
                    "seed": 890266796055272,
                    "steps": 20,
                    "cfg": 1,
                    "sampler_name": "euler",
                    "scheduler": "simple",
                    "denoise": 1,
                    "model": [
                        "38",
                        0
                    ],
                    "positive": [
                        "41",
                        0
                    ],
                    "negative": [
                        "42",
                        0
                    ],
                    "latent_image": [
                        "27",
                        0
                    ]
                },
                "class_type": "KSampler",
                "_meta": {
                    "title": "K Sampler"
                }
            },
            "38": {
                "inputs": {
                    "unet_name": "flux1-dev.safetensors",
                    "weight_dtype": "default"
                },
                "class_type": "UNETLoader",
                "_meta": {
                    "title": "UNet Loader"
                }
            },
            "39": {
                "inputs": {
                    "vae_name": "ae.safetensors"
                },
                "class_type": "VAELoader",
                "_meta": {
                    "title": "VAE Loader"
                }
            },
            "40": {
                "inputs": {
                    "clip_name1": "clip_l.safetensors",
                    "clip_name2": "t5xxl_fp8_e4m3fn.safetensors",
                    "type": "flux",
                    "device": "default"
                },
                "class_type": "DualCLIPLoader",
                "_meta": {
                    "title": "Dual CLIP Loader"
                }
            },
            "41": {
                "inputs": {
                    "clip_l": "A beautiful fantasy dog with long curly red hair and big blue eyes, wearing a green transparent fairy dress with lace and puffed sleeves. Surrounded by iridescent butterflies and giant glass roses, dreamy lighting, ethereal atmosphere, soft glow, magical realism, highly detailed, cinematic, 8K render.\n",
                    "t5xxl": "A fairy tale scene of a fire dog with red curly hair wearing a delicate blue dress, standing among crystal butterflies and glowing glass roses. The scene is filled with soft magical light, like a dream from a fantasy world.",
                    "guidance": 3.5,
                    "clip": [
                        "40",
                        0
                    ]
                },
                "class_type": "CLIPTextEncodeFlux",
                "_meta": {
                    "title": "CLIP Text Encode Flux"
                }
            },
            "42": {
                "inputs": {
                    "conditioning": [
                        "41",
                        0
                    ]
                },
                "class_type": "ConditioningZeroOut",
                "_meta": {
                    "title": "Conditioning Zero Out"
                }
            }
        }
    }
}'
```

Response example (where `id` is the job\_id):

```JSON theme={"system"}
{"id":"8cb6a77c-62aa-4eb4-9226-1ca5724fd9dd","status":"PENDING"}
```

**Check job status and retrieve results**:

<Note>
  The maximum output you can get via the status API of the Async Service Endpoint is **4 MiB**. To avoid this limitation, configure S3 environment variables and upload output images or videos to S3 in your `handler.py`, so output size is not limited.

  Job results are kept in the Async Serverless Endpoint for up to **6 hours after completion**.
</Note>

```bash theme={"system"}
curl -X GET https://async.novita.ai/v1/0f43a6867e05fddd/status/33a0bc4b-7312-41f6-ad15-eb9016bd68f9 \
-H "Authorization: Bearer sk_yyy"
```

**Cancel Job**:

```bash theme={"system"}
curl -X GET https://async.novita.ai/v1/0f43a6867e05fddd/cancel/e5f3c3c0-c3b1-49c2-9452-bb96eaa34ce6 \
 -H "Authorization: Bearer sk_yyy"
```

Check Endpoint Job Queue Status:

```
curl -X GET https://async.novita.ai/v1/e41a4c7e58a4eddd/stats \
-H 'Authorization: Bearer sk_yyy'
```

Response example:

```JSON theme={"system"}
{"busy_workers":0,"endpoint":"e41a4c7e58a4eddd","in_progress":0,"pending":0,"total_workers":0}
```

### 5.2 Create Job & Get Results via Runpod SDK

```python theme={"system"}
import runpod
import os

runpod.api_key = "sk_xxx"
runpod.endpoint_url_base = "https://async.novita.ai/v1"
input_payload = { xxxx }

endpoint = runpod.Endpoint("e41a4c7e58a4e7bc")
run_request = endpoint.run(input_payload)

# Initial check without blocking, useful for quick tasks
status = run_request.status()
print(f"Initial job status: {status}")

if status != "COMPLETED":
    # Polling with timeout for long-running tasks
    output = run_request.output(timeout=60)
else:
    output = run_request.output()
print(f"Job output: {output}")
```

## 6. Manage Async Serverless Endpoint

See [Manage serverless Endpoint](https://novita.ai/docs/guides/serverless-gpus-quickstart-manage-endpoint)


# Create Serverless Endpoint
Source: https://novita.ai/docs/guides/serverless-gpus-quickstart-create-endpoint



This guide takes deploying a **Llama 3.1 8B model** as an example to introduce how to create a Serverless Endpoint from scratch.

## Step 1: Prepare Container Image

You need to package the runtime environment into a Docker image and upload it to an image repository in advance. Currently, <a href="https://novita.ai">Novita AI</a> supports specifying **"public image repository"** and **"private image repository"** (including image repository access credentials).

We use the vLLM official image repository for serving the Llama 3.1 8B model: `vllm/vllm-openai:latest`. You can use this image address directly.

## Step 2: Go to the Console

Go to the <a href="https://novita.ai/gpu-instance/console/serverless">Serverless Console</a>, select the appropriate GPU container instance specification, and click **"Create Endpoint"**.

<Tip>
  Currently, only **RTX 4090 24GB** instance specifications are supported. More options will be available gradually, please stay tuned for official updates.
</Tip>

## Step 3: Configure Serverless Endpoint

Here we use the public image `vllm/vllm-openai:latest` as an example for configuration:

* **Endpoint Name**: Used to uniquely identify your Endpoint. The system will generate a name for you by default, but you can also specify one yourself.
* **App Name**: The application name is part of the Endpoint URL. It is optional and supports customization, **only lowercase letters, numbers, and hyphens are allowed**. If not specified, the system will generate one automatically.
* **Worker Configuration**
  * **Workers Min**: The minimum number of Workers to retain. It can be set to 0, so no Workers will be retained when your service has no requests. Note that setting it to 0 may not respond quickly to subsequent requests. Be cautious if your scenario requires quick response time.
  * **Workers Max**: The maximum number of Workers to retain. When your service request volume increases and triggers the auto-scaling mechanism, the number of Workers will increase. This configuration limits the maximum number of Workers to help control costs.
  * **Idle Timeout (seconds)**: When the auto-scaling mechanism triggers a Worker to be taken offline, the platform will retain the Worker for the specified time to quickly handle potential subsequent request increases. Note that the platform will charge you for this time.
  * **Max Concurrency**: The maximum number of concurrent requests each Worker can handle. When the concurrency exceeds the maximum value, requests will be dispatched to other Workers. If all Workers are fully occupied, requests will be queued for execution.
  * **GPUs/Worker**: The number of GPUs each Worker occupies.
  * **CUDA Version**: Supports specifying the CUDA version.
* **Scale Policy**:
  * **Queue Delay**: Adjusts the number of Workers based on the waiting time of requests in the queue. You need to configure the "Queue Delay Time (seconds)". When the waiting time of requests in the queue exceeds this value, auto-scaling will be triggered. When it is less than this value, auto-scaling will be triggered to scale down (combined with the "Idle Timeout (seconds)" set earlier to determine the specific time for Worker to go offline).
  * **Request Count**: Adjusts the number of Workers based on the number of requests in the queue. You need to configure the "Queue Max Request Count". When the number of requests in the queue exceeds this value, auto-scaling will be triggered. When it is less than this value, auto-scaling will be triggered to scale down (combined with the "Idle Timeout (seconds)" set earlier to determine the specific time for Worker to go offline).
* **Image Configuration**:
  * **Container Image**: The image repository address, such as `vllm/vllm-openai:latest`.
  * **Container Registry Credentials**: When you specify a private image repository, you need to set the access credentials. Please configure it through the <a href="https://novita.ai/gpu-instance/console/settings">Settings - Container Registry Auth</a>.
  * **HTTP Port**: The HTTP port exposed by the Workers. The load balancer will forward requests to this port of the Workers, for example, `8080` in this case.
  * **Container Start Command**: The command executed when the container starts. For example: `--model meta-llama/Llama-3.1-8B-Instruct --max-model-len 4096`.
* **Storage Configuration**: Here you can configure the container disk, volume disk and network volume. Currently, the container disk and volume disk sizes are fixed. More options will be available gradually, please stay tuned for official updates.
* **Others**:
  * **Health Check Path**: The built-in **load balancer** will perform health checks through this path. It will determine whether to forward requests to the Worker based on whether the returned status code is `200`, such as `/health`.
  * **Environment Variables**: Here you can configure the environment variables that the service depends on. For example: `HUGGING_FACE_HUB_TOKEN={Your Hugging Face Access Token (with read permission)}`.

After confirming that the configuration is correct, click **"Deploy"** to complete the creation process.

## Step 4: Access the Deployed Llama 3 8B Model Service

You can find the Serverless Endpoint you just created in the <a href="https://novita.ai/gpu-instance/console/serverless">Serverless Console</a>. When the Endpoint's status changes to **"Serving"**, and at least one Worker is in the **"Running"** state, click the **"Copy"** button to copy the URL for accessing the model service.

And you can use the `curl` command to access the service like below:

```bash theme={"system"}
curl "{URL you just copied}/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "messages": [
        {
            "role": "system",
            "content": "Act like you are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Hi there!"
        }
    ],
    "max_tokens": 512
}'
```

## Next Step

Next, please refer to the document [Manage Serverless Endpoint](/guides/serverless-gpus-quickstart-manage-endpoint) to learn how to check and modify the serverless endpoint you just created.


# Manage Serverless Endpoint
Source: https://novita.ai/docs/guides/serverless-gpus-quickstart-manage-endpoint



## Check Serverless Endpoint

Go to the <a href="https://novita.ai/gpu-instance/console/serverless">Serverless Console</a> to check all the Serverless Endpoints you have created.

Click the **"Dropdown"** button at the bottom right corner of the target serverless endpoint to view the number of running Workers, Worker logs, and advanced operation options for the serverless endpoint.

## Modify Serverless Endpoint

Click the **"Modify"** button to modify the configuration of the target serverless endpoint in the subsequent pop-up window. Except for the "App Name", all other configurations can be modified. For details, refer to: [Configure Serverless Endpoint](/guides/serverless-gpus-quickstart-create-endpoint#step-3-configure-serverless-endpoint).


# Preparations
Source: https://novita.ai/docs/guides/serverless-gpus-quickstart-preparations



Before creating a **serverless endpoint**, you need to be aware of the following information:

* Please ensure that you have completed the [Novita AI](https://novita.ai) account registration;
* Please refer to the [Introduction Document](/guides/serverless-gpus-overview) to know about the product features, terminology, and other information.


# Skyvern
Source: https://novita.ai/docs/guides/skyvern

Learn how to seamlessly connect Novita AI's powerful GPU infrastructure with Skyvern's automation capabilities.

The collaboration between Skyvern and Novita AI marks a significant advancement in AI-powered automation and development capabilities. By combining Skyvern's expertise in browser-based workflow automation with Novita AI's robust GPU infrastructure and model deployment platform, developers and businesses can now access a comprehensive solution for building and scaling AI applications.

Our comprehensive guide will walk you through Novita AI implementation on Skyvern, including setting up Docker Compose and leveraging Novita AI in Skyvern.

## Setting Up Docker Compose

Step 1: Ensure [Docker Desktop](https://www.docker.com/products/docker-desktop/) is installed and running on your machine.

Step 2: Check for running PostgreSQL instances using `docker ps` the command.

Step 3: Navigate to the project directory after cloning the repository.

```bash theme={"system"}
git clone <repository-url> && cd <repository-name>
```

Step 4: Add your LLM provider API Key on the [docker-compose.yml](https://github.com/Skyvern-AI/skyvern/blob/main/docker-compose.yml). (*If you want to run Skyvern on a remote server, make sure you set the correct server ip for the UI container in* [*docker-compose.yml*](https://github.com/Skyvern-AI/skyvern/blob/main/docker-compose.yml)*.)*

Step 5: Enter the following command via the command line.

```
docker compose up -d
```

Step 6: Access the application interface at`http://localhost:8080` in your browser to start using the UI.

## Leveraging Novita AI in Skyvern

Step 1: Update environment variables in docker-compose.yml before building the docker image.

Step 2:  Start Novita AI LLM service by running`docker compose up -d`.

<Frame>
  <img alt="Leveraging Novita AI in Skyvern- edit environment variables" />
</Frame>


# Team
Source: https://novita.ai/docs/guides/team



With Team feature, you can convert your personal account into a team account or join an existing team to collaborate with others.

<Warning>Please note that once you convert your personal account into a team account, you will <u>not be able to downgrade</u> to a personal account.</Warning>

Additionally, you can:

* Invite other users to join your team, and share the team's resources with them;
* Manage your members' permissions to the team's resources by assigning different roles;
* Analyze usage data for each team member.

## Upgrade to Team Account

By default, your account is a personal account. To convert your personal account into a team account, go to [Team Settings](https://novita.ai/settings/team), click the **Upgrade to Team Account** button, and follow the instructions to complete the upgrade.

## Role

Role is a set of permissions that define what actions a member can perform within a team. There are 5 roles in one team:

**<u>Owner</u>**

The Owner member has the same permissions as Admin members. The Owner is the member who created the team. It's a special role and each team can only have one Owner.

**<u>Admin</u>**

Admin members can edit any Novita AI settings, make purchases, update billing, and manage memberships. They can also revoke the access of other Super Administrators.

**<u>Developer</u>**

Developer members can access the full account resources, except for membership management and billing.

**<u>Basic</u>**

Basic members can only access resources they have personally created and cannot view or manage resources created by other team members.

**<u>Billing</u>**

Billing members can manage all billing-related functions, including handling payments, reviewing invoices, and managing subscriptions.

For detailed information about role permissions, visit: [Role Permissions](https://novita.ai/team-permission-details).

## Invite Members

Once you upgrade to a team account, you can invite other users to join your team by clicking the **Invite Members** button in the [Team Settings](https://novita.ai/settings/team).

<Tip>
  **Please note that:**

  * Currently, you can invite up to <u>50</u> members to your team.
  * Each member need to be assigned a <u>Role</u> to access the team's resources.
  * The email address you input will be used to send an invitation link to the member. The member can join the team after logging into Novita AI with <u>the consistent email address</u>.
</Tip>

## Manage Members

In the [Team Settings](https://novita.ai/settings/team), you can manage your team members or pending invitations.

### Edit Member Role

To edit a member's role, click the **Setting Icon** on the right side of the member's row, then click the **Edit** button and follow the instructions to change the role.

Note that after the role is changed, the member will need to log in to Novita AI again for the new role to take effect.

### Remove Member

To remove a active member from your team, click **Setting Icon** in the right side of the target member's row, then click **Remove** button, and a confirmation dialog will be shown. Click **Remove** to confirm the removal.

### Cancel Pending Invitation

To cancel a pending invitation, click the **Setting Icon** in the right side of the member's row, then click **Cancel Invitation** button, and a confirmation dialog will be shown. Click **Confirm** to confirm the cancellation.

## Audit Logs

Audit logs provide a detailed record of important resource actions performed within a team and can be used to track team members' activities. For now, only the owner and admin members can view the audit logs.

To view the audit logs, please get to the [Team Settings](https://novita.ai/settings/team).


# How to Explore the Templates in Novita?
Source: https://novita.ai/docs/guides/template_library

The Template Community enables you to easily create, share, and deploy templates. Join us and become a part of the community!

## Let’s start by creating a template!

There are two ways to access the `Create New Template` :

1. **Option 1**: In the Console, go to the [Explore ](https://novita.ai/gpus-console/explore)section and find the `Create My Template` button.

<Frame>
  <img alt="Temlib1 Pn" />
</Frame>

2. **Option 2**: In the Console, go to the [Template ](https://novita.ai/gpus-console/templates)section and find the `New Template` button.

<Frame>
  <img alt="Temlib2 Pn" />
</Frame>

Once you click on it, you’ll open the `Create Template` popup.

<Frame>
  <img alt="Temlib3 Pn" />
</Frame>

**Here, you’ll need to configure your template:**

1. **Name Your Template:** Choose a clear name that makes it easy to identify and use. We suggest selecting a name that relates to the content of the image.
2. **Set up the image:** Bundle your runtime environment into an image and upload it to an image repository ahead of time. Then, paste the image URL into the `Container Image` field.\
   Novita AI supports both public and private image repositories (with optional access credentials). If you're using a **private image repository**, you must provide Container Registry Credentials, which can be added under  [**Settings > Container Registry Auth.**](https://novita.ai/gpus-console/settings)
3. **Set Template Visibility:** You can choose `Private`, which makes the template accessible only to you and your team. However, we strongly recommend selecting `Public` to share your work with the broader community. Public templates will appear in the Template Library, where all users can view, deploy, favorite, and share them—helping your work gain visibility and appreciation.

   **Please note:** for security reasons, **public templates only support public image repositories**, and the Container Registry Credentials input will be disabled.
4. **Specify Container Disk Size:** Determine the disk size based on your needs. We provide 60 GB of free disk space by default.
5. **Advanced Configuration Options:** To improve usability, you can optionally provide advanced configuration options such as `Container Start Command`, `Local Mount`, `Expose HTTP/TCP Ports`, and `Environment Variables`.

You can find detailed explanations of these terms [here](https://novita.ai/docs/guides/gpu-instance-overview).

<Frame>
  <img alt="Readmechanchanchan Pn" />
</Frame>

We strongly encourage you to create a `README` that clearly explains the purpose and configuration of your template. A well-written README helps both you and your team quickly understand the template and makes it easier for others to use—especially if you choose to share it publicly.

* To ensure your template is easy to adopt, we recommend keeping your README **concise and beginner-friendly**.
* If your template requires any **external dependencies**, please include **clear setup instructions** within the README. This guidance helps others successfully deploy your template and ensures a smooth experience

**Unsure What Kind of Template to Create?**

* We suggest checking out popular open-source projects such as **vLLM**, **SGLang**, **Ollama**, **ComfyUI**, **Stable Diffusion WebUI**, or base environments like **CUDA**, **PyTorch**, or OS-specific setups (e.g., **CentOS** / **Ubuntu**, different versions).

We look forward to seeing what you create!

***

## Then try to explore some templates in the library!

If you've created a public template, you’ll see it in the [**Console > Template Library**](https://novita.ai/gpus-console/templates-library) section.

<Frame>
  <img alt="Temlib5 Pn" />
</Frame>

In the `Template Library`, you’ll find templates uploaded by both Novita and the community. Clicking on a template will display the information about it, including the `README` and `configuration details`. If you like the template, you can click `Deploy` to instantly deploy it.

<Frame>
  <img alt="Temlib6 Pn" />
</Frame>

If you really like a template, you can click `Favorite` to save it to your favorites. This makes it easier to find later, and your `favoriting` helps bring attention to the template, allowing more users to discover it. Your favorited templates will be displayed when you filter by `My favorites`.

<Frame>
  <img alt="Temlib7 Pn" />
</Frame>

**Want to share this template with your friends?** Click the `Copy Link` button to easily share it. This way, they can check it out and use it!

<Frame>
  <img alt="Temlib8 Pn" />
</Frame>

***

## Use a template to create an instance

The `Template Library` is integrated into the `Explore` section during instance creation.

<Frame>
  <img alt="Temlib9 Pn" />
</Frame>

Click `Change Template` to view both personal/team-created templates and all templates from the Template Library. Here, you can also filter to select your favorited templates.

<Frame>
  <img alt="Temlib10 Pn" />
</Frame>

Click on a template’s icon to view its details. Once you’ve found the template you need, click on it to select it and proceed with instance creation.

<Frame>
  <img alt="Temlib11 Pn" />
</Frame>

***

## Join Us!

**Now that you know how to create, upload, and share templates, come join us in building a community-friendly template ecosystem for tech enthusiasts!**

**Get in Touch:**

* Discord: [novita.ai](https://discord.com/invite/a3vd9r3uET)


# Verba
Source: https://novita.ai/docs/guides/verba

Integrate Novita AI with Verba to simplify data management and unlock contextual answers instantly.

Novita AI has redefined LLM application development through its seamless integration with Verba. By merging Novita AI's innovative platform with Verba's advanced NLP framework, developers gain access to superior performance, enhanced customizability, and a user-friendly experience.

This guide will walk you through how to integrate Novita AI API with Verba.

## Integration Steps

### Step 1: **Visit the Verba Website**

* Open your browser and navigate to [https://verba.weaviate.io/](https://verba.weaviate.io/).

<Frame>
  <img alt="" />
</Frame>

### Step 2: **Choose Deployment Option**

* Select your preferred deployment method on the homepage to proceed.

<Frame>
  <img alt="" />
</Frame>

### Step 3: **Configure Settings**

* Click the "Start" button at the bottom-right corner.
* On the left-hand side, click **Config**.
* Under **Generator**, select **Novita**.
* Enter your [Novita API Key](https://novita.ai/settings/key-management) in the **API Key** field.
* Finally, click the **Save Config** button to apply your settings.

<Frame>
  <img alt="" />
</Frame>

## Step 4: **Import Data**

* Click the **Import Data** button in the top-right corner to open the file import page.
* Select the **Files** button at the bottom to open the file selection window.
* Choose the files you want to import and click the **Import Selected** button at the bottom-left corner.
* A successfully imported file will display on the right-hand side of the page.

<Frame>
  <img alt="" />
</Frame>

### Step 5: **Start Chatting**

* Click the **Chat** button at the top to return to the chat page.
* Enter your questions based on the imported file to receive accurate results instantly.

<Frame>
  <img alt="" />
</Frame>