# 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
{
    "Authorization": "Bearer {{API Key}}"
}
```


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



## Image / Video / Audio

<table class="table table-big">
  <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 class="table table-big">
  <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 class="table table-big">
  <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 class="table table-big">
  <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>


# Account Info
Source: https://novita.ai/docs/api-reference/basic-get-user-info

GET https://api.novita.ai/v3/user

> This endpoint facilitates queries for user information, primarily focusing on the functions available to the user and their account balance.

## Request Headers

<ParamField header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Response

<ResponseField name="credit_balance" type="number" required={false}>
  The credit balance of the user, calculated as the Balance (shown in the top right corner of the novita.ai website) multiplied by 10,000.
</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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Query Parameters

<ParamField query="category" type="string" required={false}>
  Product type. default: `summary`, Options:

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

<ParamField query="productName" type="string" required={false}>
  Product name. Supports fuzzy matching.
</ParamField>

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

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

<ParamField query="ownerId" type="string" required={false}>
  Specify the instance ID to query.
</ParamField>

## Response Parameters

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

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

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

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

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

    <ResponseField name="productName" type="string" required={true}>
      Product name.
    </ResponseField>

    <ResponseField name="productCategory" type="string" required={true}>
      Product type.
    </ResponseField>

    <ResponseField name="ownerID" type="string" required={true}>
      Instance ID.
    </ResponseField>

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

    <ResponseField name="tradeType" type="string" required={true}>
      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" required={true}>
      Monthly unit price.
    </ResponseField>

    <ResponseField name="billNum" type="string" required={true}>
      Usage.
    </ResponseField>

    <ResponseField name="amount" type="string" required={true}>
      Total price.
    </ResponseField>

    <ResponseField name="voucherAmount" type="string" required={true}>
      Voucher deduction amount.
    </ResponseField>

    <ResponseField name="payAmount" type="string" required={true}>
      Cash payment amount.
    </ResponseField>

    <ResponseField name="payAmountDisplay" type="string" required={true} />

    <ResponseField name="pricePrecision" type="string" required={true}>
      Price Precision.
    </ResponseField>

    <ResponseField name="createTime" type="string" required={true}>
      Bill creation time.
    </ResponseField>

    <ResponseField name="cycle" type="string" required={true}>
      Billing Cycle.
    </ResponseField>

    <ResponseField name="storageDays" type="string" required={true}>
      Storage service duration (days).
    </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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Query Parameters

<ParamField query="cycleType" type="string" required={true}>
  Billing cycle granularity. Options: `Hour`, `Day`, `Week`, `Month`
</ParamField>

<ParamField query="productCategory" type="string" required={true}>
  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 query="productName" type="string" required={false}>
  Product name. Supports fuzzy matching.
</ParamField>

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

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

<ParamField query="ownerId" type="string" required={false}>
  Specify instance ID to query.
</ParamField>

## Response Parameters

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

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

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

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

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

    <ResponseField name="productName" type="string" required={true}>
      Product name.
    </ResponseField>

    <ResponseField name="category" type="string" required={true}>
      Product category.
    </ResponseField>

    <ResponseField name="ownerID" type="string" required={true}>
      Instance ID.
    </ResponseField>

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

    <ResponseField name="billNum1" type="string" required={true}>
      * llm: output token
    </ResponseField>

    <ResponseField name="basePrice0" type="string" required={true}>
      Original Price
    </ResponseField>

    <ResponseField name="basePrice1" type="string" required={true}>
      No significance
    </ResponseField>

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

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

    <ResponseField name="amount" type="string" required={true}>
      Total price.
    </ResponseField>

    <ResponseField name="voucherAmount" type="string" required={true}>
      Voucher deduction amount.
    </ResponseField>

    <ResponseField name="payAmount" type="string" required={true}>
      Cash payment amount.
    </ResponseField>

    <ResponseField name="payAmountDisplay" type="string" required={true} />

    <ResponseField name="pricePrecision" type="string" required={true}>
      Price Precision.
    </ResponseField>

    <ResponseField name="productId" type="string" required={true}>
      Product ID.
    </ResponseField>
  </Expandable>
</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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

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

<ParamField body="month" type="integer" required={true}>
  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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="name" type="string" required={true} />

<ParamField body="username" type="string" required={true} />

<ParamField body="password" type="string" required={true} />

## Example

Request

```bash
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
{}
```


# 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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

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

<ParamField body="productId" type="string" required={true}>
  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 body="imageUrl" type="string" required={true}>
  Container image URL. String, length limit: 1-500 characters.
</ParamField>

<ParamField body="imageAuth" type="string" required={false}>
  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 body="imageAuthId" type="string" required={false}>
  Image repository authentication ID.
</ParamField>

<ParamField body="ports" type="string" required={false}>
  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 body="envs" type="object[]" required={false}>
  Instance environment variables. Array, up to 100 environment variables.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="key" type="string" required={false}>
      Environment variable name. String, length limit: 0-511 characters.
    </ParamField>

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

<ParamField body="tools" type="object[]" required={false}>
  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" defaultOpen={false}>
    <ParamField body="name" type="string" required={false}>
      Tool name. Valid value: Jupyter.
    </ParamField>

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

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

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

<ParamField body="clusterId" type="string" required={false}>
  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 body="localStorageMountPoint" type="string" required={false}>
  Mount point for local storage. Default: "/workspace". String, length limit: 1-4095 characters.
</ParamField>

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

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="Id" type="string" required={false}>
      Cloud storage ID.
    </ParamField>

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

<ParamField body="networkId" type="string" required={false}>
  VPC network ID. Leave empty if not using a VPC network.
</ParamField>

<ParamField body="kind" type="string" required={true}>
  Instance type. Valid values: cpu, gpu. Must be set to cpu.
</ParamField>

## Response

<ResponseField name="id" type="string" required={false}>
  Created instance 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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

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

<ParamField body="productId" type="string" required={true}>
  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 body="gpuNum" type="integer" required={true}>
  Number of GPUs. Integer, valid range: \[1, 8].
</ParamField>

<ParamField body="rootfsSize" type="integer" required={true}>
  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 body="imageUrl" type="string" required={true}>
  Image URL. String, length limit: 1-500 characters.
</ParamField>

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

<ParamField body="imageAuthId" type="string" required={false}>
  Image repository authentication ID.
</ParamField>

<ParamField body="ports" type="string" required={false}>
  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 body="envs" type="object[]" required={false}>
  Instance environment variables. Up to 100 environment variables can be created.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="key" type="string" required={false}>
      Environment variable name. String, length limit: 0-511 characters.
    </ParamField>

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

<ParamField body="tools" type="object[]" required={false}>
  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" defaultOpen={false}>
    <ParamField body="name" type="string" required={false}>
      Tool name. Valid values: \[Jupyter].
    </ParamField>

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

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

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

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

<ParamField body="networkStorages" type="object[]" required={false}>
  Cloud storage mount configuration. Up to 30 cloud storages can be mounted.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="Id" type="string" required={false}>
      Network storage ID.
    </ParamField>

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

<ParamField body="networkId" type="string" required={false}>
  VPC network ID. Leave empty if not using a VPC network.
</ParamField>

<ParamField body="kind" type="string" required={true}>
  Instance type. Valid values: \[gpu, cpu].
</ParamField>

<ParamField body="month" type="integer" required={false}>
  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>

## Response

<ResponseField name="id" type="string" required={false}>
  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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="clusterId" type="string" required={true} />

<ParamField body="storageName" type="string" required={true} />

<ParamField body="storageSize" type="integer" required={true} />

## Example

Request

```bash
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
"<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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="template" type="object" required={true}>
  Template settings.

  <Expandable title="properties" defaultOpen={true}>
    <ParamField body="name" type="string" required={true}>
      Template name.
    </ParamField>

    <ParamField body="readme" type="string" required={true}>
      Template README content (in Markdown format).
    </ParamField>

    <ParamField body="type" type="string" required={true}>
      Template type.<br />
      Enum: `instance`
    </ParamField>

    <ParamField body="channel" type="string" required={true}>
      Template channel.<br />
      Enum: `private`
    </ParamField>

    <ParamField body="image" type="string" required={true}>
      Docker image address for instance startup.
    </ParamField>

    <ParamField body="startCommand" type="string" required={true}>
      Startup command for the instance.
    </ParamField>

    <ParamField body="rootfsSize" type="integer" required={true}>
      Root filesystem storage (GB).
    </ParamField>

    <ParamField body="ports" type="object[]" required={true}>
      Exposed port settings.

      <Expandable title="properties" defaultOpen={true}>
        <ParamField body="type" type="string" required={true}>
          Exposed port types.<br />
          Enum: `http`, `tcp`
        </ParamField>

        <ParamField body="ports" type="string[]" required={true}>
          Exposed ports (maximum of 10).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="volumes" type="object[]" required={true}>
      Volume settings.

      <Expandable title="properties" defaultOpen={true}>
        <ParamField body="type" type="string" required={false}>
          Volume type.
        </ParamField>

        <ParamField body="size" type="integer" required={false}>
          Volume size (GB).
        </ParamField>

        <ParamField body="mountPath" type="string" required={false}>
          Volume mount path.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="envs" type="object[]" required={true}>
      Environment variables injected into the instance.

      <Expandable title="properties" defaultOpen={true}>
        <ParamField body="key" type="string" required={false}>
          Environment variable key.
        </ParamField>

        <ParamField body="value" type="string" required={false}>
          Environment variable value.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Response

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

## Example

Request

```bash

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",
      "image": "redis",
      "startCommand": "",
      "rootfsSize": 10,
      "localVolumeSize": 20,
      "localVolumeMount": "/workspace",
      "ports": [
        {
          "type": "tcp",
          "ports": [
            "8080",
            "8090"
          ]
        },
        {
          "type": "http",
          "ports": [
            "6000",
            "60001"
          ]
        }
      ],
      "volumes": [
        {
          "type": "local",
          "size": 20,
          "mountPath": "/workspace"
        }
      ],
      "envs": [
        {
          "key": "testkey",
          "value": "123"
        }
      ]
    }
  }'
```

Response

```json
{
  "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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="clusterId" type="string" required={true}>
  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 body="name" type="string" required={false}>
  Name of the VPC network. Customizable. String, length limit: 0-30 characters.
</ParamField>

## Response

<ResponseField name="network" type="object[]" required={true}>
  VPC network information.

  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="Id" type="string" required={true}>
      VPC network ID.
    </ResponseField>

    <ResponseField name="user" type="string" required={true}>
      User account ID.
    </ResponseField>

    <ResponseField name="name" type="string" required={true}>
      VPC network name.
    </ResponseField>

    <ResponseField name="state" type="object[]" required={true}>
      VPC network status.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="state" type="string" required={true}>
          VPC network status. Possible values:

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

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

    <ResponseField name="segment" type="string" required={true}>
      VPC network segment.
    </ResponseField>

    <ResponseField name="clusterId" type="string" required={true}>
      Cluster ID.
    </ResponseField>

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

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="Id" type="string" required={true}>
          Instance ID.
        </ResponseField>

        <ResponseField name="Ip" type="string" required={true}>
          Instance IP address.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="createTime" type="string" required={true}>
      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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="id" type="string" required={true} />

## Example

Request

```bash
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
{}
```


# 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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="instanceId" type="string" required={true}>
  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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="storageId" type="string" required={true} />

## Example

Request

```bash
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
{}
```


# 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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="templateId" type="string" required={true}>
  The ID of the template to be deleted.
</ParamField>

## Response

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

## Example

Request

```bash
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
{
  "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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="networkId" type="string" required={true}>
  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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="instanceId" type="string" required={true}>
  ID of the instance to edit.
</ParamField>

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

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

    <ParamField body="type" type="string" required={false}>
      Protocol type. Supported values: `tcp`, `http`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="expandRootDisk" type="integer" required={false}>
  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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="storageId" type="string" required={true}>
  The unique identifier for the storage.
</ParamField>

<ParamField body="storageName" type="string" required={true}>
  The name of the storage.
</ParamField>

<ParamField body="storageSize" type="string" required={true}>
  The size of the storage in appropriate units.
</ParamField>

## Example

Request

```bash
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
{}
```


# 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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Query Parameters

<ParamField query="instanceId" type="string" required={true}>
  ID of the instance being queried.
</ParamField>

## Response

<ResponseField name="id" type="string" required={true}>
  Instance ID.
</ResponseField>

<ResponseField name="name" type="string" required={true}>
  Instance name.
</ResponseField>

<ResponseField name="clusterId" type="string" required={true}>
  Cluster ID.
</ResponseField>

<ResponseField name="clusterName" type="string" required={true}>
  Name of the cluster.
</ResponseField>

<ResponseField name="imageUrl" type="string" required={true}>
  Container image URL.
</ResponseField>

<ResponseField name="imageAuthId" type="string" required={true}>
  Image registry authentication information.
</ResponseField>

<ResponseField name="command" type="string" required={true}>
  Container startup command.
</ResponseField>

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

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

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

<ResponseField name="status" type="string" required={true}>
  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" required={false}>
  Error information when instance creation fails or the instance is unavailable.

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="state" type="string" required={false}>
      Abnormal instance status.
    </ResponseField>

    <ResponseField name="message" type="string" required={false}>
      Error message.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="network" type="object" required={false}>
  VPC network information for the instance.

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="id" type="string" required={false}>
      VPC network ID.
    </ResponseField>

    <ResponseField name="ip" type="string" required={false}>
      Instance IP address.
    </ResponseField>
  </Expandable>
</ResponseField>

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

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="port" type="integer" required={true}>
      Port number.
    </ResponseField>

    <ResponseField name="endpoint" type="string" required={true}>
      Endpoint.
    </ResponseField>

    <ResponseField name="type" type="string" required={true}>
      Protocol type.
    </ResponseField>
  </Expandable>
</ResponseField>

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

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="type" type="string" required={false}>
      Storage type. Possible values:

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

    <ResponseField name="size" type="number" required={false}>
      Storage capacity.
    </ResponseField>

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

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

<ResponseField name="node" type="object[]" required={false}>
  Node information.

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="maxRootfsSize" type="number" required={false}>
      Maximum available system disk size.
    </ResponseField>
  </Expandable>
</ResponseField>

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

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="id" type="string" required={false}>
      Task ID.
    </ResponseField>

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

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

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="key" type="string" required={false}>
      Environment variable name.
    </ResponseField>

    <ResponseField name="value" type="string" required={false}>
      Environment variable value.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="connectComponentSSH" type="object" required={false}>
  Instance SSH connection information.

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="sshCommand" type="string" required={false}>
      Command for SSH remote login.
    </ResponseField>

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

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

<ResponseField name="connectComponentWebTerminal" type="object" required={false}>
  Instance WebSSH connection information.

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

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

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

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

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

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="port" type="integer" required={false}>
      Connection port.
    </ResponseField>

    <ResponseField name="address" type="string" required={false}>
      Connection address.
    </ResponseField>

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

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

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="systemLogAddress" type="string" required={false}>
      System log address.
    </ResponseField>

    <ResponseField name="instanceLogAddress" type="string" required={false}>
      Instance log address.
    </ResponseField>

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

<ResponseField name="kind" type="string" required={false}>
  Instance type.
</ResponseField>

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

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

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

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

<ResponseField name="keepDataDay" type="integer" required={false}>
  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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

<ParamField header="Authorization" type="string" required={true}>
  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 query="instanceId" type="string" required={true}>
  Instance ID.
</ParamField>

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

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

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

## Response

<ResponseField name="cpuUtilization" type="array" required={true}>
  CPU utilization data.

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="timestamp" type="string" required={true}>
      Timestamp.
    </ResponseField>

    <ResponseField name="value" type="number" required={true}>
      CPU utilization.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="memUtilization" type="array" required={true}>
  Memory utilization data.

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="timestamp" type="string" required={true}>
      Timestamp.
    </ResponseField>

    <ResponseField name="value" type="number" required={true}>
      Memory utilization.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="rootDiskUtilization" type="array" required={true}>
  Root disk utilization data.

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="timestamp" type="string" required={true}>
      Timestamp.
    </ResponseField>

    <ResponseField name="value" type="number" required={true}>
      Root disk utilization.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="gpuUtilization" type="object" required={true}>
  GPU utilization data.

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="avg" type="array" required={true}>
      Average utilization across all GPUs.

      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="timestamp" type="string" required={true}>
          Timestamp.
        </ResponseField>

        <ResponseField name="value" type="number" required={true}>
          Utilization.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="gpuIds" type="array" required={true}>
      Utilization for each GPU.

      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="gpuId" type="string" required={true}>
          GPU ID in use.
        </ResponseField>

        <ResponseField name="items" type="array" required={true}>
          GPU utilization data.

          <Expandable title="properties" defaultOpen={false}>
            <ResponseField name="timestamp" type="string" required={true}>
              Timestamp.
            </ResponseField>

            <ResponseField name="value" type="number" required={true}>
              Utilization.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="gpuMemUtilization" type="object" required={true}>
  GPU memory utilization data.

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="avg" type="array" required={true}>
      Average GPU memory utilization across all GPUs.

      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="timestamp" type="string" required={true}>
          Timestamp.
        </ResponseField>

        <ResponseField name="value" type="number" required={true}>
          Utilization.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="gpuIds" type="array" required={true}>
      GPU memory utilization for each GPU.

      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="gpuId" type="string" required={true}>
          GPU ID in use.
        </ResponseField>

        <ResponseField name="items" type="array" required={true}>
          GPU memory utilization data.

          <Expandable title="properties" defaultOpen={false}>
            <ResponseField name="timestamp" type="string" required={true}>
              Timestamp.
            </ResponseField>

            <ResponseField name="value" type="number" required={true}>
              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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Query Parameters

<ParamField query="templateId" type="string" required={false}>
  ID of the template being queried.
</ParamField>

## Response

<ResponseField name="template" type="object" required={false}>
  Template settings.

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="Id" type="string" required={false}>
      Template ID.
    </ResponseField>

    <ResponseField name="createTime" type="string" required={false}>
      Template creation time.
    </ResponseField>

    <ResponseField name="user" type="string" required={false}>
      ID of the user who created the template.
    </ResponseField>

    <ResponseField name="tools" type="string[]" required={false}>
      List of tools associated with the template.
    </ResponseField>

    <ResponseField name="name" type="string" required={false}>
      Template name.
    </ResponseField>

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

    <ResponseField name="type" type="string" required={false}>
      Template type.Enum: `instance`
    </ResponseField>

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

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

    <ResponseField name="imageAuth" type="string" required={false}>
      Credentials for the Docker image registry to pull private images.
    </ResponseField>

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

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

    <ResponseField name="volumes" type="object[]" required={false}>
      Volumes settings.

      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="type" type="string" required={false}>
          Volume type.Enum: `local`
        </ResponseField>

        <ResponseField name="size" type="integer" required={false}>
          Volume size (GB).
        </ResponseField>

        <ResponseField name="mountPath" type="string" required={false}>
          Volume mount path.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ports" type="object[]" required={false}>
      Exposed ports settings.

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

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

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

      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="key" type="string" required={false}>
          Environment variable key.
        </ResponseField>

        <ResponseField name="value" type="string" required={false}>
          Environment variable value.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

Request

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

Response

```json
{
  "template": {
    "Id": "212",
    "user": "9141320498493177",
    "name": "ubuntu",
    "readme": "readme",
    "logo": "",
    "type": "instance",
    "channel": "private",
    "image": "ubuntu:latest",
    "imageAuth": "",
    "startCommand": "",
    "rootfsSize": 10,
    "volumes": [
      {
        "type": "local",
        "size": 20,
        "mountPath": "/workspace"
      }
    ],
    "ports": [
      {
        "type": "tcp",
        "ports": [8080, 8090]
      },
      {
        "type": "http",
        "ports": [6000, 60001]
      }
    ],
    "envs": [
      {
        "key": "testkey",
        "value": "123"
      }
    ],
    "tools": [],
    "createTime": "1713162260"
  }
}
```


# 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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Query Parameters

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

## Response

<ResponseField name="network" type="object[]" required={true}>
  VPC network information.

  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="Id" type="string" required={true}>
      VPC network ID.
    </ResponseField>

    <ResponseField name="user" type="string" required={true}>
      User account ID.
    </ResponseField>

    <ResponseField name="name" type="string" required={true}>
      VPC network name.
    </ResponseField>

    <ResponseField name="state" type="object[]" required={true}>
      VPC network status.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="state" type="string" required={true}>
          VPC network status. Possible values:

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

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

    <ResponseField name="segment" type="string" required={true}>
      VPC network segment.
    </ResponseField>

    <ResponseField name="clusterId" type="string" required={true}>
      Cluster ID.
    </ResponseField>

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

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="Id" type="string" required={true}>
          Instance ID.
        </ResponseField>

        <ResponseField name="Ip" type="string" required={true}>
          Instance IP address.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="createTime" type="string" required={true}>
      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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Response

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

    <ResponseField name="name" type="string" required={true}>
      Cluster name.
    </ResponseField>

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

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

    <ResponseField name="supportInstanceNetwork" type="boolean" required={true}>
      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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Response

<ResponseField name="data" type="object[]" required={false}>
  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="id" type="string" required={false} />

    <ResponseField name="name" type="string" required={false} />

    <ResponseField name="username" type="string" required={false} />

    <ResponseField name="password" type="string" required={false} />
  </Expandable>
</ResponseField>

## Example

Request

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

Response

```json
{
  "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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Query Parameters

<ParamField query="clusterId" type="string" required={false}>
  Filter by specified cluster ID. String, length limit: 0-255 characters.
</ParamField>

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

## Response

<ResponseField name="id" type="string" required={true}>
  CPU product ID.
</ResponseField>

<ResponseField name="name" type="string" required={true}>
  CPU product name.
</ResponseField>

<ResponseField name="cpuNum" type="integer" required={false}>
  Number of CPU cores.
</ResponseField>

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

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

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

<ResponseField name="availableDeploy" type="boolean" required={false}>
  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" required={false}>
  Unit price of the product.
</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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Query Parameters

<ParamField query="pageSize" type="integer" required={true}>
  Maximum number of items returned per page. Integer, value >= 0.
</ParamField>

<ParamField query="pageNum" type="integer" required={true}>
  Page number to retrieve. Integer, value >= 0.
</ParamField>

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

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

<ParamField query="status" type="string" required={false}>
  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[]" required={true}>
  Instance information.

  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="id" type="string" required={true}>
      Instance ID.
    </ResponseField>

    <ResponseField name="name" type="string" required={true}>
      Instance name.
    </ResponseField>

    <ResponseField name="clusterId" type="string" required={true}>
      Cluster ID.
    </ResponseField>

    <ResponseField name="clusterName" type="string" required={false}>
      Cluster name.
    </ResponseField>

    <ResponseField name="status" type="string" required={true}>
      Instance status.
    </ResponseField>

    <ResponseField name="imageUrl" type="string" required={true}>
      Container image URL.
    </ResponseField>

    <ResponseField name="imageAuthId" type="string" required={false}>
      Image repository authentication information.
    </ResponseField>

    <ResponseField name="command" type="string" required={false}>
      Container startup command.
    </ResponseField>

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

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

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

    <ResponseField name="portMappings" type="object[]" required={false}>
      Instance port information.

      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="port" type="integer" required={true}>
          Port value.
        </ResponseField>

        <ResponseField name="type" type="string" required={true}>
          Port type.
        </ResponseField>
      </Expandable>
    </ResponseField>

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

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

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

    <ResponseField name="volumeMounts" type="object[]" required={false}>
      Instance storage configuration.

      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="type" type="string" required={false}>
          Storage type. Values:

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

        <ResponseField name="size" type="string" required={false}>
          Storage capacity.
        </ResponseField>

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

        <ResponseField name="mountPath" type="string" required={false}>
          Storage mount path.
        </ResponseField>
      </Expandable>
    </ResponseField>

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

      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="state" type="string" required={false}>
          Abnormal instance status.
        </ResponseField>

        <ResponseField name="message" type="string" required={false}>
          Error message.
        </ResponseField>
      </Expandable>
    </ResponseField>

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

      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="key" type="string" required={false}>
          Environment variable name.
        </ResponseField>

        <ResponseField name="value" type="string" required={false}>
          Environment variable value.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="kind" type="string" required={false}>
      Instance type.
    </ResponseField>

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

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

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

<ParamField name="total" type="integer" required={false}>
  Total number of results.
</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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Query Parameters

<ParamField query="pageNo" type="integer" required={false} />

<ParamField query="pageSize" type="integer" required={false} />

<ParamField query="storageName" type="string" required={false} />

<ParamField query="storageId" type="string" required={false} />

## Response

<ResponseField name="data" type="object[]" required={false}>
  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="storageId" type="string" required={false} />

    <ResponseField name="storageName" type="string" required={false} />

    <ResponseField name="storageSize" type="integer" required={false} />

    <ResponseField name="clusterId" type="string" required={false} />

    <ResponseField name="clusterName" type="string" required={false} />

    <ResponseField name="price" type="string" required={false} />
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer" required={false} />

## Example

Request

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

Response

```json
{
  "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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Query Parameters

<ParamField query="clusterId" type="string" required={false}>
  Filter by specified cluster ID. String, length limit: 0-255 characters.
</ParamField>

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

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

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

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

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

<ParamField query="billingMethod" type="string" required={false}>
  Filter by billing method. Options:

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

## Response

<ResponseField name="data" type="object[]" required={true}>
  GPU product information.

  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="id" type="string" required={true}>
      Product ID.
    </ResponseField>

    <ResponseField name="name" type="string" required={true}>
      Product name.
    </ResponseField>

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

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

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

    <ResponseField name="availableDeploy" type="boolean" required={true}>
      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" required={true}>
      Minimum available root filesystem size (GB).
    </ResponseField>

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

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

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

    <ResponseField name="regions" type="[string]" required={true}>
      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" required={true}>
      Price for creating a pay-as-you-go instance with this product.
    </ResponseField>

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

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="price" type="integer" required={true}>
          Unit price for the subscription instance.
        </ResponseField>

        <ResponseField name="month" type="integer" required={true}>
          Subscription duration, in months.
        </ResponseField>
      </Expandable>
    </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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Query Parameters

<ParamField query="pageSize" type="integer" required={false}>
  Maximum number of entries returned on one page.
</ParamField>

<ParamField query="pageNum" type="integer" required={false}>
  Current page index.
</ParamField>

<ParamField query="name" type="string" required={false}>
  Filter the templates by name.
</ParamField>

<ParamField query="type" type="string" required={false}>
  Filter the templates by type.
</ParamField>

<ParamField query="channel" type="string[]" required={false}>
  Filter the templates by channel.
</ParamField>

## Response

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

    <ResponseField name="createTime" type="string" required={false}>
      Template creation time.
    </ResponseField>

    <ResponseField name="user" type="string" required={false}>
      ID of the user who created the template.
    </ResponseField>

    <ResponseField name="tools" type="string[]" required={false} />

    <ResponseField name="name" type="string" required={false}>
      Template name.
    </ResponseField>

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

    <ResponseField name="type" type="string" required={false}>
      Template type.Enum: `instance`
    </ResponseField>

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

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

    <ResponseField name="imageAuth" type="string" required={false}>
      Credentials for the Docker image registry to pull private images.
    </ResponseField>

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

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

    <ResponseField name="volumes" type="object[]" required={false}>
      Volumes settings.

      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="type" type="string" required={false}>
          Volume type.Enum: `local`
        </ResponseField>

        <ResponseField name="size" type="integer" required={false}>
          Volume size (GB).
        </ResponseField>

        <ResponseField name="mountPath" type="string" required={false}>
          Volume mount path.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ports" type="object[]" required={false}>
      Exposed ports settings.

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

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

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

      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="key" type="string" required={false}>
          Environment variable key.
        </ResponseField>

        <ResponseField name="value" type="string" required={false}>
          Environment variable value.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pageSize" type="integer" required={false}>
  Maximum number of entries returned on one page.
</ResponseField>

<ResponseField name="pageNum" type="integer" required={false}>
  Current page index.
</ResponseField>

<ResponseField name="total" type="integer" required={false}>
  Total number of templates.
</ResponseField>

## Example

Request

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

Response

````json
{
  "template": [
    {
      "Id": "100",
      "user": "1032922317920824",
      "name": "name",
      "readme": "```\nreadme\n```\n# uiohiu\n68686",
      "logo": "",
      "type": "instance",
      "channel": "private",
      "image": "image",
      "imageAuth": "",
      "startCommand": "startCommand",
      "rootfsSize": 10,
      "volumes": [
        {
          "type": "local",
          "size": 20,
          "mountPath": "localVolumeMount"
        }
      ],
      "ports": [
        {
          "type": "tcp",
          "ports": [8080, 8090]
        },
        {
          "type": "http",
          "ports": [6000, 60001]
        }
      ],
      "envs": [
        {
          "key": "testkey",
          "value": "123"
        }
      ],
      "tools": [],
      "createTime": "1711995567"
    }
  ],
  "pageSize": 1,
  "pageNum": 0,
  "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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Query Parameters

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

<ParamField query="pageNum" type="integer" required={false}>
  Page number to retrieve. Integer, value must be greater than or equal to 0.
</ParamField>

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

<ParamField query="creators" type="string" required={false}>
  Creator user ID. String, length limit: 0-255 characters.
</ParamField>

## Response

<ResponseField name="network" type="object[]" required={true}>
  VPC network information.

  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="Id" type="string" required={true}>
      VPC network ID.
    </ResponseField>

    <ResponseField name="user" type="string" required={true}>
      User account ID.
    </ResponseField>

    <ResponseField name="name" type="string" required={true}>
      VPC network name.
    </ResponseField>

    <ResponseField name="state" type="object[]" required={true}>
      VPC network status.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="state" type="string" required={true}>
          VPC network status. Possible values:

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

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

    <ResponseField name="segment" type="string" required={true}>
      VPC network segment.
    </ResponseField>

    <ResponseField name="clusterId" type="string" required={true}>
      Cluster ID.
    </ResponseField>

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

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="Id" type="string" required={true}>
          Instance ID.
        </ResponseField>

        <ResponseField name="Ip" type="string" required={true}>
          Instance IP address.
        </ResponseField>
      </Expandable>
    </ResponseField>

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

<ResponseField name="total" type="string" required={true}>
  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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="instanceId" type="string" required={true}>
  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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="instanceId" type="string" required={true}>
  The ID of the subscription instance to be renewed.
</ParamField>

<ParamField body="month" type="integer" required={true}>
  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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="instanceId" type="string" required={true}>
  ID of the instance to be restarted.
</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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="instanceId" type="string" required={true}>
  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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="instanceId" type="string" required={true}>
  ID of the instance to be stopped.
</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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="networkId" type="string" required={true}>
  Cluster ID. String, length limit: 1-255 characters.
</ParamField>

<ParamField body="name" type="string" required={false}>
  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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="instanceId" type="string" required={true}>
  The ID of the instance to be upgraded.
</ParamField>

<ParamField body="imageUrl" type="string" required={true}>
  Container image URL. String, length limit: 1-500 characters.
</ParamField>

<ParamField body="imageAuthId" type="string" required={false}>
  Image registry authentication ID.
</ParamField>

<ParamField body="envs" type="object[]" required={true}>
  Instance environment variables. Up to 100 environment variable pairs can be created.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="key" type="string" required={false}>
      Environment variable name. String, length limit: 0-511 characters.
    </ParamField>

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

<ParamField body="command" type="string" required={true}>
  Container startup command. String, length limit: 0-2047 characters.
</ParamField>

<ParamField body="save" type="boolean" required={true}>
  Whether to retain data from the previous instance. Boolean, values: true or false.
</ParamField>

<ParamField body="networkVolume" type="object" required={true}>
  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" defaultOpen={false}>
    <ParamField body="volumeMounts" type="object[]" required={true}>
      Cloud storage mount information.

      <Expandable title="properties" defaultOpen={true}>
        <ParamField body="type" type="string" required={true}>
          Storage type. Must be set to network.
        </ParamField>

        <ParamField body="id" type="string" required={true}>
          Cloud storage ID.
        </ParamField>

        <ParamField body="mountPath" type="string" required={true}>
          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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="extra" type="object" required={false}>
  Optional extra parameters for the request.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="response_image_type" type="string" required={false}>
      The returned image type. Default is png.<br />
      Enum: `png, webp, jpeg`
    </ParamField>

    <ParamField body="enterprise_plan" type="object" required={false}>
      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" defaultOpen={false}>
        <ParamField body="enabled" type="boolean" required={false}>
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="image_file" type="string" required={true}>
  The base64-encoded original image, with a maximum resolution of 16 megapixels and a maximum file size of 30 MB.
</ParamField>

<ParamField body="mask_file" type="string" required={true}>
  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" required={false}>
  The Base64-encoded content of the returned image.
</ResponseField>

<ResponseField name="image_type" type="string" required={false}>
  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
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
{
    "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
{
    "image_file": "{{Base64 encoded image}}",
    "image_type": "png"
}
```

<Frame>
  <img height="390" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/UseCase_cleanup01.png" />
</Frame>

<Frame>
  <img height="390" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/UseCase_cleanup02.png" />
</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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

### Request Body

<ParamField body="name" type="string" required={true}>
  Task name for this model training.
</ParamField>

<ParamField body="base_model" type="string" required={true}>
  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 body="width" type="integer" required={true}>
  Width of training images, must be > 0
</ParamField>

<ParamField body="height" type="integer" required={true}>
  Height of training images, must be > 0
</ParamField>

<ParamField body="image_dataset_items" type="object[]" required={true}>
  Image asset IDs and their captions.

  <Expandable title="properties" defaultOpen={true}>
    <ParamField body="assets_id" type="integer" required={true}>
      Image asset ID; see <a href="#_1-upload-images-for-training">Upload Images For Training</a> for reference.
    </ParamField>

    <ParamField body="caption" type="string" required={true}>
      Image caption; refer to <a href="/guides/model-apis-training-guidance">Training Image Caption Guidance</a> for more information.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="expert_setting" type="object" required={false}>
  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="train_batch_size" type="integer" required={false}>
      batch size of training, Range \[1, 4]
    </ParamField>

    <ParamField body="learning_rate" type="number(float)" required={false}>
      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 body="max_train_steps" type="integer" required={false}>
      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 body="seed" type="integer" required={false}>
      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 body="lr_scheduler" type="string" required={false}>
      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 body="lr_warmup_steps" type="integer" required={false}>
      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 body="components" type="object[]" required={true}>
  Common parameters configured for training.

  <Expandable title="properties" defaultOpen={true}>
    <ParamField body="name" type="string" required={true}>
      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 body="args" type="object[]" required={true}>
      Component detail settings.

      <Expandable title="properties" defaultOpen={true}>
        <ParamField body="name" type="string" required={true}>
          Name of argument.
        </ParamField>

        <ParamField body="value" type="string" required={true}>
          Argument value.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="task_id" type="string" required={false}>
  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 header="Authorization" type="string" required={true}>
  In Bearer \{\{API Key}} format.
</ParamField>

### Request Body

<ParamField body="task_id" type="string" required={true} />

### Response

<ResponseField name="task_id" type="string" required={false}>
  The task id of training.
</ResponseField>

<ResponseField name="task_status" type="string" required={false}>
  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" required={false}>
  Model trained type.<br />
  Enum: `lora`
</ResponseField>

<ResponseField name="models" type="object[]" required={false}>
  models info

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="model_name" type="string" required={false}>
      model file name.
    </ResponseField>

    <ResponseField name="model_status" type="string" required={false}>
      model status.<br />
      Enum: `DEPLOYING`, `SERVING`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="extra" type="object" required={false}>
  extra info

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="eta_relative" type="number" required={false}>
      Estimated time of arrival in seconds.
    </ResponseField>

    <ResponseField name="progress_percent" type="number" required={false}>
      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
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
{
    "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
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
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
{
    "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
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
{
    "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
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
{
    "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
curl --location 'https://api.novita.ai/v3/async/task-result?task_id=bec2bcfe-47c6-4536-af34-f26cfe6fd457' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js
{
  "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
curl --location --request GET 'https://api.novita.ai/v3/training?pagination.limit=10&pagination.cursor=c_0' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js
{
    "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 height="430" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/training_playground01.png" />
</Frame>

#### 4.2 Switch to the inferencing tab and add more detail

<Frame>
  <img height="430" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/training_playground02.png" />
</Frame>

<Frame>
  <img height="430" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/training_playground03.png" />
</Frame>

#### Review the training results

<Frame>
  <img height="430" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/training_playground04.png" />
</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 header="Authorization" type="string" required={true}>
  In Bearer \{\{API Key}} format.
</ParamField>

<ParamField header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

### Request Body

<ParamField body="name" type="string" required={true}>
  Task name for this model training.
</ParamField>

<ParamField body="base_model" type="string" required={true}>
  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 body="width" type="integer" required={true}>
  Training image width. Minimum value is 1.
</ParamField>

<ParamField body="height" type="integer" required={true}>
  Training image height. Minimum value is 1.
</ParamField>

<ParamField body="image_dataset_items" type="object[]" required={true}>
  Image asset IDs and image captions.

  <Expandable title="properties" defaultOpen={true}>
    <ParamField body="assets_id" type="string" required={true}>
      Image asset ID. Refer to <a href="#_1-upload-images-for-training">Upload Images For Training</a> for more information.
    </ParamField>

    <ParamField body="caption" type="string" required={false}>
      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 body="expert_setting" type="object" required={false}>
  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="train_batch_size" type="integer" required={false}>
      batch size of training, Range: \[1, 4]
    </ParamField>

    <ParamField body="learning_rate" type="number(float)" required={false}>
      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 body="max_train_steps" type="integer" required={false}>
      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 body="seed" type="integer" required={false}>
      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 body="lr_scheduler" type="string" required={false}>
      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 body="lr_warmup_steps" type="integer" required={false}>
      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 body="instance_prompt" type="string" required={true}>
      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 body="class_prompt" type="string" required={true}>
      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 body="with_prior_preservation" type="boolean" required={false}>
      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 body="prior_loss_weight" type="number(float)" required={false}>
      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 body="train_text_encoder" type="boolean" required={false}>
      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 body="lora_r" type="integer" required={false}>
      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 body="lora_alpha" type="integer" required={false}>
      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 body="lora_text_encoder_r" type="integer" required={false}>
      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 body="lora_text_encoder_alpha" type="integer" required={false}>
      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 body="components" type="object[]" required={true}>
  Common parameters configured for training.

  <Expandable title="properties" defaultOpen={true}>
    <ParamField body="name" type="string" required={true}>
      Type of components.<br />
      Enum: `face_crop_region`, `resize`, `face_restore`
    </ParamField>

    <ParamField body="args" type="object[]" required={true}>
      Component detail settings.

      <Expandable title="properties" defaultOpen={true}>
        <ParamField body="name" type="string" required={true}>
          Name of argument.
        </ParamField>

        <ParamField body="value" type="string" required={true}>
          Argument value.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="task_id" type="string" required={false}>
  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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

### Request Body

<ParamField body="task_id" type="string" required={true} />

### Response

<ResponseField name="task_id" type="string" required={false}>
  The task id of training.
</ResponseField>

<ResponseField name="task_status" type="string" required={false}>
  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" required={false}>
  Model trained type.<br />
  Enum: `lora`
</ResponseField>

<ResponseField name="models" type="object[]" required={false}>
  models info

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="model_name" type="string" required={false}>
      model file name.
    </ResponseField>

    <ResponseField name="model_status" type="string" required={false}>
      model status.<br />
      Enum: `DEPLOYING`, `SERVING`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="extra" type="object" required={false}>
  extra info

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="eta_relative" type="number" required={false}>
      Estimated time of arrival in seconds.
    </ResponseField>

    <ResponseField name="progress_percent" type="number" required={false}>
      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
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
{
    "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
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
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
{
    "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
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
{
    "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
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
{
    "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
curl --location 'https://api.novita.ai/v3/async/task-result?task_id=bec2bcfe-47c6-4536-af34-f26cfe6fd457' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js
{
  "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
curl --location --request GET 'https://api.novita.ai/v3/training?pagination.limit=10&pagination.cursor=c_0' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js
{
    "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 height="430" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/training_playground01.png" />
</Frame>

#### 4.2 Switch to the inferencing tab and add more detail

<Frame>
  <img height="430" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/training_playground02.png" />
</Frame>

<Frame>
  <img height="430" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/training_playground03.png" />
</Frame>

#### Review the training results

<Frame>
  <img height="430" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/training_playground04.png" />
</Frame>


# 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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="response_image_type" type="string" required={false}>
  The returned image type. Default is png.<br />
  Enum: `png` `webp` `jpeg`
</ParamField>

<ParamField body="prompt" type="string" required={true}>
  Text input required to guide the image generation, divided by `,` . Range \[1, 1024].
</ParamField>

<ParamField body="seed" type="integer" required={true}>
  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 body="steps" type="integer" required={true}>
  The number of denoising steps. More steps usually can produce higher quality images, but take more time to generate, Range \[1, 100].
</ParamField>

<ParamField body="width" type="integer" required={true}>
  Width of image. Range \[64, 2048].
</ParamField>

<ParamField body="height" type="integer" required={true}>
  Height of image. Range \[64, 2048].
</ParamField>

<ParamField body="image_num" type="integer" required={true}>
  Images numbers generated in one single generation. Range \[1, 8].
</ParamField>

## Response

<ResponseField name="task" type="object" required={false}>
  Task information.

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="task_id" type="string" required={false}>
      Task ID.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="images" type="object[]" required={false}>
  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" defaultOpen={false}>
    <ResponseField name="image_url" type="string" required={false}>
      Image URL.
    </ResponseField>

    <ResponseField name="image_url_ttl" type="integer" required={false}>
      Image expiration time in seconds.
    </ResponseField>

    <ResponseField name="image_type" type="string" required={false}>
      Image type.<br />
      Enum: `jpeg`, `png`, `webp`
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

request

```bash
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
{
  "images": [
    {
      "image_url": "https://model-api-output.5e61b0cbce9f453eb9db49fdd85c7cac.r2.cloudflarestorage.com/xxx",
      "image_url_ttl": 604800,
      "image_type": "png"
    }
  ],
  "task": {
    "task_id": "xxx"
  }
}
```


# 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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Query Parameters

<ParamField query="filter.visibility" type="string" required={false}>
  Model types: `public` or `private`. If not set, the interface will query all types of models.
</ParamField>

<ParamField query="filter.source" type="string" required={false}>
  Source of the model.<br />
  Enum: `civitai`, `training`, `uploading`
</ParamField>

<ParamField query="filter.types" type="string" required={false}>
  Specifies the types of models to include in the query.<br />
  Enum: `checkpoint`, `lora`, `vae`, `controlnet`, `upscaler`, `textualinversion`
</ParamField>

<ParamField query="filter.is_sdxl" type="boolean" required={false}>
  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 query="filter.query" type="string" required={false}>
  Searches the content of sd\_name, name, and tags.
</ParamField>

<ParamField query="filter.is_inpainting" type="boolean" required={false}>
  If set to true, it will filter out the checkpoints used for inpainting. The default is false.
</ParamField>

<ParamField query="pagination.limit" type="string" required={false}>
  Number of models to query per request, range (0, 100].
</ParamField>

<ParamField query="pagination.cursor" type="string" required={false}>
  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[]" required={false}>
  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="id" type="integer" required={false}>
      ID of the model.
    </ResponseField>

    <ResponseField name="name" type="string" required={false}>
      Model name.
    </ResponseField>

    <ResponseField name="hash_sha256" type="string" required={false}>
      Hash of the model file.
    </ResponseField>

    <ResponseField name="sd_name" type="string" required={false}>
      Model file name.
    </ResponseField>

    <ResponseField name="type" type="object" required={false}>
      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="name" type="string" required={false}>
          Model type name.
        </ResponseField>

        <ResponseField name="display_name" type="string" required={false} />
      </Expandable>
    </ResponseField>

    <ResponseField name="categories" type="string[]" required={false}>
      Model categories.
    </ResponseField>

    <ResponseField name="status" type="integer" required={false}>
      Model status: 0 for unavailable, 1 for available.
    </ResponseField>

    <ResponseField name="download_url" type="string" required={false}>
      Model download URL.
    </ResponseField>

    <ResponseField name="tags" type="string[]" required={false}>
      Model tags, such as photorealistic, anatomical, base model, CGI, realistic, semi-realistic.
    </ResponseField>

    <ResponseField name="cover_url" type="string" required={false}>
      Model cover image URL.
    </ResponseField>

    <ResponseField name="source" type="string" required={false}>
      The source of the model, such as civitai, training, uploading.
    </ResponseField>

    <ResponseField name="base_model" type="string" required={false}>
      Base model of the model, such as SD 1.5 or SDXL 1.0.
    </ResponseField>

    <ResponseField name="base_model_type" type="string" required={false}>
      Base model type of the model, such as Inpainting or Standard.
    </ResponseField>

    <ResponseField name="download_url_ttl" type="integer" required={false}>
      The expiration time of the download URL in seconds, default is 1 day.
    </ResponseField>

    <ResponseField name="sd_name_in_api" type="string" required={false}>
      The name users can add in the interface.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object" required={false}>
  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="next_cursor" type="string" required={false}>
      Next request starting cursor.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

request

```bash
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
{
  "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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="file_extension" type="string" required={true}>
  Enum: `png`, `webp`, `jpeg`
</ParamField>

## Response

<ResponseField name="assets_id" type="integer" required={false}>
  The asset ID.
</ResponseField>

<ResponseField name="upload_url" type="string" required={false}>
  The S3 pre-signed uploading URL.
</ResponseField>

<ResponseField name="method" type="string" required={false}>
  The method for uploading.<br />
  Enum: `PUT`
</ResponseField>

<ResponseField name="headers" type="object" required={false}>
  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="Host" type="object" required={false}>
      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="values" type="string[]" required={false}>
          The host value.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

request

```bash
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
{
  "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"]
    }
  }
}
```


# 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 header="Content-Type" type="string" required={true}>
  Supports: `application/json`
</ParamField>

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

## Request Body

<ParamField body="model_name" type="string" required={true}>
  Name of the model checkpoint.

  Supports: `hunyuan-video-fast`.
</ParamField>

<ParamField body="width" type="integer" required={true}>
  Width of the output video.

  Supports: `720`, `1280`.
</ParamField>

<ParamField body="height" type="integer" required={true}>
  Height of the output video.

  Supports:

  * `720` for `width` of `1280`
  * `1280` for `width` of `720`
</ParamField>

<ParamField body="seed" type="integer" required={true}>
  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 body="steps" type="integer" required={true}>
  The number of denoising steps. More steps usually produce higher quality content but take more time to generate.

  Range: `2 <= x <= 30`.
</ParamField>

<ParamField body="prompt" type="string" required={true}>
  Prompt text required to guide the generation.

  Range: `1 <= x <= 2000`.
</ParamField>

## Response

<ResponseField name="task_id" type="string" required={true}>
  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
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
{
    "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
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id={Returned Task ID}' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js
{
    "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 controls className="w-full aspect-video" src="https://pub-f964a1c641c04024bce400ad128c8cd6.r2.dev/hunyuan-video-fast-demo.mp4" />


# 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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="extra" type="object" required={false}>
  Optional extra parameters for the request.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="response_image_type" type="string" required={false}>
      The returned image type. Default is png.<br />
      Enum: `png`, `webp`, `jpeg`
    </ParamField>

    <ParamField body="webhook" type="object" required={false}>
      Webhook settings. More details can be found at [Webhook Documentation](/api-reference/model-apis-webhook).

      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="url" type="string" required={true}>
          The URL of the webhook endpoint. Novita AI will send the task generated outputs to your specified webhook endpoint.
        </ParamField>

        <ParamField body="test_mode" type="object" required={false}>
          By specifying Test Mode, a mock event will be sent to the webhook endpoint.

          <Expandable title="properties" defaultOpen={false}>
            <ParamField body="enabled" type="boolean" required={true}>
              Set to true to enable Test Mode, or false to disable it. The default is false.
            </ParamField>

            <ParamField body="return_task_status" type="string" required={true}>
              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 body="custom_storage" type="object" required={false}>
      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" defaultOpen={false}>
        <ParamField body="aws_s3" type="object" required={false}>
          AWS S3 Bucket settings.

          <Expandable title="properties" defaultOpen={false}>
            <ParamField body="region" type="string" required={true}>
              AWS S3 regions, <a href="https://docs.aws.amazon.com/general/latest/gr/rande.html" target="_blank">more details</a>.
            </ParamField>

            <ParamField body="bucket" type="string" required={true}>
              AWS S3 bucket name.
            </ParamField>

            <ParamField body="path" type="string" required={true}>
              AWS S3 bucket path for saving generated outputs.
            </ParamField>

            <ParamField body="save_to_path_directly" type="boolean" required={false}>
              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 body="enterprise_plan" type="object" required={false}>
      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" defaultOpen={false}>
        <ParamField body="enabled" type="boolean" required={false}>
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="enable_nsfw_detection" type="boolean" required={false}>
      When set to true, NSFW detection will be enabled, incurring an additional cost of \$0.0015 for each generated image.
    </ParamField>

    <ParamField body="nsfw_detection_level" type="integer" required={false}>
      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 body="request" type="object" required={true}>
  <Expandable title="properties" defaultOpen={true}>
    <ParamField body="model_name" type="string" required={true}>
      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" target="_blank">Query Model</a> API with filter.types=checkpoint as the query parameter.
    </ParamField>

    <ParamField body="image_base64" type="string" required={true}>
      The base64 of original image, with a maximum resolution of 16 megapixels and a maximum file size of 10 Mb.
    </ParamField>

    <ParamField body="prompt" type="string" required={true}>
      Text input required to guide the image generation, divided by `,` . Range \[1, 1024].
    </ParamField>

    <ParamField body="width" type="integer" required={true}>
      Width of image. Range \[128, 2048].
    </ParamField>

    <ParamField body="height" type="integer" required={true}>
      Height of image. Range \[128, 2048].
    </ParamField>

    <ParamField body="image_num" type="integer" required={true}>
      Images numbers generated in one single generation. Range \[1, 8].
    </ParamField>

    <ParamField body="steps" type="integer" required={true}>
      The number of denoising steps. More steps usually can produce higher quality images, but take more time to generate, Range \[1, 100].
    </ParamField>

    <ParamField body="guidance_scale" type="number(float32)" required={true}>
      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 body="sampler_name" type="string" required={true}>
      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 body="negative_prompt" type="string" required={false}>
      Text input that specifies what to exclude from the generated images, divided by `,` . Range \[1, 1024].
    </ParamField>

    <ParamField body="sd_vae" type="string" required={false}>
      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 body="controlnet" type="object" required={false}>
      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" defaultOpen={false}>
        <ParamField body="units" type="object[]" required={true}>
          <Expandable title="properties" defaultOpen={true}>
            <ParamField body="model_name" type="string" required={true}>
              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 body="image_base64" type="string" required={true}>
              base64 of input controlNet image
            </ParamField>

            <ParamField body="strength" type="number(float32)" required={true}>
              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 body="preprocessor" type="string" required={false}>
              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 body="guidance_start" type="number(float32)" required={false}>
              Ratio of generation where this unit starts to impact the process. Range \[0, 1].
            </ParamField>

            <ParamField body="guidance_end" type="number(float32)" required={false}>
              Ratio of generation where this unit stops impacting the process. Range \[0, 1].
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="seed" type="integer" required={false}>
      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 body="loras" type="object[]" required={false}>
      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" defaultOpen={false}>
        <ParamField body="model_name" type="string" required={true}>
          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 body="strength" type="number(float32)" required={true}>
          The strength value of lora. The larger the value, the more biased the effect is towards lora, Range \[0, 1]
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="embeddings" type="object[]" required={false}>
      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" defaultOpen={false}>
        <ParamField body="model_name" type="string" required={true}>
          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 body="clip_skip" type="integer" required={false}>
      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 body="strength" type="number(float)¦null" required={false}>
      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 body="ip_adapters" type="object[]" required={false}>
      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" defaultOpen={false}>
        <ParamField body="model_name" type="string" required={true}>
          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 body="image_base64" type="string" required={true}>
          The base64 decoded content for input image.
        </ParamField>

        <ParamField body="strength" type="number(float)" required={true}>
          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" required={false}>
  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
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
{
    "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
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
{
    "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
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
{
    "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
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
{
    "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
"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
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
{
    "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
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
{
    "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
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
{
    "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
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
{
    "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 header="Authorization" type="string" required={true} />

## Request Body

<ParamField body="extra" type="object" required={false}>
  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="enable_nsfw_detection" type="boolean" required={false}>
      When set to true, NSFW detection will be enabled, incurring an additional cost of \$0.0015 for each generated image.
    </ParamField>

    <ParamField body="nsfw_detection_level" type="integer" required={false}>
      \*\*\* 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 body="enable_progress_info" type="boolean¦null" required={false}>
      You will receive empty preview images after setting enable\_progress\_info to false.
    </ParamField>

    <ParamField body="response_image_type" type="string" required={false}>
      The format of returned images, default: `png`<br />
      Enum: `png`, `jpeg`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="prompt" type="string¦null" required={true}>
  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 body="negative_prompt" type="string¦null" required={false}>
  Negative prompt words, separated by commas.
</ParamField>

<ParamField body="sampler_name" type="string¦null" required={true}>
  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 body="batch_size" type="integer¦null" required={true}>
  Number of images generated in a single generation. Range: \[0, 8]
</ParamField>

<ParamField body="n_iter" type="integer¦null" required={true}>
  Number of generations. Range: \[0, 8]
</ParamField>

<ParamField body="steps" type="integer¦null" required={true}>
  Think of steps as iterations of the image creation process. Range: (0, 50]
</ParamField>

<ParamField body="cfg_scale" type="number¦null" required={true}>
  This setting indicates how closely Stable Diffusion will adhere to your prompt. Range: (0, 30]
</ParamField>

<ParamField body="seed" type="integer¦null" required={false}>
  A seed is a number from which Stable Diffusion generates noise.
</ParamField>

<ParamField body="height" type="integer" required={true}>
  Height of the image. Range: (0, 2048]
</ParamField>

<ParamField body="width" type="integer" required={true}>
  Width of the image. Range: (0, 2048]
</ParamField>

<ParamField body="model_name" type="string" required={true}>
  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 body="init_images" type="string[]" required={true} />

<ParamField body="denoising_strength" type="number¦null" required={false}>
  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 body="restore_faces" type="boolean¦null" required={false}>
  Enable Stable Diffusion restore faces plugin.
</ParamField>

<ParamField body="sd_vae" type="string¦null" required={false}>
  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 body="clip_skip" type="integer¦null" required={false}>
  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 body="mask" type="string" required={false}>
  Base64 of png, mask of inpaintings.
</ParamField>

<ParamField body="mask_blur" type="integer" required={false}>
  Sets the degree of blurring of the border of the filled area.
</ParamField>

<ParamField body="resize_mode" type="integer¦null" required={false}>
  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 body="image_cfg_scale" type="integer¦null" required={false}>
  Image cfg scale
</ParamField>

<ParamField body="inpainting_fill" type="integer¦null" required={false}>
  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 body="inpaint_full_res" type="integer¦null" required={false}>
  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 body="inpaint_full_res_padding" type="integer¦null" required={false}>
  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 body="inpainting_mask_invert" type="integer" required={false}>
  Specify whether to invert the mask. 0 - Inpaint Masked 1 - Inpaint Not Masked<br />
  Enum: `0`, `1`
</ParamField>

<ParamField body="initial_noise_multiplier" type="number" required={false}>
  Noise multiplier for img2img in settings. This scaling factor is applied to the random latent tensor for img2img. Lowering it reduces flickering.
</ParamField>

<ParamField body="img_expire_ttl" type="integer" required={false}>
  Image storage time (seconds). Range \[0, 604800]
</ParamField>

<ParamField body="sd_refiner" type="object" required={false}>
  Refiner infos to enhances the image details.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="checkpoint" type="string" required={true}>
      Refiner checkpoint name. Currently only `sd_xl_refiner_1.0.safetensors` supported.<br />
      Enum: `sd_xl_refiner_1.0.safetensors`
    </ParamField>

    <ParamField body="switch_at" type="number" required={true}>
      Weight of refiner. From 0 to 1
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="controlnet_units" type="object[]¦null" required={false}>
  ControlNet.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="model" type="string" required={true}>
      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 body="weight" type="number¦null" required={true}>
      weight of this unit. defaults to 1
    </ParamField>

    <ParamField body="input_image" type="string" required={true}>
      base64 of input image
    </ParamField>

    <ParamField body="module" type="string" required={true}>
      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 body="control_mode" type="integer¦null" required={true}>
      0 for Balanced,1 for My prompt is more important 2 for ControlNet is more important<br />
      Enum: `0`, `1`, `2`
    </ParamField>

    <ParamField body="mask" type="string¦null" required={false}>
      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 body="resize_mode" type="integer¦null" required={false}>
      How to resize the input image so as to fit the output resolution of the generation.<br />
      Enum: `0`, `1`, `2`
    </ParamField>

    <ParamField body="processor_res" type="integer¦null" required={false}>
      Resolution of the preprocessor.
    </ParamField>

    <ParamField body="threshold_a" type="integer¦null" required={false}>
      First parameter of the preprocessor, only takes effect when preprocessor accepts arguments.
    </ParamField>

    <ParamField body="threshold_b" type="integer¦null" required={false}>
      Second parameter of the preprocessor, only takes effect when preprocessor accepts arguments.
    </ParamField>

    <ParamField body="guidance_start" type="number¦null" required={false}>
      ratio of generation where this unit starts to have an effect.
    </ParamField>

    <ParamField body="guidance_end" type="number¦null" required={false}>
      ratio of generation where this unit stops to have an effect.
    </ParamField>

    <ParamField body="pixel_perfect" type="boolean¦null" required={false}>
      Enable pixel-perfect preprocessor, when set to false, it means not to resize images.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="code" type="integer" required={false} />

<ResponseField name="msg" type="string" required={false} />

<ResponseField name="data" type="object" required={false}>
  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="task_id" type="string" required={false} />

    <ResponseField name="warn" type="string" required={false} />
  </Expandable>
</ResponseField>

## Example

request

```bash
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
{
  "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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="image_file" type="string" required={true}>
  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" required={false}>
  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
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 src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/img2prompt.png" />
</Frame>

`Response:`

```js
{
    "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 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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="extra" type="object" required={false}>
  Optional extra parameters for the request.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="response_video_type" type="string" required={false}>
      The returned video type. Default is mp4.Enum: `mp4, gif`
    </ParamField>

    <ParamField body="webhook" type="object" required={false}>
      Webhook settings. More details can be found at [Webhook Documentation](/api-reference/model-apis-webhook).

      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="url" type="string" required={true}>
          The URL of the webhook endpoint. Novita AI will send the task generated outputs to your specified webhook endpoint.
        </ParamField>

        <ParamField body="test_mode" type="object" required={false}>
          By specifying Test Mode, a mock event will be sent to the webhook endpoint.

          <Expandable title="properties" defaultOpen={false}>
            <ParamField body="enabled" type="boolean" required={true}>
              Set to true to enable Test Mode, or false to disable it. The default is false.
            </ParamField>

            <ParamField body="return_task_status" type="string" required={true}>
              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 body="enterprise_plan" type="object" required={false}>
      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" defaultOpen={false}>
        <ParamField body="enabled" type="boolean" required={false}>
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="model_name" type="string" required={true}>
  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 body="image_file" type="string" required={true}>
  The base64 of input image, with a maximum resolution of 2048 x 2048 and a maximum file size of 30 Mb.
</ParamField>

<ParamField body="frames_num" type="integer" required={true}>
  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 body="frames_per_second" type="integer" required={true}>
  Frames per second; the larger the frame rate, the smoother the video. Currently, only the number 6 is supported.
</ParamField>

<ParamField body="image_file_resize_mode" type="string" required={true}>
  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 body="steps" type="integer" required={true}>
  The number of denoising steps. More steps usually produce higher quality content, but take more time to generate. Range \[1, 50].
</ParamField>

<ParamField body="seed" type="integer" required={false}>
  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 body="motion_bucket_id" type="integer" required={false}>
  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 body="cond_aug" type="number" required={false}>
  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 body="enable_frame_interpolation" type="boolean" required={false}>
  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" required={false}>
  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
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
{
    "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
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
{
    "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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="extra" type="object" required={false}>
  Optional extra parameters for the request.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="response_image_type" type="string" required={false}>
      The returned image type. Default is png.<br />
      Enum: `png`, `webp`, `jpeg`
    </ParamField>

    <ParamField body="webhook" type="object" required={false}>
      Webhook settings. More details can be found at [Webhook Documentation](/api-reference/model-apis-webhook).

      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="url" type="string" required={true}>
          The URL of the webhook endpoint. Novita AI will send the task generated outputs to your specified webhook endpoint.
        </ParamField>

        <ParamField body="test_mode" type="object" required={false}>
          By specifying Test Mode, a mock event will be sent to the webhook endpoint.

          <Expandable title="properties" defaultOpen={false}>
            <ParamField body="enabled" type="boolean" required={true}>
              Set to true to enable Test Mode, or false to disable it. The default is false.
            </ParamField>

            <ParamField body="return_task_status" type="string" required={true}>
              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 body="custom_storage" type="object" required={false}>
      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" defaultOpen={false}>
        <ParamField body="aws_s3" type="object" required={false}>
          AWS S3 Bucket settings.

          <Expandable title="properties" defaultOpen={false}>
            <ParamField body="region" type="string" required={true}>
              AWS S3 regions, <a href="https://docs.aws.amazon.com/general/latest/gr/rande.html" target="_blank">more details</a>.
            </ParamField>

            <ParamField body="bucket" type="string" required={true}>
              AWS S3 bucket name.
            </ParamField>

            <ParamField body="path" type="string" required={true}>
              AWS S3 bucket path for saving generated outputs.
            </ParamField>

            <ParamField body="save_to_path_directly" type="boolean" required={false}>
              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 body="enterprise_plan" type="object" required={false}>
      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" defaultOpen={false}>
        <ParamField body="enabled" type="boolean" required={false}>
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="enable_nsfw_detection" type="boolean" required={false}>
      When set to true, NSFW detection will be enabled, incurring an additional cost of \$0.0015 for each generated image.
    </ParamField>

    <ParamField body="nsfw_detection_level" type="integer" required={false}>
      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 body="request" type="object" required={true}>
  <Expandable title="properties" defaultOpen={true}>
    <ParamField body="model_name" type="string" required={true}>
      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" target="_blank">Query Model</a> API with filter.types=checkpoint\&filter.is\_inpainting=true as the query parameter.
    </ParamField>

    <ParamField body="image_base64" type="string" required={true}>
      The base64 representation of the original image, with a maximum resolution of 16 megapixels and a maximum file size of 30 Mb.
    </ParamField>

    <ParamField body="mask_image_base64" type="string" required={true}>
      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 body="prompt" type="string" required={true}>
      Text input required to guide the image generation, divided by `,` . Range \[1, 1024].
    </ParamField>

    <ParamField body="image_num" type="integer" required={true}>
      Images numbers generated in one single generation. Range \[1, 8].
    </ParamField>

    <ParamField body="steps" type="integer" required={true}>
      The number of denoising steps. More steps usually can produce higher quality images, but take more time to generate, Range \[1, 100].
    </ParamField>

    <ParamField body="guidance_scale" type="number(float32)" required={true}>
      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 body="sampler_name" type="string" required={true}>
      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 body="mask_blur" type="integer" required={false}>
      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 body="negative_prompt" type="string" required={false}>
      Text input that specifies what to exclude from the generated images, divided by `,` . Range \[1, 1024].
    </ParamField>

    <ParamField body="sd_vae" type="string" required={false}>
      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 body="seed" type="integer" required={false}>
      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 body="loras" type="object[]" required={false}>
      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" defaultOpen={false}>
        <ParamField body="model_name" type="string" required={true}>
          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 body="strength" type="number(float32)" required={true}>
          The strength value of lora. The larger the value, the more biased the effect is towards lora, Range \[0, 1]
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="embeddings" type="object[]" required={false}>
      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" defaultOpen={false}>
        <ParamField body="model_name" type="string" required={true}>
          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 body="clip_skip" type="integer" required={false}>
      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 body="strength" type="number(float)¦null" required={false}>
      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 body="inpainting_full_res" type="integer" required={false}>
      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 body="inpainting_full_res_padding" type="integer" required={false}>
      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 body="inpainting_mask_invert" type="integer" required={false}>
      Specifies whether to invert the mask. Set to 1 to invert the mask. Default is 0.<br />
      Enum: `0`, `1`
    </ParamField>

    <ParamField body="initial_noise_multiplier" type="number(float32)" required={false}>
      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" required={false}>
  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 height="410" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/inpainting-01.jpg" />
</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
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
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
{
    "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
{
    "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 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 header="Content-Type" type="string" required={true}>
  Supports: `application/json`
</ParamField>

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

## Request Body

<ParamField body="mode" type="string" required={false}>
  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 body="image_url" type="string" required={true}>
  The URL of the start frame image to be used for video generation.
</ParamField>

<ParamField body="end_image_url" type="string" required={false}>
  The URL of the end frame image to be used for video generation.

  <Warning>Only available when `mode` is `Professional`.</Warning>
</ParamField>

<ParamField body="prompt" type="string" required={true}>
  Prompt text required to guide the generation.

  Range: `1 <= x <= 2000`.
</ParamField>

<ParamField body="negative_prompt" type="string" required={false}>
  Negative prompts instruct the model on what elements to avoid generating.

  Range: `0 <= x <= 2000`.
</ParamField>

<ParamField body="duration" type="integer" required={false}>
  The length of the generated video in seconds. Default: `5`.<br />
  Optional values: `5`, `10`
</ParamField>

<ParamField body="guidance_scale" type="float" required={false}>
  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" required={true}>
  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
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
{
    "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
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id={Returned Task ID}' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js
{
    "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 controls className="w-full aspect-video" src="https://pub-f964a1c641c04024bce400ad128c8cd6.r2.dev/kling-v1.6-i2v-result.mp4" />


# 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 header="Content-Type" type="string" required={true}>
  Supports: `application/json`
</ParamField>

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

## Request Body

<ParamField body="mode" type="string" required={false}>
  The mode of the video generation.

  Supports:

  * `Standard`: fast creation, lower cost, and generate 720p video.

  Default: `Standard`.
</ParamField>

<ParamField body="prompt" type="string" required={true}>
  Prompt text required to guide the generation.

  Range: `1 <= x <= 2000`.
</ParamField>

<ParamField body="negative_prompt" type="string" required={false}>
  Negative prompts instruct the model on what elements to avoid generating.

  Range: `0 <= x <= 2000`.
</ParamField>

<ParamField body="duration" type="integer" required={false}>
  The length of the generated video in seconds. Default: `5`.<br />
  Optional values: `5`, `10`
</ParamField>

<ParamField body="guidance_scale" type="float" required={false}>
  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" required={true}>
  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
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
{
    "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
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id={Returned Task ID}' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js
{
    "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 controls className="w-full aspect-video" src="https://pub-f964a1c641c04024bce400ad128c8cd6.r2.dev/kling-v1.6-t2v-result.mp4" />


# 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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Query Parameters

<ParamField query="pagination.limit" type="integer" required={false}>
  The number of model records to query per request, within the range (0, 100].
</ParamField>

<ParamField query="pagination.cursor" type="string" required={false}>
  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[]" required={false}>
  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="task_name" type="string" required={false}>
      The name of the training task.
    </ResponseField>

    <ResponseField name="task_id" type="string" required={false}>
      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" required={false}>
      The type of the training task.
    </ResponseField>

    <ResponseField name="task_status" type="string" required={false}>
      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" required={false}>
      The timestamp of when the task was created.
    </ResponseField>

    <ResponseField name="models" type="object[]" required={false}>
      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="model_name" type="string" required={false}>
          The name of the model.
        </ResponseField>

        <ResponseField name="model_status" type="string" required={false}>
          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" required={false}>
  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="next_cursor" type="string" required={false} />
  </Expandable>
</ResponseField>

## Example

In this step, we can obtain all the information about trained models.

```bash
curl --location --request GET 'https://api.novita.ai/v3/training?pagination.limit=10&pagination.cursor=c_0' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js
{
    "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`.


# Create chat completion
Source: https://novita.ai/docs/api-reference/model-apis-llm-create-chat-completion

POST https://api.novita.ai/v3/openai/chat/completions

Creates a model response for the given chat conversation.

## Request Headers

<ParamField header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="model" type="string" required={true}>
  The name of the model to use.
</ParamField>

<ParamField body="messages" type="object[]" required={true}>
  A list of messages comprising the conversation so far.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="content" type="string | null" required={true}>
      The contents of the message. content is required for all messages, and may be null for assistant messages with function calls.
    </ParamField>

    <ParamField body="role" type="string" required={true}>
      The role of the messages author. One of system, user, or assistant.

      Enum: `system`, `user`, `assistant`
    </ParamField>

    <ParamField body="name" 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 body="max_tokens" type="integer" required={true}>
  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 body="stream" type="boolean | null" default={false}>
  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 body="stream_options" type="object | null">
  Options for streaming response. Only set this when you set stream: true.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="include_usage" 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 body="n" type="integer | null" default={1}>
  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 body="seed" 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 body="frequency_penalty" type="number | null" default={0}>
  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 body="presence_penalty" type="number | null" default={0}>
  Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.

  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 body="repetition_penalty" 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 body="stop" 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 body="temperature" type="number | null" default={1}>
  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 body="top_p" 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 body="top_k" 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 body="min_p" 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 body="logit_bias" type="map[string, integer] | null" required={false}>
  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 body="logprobs" type="boolean | null" default={false}>
  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 body="top_logprobs" 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 body="tools" 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" defaultOpen={false}>
    <ParamField body="type" type="string" required={true}>
      The type of the tool.

      Supported types: `function`
    </ParamField>

    <ParamField body="function" type="object" required={true}>
      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="name" type="string" required={true}>
          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 body="description" 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 body="parameters" 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 body="strict" type="boolean" default={false}>
          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 body="response_format" 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" defaultOpen={false}>
    <ParamField body="type" type="string" required={true} default="text">
      Enum: `text`, `json_object`, `json_schema`
    </ParamField>

    <ParamField body="json_schema" 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" defaultOpen={false}>
        <ParamField body="name" type="string" required={true}>
          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 body="description" 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 body="schema" 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 body="strict" type="boolean" default={false}>
          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 body="separate_reasoning" type="boolean | null" default={false}>
  Whether to separate the reasoning from the "content" into "reasoning\_content" field.

  Supported models: `deepseek/deepseek-r1-turbo`.
</ParamField>

## Response

<ResponseField name="choices" type="object[]" required={true}>
  The list of chat completion choices.

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="finish_reason" type="string" required={true}>
      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" required={true}>
      The index of the chat completion choice.
    </ResponseField>

    <ResponseField name="message" type="object" required={true}>
      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="role" type="string" required={true}>
          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.

          Supported models: `deepseek/deepseek-r1-turbo`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created" type="integer" required={true}>
  The Unix time in seconds when the response was generated.
</ResponseField>

<ResponseField name="id" type="string" required={true}>
  A unique identifier of the response.
</ResponseField>

<ResponseField name="model" type="string" required={true}>
  The model used for the chat completion.
</ResponseField>

<ResponseField name="object" type="string" required={true}>
  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" defaultOpen={false}>
    <ResponseField name="completion_tokens" type="integer" required={true}>
      The number of tokens in the generated completion.
    </ResponseField>

    <ResponseField name="prompt_tokens" type="integer" required={true}>
      The number of tokens in the prompt.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer" required={true}>
      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/v3/openai/completions

Creates a completion for the provided prompt and parameters.

## Request Headers

<ParamField header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="model" type="string" required={true}>
  The name of the model to use.
</ParamField>

<ParamField body="prompt" type="string" required={true}>
  The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays.
</ParamField>

<ParamField body="max_tokens" type="integer" required={false}>
  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 body="stream" type="boolean | null" default={false}>
  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 body="stream_options" type="object | null">
  Options for streaming response. Only set this when you set stream: true.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="include_usage" 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 body="n" type="integer | null" default={1}>
  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 body="seed" 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 body="frequency_penalty" type="number | null" default={0}>
  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 body="presence_penalty" type="number | null" default={0}>
  Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.

  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 body="repetition_penalty" 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 body="stop" 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 body="temperature" type="number | null" default={1}>
  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 body="top_p" 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 body="top_k" 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 body="min_p" 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 body="logit_bias" type="map[string, integer] | null" required={false}>
  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 body="logprobs" type="integer | 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.

  The maximum value for logprobs is 5.
</ParamField>

<ParamField body="best_of" type="integer" required={false}>
  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" required={true}>
  The list of generated completion choices.

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="finish_reason" type="string" required={true}>
      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" required={true}>
      The index of the completion choice.
    </ResponseField>

    <ResponseField name="logprobs" type="object" required={true}>
      The log probabilities of the most likely tokens.

      <Expandable title="properties" defaultOpen={false}>
        <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" defaultOpen={false}>
            <ResponseField name="{key}" type="integer" required={true}>
              Log probability value for the given key.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="text" type="string" required={true}>
      The completion response.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created" type="integer" required={true}>
  The Unix time in seconds when the response was generated.
</ResponseField>

<ResponseField name="id" type="string" required={true}>
  A unique identifier of the response.
</ResponseField>

<ResponseField name="model" type="string" required={true}>
  The model used for the completion.
</ResponseField>

<ResponseField name="object" type="string" required={true}>
  The object type, which is always `text_completion`.
</ResponseField>

<ResponseField name="usage" type="object" required={true}>
  Usage statistics.

  For streaming responses, usage field is included in the very last response chunk returned.

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="completion_tokens" type="integer" required={true}>
      The number of tokens in the generated completion.
    </ResponseField>

    <ResponseField name="prompt_tokens" type="integer" required={true}>
      The number of tokens in the prompt.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer" required={true}>
      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/v3/openai/embeddings

Creates an embedding vector representing the input text.

## Request Headers

<ParamField header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="input" type="string | arrary" required={true}>
  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 body="model" type="enum<string>" required={true}>
  ID of the model to use. Enum: `baai/bge-m3`.
</ParamField>

<ParamField body="encoding_format" type="string" required={false}>
  The format to return the embeddings in. Can be either float or base64.
</ParamField>

## Response

<ResponseField name="object" type="string" required={true}>
  Fixed as list
</ResponseField>

<ResponseField name="data" type="array" required={true}>
  List of embeddings vectors generated by the model.

  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="index" type="integer" required={true}>
      The index of the embedding vector.
    </ResponseField>

    <ResponseField name="embedding" type="array" required={true}>
      The embedding vector.
    </ResponseField>

    <ResponseField name="object" type="string" required={true}>
      Fixed as embedding
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="model" type="string" required={true}>
  The ID of the model used.
</ResponseField>

<ResponseField name="usage" type="object" required={true}>
  Usage information.

  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="prompt_tokens" type="integer" required={true}>
      The number of prompt tokens.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer" required={true}>
      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/v3/openai/rerank

Creates a rerank request.

## Request Headers

<ParamField header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="model" type="string" required={true}>
  The name of the model to use.
</ParamField>

<ParamField body="query" type="string" required={true}>
  The search query.
</ParamField>

<ParamField body="documents" type="string[]" required={true}>
  Document List.
</ParamField>

<ParamField body="top_n" type="integer" required={false}>
  Number of most relevant documents or indices to return.
</ParamField>

## Response

<ResponseField name="id" type="string" required={true}>
  ID
</ResponseField>

<ResponseField name="results" type="object[]" required={true}>
  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="document" type="object">
      Original document content.

      <Expandable title="properties" defaultOpen={false}>
        <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" defaultOpen={false}>
    <ResponseField name="completion_tokens" type="integer" required={true}>
      The number of tokens in the generated completion.
    </ResponseField>

    <ResponseField name="prompt_tokens" type="integer" required={true}>
      The number of tokens in the prompt.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer" required={true}>
      The total number of tokens used in the request (prompt + completion).
    </ResponseField>
  </Expandable>
</ResponseField>


# List models
Source: https://novita.ai/docs/api-reference/model-apis-llm-list-models

GET https://api.novita.ai/v3/openai/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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Response

<ResponseExample>
  ```json
  {
    "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" required={true}>
  Array of model objects with the following properties:

  <Expandable title="Model Object Properties">
    <ResponseField name="id" type="string" required={true}>
      The model identifier, which can be referenced in the API endpoints.
    </ResponseField>

    <ResponseField name="created" type="integer" required={true}>
      The Unix timestamp (in seconds) when the model was created.
    </ResponseField>

    <ResponseField name="object" type="string" required={true}>
      The object type, which is always "model".
    </ResponseField>

    <ResponseField name="input_token_price_per_m" type="integer" required={true}>
      The price per million input tokens.
    </ResponseField>

    <ResponseField name="output_token_price_per_m" type="integer" required={true}>
      The price per million output tokens.
    </ResponseField>

    <ResponseField name="title" type="string" required={true}>
      The title of the model.
    </ResponseField>

    <ResponseField name="description" type="string" required={true}>
      The description of the model.
    </ResponseField>

    <ResponseField name="context_size" type="integer" required={true}>
      The maximum context size of the model.
    </ResponseField>
  </Expandable>
</ResponseField>


# Retrieve model
Source: https://novita.ai/docs/api-reference/model-apis-llm-retrieve-model

GET https://api.novita.ai/v3/openai/models/{model}

Retrieves a model instance, providing basic information about the model. This endpoint is compatible with OpenAI API.

## Request Headers

<ParamField header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Path Parameters

<ParamField path="model" type="string" required={true}>
  The ID of the model to use for this request.
</ParamField>

## Response

<ResponseExample>
  ```json
  {
    "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" required={true}>
  The model identifier, which can be referenced in the API endpoints.
</ResponseField>

<ResponseField name="created" type="integer" required={true}>
  The Unix timestamp (in seconds) when the model was created.
</ResponseField>

<ResponseField name="object" type="string" required={true}>
  The object type, which is always "model".
</ResponseField>

<ResponseField name="input_token_price_per_m" type="integer" required={true}>
  The price per million input tokens.
</ResponseField>

<ResponseField name="output_token_price_per_m" type="integer" required={true}>
  The price per million output tokens.
</ResponseField>

<ResponseField name="title" type="string" required={true}>
  The title of the model.
</ResponseField>

<ResponseField name="description" type="string" required={true}>
  The description of the model.
</ResponseField>

<ResponseField name="context_size" type="integer" required={true}>
  The maximum context size of the model.
</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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="extra" type="object" required={false}>
  Optional extra parameters for the request.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="response_image_type" type="string" required={false}>
      The returned image type. Default is png.<br />
      Enum: `png`, `webp`, `jpeg`
    </ParamField>

    <ParamField body="enterprise_plan" type="object" required={false}>
      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" defaultOpen={false}>
        <ParamField body="enabled" type="boolean" required={false}>
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="face_image_file" type="string" required={true}>
  The base64-encoded face image, with a maximum resolution of 2048 x 2048 and a maximum file size of 30 MB.
</ParamField>

<ParamField body="image_file" type="string" required={true}>
  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" required={false}>
  The Base64-encoded content of the returned image.
</ResponseField>

<ResponseField name="image_type" type="string" required={false}>
  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
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
{
    "image_file": "{{Base64 encoded image}}",
    "image_type": "png"
}
```

<Frame>
  <img src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/mergeface01.png" />
</Frame>

<Frame>
  <img src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/mergeface02.png" />
</Frame>

<Frame>
  <img src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/mergeface03.png" />
</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 header="Content-Type" type="string" required={true}>
  Supports: `application/json`
</ParamField>

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

## Request Body

<ParamField body="prompt" type="string" required={true}>
  Prompt text required to guide the generation.

  Range: `1 <= x <= 2000`.
</ParamField>

<ParamField body="image_url" type="string" required={false}>
  The URL of the first frame image to be used for video generation.
</ParamField>

<ParamField body="duration" type="integer" required={false}>
  The length of the generated video in seconds. Default: `6`<br />
  Optional values: `6`, `10`
</ParamField>

<ParamField body="resolution" type="string" required={false}>
  The resolution of the generated video. Default: `768P`

  * For 6-second videos: supports `768P`, `1080P`
  * For 10-second videos: supports `768P` only
</ParamField>

<ParamField body="enable_prompt_expansion" type="boolean" required={false}>
  Whether to enable prompt optimization.

  Default: `true`.
</ParamField>

## Response

<ResponseField name="task_id" type="string" required={true}>
  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
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_url": "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
{
    "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
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id={Returned Task ID}' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js
{
    "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 controls className="w-full aspect-video" src="https://doc-assets.novitai.com/minimax-hailuo-video-02-result.mp4" />


# 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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="text" type="string" required={true}>
  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 body="voice_setting" type="object">
  <Expandable title="properties">
    <ParamField body="speed" type="float" default="1.0">
      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 body="vol" type="float" default="1.0">
      Range: (0, 10], default is 1.0

      Controls the volume of the generated audio. Optional. Higher values result in louder audio.
    </ParamField>

    <ParamField body="pitch" type="int" default="0">
      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 body="voice_id" type="string">
      The requested timbre ID. Required (choose either this or timber\_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 body="emotion" 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 body="english_normalization" type="bool" default="false">
      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 body="audio_setting" type="object">
  <Expandable title="properties">
    <ParamField body="sample_rate" type="number" default={32000}>
      Range: \[8000, 16000, 22050, 24000, 32000, 44100]

      The sample rate of the generated audio. Optional, default is 32000.
    </ParamField>

    <ParamField body="bitrate" type="number" default={128000}>
      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 body="format" type="string" default="mp3">
      The audio format of the output. Default is mp3. Options: `mp3`, `pcm`, `flac`, `wav`. wav is only supported for non-streaming output.
    </ParamField>

    <ParamField body="channel" type="number" default={1}>
      Number of audio channels. Default is 1 (mono). Options:

      1: mono

      2: stereo
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="pronunciation_dict" type="object">
  <Expandable title="properties">
    <ParamField body="tone" 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 body="timber_weights" type="object[]">
  Required if voice\_id is not provided (choose one of the two).

  <Expandable title="properties">
    <ParamField body="voice_id" type="string">
      The requested timbre ID. Must be provided together with the weight parameter.
    </ParamField>

    <ParamField body="weight" 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 body="stream" type="boolean" default="false">
  Whether to enable streaming. Default is false, i.e., streaming is disabled.
</ParamField>

<ParamField body="language_boost" type="string" default="null">
  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 body="output_format" type="string" default="hex">
  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>

## 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
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
{
  "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 controls className="w-full h-12 m-t-4" src="https://pub-f964a1c641c04024bce400ad128c8cd6.r2.dev/minimax-speech-02-hd-result.mp3" />

2. Streaming (`stream` is true)

`Request:`

```bash
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
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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="text" type="string" required={true}>
  The text to be synthesized. Maximum length: 50,000 characters.
</ParamField>

<ParamField body="voice_setting" type="object">
  <Expandable title="properties">
    <ParamField body="speed" type="number" default={1.0}>
      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 body="vol" type="number" default={1.0}>
      Range: (0, 10], default is 1.0.

      Controls the volume of the generated audio. Optional. Higher values result in louder audio.
    </ParamField>

    <ParamField body="pitch" type="number" default={0}>
      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 body="voice_id" type="string">
      The requested voice ID. Required (choose either this or timber\_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 body="emotion" 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 body="english_normalization" type="bool" default="false">
      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 body="audio_setting" type="object">
  <Expandable title="properties">
    <ParamField body="sample_rate" type="number" default={32000}>
      Range: \[8000, 16000, 22050, 24000, 32000, 44100]

      The sample rate of the generated audio. Optional, default is 32000.
    </ParamField>

    <ParamField body="bitrate" type="number" default={128000}>
      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 body="format" type="string" default="mp3">
      The audio format of the output. Default is mp3. Options: `mp3`, `pcm`, `flac`, `wav`. wav is only supported for non-streaming output.
    </ParamField>

    <ParamField body="channel" type="number" default={1}>
      Number of audio channels. Default is 1 (mono). Options:

      1: mono

      2: stereo
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="pronunciation_dict" type="object">
  <Expandable title="properties">
    <ParamField body="tone" 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 body="timber_weights" type="object[]">
  Required if voice\_id is not provided (choose one of the two).

  <Expandable title="properties">
    <ParamField body="voice_id" type="string">
      The requested timbre ID. Must be provided together with the weight parameter.
    </ParamField>

    <ParamField body="weight" 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 body="language_boost" type="string" default="null">
  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>

## Response

<ResponseField name="task_id" type="string" required={false}>
  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
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
{
    "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
{
  "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 controls className="w-full h-12 m-t-4" src="https://pub-f964a1c641c04024bce400ad128c8cd6.r2.dev/minimax-speech-02-hd-result.mp3" />


# 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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="text" type="string" required={true}>
  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 body="voice_setting" type="object">
  <Expandable title="properties">
    <ParamField body="speed" type="float" default="1.0">
      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 body="vol" type="float" default="1.0">
      Range: (0, 10], default is 1.0

      Controls the volume of the generated audio. Optional. Higher values result in louder audio.
    </ParamField>

    <ParamField body="pitch" type="int" default="0">
      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 body="voice_id" type="string">
      The requested timbre ID. Required (choose either this or timber\_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 body="emotion" 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 body="english_normalization" type="bool" default="false">
      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 body="audio_setting" type="object">
  <Expandable title="properties">
    <ParamField body="sample_rate" type="number" default={32000}>
      Range: \[8000, 16000, 22050, 24000, 32000, 44100]

      The sample rate of the generated audio. Optional, default is 32000.
    </ParamField>

    <ParamField body="bitrate" type="number" default={128000}>
      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 body="format" type="string" default="mp3">
      The audio format of the output. Default is mp3. Options: `mp3`, `pcm`, `flac`, `wav`. wav is only supported for non-streaming output.
    </ParamField>

    <ParamField body="channel" type="number" default={1}>
      Number of audio channels. Default is 1 (mono). Options:

      1: mono

      2: stereo
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="pronunciation_dict" type="object">
  <Expandable title="properties">
    <ParamField body="tone" 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 body="timber_weights" type="object[]">
  Required if voice\_id is not provided (choose one of the two).

  <Expandable title="properties">
    <ParamField body="voice_id" type="string">
      The requested timbre ID. Must be provided together with the weight parameter.
    </ParamField>

    <ParamField body="weight" 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 body="stream" type="boolean" default="false">
  Whether to enable streaming. Default is false, i.e., streaming is disabled.
</ParamField>

<ParamField body="language_boost" type="string" default="null">
  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 body="output_format" type="string" default="hex">
  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>

## 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
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
{
  "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 controls className="w-full h-12 m-t-4" src="https://pub-f964a1c641c04024bce400ad128c8cd6.r2.dev/minimax-speech-02-turbo-result.mp3" />

2. Streaming (`stream` is true)

`Request:`

```bash
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
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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="text" type="string" required={true}>
  The text to be synthesized. Maximum length: 50,000 characters.
</ParamField>

<ParamField body="voice_setting" type="object">
  <Expandable title="properties">
    <ParamField body="speed" type="number" default={1.0}>
      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 body="vol" type="number" default={1.0}>
      Range: (0, 10], default is 1.0.

      Controls the volume of the generated audio. Optional. Higher values result in louder audio.
    </ParamField>

    <ParamField body="pitch" type="number" default={0}>
      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 body="voice_id" type="string">
      The requested voice ID. Required (choose either this or timber\_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 body="emotion" 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 body="english_normalization" type="bool" default="false">
      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 body="audio_setting" type="object">
  <Expandable title="properties">
    <ParamField body="sample_rate" type="number" default={32000}>
      Range: \[8000, 16000, 22050, 24000, 32000, 44100]

      The sample rate of the generated audio. Optional, default is 32000.
    </ParamField>

    <ParamField body="bitrate" type="number" default={128000}>
      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 body="format" type="string" default="mp3">
      The audio format of the output. Default is mp3. Options: `mp3`, `pcm`, `flac`, `wav`. wav is only supported for non-streaming output.
    </ParamField>

    <ParamField body="channel" type="number" default={1}>
      Number of audio channels. Default is 1 (mono). Options:

      1: mono

      2: stereo
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="pronunciation_dict" type="object">
  <Expandable title="properties">
    <ParamField body="tone" 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 body="timber_weights" type="object[]">
  Required if voice\_id is not provided (choose one of the two).

  <Expandable title="properties">
    <ParamField body="voice_id" type="string">
      The requested timbre ID. Must be provided together with the weight parameter.
    </ParamField>

    <ParamField body="weight" 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 body="language_boost" type="string" default="null">
  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>

## Response

<ResponseField name="task_id" type="string" required={false}>
  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
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
{
    "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
{
  "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 controls className="w-full h-12 m-t-4" src="https://pub-f964a1c641c04024bce400ad128c8cd6.r2.dev/minimax-speech-02-turbo-result.mp3" />


# 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 header="Content-Type" type="string" required={true}>
  Supports: `application/json`
</ParamField>

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

## Request Body

<ParamField body="prompt" type="string" required={true}>
  Prompt text required to guide the generation.

  Range: `1 <= x <= 2000`.
</ParamField>

<ParamField body="image_url" type="string" required={false}>
  The URL of the first frame image to be used for video generation.
</ParamField>

<ParamField body="enable_prompt_expansion" type="boolean" required={false}>
  Whether to enable prompt optimization.

  Default: `true`.
</ParamField>

## Response

<ResponseField name="task_id" type="string" required={true}>
  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
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
{
    "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
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id={Returned Task ID}' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js
{
    "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 controls className="w-full aspect-video" src="https://pub-f964a1c641c04024bce400ad128c8cd6.r2.dev/minimax-video-01-result.mp4" />


# 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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="audio_url" type="string" required={true}>
  The URL of the audio file to be cloned. Supported formats: mp3, m4a, wav.
</ParamField>

<ParamField body="clone_prompt">
  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 body="prompt_audio_url" type="string" required={true}>
      Audio prompt parameter. The URL of the sample audio. Duration must be less than 8 seconds.
    </ParamField>

    <ParamField body="prompt_text" type="string" required={true}>
      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 body="text_validation" type="string">
  Voice cloning parameter. Maximum 200 characters. If this field is provided, the service will compare the audio and the text; if the difference is too large, error code 1043 will be returned.
</ParamField>

<ParamField body="text" 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 body="model" 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`
</ParamField>

<ParamField body="accuracy" 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 body="need_noise_reduction" type="bool">
  Voice cloning parameter. Whether to enable noise reduction. Defaults to false if not specified.
</ParamField>

<ParamField body="need_volume_normalization" 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
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
{
  "demo_audio_url": "https://demo.com/audio.mp3", // Audio sample
  "voice_id": "xxxxxxx" // Generated voice_id
}
```


# 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 header="Authorization" type="string" required={true} />

## Query Parameters

<ParamField query="task_id" type="arraystring[]" required={true}>
  The ID of the task being queried.
</ParamField>

## Response

<ResponseField name="code" type="integer" required={false}>
  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" required={false} />

<ResponseField name="data" type="object" required={false}>
  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="status" type="integer" required={false} />

    <ResponseField name="progress" type="number" required={false} />

    <ResponseField name="eta_relative" type="number" required={false} />

    <ResponseField name="imgs" type="string[]¦null" required={false} />

    <ResponseField name="failed_reason" type="string" required={false} />

    <ResponseField name="current_images" type="string[]" required={false} />

    <ResponseField name="submit_time" type="string" required={false} />

    <ResponseField name="execution_time" type="string" required={false} />

    <ResponseField name="txt2img_time" type="string" required={false} />

    <ResponseField name="finish_time" type="string" required={false} />

    <ResponseField name="info" type="string" required={false} />

    <ResponseField name="enable_nsfw_detection" type="boolean" required={false} />

    <ResponseField name="nsfw_detection_result" type="object[]" required={false}>
      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="valid" type="boolean" required={false} />

        <ResponseField name="confidence" type="number(float32)" required={false} />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

request

```bash
curl --location 'https://api.novita.ai/v2/progress?task_id=' \
--header 'Authorization: Bearer {{API Key}}'
```

response

```json
{
  "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
    }
  }
}
```


# 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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="extra" type="object" required={false}>
  Optional extra parameters for the request.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="response_image_type" type="string" required={false}>
      The returned image type. Default is png.Enum: `png, webp, jpeg`
    </ParamField>

    <ParamField body="enterprise_plan" type="object" required={false}>
      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" defaultOpen={false}>
        <ParamField body="enabled" type="boolean" required={false}>
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="image_file" type="string" required={true}>
  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" required={false}>
  The Base64-encoded content of the returned image.
</ResponseField>

<ResponseField name="image_type" type="string" required={false}>
  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
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
{
    "image_file": "{{Base64 encoded image}}",
    "image_type": "png"
}
```

<Frame>
  <img src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/reimagine_01.png" />
</Frame>

<Frame>
  <img src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/reimagine_02.png" />
</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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="extra" type="object" required={false}>
  Optional extra parameters for the request.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="response_image_type" type="string" required={false}>
      The returned image type. Default is png.<br />
      Enum: `png`, `webp`, `jpeg`
    </ParamField>

    <ParamField body="enterprise_plan" type="object" required={false}>
      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" defaultOpen={false}>
        <ParamField body="enabled" type="boolean" required={false}>
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="image_file" type="string" required={true}>
  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" required={false}>
  The Base64-encoded content of the returned image.
</ResponseField>

<ResponseField name="image_type" type="string" required={false}>
  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
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
{
    "image_file": "{{Base64 encoded image}}",
    "image_type": "png"
}
```

<Frame>
  <img height="390" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/remove_background_01.png" />
</Frame>

<Frame>
  <img height="390" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/remove_background_02.png" />
</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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="extra" type="object" required={false}>
  Optional extra parameters for the request.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="response_image_type" type="string" required={false}>
      The returned image type. Default is png.<br />
      Enum: `png, webp, jpeg`
    </ParamField>

    <ParamField body="enterprise_plan" type="object" required={false}>
      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" defaultOpen={false}>
        <ParamField body="enabled" type="boolean" required={false}>
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="image_file" type="string" required={true}>
  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" required={false}>
  The Base64-encoded content of the returned image.
</ResponseField>

<ResponseField name="image_type" type="string" required={false}>
  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
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
{
    "image_file": "{{Base64 encoded image}}",
    "image_type": "jpeg"
}
```

<Frame>
  <img height="390" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/remove-text01.png" />
</Frame>

<Frame>
  <img height="390" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/remove-text02.jpg" />
</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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="extra" type="object" required={false}>
  Optional extra parameters for the request.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="response_image_type" type="string" required={false}>
      The returned image type. Default is png.Enum: `png, webp, jpeg`
    </ParamField>

    <ParamField body="enterprise_plan" type="object" required={false}>
      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" defaultOpen={false}>
        <ParamField body="enabled" type="boolean" required={false}>
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="image_file" type="string" required={true}>
  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" required={false}>
  The Base64-encoded content of the returned image.
</ResponseField>

<ResponseField name="image_type" type="string" required={false}>
  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
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
{
    "image_file": "{{Base64 encoded image}}",
    "image_type": "png"
}
```

<Frame>
  <img height="420" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/UseCase_replace_background01.png" />
</Frame>

<Frame>
  <img height="420" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/UseCase_replace_background02.png" />
</Frame>


# 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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Query Parameters

<ParamField query="task_id" type="string" required={true}>
  Returned in the 200 response of v3 asynchronous APIs.
</ParamField>

## Response

<ResponseField name="extra" type="object" required={false}>
  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="seed" type="string" required={false}>
      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" required={false}>
      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" required={false}>
      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="request_info" type="string" required={false}>
          Records request parameters for debugging purposes.
        </ResponseField>

        <ResponseField name="submit_time_ms" type="string" required={false}>
          The timestamp (in milliseconds) of when the task was submitted.
        </ResponseField>

        <ResponseField name="execute_time_ms" type="string" required={false}>
          The timestamp (in milliseconds) of when the task started execution.
        </ResponseField>

        <ResponseField name="complete_time_ms" type="string" required={false}>
          The timestamp (in milliseconds) of when the task was completed.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="task" type="object" required={false}>
  Task information.

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="task_id" type="string" required={false}>
      Task ID.
    </ResponseField>

    <ResponseField name="status" type="string" required={false}>
      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" required={false}>
      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" required={false}>
      Specifies the type of task.
    </ResponseField>

    <ResponseField name="eta" type="number" required={false}>
      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" required={false}>
      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[]" required={false}>
  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" defaultOpen={false}>
    <ResponseField name="image_url" type="string" required={false}>
      Image URL.
    </ResponseField>

    <ResponseField name="image_url_ttl" type="integer" required={false}>
      Image expiration time in seconds.
    </ResponseField>

    <ResponseField name="image_type" type="string" required={false}>
      Image type.<br />
      Enum: `jpeg`, `png`, `webp`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="videos" type="object[]" required={false}>
  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" defaultOpen={false}>
    <ResponseField name="video_url" type="string" required={false}>
      Video URL.
    </ResponseField>

    <ResponseField name="video_url_ttl" type="string" required={false}>
      Video expiration time in seconds.
    </ResponseField>

    <ResponseField name="video_type" type="string" required={false}>
      Video type.<br />
      Enum: `mp4`, `gif`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="audios" type="object[]" required={false}>
  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" defaultOpen={false}>
    <ResponseField name="audio_url" type="string" required={false}>
      Audio url.
    </ResponseField>

    <ResponseField name="audio_url_ttl" type="string" required={false}>
      Audio url expire time in seconds.
    </ResponseField>

    <ResponseField name="audio_type" type="string" required={false}>
      Audio type.<br />
      Enum: `wav`
    </ResponseField>

    <ResponseField name="audio_metadata" type="object" required={false}>
      Contains detailed metadata about audio files processed or generated during audio-related tasks.

      <Expandable title="properties" defaultOpen={false}>
        <ResponseField name="text" type="string" required={false} />

        <ResponseField name="start_time" type="float32" required={false}>
          the start\_time of the text in seconds.
        </ResponseField>

        <ResponseField name="end_time" type="float32" required={false}>
          the end\_time of the text in seconds.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

request

```bash
curl --location --globoff 'https://api.novita.ai/v3/async/task-result?task_id={{Novita-TaskID}}' \
--header 'Authorization: Bearer {{API Key}}'
```

response

```json
{
  "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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="extra" type="object" required={false}>
  Optional extra parameters for the request.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="response_image_type" type="string" required={false}>
      The returned image type. Default is png.Enum: `png, webp, jpeg`
    </ParamField>

    <ParamField body="webhook" type="object" required={false}>
      Webhook settings. More details can be found at [Webhook Documentation](/api-reference/model-apis-webhook).

      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="url" type="string" required={true}>
          The URL of the webhook endpoint. Novita AI will send the task generated outputs to your specified webhook endpoint.
        </ParamField>

        <ParamField body="test_mode" type="object" required={false}>
          By specifying Test Mode, a mock event will be sent to the webhook endpoint.

          <Expandable title="properties" defaultOpen={false}>
            <ParamField body="enabled" type="boolean" required={true}>
              Set to true to enable Test Mode, or false to disable it. The default is false.
            </ParamField>

            <ParamField body="return_task_status" type="string" required={true}>
              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 body="custom_storage" type="object" required={false}>
      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" defaultOpen={false}>
        <ParamField body="aws_s3" type="object" required={false}>
          AWS S3 Bucket settings.

          <Expandable title="properties" defaultOpen={false}>
            <ParamField body="region" type="string" required={true}>
              AWS S3 regions, <a href="https://docs.aws.amazon.com/general/latest/gr/rande.html" target="_blank">more details</a>.
            </ParamField>

            <ParamField body="bucket" type="string" required={true}>
              AWS S3 bucket name.
            </ParamField>

            <ParamField body="path" type="string" required={true}>
              AWS S3 bucket path for saving generated outputs.
            </ParamField>

            <ParamField body="save_to_path_directly" type="boolean" required={false}>
              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 body="enterprise_plan" type="object" required={false}>
      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" defaultOpen={false}>
        <ParamField body="enabled" type="boolean" required={false}>
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="enable_nsfw_detection" type="boolean" required={false}>
      When set to true, NSFW detection will be enabled, incurring an additional cost of \$0.0015 for each generated image.
    </ParamField>

    <ParamField body="nsfw_detection_level" type="integer" required={false}>
      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 body="request" type="object" required={true}>
  <Expandable title="properties" defaultOpen={true}>
    <ParamField body="model_name" type="string" required={true}>
      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" target="_blank">Query Model</a> API with filter.types=checkpoint as the query parameter.
    </ParamField>

    <ParamField body="prompt" type="string" required={true}>
      Text input required to guide the image generation, divided by `,` . Range \[1, 1024].
    </ParamField>

    <ParamField body="width" type="integer" required={true}>
      Width of image. Range \[128, 2048].
    </ParamField>

    <ParamField body="height" type="integer" required={true}>
      Height of image. Range \[128, 2048].
    </ParamField>

    <ParamField body="image_num" type="integer" required={true}>
      Images numbers generated in one single generation. Range \[1, 8].
    </ParamField>

    <ParamField body="steps" type="integer" required={true}>
      The number of denoising steps. More steps usually can produce higher quality images, but take more time to generate, Range \[1, 100].
    </ParamField>

    <ParamField body="guidance_scale" type="number(float32)" required={true}>
      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 body="sampler_name" type="string" required={true}>
      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 body="negative_prompt" type="string" required={false}>
      Text input that specifies what to exclude from the generated images, divided by `,` . Range \[1, 1024].
    </ParamField>

    <ParamField body="sd_vae" type="string" required={false}>
      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 body="seed" type="integer" required={false}>
      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 body="loras" type="object[]" required={false}>
      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" defaultOpen={false}>
        <ParamField body="model_name" type="string" required={true}>
          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 body="strength" type="number(float32)" required={true}>
          The strength value of lora. The larger the value, the more biased the effect is towards lora, Range \[0, 1]
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="embeddings" type="object[]" required={false}>
      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" defaultOpen={false}>
        <ParamField body="model_name" type="string" required={true}>
          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 body="hires_fix" type="object" required={false}>
      Upscale images while they are generating.

      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="target_width" type="integer" required={true}>
          Target width, Range \[128, 4096].
        </ParamField>

        <ParamField body="target_height" type="integer" required={true}>
          Target height, Range \[128, 4096].
        </ParamField>

        <ParamField body="strength" type="number(float32)" required={true}>
          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 body="upscaler" type="string" required={false}>
          The `upscaler` model's name.Enum: `RealESRGAN_x4plus_anime_6B,RealESRNet_x4plus,Latent`
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="refiner" type="object" required={false}>
      SD refiner.

      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="switch_at" type="number(float32)" required={true}>
          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 body="enable_transparent_background" type="bool" required={false}>
      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 body="restore_faces" type="bool" required={false}>
      Used to control whether the Face Restoration feature is enabled.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string" required={false}>
  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
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
{
    "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
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
{
	"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
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
{
    "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
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
{
    "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
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
{
    "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
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
{
    "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
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
{
    "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
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
{
    "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
"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
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
{
    "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
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
{
    "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
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
{
    "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
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
{
    "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 header="Authorization" type="string" required={true} />

## Request Body

<ParamField body="extra" type="object" required={false}>
  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="enable_nsfw_detection" type="boolean" required={false}>
      When set to true, NSFW detection will be enabled, incurring an additional cost of \$0.0015 for each generated image.
    </ParamField>

    <ParamField body="nsfw_detection_level" type="integer" required={false}>
      \*\*\* 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 body="enable_progress_info" type="boolean¦null" required={false}>
      You will receive empty preview images if `enable_progress_info` is set to false.
    </ParamField>

    <ParamField body="response_image_type" type="string" required={false}>
      The format of the returned images; default: png<br />
      Enum: `png`, `jpeg`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="prompt" type="string" required={true}>
  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 body="negative_prompt" type="string" required={true}>
  Negative prompt words, separated by `,`.
</ParamField>

<ParamField body="sampler_name" type="string" required={true}>
  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 body="batch_size" type="integer" required={true}>
  The number of images generated in one single generation. Range: \[0, 8]
</ParamField>

<ParamField body="n_iter" type="integer" required={true}>
  The number of generations. Range: \[0, 8]
</ParamField>

<ParamField body="steps" type="integer" required={true}>
  Think of steps as iterations in the image creation process. Range: (0, 50]
</ParamField>

<ParamField body="cfg_scale" type="integer" required={true}>
  This setting determines how closely Stable Diffusion will adhere to your prompt. Range: (0, 30]
</ParamField>

<ParamField body="seed" type="integer" required={true}>
  A seed is a number from which Stable Diffusion generates noise.
</ParamField>

<ParamField body="height" type="integer" required={true}>
  Height of the image. Range: (0, 2048]
</ParamField>

<ParamField body="width" type="integer" required={true}>
  Width of the image. Range: (0, 2048]
</ParamField>

<ParamField body="model_name" type="string" required={true}>
  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 body="restore_faces" type="boolean" required={true}>
  Enable the Stable Diffusion face restoration plugin.
</ParamField>

<ParamField body="restore_faces_model" type="null" required={true} />

<ParamField body="sd_vae" type="string¦null" required={false}>
  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 body="clip_skip" type="integer" required={false}>
  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 body="enable_hr" type="boolean¦null" required={false}>
  Hires.fix function switch.
</ParamField>

<ParamField body="hr_upscaler" type="string¦null" required={false}>
  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 body="hr_scale" type="number¦null" required={false}>
  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 body="hr_resize_x" type="integer¦null" required={false}>
  The target image width, the maximum image size is 2048, only take effect when parameters hr\_scale=1.
</ParamField>

<ParamField body="hr_resize_y" type="integer¦null" required={false}>
  The target image hight, the maximum image size is 2048, only take effect when parameters hr\_scale=1.
</ParamField>

<ParamField body="img_expire_ttl" type="integer¦null" required={false}>
  Image storage time (seconds). Range \[0, 604800]
</ParamField>

<ParamField body="sd_refiner" type="object¦null" required={false}>
  Refiner infos to enhances the image details.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="checkpoint" type="string" required={true}>
      Refiner checkpoint name. Currently only `sd_xl_refiner_1.0.safetensors` supported.<br />
      Enum: `sd_xl_refiner_1.0.safetensors`
    </ParamField>

    <ParamField body="switch_at" type="number" required={true}>
      weight of refiner, from 0 to 1.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="controlnet_units" type="object[]¦null" required={false}>
  ControlNet.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="model" type="string" required={true}>
      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 body="weight" type="number¦null" required={true}>
      weight of this unit. defaults to 1
    </ParamField>

    <ParamField body="input_image" type="string" required={true}>
      base64 of input image
    </ParamField>

    <ParamField body="module" type="string" required={true}>
      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 body="control_mode" type="integer¦null" required={true}>
      0 for Balanced,1 for My prompt is more important 2 for ControlNet is more important<br />
      Enum: `0`, `1`, `2`
    </ParamField>

    <ParamField body="mask" type="string¦null" required={false}>
      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 body="resize_mode" type="integer¦null" required={false}>
      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 body="processor_res" type="integer" required={false}>
      Resolution of the preprocessor.
    </ParamField>

    <ParamField body="threshold_a" type="integer" required={false}>
      First parameter of the preprocessor, only takes effect when preprocessor accepts arguments.
    </ParamField>

    <ParamField body="threshold_b" type="integer" required={false}>
      Second parameter of the preprocessor, only takes effect when preprocessor accepts arguments.
    </ParamField>

    <ParamField body="guidance_start" type="number" required={false}>
      ratio of generation where this unit starts to have an effect.
    </ParamField>

    <ParamField body="guidance_end" type="number" required={false}>
      ratio of generation where this unit stops to have an effect.
    </ParamField>

    <ParamField body="pixel_perfect" type="boolean" required={false}>
      Enable pixel-perfect preprocessor, when set to false, it means not to resize images.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="code" type="integer" required={false} />

<ResponseField name="msg" type="string" required={false} />

<ResponseField name="data" type="object" required={false}>
  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="task_id" type="string" required={false} />

    <ResponseField name="warn" type="string" required={false} />
  </Expandable>
</ResponseField>

## Example

request

```bash
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
{
  "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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="extra" type="object" required={false}>
  Optional extra parameters for the request.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="response_audio_type" type="string" required={false}>
      The returned audio type. Default is wav.<br />
      Enum: `wav`, `mp3`
    </ParamField>

    <ParamField body="webhook" type="object" required={false}>
      Webhook settings. More details can be found at [Webhook Documentation](/api-reference/model-apis-webhook).

      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="url" type="string" required={true}>
          The URL of the webhook endpoint. Novita AI will send the task generated outputs to your specified webhook endpoint.
        </ParamField>

        <ParamField body="test_mode" type="object" required={false}>
          By specifying Test Mode, a mock event will be sent to the webhook endpoint.

          <Expandable title="properties" defaultOpen={false}>
            <ParamField body="enabled" type="boolean" required={true}>
              Set to true to enable Test Mode, or false to disable it. The default is false.
            </ParamField>

            <ParamField body="return_task_status" type="string" required={true}>
              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 body="enterprise_plan" type="object" required={false}>
      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" defaultOpen={false}>
        <ParamField body="enabled" type="boolean" required={false}>
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="request" type="object" required={true}>
  <Expandable title="properties" defaultOpen={true}>
    <ParamField body="voice_id" type="string" required={true}>
      Voice ID<br />
      Enum: `Emily`, `James`, `Olivia`, `Michael`, `Sarah`, `John`
    </ParamField>

    <ParamField body="language" type="string" required={true}>
      Identify the languages spoken in the generated audio<br />
      Enum: `en-US`, `zh-CN`, `ja-JP`
    </ParamField>

    <ParamField body="texts" type="string[]" required={true}>
      Source text for synthetic speech, UTF-8 encoded, supporting a maximum of 512 characters.
    </ParamField>

    <ParamField body="volume" type="number" required={false}>
      Control the volume of the generated audio; select a value between 1.0 and 2.0. The default value is 1.0.
    </ParamField>

    <ParamField body="speed" type="number" required={false}>
      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" required={false}>
  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
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
{
  "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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="extra" type="object" required={false}>
  Optional extra parameters for the request.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="response_video_type" type="string" required={false}>
      The returned video type. Default is mp4.<br />
      Enum: `mp4`, `gif`
    </ParamField>

    <ParamField body="webhook" type="object" required={false}>
      Webhook settings. More details can be found at [Webhook Documentation](/api-reference/model-apis-webhook).

      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="url" type="string" required={true}>
          The URL of the webhook endpoint. Novita AI will send the task generated outputs to your specified webhook endpoint.
        </ParamField>

        <ParamField body="test_mode" type="object" required={false}>
          By specifying Test Mode, a mock event will be sent to the webhook endpoint.

          <Expandable title="properties" defaultOpen={false}>
            <ParamField body="enabled" type="boolean" required={true}>
              Set to true to enable Test Mode, or false to disable it. The default is false.
            </ParamField>

            <ParamField body="return_task_status" type="string" required={true}>
              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 body="enterprise_plan" type="object" required={false}>
      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" defaultOpen={false}>
        <ParamField body="enabled" type="boolean" required={false}>
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="model_name" type="string" required={true}>
  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" target="_blank">Query Model</a> API with filter.types=checkpoint as the query parameter.
</ParamField>

<ParamField body="height" type="integer" required={true}>
  Height of the video, range \[256, 1024]
</ParamField>

<ParamField body="width" type="integer" required={true}>
  Width of the video, range \[256, 1024]
</ParamField>

<ParamField body="steps" type="integer" required={true}>
  The number of denoising steps. More steps usually produce higher quality content but take more time to generate. Range \[1, 50]
</ParamField>

<ParamField body="prompts" type="object[]" required={true}>
  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" defaultOpen={true}>
    <ParamField body="frames" type="integer" required={true}>
      Frames of this video clip, Range \[8, 64]
    </ParamField>

    <ParamField body="prompt" type="string" required={true}>
      Text input required to guide the generation, separated by `,`, Range \[1, 1024].
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="negative_prompt" type="string" required={false}>
  Text input that will not guide the generation, separated by `,`, Range \[1, 1024].
</ParamField>

<ParamField body="guidance_scale" type="number" required={false}>
  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 body="seed" type="integer" required={false}>
  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 body="loras" type="object[]" required={false}>
  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" defaultOpen={false}>
    <ParamField body="model_name" type="string" required={true}>
      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 body="strength" type="number(float32)" required={true}>
      The strength value of lora. The larger the value, the more biased the effect is towards lora, Range \[0, 1]
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="embeddings" type="object[]" required={false}>
  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" defaultOpen={false}>
    <ParamField body="model_name" type="string" required={true}>
      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 body="closed_loop" type="boolean" required={false}>
  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 body="clip_skip" type="integer" required={false}>
  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" required={false}>
  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
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
{
    "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
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
{
    "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 controls className="w-full aspect-video" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/txt2video.mp4" />


# 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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="extra" type="object" required={false}>
  Optional extra parameters for the request.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="response_image_type" type="string" required={false}>
      The returned image type. Default is png.<br />
      Enum: `png`, `webp`, `jpeg`
    </ParamField>

    <ParamField body="webhook" type="object" required={false}>
      Webhook settings. More details can be found at [Webhook Documentation](/api-reference/model-apis-webhook).

      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="url" type="string" required={true}>
          The URL of the webhook endpoint. Novita AI will send the task generated outputs to your specified webhook endpoint.
        </ParamField>

        <ParamField body="test_mode" type="object" required={false}>
          By specifying Test Mode, a mock event will be sent to the webhook endpoint.

          <Expandable title="properties" defaultOpen={false}>
            <ParamField body="enabled" type="boolean" required={true}>
              Set to true to enable Test Mode, or false to disable it. The default is false.
            </ParamField>

            <ParamField body="return_task_status" type="string" required={true}>
              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 body="custom_storage" type="object" required={false}>
      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" defaultOpen={false}>
        <ParamField body="aws_s3" type="object" required={false}>
          AWS S3 Bucket settings.

          <Expandable title="properties" defaultOpen={false}>
            <ParamField body="region" type="string" required={true}>
              AWS S3 regions, <a href="https://docs.aws.amazon.com/general/latest/gr/rande.html" target="_blank">more details</a>.
            </ParamField>

            <ParamField body="bucket" type="string" required={true}>
              AWS S3 bucket name.
            </ParamField>

            <ParamField body="path" type="string" required={true}>
              AWS S3 bucket path for saving generated outputs.
            </ParamField>

            <ParamField body="save_to_path_directly" type="boolean" required={false}>
              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 body="enterprise_plan" type="object" required={false}>
      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" defaultOpen={false}>
        <ParamField body="enabled" type="boolean" required={false}>
          Set to true to schedule this task to use your Dedicated Endpoints's dedicated resources. Default is false.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="enable_nsfw_detection" type="boolean" required={false}>
      When set to true, NSFW detection will be enabled, incurring an additional cost of \$0.0015 for each generated image.
    </ParamField>

    <ParamField body="nsfw_detection_level" type="integer" required={false}>
      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 body="request" type="object" required={true}>
  <Expandable title="properties" defaultOpen={true}>
    <ParamField body="model_name" type="string" required={true}>
      AI upscalers are models trained on massive amounts of data.<br />
      Enum: `RealESRGAN_x4plus_anime_6B`, `RealESRNet_x4plus`, `4x-UltraSharp`
    </ParamField>

    <ParamField body="image_base64" type="string" required={true}>
      The base64 of original image, with a maximum resolution of 2048x2048 and a maximum file size of 30 Mb.
    </ParamField>

    <ParamField body="scale_factor" type="number" required={true}>
      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" required={false}>
  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
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
{
    "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
curl --location 'https://api.novita.ai/v3/async/task-result?task_id=71dd988e-632e-4339-b217-74bcbe6db0ee' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js
{
    "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 src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/upscale01.png" />
</Frame>

<Frame>
  <img src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/upscale02.png" />
</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 header="Authorization" type="string" required={true} />

## Request Body

<ParamField body="image" type="string" required={true}>
  Base64 encoded image
</ParamField>

<ParamField body="upscaler_1" type="string|null" required={false}>
  AI upscalers are models trained with massive amounts of data.
</ParamField>

<ParamField body="resize_mode" type="integer|null" required={false}>
  Resizing mode:
</ParamField>

<ParamField body="upscaling_resize" type="number|null" required={false}>
  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 body="upscaling_resize_w" type="integer|null" required={false}>
  The target image width; the maximum image size is 2048.
</ParamField>

<ParamField body="upscaling_resize_h" type="integer|null" required={false}>
  The target image height; the maximum image size is 2048.
</ParamField>

<ParamField body="upscaling_crop" type="boolean|null" required={false}>
  Zoom in after cropping.
</ParamField>

<ParamField body="upscaler_2" type="string|null" required={false}>
  AI upscalers are models trained with massive amounts of data.
</ParamField>

<ParamField body="extras_upscaler_2_visibility" type="number|null" required={false}>
  Range \[0\~1], Extras upscaler 2 visibility.
</ParamField>

<ParamField body="gfpgan_visibility" type="number|null" required={false}>
  Range \[0\~1], GFPGAN visibility.
</ParamField>

<ParamField body="codeformer_visibility" type="number|null" required={false}>
  Range \[0\~1], CodeFormer visibility.
</ParamField>

<ParamField body="codeformer_weight" type="number|null" required={false}>
  Range \[0\~1], CodeFormer weight (0 = maximum effect, 1 = minimum effect).
</ParamField>

<ParamField body="img_expire_ttl" type="integer" required={false}>
  Image storage time (seconds). Range \[0, 604800].
</ParamField>

## Response

<ResponseField name="code" type="integer" required={false}>
  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" required={false} />

<ResponseField name="data" type="object" required={false}>
  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="task_id" type="string" required={false} />

    <ResponseField name="warn" type="string" required={false} />
  </Expandable>
</ResponseField>

## Example

request

```bash
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
{
  "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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="extra" type="object" required={false}>
  Optional extra parameters for the request.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="response_video_type" type="string" required={false}>
      The returned video type. Default is mp4.<br />
      Enum: `mp4`, `gif`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="request" type="object" required={true}>
  <Expandable title="properties" defaultOpen={true}>
    <ParamField body="video_assets_id" type="string" required={true}>
      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 body="enable_restore" type="boolean" required={true}>
      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 body="face_image_base64" type="string" required={true}>
      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" required={false}>
  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
curl -X PUT -T "{{video file path}}" 'https://assets.novitai.com/video'
```

`Response:`

```js
{
    "assets_id": "cjIvbm92aXRhLWFpLWFzc2V0L3ZpZGVvL0NLd0N3aHJwS0ZyYVduNWVoejVFV0tleGlzN0toNmRq"
}
```


# 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 header="Content-Type" type="string" required={true}>
  Supports: `application/json`
</ParamField>

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

## Request Body

<ParamField body="extra" type="object" required={false}>
  Optional extra parameters for the request.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="webhook" type="object" required={false}>
      Webhook settings. More details can be found at [Webhook Documentation](/api-reference/model-apis-webhook).

      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="url" type="string" required={true}>
          The URL of the webhook endpoint. Novita AI will send the task generated outputs to your specified webhook endpoint.
        </ParamField>

        <ParamField body="test_mode" type="object" required={false}>
          By specifying Test Mode, a mock event will be sent to the webhook endpoint.

          <Expandable title="properties" defaultOpen={false}>
            <ParamField body="enabled" type="boolean" required={true}>
              Set to true to enable Test Mode, or false to disable it.

              The default is `false`.
            </ParamField>

            <ParamField body="return_task_status" type="string" required={true}>
              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 body="prompt" type="string" required={true}>
  Prompt text required to guide the generation.

  Range: `1 <= x <= 2000`.
</ParamField>

<ParamField body="image_url" type="string" required={true}>
  The URL of the image to be used for video generation.
</ParamField>

<ParamField body="negative_prompt" type="string" required={false}>
  Negative prompts instruct the model on what elements to avoid generating.

  Range: `0 <= x <= 2000`.
</ParamField>

<ParamField body="width" type="integer" required={false}>
  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 body="height" type="integer" required={false}>
  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 body="loras" type="object[]" required={false}>
  LoRA models to be applied to the video generation.

  Currently supports up to **3 LoRAs**.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="path" type="string" required={true}>
      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 body="scale" type="number(float32)" required={true}>
      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 body="seed" type="integer" required={false}>
  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 body="steps" type="integer" required={false}>
  The number of inference steps.

  Range: `1 <= x <= 40`. Default: `30`.
</ParamField>

<ParamField body="guidance_scale" type="float" required={false}>
  Guidance scale parameter controls how closely the generated content follows the prompt.

  Range: `0 <= x <= 10`. Default: `5.0`.
</ParamField>

<ParamField body="flow_shift" type="float" required={false}>
  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 body="enable_safety_checker" type="boolean" required={false}>
  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 body="fast_mode" type="boolean" required={false}>
  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" required={true}>
  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
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
{
    "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
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id={Returned Task ID}' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js
{
    "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 controls className="w-full aspect-video" src="https://pub-f964a1c641c04024bce400ad128c8cd6.r2.dev/wan-i2v-demo.mp4" />


# 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 header="Content-Type" type="string" required={true}>
  Supports: `application/json`
</ParamField>

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

## Request Body

<ParamField body="extra" type="object" required={false}>
  Optional extra parameters for the request.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="webhook" type="object" required={false}>
      Webhook settings. More details can be found at [Webhook Documentation](/api-reference/model-apis-webhook).

      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="url" type="string" required={true}>
          The URL of the webhook endpoint. Novita AI will send the task generated outputs to your specified webhook endpoint.
        </ParamField>

        <ParamField body="test_mode" type="object" required={false}>
          By specifying Test Mode, a mock event will be sent to the webhook endpoint.

          <Expandable title="properties" defaultOpen={false}>
            <ParamField body="enabled" type="boolean" required={true}>
              Set to true to enable Test Mode, or false to disable it.

              The default is `false`.
            </ParamField>

            <ParamField body="return_task_status" type="string" required={true}>
              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 body="prompt" type="string" required={true}>
  Prompt text required to guide the generation.

  Range: `1 <= x <= 2000`.
</ParamField>

<ParamField body="negative_prompt" type="string" required={false}>
  Negative prompts instruct the model on what elements to avoid generating.

  Range: `0 <= x <= 2000`.
</ParamField>

<ParamField body="width" type="integer" required={false}>
  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 body="height" type="integer" required={false}>
  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 body="loras" type="object[]" required={false}>
  LoRA models to be applied to the video generation.

  Currently supports up to **3 LoRAs**.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="path" type="string" required={true}>
      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 body="scale" type="number(float32)" required={true}>
      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 body="seed" type="integer" required={false}>
  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 body="steps" type="integer" required={false}>
  The number of inference steps.

  Range: `1 <= x <= 40`. Default: `30`.
</ParamField>

<ParamField body="guidance_scale" type="float" required={false}>
  Guidance scale parameter controls how closely the generated content follows the prompt.

  Range: `0 <= x <= 10`. Default: `5.0`.
</ParamField>

<ParamField body="flow_shift" type="float" required={false}>
  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 body="enable_safety_checker" type="boolean" required={false}>
  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 body="fast_mode" type="boolean" required={false}>
  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" required={true}>
  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
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
{
    "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
curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id={Returned Task ID}' \
--header 'Authorization: Bearer {{API Key}}'
```

`Response:`

```js
{
    "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 controls className="w-full aspect-video" src="https://pub-f964a1c641c04024bce400ad128c8cd6.r2.dev/wan-t2v-demo.mp4" />


# 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
{
    "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
// 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
{
    "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.


# 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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="endpoint" type="object" required={true}>
  Endpoint configuration details.

  <Expandable title="properties" defaultOpen={true}>
    <ParamField body="name" type="string" required={false}>
      Endpoint name. String, length limit: 0-220 characters.
    </ParamField>

    <ParamField body="appName" type="string" required={false}>
      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 body="workerConfig" type="object[]" required={true}>
      Worker configuration. The valid range can be dynamically obtained via the parameter range API.

      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="minNum" type="integer" required={true}>
          Minimum number of workers.
        </ParamField>

        <ParamField body="maxNum" type="integer" required={true}>
          Maximum number of workers.
        </ParamField>

        <ParamField body="freeTimeout" type="integer" required={true}>
          Idle timeout (seconds). Unit: seconds.
        </ParamField>

        <ParamField body="maxConcurrent" type="integer" required={true}>
          Maximum concurrency.
        </ParamField>

        <ParamField body="gpuNum" type="integer" required={true}>
          Number of GPUs per worker.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="ports" type="object[]" required={true}>
      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" defaultOpen={false}>
        <ParamField body="port" type="string" required={true}>
          HTTP port.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="policy" type="object[]" required={true}>
      Auto-scaling policy. The valid range can be dynamically obtained via the parameter range API.

      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="type" type="string" required={true}>
          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 body="value" type="integer" required={true}>
          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 body="image" type="object[]" required={true}>
      Image information.

      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="image" type="string" required={true}>
          Image URL. String, length limit: 0-511 characters.
        </ParamField>

        <ParamField body="authId" type="string" required={false}>
          Private image credential ID (not required for public images or platform user images). String, length limit: 0-255 characters.
        </ParamField>

        <ParamField body="command" type="string" required={false}>
          Container startup command. String, length limit: 0-2047 characters.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="products" type="object[]" required={true}>
      Product information.

      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="id" type="string" required={true}>
          Product ID.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="rootfsSize" type="integer" required={true}>
      System disk size (GB). Currently, set to a fixed value of 100.
    </ParamField>

    <ParamField body="volumeMounts" type="object[]" required={true}>
      Storage information (GB).

      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="type" type="string" required={true}>
          Storage type. Options:

          * `local`: Local storage.
          * `network`: Network storage.
        </ParamField>

        <ParamField body="size" type="integer" required={false}>
          Local storage size, currently set to a fixed value of 30. Not required for network storage.
        </ParamField>

        <ParamField body="id" type="string" required={false}>
          Network storage ID. Not required for local storage.
        </ParamField>

        <ParamField body="mountPath" type="string" required={true}>
          Mount path. String, length limit: 0-255 characters.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="clusterID" type="string" required={false}>
      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 body="envs" type="object[]" required={false}>
      Environment variables.

      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="key" type="string" required={true}>
          Environment variable name.
        </ParamField>

        <ParamField body="value" type="string" required={true}>
          Environment variable value.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="healthy" type="object" required={true}>
      Health check endpoint.

      <Expandable title="properties" defaultOpen={false}>
        <ParamField body="path" type="string" required={true}>
          Path to be checked via HTTP request for health monitoring.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="id" type="string" required={false}>
  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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="name" type="string" required={true}>
  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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Query Parameters

<ParamField query="id" type="string" required={true}>
  Endpoint ID.
</ParamField>

## Response

<ResponseField name="endpoint" type="object" required={true}>
  Endpoint information.

  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="id" type="string" required={true}>
      Endpoint ID.
    </ResponseField>

    <ResponseField name="name" type="string" required={true}>
      Endpoint name.
    </ResponseField>

    <ResponseField name="appName" type="string" required={true}>
      Application name.
    </ResponseField>

    <ResponseField name="state" type="object" required={true}>
      Endpoint status.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="state" type="string" required={true}>
          Endpoint status. When the value is `serving`, the endpoint is available for service.
        </ResponseField>

        <ResponseField name="error" type="string" required={false}>
          Error code when the endpoint is in an abnormal state.
        </ResponseField>

        <ResponseField name="message" type="string" required={false}>
          Error message when the endpoint is in an abnormal state.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="url" type="string" required={true}>
      Endpoint URL. You can access your HTTP service via this URL.
    </ResponseField>

    <ResponseField name="workerConfig" type="object" required={true}>
      Worker configuration for the endpoint.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="minNum" type="integer" required={true}>
          Minimum number of workers.
        </ResponseField>

        <ResponseField name="maxNum" type="integer" required={true}>
          Maximum number of workers.
        </ResponseField>

        <ResponseField name="freeTimeout" type="string" required={true}>
          Idle timeout, in seconds.
        </ResponseField>

        <ResponseField name="maxConcurrent" type="string" required={true}>
          Maximum concurrency.
        </ResponseField>

        <ResponseField name="gpuNum" type="integer" required={true}>
          Number of GPUs per worker.
        </ResponseField>

        <ResponseField name="cudaVersion" type="string" required={true}>
          CUDA version.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="policy" type="object" required={true}>
      Auto-scaling policy for the endpoint.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="type" type="string" required={true}>
          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" required={true}>
          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" required={true}>
      Image configuration for the endpoint.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="image" type="string" required={true}>
          Image URL.
        </ResponseField>

        <ResponseField name="authId" type="string" required={true}>
          Image repository credential.
        </ResponseField>

        <ResponseField name="command" type="string" required={true}>
          Container startup command.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="rootfsSize" type="integer" required={true}>
      System disk size.
    </ResponseField>

    <ResponseField name="volumeMounts" type="object[]" required={true}>
      Storage configuration for the endpoint.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="type" type="string" required={true}>
          Storage type. Options:

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

        <ResponseField name="id" type="string" required={true}>
          Cloud storage ID.
        </ResponseField>

        <ResponseField name="size" type="integer" required={true}>
          Returned when type = local, indicates the size of the local disk.
        </ResponseField>

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

    <ResponseField name="envs" type="object[]" required={true}>
      Environment variables.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="key" type="string" required={true}>
          Environment variable name.
        </ResponseField>

        <ResponseField name="value" type="string" required={true}>
          Environment variable value.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ports" type="object[]" required={true}>
      HTTP ports.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="port" type="integer" required={true}>
          HTTP port.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="workers" type="object[]" required={true}>
      Worker information for the endpoint.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="id" type="string" required={true}>
          Worker ID.
        </ResponseField>

        <ResponseField name="state" type="object" required={true}>
          Worker status.

          <Expandable title="properties" defaultOpen={true}>
            <ResponseField name="state" type="string" required={true}>
              Worker status. When the value is `running`, the worker is available for service.
            </ResponseField>

            <ResponseField name="error" type="string" required={false}>
              Error code when the worker is in an abnormal state.
            </ResponseField>

            <ResponseField name="message" type="string" required={false}>
              Error message when the worker is in an abnormal state.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="log" type="string" required={true}>
          Log path for the worker.
        </ResponseField>

        <ResponseField name="metrics" type="string" required={true}>
          Monitoring information for the worker.
        </ResponseField>

        <ResponseField name="healthy" type="boolean" required={true}>
          Whether the worker is healthy.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="products" type="object[]" required={true}>
      Product information.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="id" type="string" required={true}>
          Product ID.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="healthy" type="object" required={true}>
      Health check configuration for the endpoint.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="path" type="string" required={true}>
          Path to be checked via HTTP request for health monitoring.
        </ResponseField>

        <ResponseField name="initialDelay" type="integer" required={true}>
          Time to wait after startup before starting health checks, in seconds.
        </ResponseField>

        <ResponseField name="period" type="integer" required={true}>
          Interval between health checks, in seconds.
        </ResponseField>

        <ResponseField name="timeout" type="integer" required={true}>
          Timeout for health checks, in seconds.
        </ResponseField>

        <ResponseField name="successThreshold" type="integer" required={true}>
          Number of consecutive successes required to consider the check successful after a previous failure.
        </ResponseField>

        <ResponseField name="failureThreshold" type="integer" required={true}>
          Number of consecutive failures required to consider the check failed after a previous success.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="clusterID" type="string" required={true}>
      Cluster ID where the cloud storage resides. Returned when using cloud storage.
    </ResponseField>

    <ResponseField name="log" type="string" required={true}>
      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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Query Parameters

<ParamField query="pageSize" type="integer" required={true}>
  Maximum number of items returned per page.
</ParamField>

<ParamField query="pageNum" type="integer" required={true}>
  Current page number.
</ParamField>

## Response

<ResponseField name="endpoints" type="object[]" required={true}>
  Endpoint information.

  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="id" type="string" required={true}>
      Endpoint ID.
    </ResponseField>

    <ResponseField name="name" type="string" required={true}>
      Endpoint name.
    </ResponseField>

    <ResponseField name="appName" type="string" required={true}>
      Application name.
    </ResponseField>

    <ResponseField name="state" type="object" required={true}>
      Endpoint status.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="state" type="string" required={true}>
          Endpoint status. When the value is `serving`, the endpoint is available for service.
        </ResponseField>

        <ResponseField name="error" type="string" required={false}>
          Error code when the endpoint is in an abnormal state.
        </ResponseField>

        <ResponseField name="message" type="string" required={false}>
          Error message when the endpoint is in an abnormal state.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="url" type="string" required={true}>
      Endpoint URL. You can access your HTTP service via this URL.
    </ResponseField>

    <ResponseField name="workerConfig" type="object" required={true}>
      Worker configuration for the endpoint.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="minNum" type="integer" required={true}>
          Minimum number of workers.
        </ResponseField>

        <ResponseField name="maxNum" type="integer" required={true}>
          Maximum number of workers.
        </ResponseField>

        <ResponseField name="freeTimeout" type="string" required={true}>
          Idle timeout, in seconds.
        </ResponseField>

        <ResponseField name="maxConcurrent" type="string" required={true}>
          Maximum concurrency.
        </ResponseField>

        <ResponseField name="gpuNum" type="integer" required={true}>
          Number of GPUs per worker.
        </ResponseField>

        <ResponseField name="cudaVersion" type="string" required={true}>
          CUDA version.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="policy" type="object" required={true}>
      Auto-scaling policy for the endpoint.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="type" type="string" required={true}>
          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" required={true}>
          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" required={true}>
      Image configuration for the endpoint.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="image" type="string" required={true}>
          Image URL.
        </ResponseField>

        <ResponseField name="authId" type="string" required={true}>
          Image repository credential.
        </ResponseField>

        <ResponseField name="command" type="string" required={true}>
          Container startup command.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="rootfsSize" type="integer" required={true}>
      System disk size.
    </ResponseField>

    <ResponseField name="volumeMounts" type="object[]" required={true}>
      Storage configuration for the endpoint.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="type" type="string" required={true}>
          Storage type. Options:

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

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

        <ResponseField name="size" type="integer" required={false}>
          Returned when type = local, indicates the size of the local disk.
        </ResponseField>

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

    <ResponseField name="envs" type="object[]" required={true}>
      Environment variables.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="key" type="string" required={true}>
          Environment variable name.
        </ResponseField>

        <ResponseField name="value" type="string" required={true}>
          Environment variable value.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ports" type="object[]" required={true}>
      HTTP ports.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="port" type="string" required={true}>
          HTTP port.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="workers" type="object[]" required={true}>
      Worker information for the endpoint.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="id" type="string" required={true}>
          Worker ID.
        </ResponseField>

        <ResponseField name="state" type="object" required={true}>
          Worker status.

          <Expandable title="properties" defaultOpen={true}>
            <ResponseField name="state" type="string" required={true}>
              Worker status. When the value is `running`, the worker is available for service.
            </ResponseField>

            <ResponseField name="error" type="string" required={false}>
              Error code when the worker is in an abnormal state.
            </ResponseField>

            <ResponseField name="message" type="string" required={false}>
              Error message when the worker is in an abnormal state.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="log" type="string" required={true}>
          Log path for the worker.
        </ResponseField>

        <ResponseField name="metrics" type="string" required={true}>
          Monitoring information for the worker.
        </ResponseField>

        <ResponseField name="healthy" type="boolean" required={true}>
          Whether the worker is healthy.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="products" type="object[]" required={true}>
      Product information.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="id" type="string" required={true}>
          Product ID.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="healthy" type="object" required={true}>
      Health check configuration for the endpoint.

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="path" type="string" required={true}>
          Path to be checked via HTTP request for health monitoring.
        </ResponseField>

        <ResponseField name="initialDelay" type="integer" required={true}>
          Time to wait after startup before starting health checks, in seconds.
        </ResponseField>

        <ResponseField name="period" type="integer" required={true}>
          Interval between health checks, in seconds.
        </ResponseField>

        <ResponseField name="timeout" type="integer" required={true}>
          Timeout for health checks, in seconds.
        </ResponseField>

        <ResponseField name="successThreshold" type="integer" required={true}>
          Number of consecutive successes required to consider the check successful after a previous failure.
        </ResponseField>

        <ResponseField name="failureThreshold" type="integer" required={true}>
          Number of consecutive failures required to consider the check failed after a previous success.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="clusterID" type="string" required={true}>
      Cluster ID where the cloud storage resides. Returned when using cloud storage.
    </ResponseField>

    <ResponseField name="log" type="string" required={true}>
      Log path for the endpoint.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer" required={true}>
  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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Response

<ResponseField name="minRootfsSize" type="integer" required={true}>
  Minimum root filesystem size (GB).
</ResponseField>

<ResponseField name="maxRootfsSize" type="integer" required={true}>
  Maximum root filesystem size (GB).
</ResponseField>

<ResponseField name="freeRootfsSize" type="integer" required={true}>
  Free root filesystem size (GB).
</ResponseField>

<ResponseField name="minLocalVolumeSize" type="integer" required={true}>
  Minimum local volume size (GB).
</ResponseField>

<ResponseField name="maxLocalVolumeSize" type="integer" required={true}>
  Maximum local volume size (GB).
</ResponseField>

<ResponseField name="freeLocalVolumeSize" type="integer" required={true}>
  Free local volume size (GB).
</ResponseField>

<ResponseField name="minWorkerNum" type="integer" required={true}>
  Minimum number of worker nodes.
</ResponseField>

<ResponseField name="maxWorkerNum" type="integer" required={true}>
  Maximum number of worker nodes.
</ResponseField>

<ResponseField name="minFreeTimeout" type="integer" required={true}>
  Minimum idle timeout (seconds).
</ResponseField>

<ResponseField name="maxFreeTimeout" type="integer" required={true}>
  Maximum idle timeout (seconds).
</ResponseField>

<ResponseField name="minConcurrencyNum" type="integer" required={true}>
  Minimum concurrency.
</ResponseField>

<ResponseField name="maxConcurrencyNum" type="integer" required={true}>
  Maximum concurrency.
</ResponseField>

<ResponseField name="minQueueWaitTime" type="integer" required={true}>
  Minimum queue wait time (seconds).
</ResponseField>

<ResponseField name="maxQueueWaitTime" type="integer" required={true}>
  Maximum queue wait time (seconds).
</ResponseField>

<ResponseField name="minRequestNum" type="integer" required={true}>
  Minimum number of requests.
</ResponseField>

<ResponseField name="maxRequestNum" type="integer" required={true}>
  Maximum number of requests.
</ResponseField>

<ResponseField name="minGPUNum" type="integer" required={true}>
  Minimum number of GPUs.
</ResponseField>

<ResponseField name="maxGPUNum" type="integer" required={true}>
  Maximum number of GPUs.
</ResponseField>

<ResponseField name="cudaVersionList" type="string[]" required={true}>
  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 header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

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

## Request Body

<ParamField body="id" type="string" required={true}>
  The ID of the endpoint to update.
</ParamField>

<ParamField body="name" type="string" required={false}>
  Endpoint name.
</ParamField>

<ParamField body="clusterID" type="string" required={false}>
  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 body="workerConfig" type="object[]" required={true}>
  Worker configuration. The valid range can be dynamically obtained via the parameter range API.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="minNum" type="integer" required={true}>
      Minimum number of workers.
    </ParamField>

    <ParamField body="maxNum" type="integer" required={true}>
      Maximum number of workers.
    </ParamField>

    <ParamField body="freeTimeout" type="integer" required={true}>
      Idle timeout (seconds). Unit: seconds.
    </ParamField>

    <ParamField body="maxConcurrent" type="integer" required={true}>
      Maximum concurrency.
    </ParamField>

    <ParamField body="gpuNum" type="integer" required={true}>
      Number of GPUs per worker.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="ports" type="object[]" required={true}>
  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" defaultOpen={false}>
    <ParamField body="port" type="string" required={true}>
      HTTP port.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="policy" type="object[]" required={true}>
  Auto-scaling policy. The valid range can be dynamically obtained via the parameter range API.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="type" type="string" required={true}>
      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 body="value" type="integer" required={true}>
      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 body="image" type="object[]" required={true}>
  Image information.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="image" type="string" required={true}>
      Image URL. String, length limit: 0-511 characters.
    </ParamField>

    <ParamField body="authId" type="string" required={false}>
      Private image credential ID (not required for public images or platform user images). String, length limit: 0-255 characters.
    </ParamField>

    <ParamField body="command" type="string" required={false}>
      Container startup command. String, length limit: 0-2047 characters.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="volumeMounts" type="object[]" required={false}>
  Storage information (GB).

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="type" type="string" required={true}>
      Storage type. Options:

      * `local`: Local storage.
      * `network`: Network storage.
    </ParamField>

    <ParamField body="size" type="integer" required={false}>
      Local storage size, currently set to a fixed value of 30. Not required for network storage.
    </ParamField>

    <ParamField body="id" type="string" required={false}>
      Network storage ID. Not required for local storage.
    </ParamField>

    <ParamField body="mountPath" type="string" required={true}>
      Mount path. String, length limit: 0-255 characters.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="envs" type="object[]" required={false}>
  Environment variables.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="key" type="string" required={true}>
      Environment variable name.
    </ParamField>

    <ParamField body="value" type="string" required={true}>
      Environment variable value.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="healthy" type="object[]" required={false}>
  Health check endpoint path.

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="path" type="string" required={true}>
      Health check path.
    </ParamField>
  </Expandable>
</ParamField>


# 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 |


# 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


# 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).


# 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))


# 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 |


# 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



## **GPUs Updates**

### **New Features**

* **Instances are allowed to upgrade in any state**

  Updated time: June 17, 2025

***

## **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


# 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


# 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


# 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 width="150" src="https://imagedelivery.net/GFvwKVAtCfKnMHdvDobR4A/docs/v2/novita_logo.svg/docs" />
</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.


# 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).


# 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).


# 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).


# 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


# 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).


# Novita AI & ai-gradio Integration Guide
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
# 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
export NOVITA_API_KEY=<your api key>
```

### Step 2: Modify the app.py entry file.

```python
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)


# Novita AI & AnythingLLM Integration Guide
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 "Novita AI key management")</Frame>

* **AnythingLLM Software**:Download and install [AnythingLLM software](https://anythingllm.com/desktop) from the official website.

<Frame>![AnythingLLM Software](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/anythingllm-1.png "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&#x20;

[<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>![Open AnythingLLM setting](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/anythingllm-2.png "Open AnythingLLM setting")</Frame>

* Go to the **LLM API Providers** section, **and then** select **Novita AI** from the dropdown menu.

  <Frame>![LLM API Providers](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/anythingllm-7.png "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>![Enable Web Search](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/anythingllm-3.png "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>![Click the Upload icon of the Workspace](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/anythingllm-4.png "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>![Save and embed in AnythingLLM](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/anythingllm-5.png "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>![Try Asking Questions](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/anythingllm-6.png "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. Add a payment method.

Go to <a href="https://novita.ai/billing/payment-methods" target="_blank">Payment Methods</a> in the console.

<Frame>
  <img height="200" src="https://cf-images.novitai.com/docs/v2/automatic_top_up_add_payment_method.png/docs" />
</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. Enable Automatic Top-Up and configure settings.

Click **"Modify"** in the **"Automatic Payments"** panel to configure your Automatic Top-Up settings.

<Frame>
  <img height="280" src="https://cf-images.novitai.com/docs/v2/automatic_top_up_ready_enable.png/docs" />
</Frame>

After enabling the **"Enable Automatic Top-Up"** toggle, set valid values for **"When credit goes below"** and **"Bring credit back up to"**, then click **"Save settings"** to complete the process.

<Frame>
  <img height="300" src="https://cf-images.novitai.com/docs/v2/automatic_top_up_enabled.png/docs" />
</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>
  ![Step1 Accessthe GPU Instance Console Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step1-AccesstheGPUInstanceConsole.png)
</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>
  ![Step2 Choosea Templateand GPU Type Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step2-ChooseaTemplateandGPUType.png)
</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>
  ![Step3 Adjust Diskand Configuration Parameters Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step3-AdjustDiskandConfigurationParameters.png)
</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>
  ![Step4 Confirm Configurationand Deploy Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step4-ConfirmConfigurationandDeploy.png)
</Frame>

Step 5: Wait for Deployment to Complete

* Wait for the instance to finish deploying.

<Frame>
  ![Step5 Waitfor Deploymentto Complete Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step5-WaitforDeploymenttoComplete.png)
</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>
  ### ![Step6 Manageand Monitor Instances Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step6-ManageandMonitorInstances.png)
</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>
  ### ![Step7 Check Instance Logs Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step7-CheckInstanceLogs.png)
</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>
  ### ![Step8 Connectto Jupyter Lab Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step8-ConnecttoJupyterLab.png)
</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>
  ### ![Step9 Access Jupyter Lab Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step9-AccessJupyterLab.png)
</Frame>

Step 10: Run a Fine-Tuning Example

* Execute the official example code to perform a fine-tuning task.

```bash
# 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.


# Novita AI & Browser Use: Quick Start
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
pip install browser-use
```

Step 2: Install Playwright (required for browser automation):

```bash
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
NOVITA_API_KEY=your_api_key_here
```

### Basic Implementation

* Here's a complete example of using Browser Use with Novita AI's API:

```python
"""
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/v3/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
task="Compare the price of gpt-4o and DeepSeek-V3"
```

* For more complex tasks, you might want to enable vision capabilities:

```python
agent = Agent(
    task="Find and summarize the latest news about AI on TechCrunch",
    llm=ChatOpenAI(
        base_url='https://api.novita.ai/v3/openai',
        model='deepseek/deepseek-v3-0324',
        api_key=SecretStr(api_key),
    ),
    use_vision=True,
)
```


# Novita AI & CodeCompanion.nvim Integration Guide 
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
require("codecompanion").setup({
    adapters = {
        novita = {
            base_url = "https://api.novita.ai/v3/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
: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.


# Novita AI & Continue Integration Guide
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.&#x20;

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>![How to use Continue.dev-VS Code](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/HowtouseContinue.dev-VSCode.webp "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>![How to use Continue.dev-JetBrains](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/HowtouseContinue.dev-JetBrains.webp "How to use Continue.dev-JetBrains")</Frame>

## How to Integrate Novita AI with Continue Using an API Key

### Step 1: Open VS Code

<Frame>![How to Integrate Novita AI with Continue Using an API Key-Open VS Code](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/HowtoIntegrateNovitaAIwithContinueUsinganAPIKey-OpenVSCode.webp "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>![How to Integrate Novita AI with Continue Using an API Key-Search Continue](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/HowtoIntegrateNovitaAIwithContinueUsinganAPIKey-SearchContinue.webp "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>![How to Integrate Novita AI with Continue Using an API Key-Install Continue](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/HowtoIntegrateNovitaAIwithContinueUsinganAPIKey-InstallContinue.webp "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>![How to Integrate Novita AI with Continue Using an API Key-Click Continue](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/HowtoIntegrateNovitaAIwithContinueUsinganAPIKey-ClickContinue.webp "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>![How to Integrate Novita AI with Continue Using an API Key-Add your Chat Model 1](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/HowtoIntegrateNovitaAIwithContinueUsinganAPIKey-AddyourChatModel1.webp "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>![How to Integrate Novita AI with Continue Using an API Key- Enter the API key from Novita AI and Get Connected](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/HowtoIntegrateNovitaAIwithContinueUsinganAPIKey-EntertheAPIkeyfromNovitaAIandGetConnected.webp "How to Integrate Novita AI with Continue Using an API Key- Enter the API key from Novita AI and Get Connected")</Frame>


# Novita AI & Cursor Integration Guide
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 "Novita AI key management")</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>![](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/cursor-1.png)</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/v3/openai`](https://api.novita.ai/v3/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>![Start a Chat with AI in Cursor](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/cursor-3.png "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.


# Novita AI & DeepSearcher: Quick Start
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>
  ![Step1followtheexample Jpe](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/step1Followtheexample.jpeg)
</Frame>

Step 2: Add the following code below the line `config = Configuration()` :

```python
config.set_provider_config("llm", "NOVITA", {"model": "deepseek/deepseek-r1-turbo"})
config.set_provider_config("embedding", "NovitaEmbedding", {"model": "baai/bge-m3"})
```

<Frame>
  ![Step2addcodebelowunderthelineconfig=configuration Jpe](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/step2Addcodebelowunderthelineconfig=Configuration.jpeg)
</Frame>

Step 3: Run `examples/basic_example.py` to execute the integration.

You'll get the following results:

<Frame>
  ![Output1 Jpe](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/output1.jpeg)
</Frame>

<Frame>
  ![Output2 Jpe](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/output2.jpeg)
</Frame>

<Frame>
  ![Output3 Jpe](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/output3.jpeg)
</Frame>

<Frame>
  ![Output4 Jpe](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/output4.jpeg)
</Frame>

<Frame>
  ![Output5 Jpe](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/output5.jpeg)
</Frame>


# Novita AI & Dify Integration Guide
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.&#x20;

## 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 "Novita AI key management")</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>![Choose Chatbot as the application type](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/dify-2.png "Choose Chatbot as the application type")</Frame>

* Give your app a name (e.g., “DeepSeek R1 Bot”) and click **Create**.

  <Frame>![Give your app a name and click Create.](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/dify-3.png "Give your app a name and click Create.")</Frame>

* From the **Model** dropdown, select **Novita AI DeepSeek R1**.

  <Frame>![From the Model dropdown, select Novita AI DeepSeek R1](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/dify-4.png "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>![go to the Knowledge Base section and click Create Knowledage.](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/dify-5.png "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>![Upload documents ](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/dify-6.png "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>![Use Parent-Child Segmentation Mode ](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/dify-7.png "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>![Add Knowledge Base](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/dify-8.png "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>![Share Your AI Application](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/dify-9.png "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>![Workflow-based Applications](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/dify-10.png "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.


# Novita AI & DocsGPT Integration Guide
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
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
./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>
  ![images/3-1LogintoNovitaAI.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/3-1LogintoNovitaAI.png)
</Frame>

<Frame>
  ![images/3-2CreateanAPIKey.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/3-2CreateanAPIKey.png)
</Frame>

Step 2: Select option4 and connect cloud API provider in your terminal

<Frame>
  ![images/2SelectOption4andConnectCloudAPIProvider.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/2SelectOption4andConnectCloudAPIProvider.png)
</Frame>

Step 3: Choose option7 Novita and enter the API key you just created

<Frame>
  ![images/4ChooseOption7NovitaandEntertheAPIKeyYouJustCreated.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/4ChooseOption7NovitaandEntertheAPIKeyYouJustCreated.png)
</Frame>

Step 4: Wait for the startup process to complete

<Frame>
  ![images/5WaitfortheStartupProcesstoComplete.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/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>
  ![images/6AccesstheApplicationathttp-localhost-5173.jpeg](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/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
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" target="_blank">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" target="_blank">contact us</a>.

<Frame>
  <img src="https://cf-images.novitai.com/docs/v2/gpu_instance_faq_logs.png/docs" height="150" />
</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" target="_blank">Explore</a>.

<Frame>
  <img width="250" src="https://cf-images.novitai.com/docs/v2/gpu_instance_faq_filter_cuda.png/docs" />
</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" target="_blank">"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" target="_blank">Container Registry Auth Configuration</a> is correct. If the problem cannot be resolved, you can <a href="https://discord.gg/YyPRAzwp7P" target="_blank">contact us</a>.

<Frame>
  <img src="https://cf-images.novitai.com/docs/v2/gpu_instance_faq_jobs_logs.png/docs" height="220" />
</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" target="_blank">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
# 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.


# 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" target="_blank">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** helps you save costs by up to 50% easily.

## 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" target="_blank">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" target="_blank">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
ssh-keygen -t rsa
```

2. Force the agent to load the new private key and verify that it's loaded:

```bash
ssh-add; ssh-add -l
```

3. Retrieve the content of your SSH public key:

```bash
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
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" target="_blank">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. Here's a guide: [Quickstart](/guides/quickstart).
* 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 cols={2}>
  <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>


# Novita AI & Helicone Integration Guide
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>![Step 2- Generate an API Key-Go to Settings-page](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/Step2-GenerateanAPIKey-GotoSettings-page.webp "Step 2- Generate an API Key-Go to Settings-page")</Frame>

* Select the API Key Tab.

  <Frame>![Step 2- Generate an API Key-Select the API Key Tab-page](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/Step2-GenerateanAPIKey-SelecttheAPIKeyTab-page.webp "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>![Step 2- Generate an API Key-Select the API Key Tab-page](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/Step2-GenerateanAPIKey-GenerateNewKey-page.webp "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>![](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/Step1-GotoNovitaAIandLog-in-page.webp)</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>![](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/Step2-KeyManagementinNovitaAI.webp)</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
$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)	&#x9;

* Then add the following headers for authentication:

```bash
* curl -H "Authorization: Bearer <your API key>"
```

**Example**

* Now you can use this simple fetch call to interact with any Novita AI model.

* ```bash
  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
  ```


# Novita AI & Hugging Face Integration Guide
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.&#x20;

  <Frame>![ Configure API Keys in Hugging Face](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/ConfigureAPIKeysinHuggingFace.jpeg " 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>![Choose Inference API Modes](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/ChooseInferenceAPIModes.png "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>![ Explore Compatible Providers on Model Pages in Hugging Face](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/ExploreCompatibleProvidersonModelPagesinHuggingFace.jpeg " 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
pip install huggingface_hub
```

### **Step 2: Call model API in Python**

```python
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
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)
```


# Novita AI & OpenAI Agents SDK Integration Guide
Source: https://novita.ai/docs/guides/integration-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
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
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/v3/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
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/v3/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
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/v3/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())
```


# Introduction
Source: https://novita.ai/docs/guides/introduction



Novita is a low-cost, reliable, and simple cloud infrastructure for shipping AI models. We empower developers with scalable, production-ready model inference so they can focus on building AI applications.

<CardGroup cols={3}>
  <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 in milliseconds with full isolation, multi-language support, 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>
  ### ![images/Step1AccessGPUInstanceControlPanel.jpg](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/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>
  ### ![images/Step2SelectKohya\_ssGUITemplate.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/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>
  ### ![images/Step3ConfigureDiskParametersandReviewConfigurationSettings.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/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>
  ### ![images/Step4ProceedtoConfirmationandDeployYourInstance.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step4ProceedtoConfirmationandDeployYourInstance.png)
</Frame>

Step 5: Wait as the System Creates Your Instance

<Frame>
  ### ![images/Step5WaitastheSystemCreatesYourInstance.jpg](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/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>
  ### ![images/Step6MonitorDeploymentProgressandTrackImageDownload.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/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>
  ### ![images/Step7CheckInstanceLogs.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/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>
  ### ![images/Step8-1ConnecttoYourInstance.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step8-1ConnecttoYourInstance.png)
</Frame>

<Frame>
  ![images/Step8-2ConnecttoYourInstance.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/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>
  ![images/Step9BeginUsingYourInstance.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step9BeginUsingYourInstance.png)
</Frame>


# Novita AI & LangChain Integration Guide
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 "Novita AI key management")</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
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
npm install @langchain/community @langchain/core
```

**Using yarn:**

```bash
yarn add @langchain/community @langchain/core
```

**Using pnpm:**

```bash
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
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
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
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
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
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
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
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/v3/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
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
if __name__ == "__main__":
    message, result = process_math_query(
        "meta-llama/llama-3.3-70b-instruct", 
        "what's 3 plus 1132"
    )
    print(result)  # Output: 1135
```


# Novita AI & Langflow Integration Guide
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.&#x20;

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>![Expand the “Models” Tag on Langflow](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/Expandthe%E2%80%9CModels%E2%80%9DTagonLangflow.webp "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>![Drag Novita AI to Your Canvas on Langflow](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/DragNovitaAItoYourCanvasonLangflow.webp "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>![Create a Global Variable for the Novita AI API Key on Langflow](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/CreateaGlobalVariablefortheNovitaAIAPIKeyonLangflow.webp "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>![Select a Model on Langflow](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/SelectaModelonLangflow.webp "Select a Model on Langflow")</Frame>

### **Step 6: Start Building Your AI App**

* &#x20;Create advanced AI functionality by connecting Novita AI components to your Langflow workflow system.


# Novita AI & Langfuse Integration Guide
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>![](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/langfuse-1.png)</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
pip install openai langfuse
```

## Step 2: Set Up Environment Variables

```python
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/v3/openai`:](https://api.novita.ai/v3/openai)

```python
# 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/v3/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
client = openai.OpenAI(
  api_key=os.environ.get("NOVITA_API_KEY"),
  base_url="https://api.novita.ai/v3/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).


# Novita AI & LiteLLM Integration Guide
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
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.
  ![Visitthekeymanagementpageandselect Add New Keytogenerateyour AP Ikey Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/-VisitthekeymanagementpageandselectAddNewKeytogenerateyourAPIkey..png)

### Step 3: Structure Your Basic API Call

* Create a completion request to Novita AI's models through LiteLLM's standardized interface.

```python
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
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,
)
```


# Novita AI & LlamaIndex Integration Guide
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>
  ![images/Step1VisitModelLibraryonNovitaAIandselectamodelofinterest.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step1VisitModelLibraryonNovitaAIandselectamodelofinterest.png)
</Frame>

Step 2: Navigate to the demo page of the chosen model and click the `Code` button on the right.

<Frame>
  ![images/Step2NavigatetothedemopageofthechosenmodelandclicktheCodebuttonontheright.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step2NavigatetothedemopageofthechosenmodelandclicktheCodebuttonontheright.png)
</Frame>

Step 3: Copy the model’s name and make a note of it.

<Frame>
  ![images/Step3Copythemodel’snameandmakeanoteofit.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step3Copythemodel%E2%80%99snameandmakeanoteofit.png)
</Frame>

Step 4: [Log in ](https://novita.ai/user/login)to the Novita platform.

<Frame>
  ![images/Step4LogintotheNovitaplatform.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step4LogintotheNovitaplatform.png)
</Frame>

Step 5: After logging in, go to the platform’s [settings page](https://novita.ai/settings).

<Frame>
  ![images/Step5Afterloggingin,gototheplatform’ssettingspage.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step5Afterloggingin,gototheplatform%E2%80%99ssettingspage.png)
</Frame>

Step 6: Create a new [API key](https://novita.ai/settings/key-management) and copy it for service authentication.

<Frame>
  ![images/Step6CreateanewAPIkeyandcopyitforserviceauthentication.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step6CreateanewAPIkeyandcopyitforserviceauthentication.png)
</Frame>

Step 7: Install `llama_index` and related Python libraries by running:

<Frame>
  ![images/Step7Installllama\_indexandrelatedPythonlibrariesbyrunning.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/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>
  ![images/Step8WritePythoncodeandsetthemodelnameandAPIkeyasparametersintheNovitaAIclass.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step8WritePythoncodeandsetthemodelnameandAPIkeyasparametersintheNovitaAIclass.png)
</Frame>

Step 9: Run the code to get the output.

<Frame>
  ![images/Step9Runthecodetogettheoutput.png](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/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).


# 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/v3/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
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.novita.ai/v3/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
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.novita.ai/v3/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
  export API_KEY="<Your API Key>"

  curl "https://api.novita.ai/v3/openai/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
  export API_KEY="<Your API Key>"

  curl "https://api.novita.ai/v3/openai/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.


# Function Calling
Source: https://novita.ai/docs/guides/llm-function-calling



export const FunctionCallingModels = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    let attempts = 0;
    const maxAttempts = 50;
    const INIT_DISPLAY_COUNT = 3;
    const interval = setInterval(() => {
      const clientComponent = document.getElementById("function-calling-models");
      if (clientComponent && window.novitaRemoteData.llmModels.status === 'loaded') {
        const modelList = window.novitaRemoteData.llmModels.data.filter(model => {
          return (model.features || []).includes('function-calling');
        });
        let displayModels = modelList.slice(0, INIT_DISPLAY_COUNT).map(model => {
          return `<li>${model.id}</li>`;
        }).join('');
        let showMoreButton = '';
        if (modelList.length > INIT_DISPLAY_COUNT) {
          showMoreButton = `<button id="show-more-function-call-btn" style="margin-left: 32px; color: rgb(22 176 99)">View More</button>`;
        }
        clientComponent.innerHTML = `
          <ul>${displayModels}</ul>
          ${showMoreButton}
        `;
        document.getElementById('show-more-function-call-btn')?.addEventListener('click', () => {
          clientComponent.innerHTML = `
            <ul>${modelList.map(model => {
            return `<li>${model.id}</li>`;
          }).join('')}</ul>
          `;
        });
        clearInterval(interval);
      }
      attempts++;
      if (attempts >= maxAttempts) {
        clearInterval(interval);
      }
    }, 200);
    return <div id="function-calling-models"></div>;
  }
};

`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`:

* `deepseek/deepseek-r1-0528`
* `deepseek/deepseek-v3-0324`
* `deepseek/deepseek-v3-turbo`
* `deepseek/deepseek-r1-turbo`
* `meta-llama/llama-4-maverick-17b-128e-instruct-fp8`
* `meta-llama/llama-4-scout-17b-16e-instruct`
* `meta-llama/llama-3.3-70b-instruct`
* `meta-llama/llama-3.2-3b-instruct`
* `baidu/ernie-4.5-vl-424b-a47b`
* `baidu/ernie-4.5-300b-a47b-paddle`
* `thudm/glm-4-32b-0414`
* `qwen/qwen2.5-7b-instruct`
* `minimaxai/minimax-m1-80k`

## 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
from openai import OpenAI
import json

client = OpenAI(
    base_url="https://api.novita.ai/v3/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
# 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
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
{'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
# 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
from openai import OpenAI
import json

client = OpenAI(
    base_url="https://api.novita.ai/v3/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)
```


# 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.


# Rate limits
Source: https://novita.ai/docs/guides/llm-rate-limits



export const DynamicRPMList = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    let attempts = 0;
    const maxAttempts = 50;
    const formatAmount = num => {
      if (typeof num === "number") {
        return num.toLocaleString();
      }
      return num || "-";
    };
    const interval = setInterval(() => {
      const clientComponent = document.getElementById("dynamic-rpm-list");
      if (clientComponent && window.novitaRemoteData.llmModels.status === 'loaded') {
        const modelList = window.novitaRemoteData.llmModels.data.filter(model => {
          return Boolean(model.rpm);
        });
        const allModels = modelList.map(model => {
          const t1 = (model.quota_items || []).find(item => item.tier === "T1") || ({});
          const t2 = (model.quota_items || []).find(item => item.tier === "T2") || ({});
          const t3 = (model.quota_items || []).find(item => item.tier === "T3") || ({});
          const t4 = (model.quota_items || []).find(item => item.tier === "T4") || ({});
          const t5 = (model.quota_items || []).find(item => item.tier === "T5") || ({});
          return `
            <tr>
              <td rowspan="2" style="vertical-align: middle; max-width: 230px">${model.id}</td>
              <td>RPM</td>
              <td>${formatAmount(t1.rpm)}</td>
              <td>${formatAmount(t2.rpm)}</td>
              <td>${formatAmount(t3.rpm)}</td>
              <td>${formatAmount(t4.rpm)}</td>
              <td>${formatAmount(t5.rpm)}</td>
            </tr>
            <tr>
              <td>TPM</td>
              <td>${formatAmount(t1.tpm)}</td>
              <td>${formatAmount(t2.tpm)}</td>
              <td>${formatAmount(t3.tpm)}</td>
              <td>${formatAmount(t4.tpm)}</td>
              <td>${formatAmount(t5.tpm)}</td>
            </tr>
          `;
        }).join('');
        clientComponent.innerHTML = `
          <table class="table table-big">
            <thead>
              <tr>
                <th>Model</th>
                <th></th>
                <th>T1</th>
                <th>T2</th>
                <th>T3</th>
                <th>T4</th>
                <th>T5</th>
              </tr>
            </thead>
            <tbody>
              ${allModels}
            </tbody>
          </table>
        `;
        clearInterval(interval);
      }
      attempts++;
      if (attempts >= maxAttempts) {
        clearInterval(interval);
      }
    }, 200);
    return <div id="dynamic-rpm-list"></div>;
  }
};

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 class="table table-big">
  <thead>
    <tr>
      <th class="min-w-10">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" target="_blank">Contact us through Discord</a>
   * or <a href="https://meet.brevo.com/novita-ai/contact-sales" target="_blank">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
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
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.novita.ai/v3/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
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
messages.append({"role": "assistant", "content": content})
messages.append({"role": "user", "content": "Please continue explaining the solution."})
```

***

## Supported Models

### DeepSeek Series

* `deepseek/deepseek-r1-0528`
* `deepseek/deepseek-r1-0528-qwen3-8b`
* `deepseek/deepseek-r1-turbo`
* `deepseek/deepseek-r1-distill-qwen-32b`
* `deepseek/deepseek-r1-distill-qwen-14b`
* `deepseek/deepseek-r1-distill-llama-70b`
* `deepseek/deepseek-r1-distill-llama-8b`
* `deepseek/deepseek-r1/community`

### Qwen Series

* `qwen/qwen3-235b-a22b-fp8`
* `qwen/qwen3-30b-a3b-fp8`
* `qwen/qwen3-32b-fp8`
* `qwen/qwen3-8b-fp8`
* `qwen/qwen3-4b-fp8`

### GLM Series

* `thudm/glm-z1-rumination-32b-0414`
* `thudm/glm-z1-9b-0414`
* `thudm/glm-z1-32b-0414`

### LLaMA Series

* `meta-llama/llama-4-maverick-17b-128e-instruct-fp8`

Visit the model library for the latest list and details.

***

## 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.


# Structured Outputs
Source: https://novita.ai/docs/guides/llm-structured-outputs



export const StructuredOutputsModels = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    let attempts = 0;
    const maxAttempts = 50;
    const INIT_DISPLAY_COUNT = 3;
    const interval = setInterval(() => {
      const clientComponent = document.getElementById("structured-outputs-models");
      if (clientComponent && window.novitaRemoteData.llmModels.status === 'loaded') {
        const modelList = window.novitaRemoteData.llmModels.data.filter(model => {
          return (model.features || []).includes('structured-outputs');
        });
        let displayModels = modelList.slice(0, INIT_DISPLAY_COUNT).map(model => {
          return `<li>${model.id}</li>`;
        }).join('');
        let showMoreButton = '';
        if (modelList.length > INIT_DISPLAY_COUNT) {
          showMoreButton = `<button id="show-more-function-call-btn" style="margin-left: 32px; color: rgb(22 176 99)">View More</button>`;
        }
        clientComponent.innerHTML = `
          <ul>${displayModels}</ul>
          ${showMoreButton}
        `;
        document.getElementById('show-more-function-call-btn')?.addEventListener('click', () => {
          clientComponent.innerHTML = `
            <ul>${modelList.map(model => {
            return `<li>${model.id}</li>`;
          }).join('')}</ul>
          `;
        });
        clearInterval(interval);
      }
      attempts++;
      if (attempts >= maxAttempts) {
        clearInterval(interval);
      }
    }, 200);
    return <div id="structured-outputs-models"></div>;
  }
};

`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`:

* `deepseek/deepseek-r1-0528`
* `deepseek/deepseek-r1-distill-llama-8b`
* `deepseek/deepseek-r1-distill-qwen-14b`
* `deepseek/deepseek-r1-distill-qwen-32b`
* `deepseek/deepseek-r1-distill-llama-70b`
* `google/gemma-3-27b-it`
* `qwen/qwen-2.5-72b-instruct`
* `qwen/qwen2.5-7b-instruct`
* `mistralai/mistral-nemo`
* `meta-llama/llama-3-70b-instruct`
* `meta-llama/llama-3.1-8b-instruct-bf16`
* `nousresearch/hermes-2-pro-llama-3-8b`
* `cognitivecomputations/dolphin-mixtral-8x22b`
* `sao10k/l3-8b-lunarisQuick Start Guide`
* `baidu/ernie-4.5-300b-a47b-paddle`
* `thudm/glm-4-32b-0414`
* `minimaxai/minimax-m1-80k`

## 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
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/v3/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

# 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
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
{
  "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
from openai import OpenAI
import json

client = OpenAI(
    base_url="https://api.novita.ai/v3/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
{
  "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
{
  "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
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
{
  "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:

* `meta-llama/llama-4-maverick-17b-128e-instruct-fp8`
* `meta-llama/llama-4-scout-17b-16e-instruct`
* `google/gemma-3-27b-it`
* `qwen/qwen2.5-vl-72b-instruct`
* `baidu/ernie-4.5-vl-424b-a47b`

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
from openai import OpenAI

client = OpenAI(api_key="YOUR_KEY", base_url="https://api.novita.ai/v3/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
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.


# Novita AI & LobeChat Integration Guide
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 "Novita AI key management")</Frame>

* **LobeChat Account**

  * Sign up for a LobeChat account at [LobeChat](https://lobechat.com).

## **Integration Steps**

### **Step 1: Connect Novita AI to LobeChat**

<Frame>![Connect Novita AI to LobeChat](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/lobechat-1.png "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>![Choose a Novita AI Model](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/lobechat-2.png "Choose a Novita AI Model")</Frame>

### Step 3: Launch Your First Chat

Begin your conversation with Novita AI LLM on LobeChat.


# Novita AI & LoLLMS WebUI Integration Guide
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
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
python -m venv venv
```

* Activate the Virtual Environment:
  * On Windows:

    ```bash
    .\venv\Scripts\activate
    ```
  * On Linux/Mac:

    ```bash
    source venv/bin/activate
    ```

Step 3: Install Requirements

```bash
pip install -r requirements.txt
pip install -e ./lollms_core
```

Step 4: Create global\_paths\_cfg.yaml

```bash
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
  set NOVITA_AI_API_KEY="your_api_key_here"
  set NOVITA_AI_MODEL_NAME="your_model_name_here"
  ```

  * On Linux/Mac:

  ```bash
  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
  python zoos/bindings_zoo/novita_ai/__init__.py
  ```

2. Run the Server

```bash
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)


# 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
{
  "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
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
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
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 cols={2}>
  <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 height="404" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/sampler_01.png" />
</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 height="404" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/sampler_02.webp" />
</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 height="404" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/sampler_03.png" />
</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 height="404" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/sampler_04.webp" />
</Frame>

Euler converges. (sampling steps 2-40)

<Frame>
  <img height="404" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/sampler_05.webp" />
</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 height="404" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/sampler_06.png" />
</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 height="404" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/sampler_07.png" />
</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 height="404" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/sampler_08.png" />
</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 height="404" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/sampler_09.png" />
</Frame>

> UniPC

UniPC converges a bit slower than Euler, but not too bad.

<Frame>
  <img height="404" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/sampler_10.png" />
</Frame>

#### Speed

<Frame>
  <img height="404" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/sampler_11.png" />
</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 height="1200" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/sampler_12.png" />
</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
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
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 class="table">
  <thead>
    <tr>
      <th>V2</th>
      <th>V3</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**extra**<span class="type-desc">object</span></td>
      <td>**extra**<span class="type-desc">object</span></td>

      <td />
    </tr>

    <tr>
      <td class="list-col">enable\_nsfw\_detection<br /><span class="type-desc mt-1 ml-0">boolean</span></td>
      <td class="list-col">enable\_nsfw\_detection<br /><span class="type-desc mt-1 ml-0">boolean</span></td>

      <td />
    </tr>

    <tr>
      <td class="list-col">nsfw\_detection\_level<br /><span class="type-desc mt-1 ml-0">Enum: `0, 1, 2`</span></td>
      <td class="list-col">nsfw\_detection\_level<br /><span class="type-desc mt-1 ml-0">Enum: `0, 1, 2`</span></td>

      <td />
    </tr>

    <tr>
      <td class="list-col delete">enable\_progress\_info</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="list-col">response\_image\_type<br /><span class="type-desc mt-1 ml-0">Enum: `png`, `jpeg`</span></td>
      <td class="list-col">response\_image\_type<br /><span class="type-desc mt-1 ml-0">Enum: `png, webp, jpeg`</span></td>
      <td>V3 adds support for `webp`image format</td>
    </tr>

    <tr>
      <td />

      <td>**request**<span class="type-desc">object</span></td>
      <td><span class="new-field">New Field</span><br />All image generation parameters must be passed via the `request`in V3</td>
    </tr>

    <tr>
      <td class="delete">**prompt**<span class="type-desc">string</span><br />\<lora:\$sd\_name:\$weight></td>
      <td class="list-col">prompt<span class="type-desc">string</span></td>
      <td class="moved">Moved Inside</td>
    </tr>

    <tr>
      <td />

      <td class="list-col">loras<span class="type-desc">object\[]</span></td>
      <td><span class="moved">Moved Inside</span><br />**Migrate LoRA usage: From **`prompt`** to **`request.loras`** parameter**</td>
    </tr>

    <tr>
      <td />

      <td class="list-sub-col">model\_name<span class="type-desc">string</span></td>
      <td><span class="new-field">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 class="list-sub-col">strength<span class="type-desc">number(float32)</span></td>
      <td><span class="new-field">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 class="delete">**negative\_prompt**<span class="type-desc">string</span></td>
      <td class="list-col">negative\_prompt<span class="type-desc">string</span></td>
      <td class="moved">Moved Inside</td>
    </tr>

    <tr>
      <td class="delete">**sampler\_name**<span class="type-desc">string</span></td>
      <td class="list-col">sampler\_name<span class="type-desc">string</span></td>
      <td class="moved">Moved Inside</td>
    </tr>

    <tr>
      <td class="delete">**batch\_size**<span class="type-desc">integer</span></td>
      <td class="list-col">image\_num<span class="type-desc">integer</span></td>
      <td><span class="moved">Changed</span><br /> `num_images` **→** `request.image_num`</td>
    </tr>

    <tr>
      <td class="delete">**n\_iter**</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="delete">**steps**<span class="type-desc">string</span></td>
      <td class="list-col">steps<span class="type-desc">string</span></td>
      <td class="moved">Moved Inside</td>
    </tr>

    <tr>
      <td class="delete">**cfg\_scale**<span class="type-desc">integer</span></td>
      <td class="list-col">guidance\_scale<br /><span class="type-desc mt-1 ml-0">number(float32)</span></td>
      <td><span class="moved">Changed</span><br /> `cfg_scale`**→** `request.guidance_scale`</td>
    </tr>

    <tr>
      <td class="delete">**seed**<span class="type-desc">integer</span></td>
      <td class="list-col">seed<span class="type-desc">integer</span></td>
      <td class="moved">Moved Inside</td>
    </tr>

    <tr>
      <td class="delete">**height**<span class="type-desc">integer</span></td>
      <td class="list-col">height<span class="type-desc">integer</span></td>
      <td><span class="moved">Moved Inside</span><br />Range Change: \[128, 2048].</td>
    </tr>

    <tr>
      <td class="delete">**width**<span class="type-desc">integer</span></td>
      <td class="list-col">width<span class="type-desc">integer</span></td>
      <td><span class="moved">Moved Inside</span><br />Range Change: \[128, 2048].</td>
    </tr>

    <tr>
      <td class="delete">**model\_name**<span class="type-desc">string</span></td>
      <td class="list-col">model\_name<span class="type-desc">string</span></td>
      <td><span class="moved">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 class="delete">**restore\_faces**<span class="type-desc">bool</span></td>
      <td class="list-col">restore\_faces<span class="type-desc">bool</span></td>
      <td class="moved">Moved Inside</td>
    </tr>

    <tr>
      <td class="delete">**restore\_faces\_model**</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="delete">**sd\_vae**<span class="type-desc">string</span></td>
      <td class="list-col">sd\_vae<span class="type-desc">string</span></td>
      <td class="moved">Moved Inside</td>
    </tr>

    <tr>
      <td class="delete">**clip\_skip**<span class="type-desc">integer</span></td>
      <td class="list-col">clip\_skip<span class="type-desc">integer</span></td>
      <td class="moved">Moved Inside</td>
    </tr>

    <tr>
      <td class="delete">**enable\_hr**<span class="type-desc">boolean</span></td>
      <td class="list-col">hires\_fix<span class="type-desc">object</span></td>
      <td><span class="moved">Changed</span><br /> `enable_hr`**→** `request.hires_fix`</td>
    </tr>

    <tr>
      <td class="delete">**hr\_upscaler**<br /><span class="type-desc mt-1 ml-0">Enum:<br /> `Latent`, `ESRGAN_4x`, `R-ESRGAN 4x+`, `R-ESRGAN 4x+ Anime6B`</span></td>
      <td class="list-sub-col">upscaler<br /><span class="type-desc mt-1 ml-0">Enum: `RealESRGAN_x4plus_anime_6B`, `RealESRNet_x4plus,Latent`</span></td>
      <td><span class="moved">Changed</span><br /> `hr_upscaler`**→**`request.hires_fix.upscaler`</td>
    </tr>

    <tr>
      <td class="delete">**hr\_scale**<span class="type-desc">number</span></td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="delete">**hr\_resize\_x**<span class="type-desc">integer</span></td>
      <td class="list-sub-col">target\_width<span class="type-desc">integer</span></td>
      <td><span class="moved">Changed</span><br /> `hr_resize_x`**→** `request.hires_fix.target_width`</td>
    </tr>

    <tr>
      <td class="delete">**hr\_resize\_y**<span class="type-desc">integer</span></td>
      <td class="list-sub-col">target\_height<span class="type-desc">integer</span></td>
      <td><span class="moved">Changed</span><br /> `hr_resize_y`**→** `request.hires_fix.target_height`</td>
    </tr>

    <tr>
      <td class="delete">**img\_expire\_ttl**<span class="type-desc">integer</span></td>

      <td />

      <td><span class="deprecated">Deprecated</span><br />Default 3600s</td>
    </tr>

    <tr>
      <td class="delete">**sd\_refiner**<span class="type-desc">object</span></td>
      <td class="list-col">refiner<span class="type-desc">object</span></td>
      <td><span class="moved">Changed</span><br /> `sd_refiner`**→** `request.refiner`</td>
    </tr>

    <tr>
      <td class="list-col delete">checkpoint<span class="type-desc">string</span></td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="list-col delete">switch\_at<br /><span class="type-desc mt-1 ml-0">number(float32)</span></td>
      <td class="list-sub-col">switch\_at<br /><span class="type-desc mt-1 ml-0">number(float32)</span></td>
      <td><span class="moved">Changed</span><br /> `sd_refiner.switch_at`**→** `request.refiner.switch_at`</td>
    </tr>

    <tr>
      <td class="delete">**controlnet\_units**<span class="type-desc">object\[]</span></td>

      <td />

      <td><span class="deprecated">Deprecated</span><br /><span class="inline-block mt-2">`img2img` Only</span></td>
    </tr>
  </tbody>
</table>

### Response Parameter Mapping

<table class="table">
  <thead>
    <tr>
      <th>V2</th>
      <th>V3</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="delete">**code**</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="delete">**msg**</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="delete">**data**</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="list-col delete">task\_id</td>
      <td>**task\_id**</td>
      <td><span class="moved">Changed</span><br /> `data.task_id`**→** `task_id`</td>
    </tr>

    <tr>
      <td class="list-col delete">warn</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>
  </tbody>
</table>

### Example

<CardGroup cols={2}>
  <Card title="Text to Image V2">
    * Request

    ```bash
    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
    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
    {
      "task_id":"0696ce57-22df-4a89-9efc-80c386a82dbd"
    }
    ```
  </Card>
</CardGroup>

## Image to Image

### Request Body Parameter Mapping

<table class="table">
  <thead>
    <tr>
      <th>V2</th>
      <th>V3</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**extra**<span class="type-desc">object</span></td>
      <td>**extra**<span class="type-desc">object</span></td>

      <td />
    </tr>

    <tr>
      <td class="list-col">enable\_nsfw\_detection<br /><span class="type-desc mt-1 ml-0">boolean</span></td>
      <td class="list-col">enable\_nsfw\_detection<br /><span class="type-desc mt-1 ml-0">boolean</span></td>

      <td />
    </tr>

    <tr>
      <td class="list-col">nsfw\_detection\_level<br /><span class="type-desc mt-1 ml-0">Enum: `0, 1, 2`</span></td>
      <td class="list-col">nsfw\_detection\_level<br /><span class="type-desc mt-1 ml-0">Enum: `0, 1, 2`</span></td>

      <td />
    </tr>

    <tr>
      <td class="list-col delete">enable\_progress\_info</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="list-col">response\_image\_type<br /><span class="type-desc mt-1 ml-0">Enum: `png`, `jpeg`</span></td>
      <td class="list-col">response\_image\_type<br /><span class="type-desc mt-1 ml-0">Enum: `png, webp, jpeg`</span></td>
      <td>V3 adds support for `webp`image format</td>
    </tr>

    <tr>
      <td />

      <td>**request**<span class="type-desc">object</span></td>
      <td><span class="new-field">New field</span><br />All image generation parameters must be passed via the `request`in V3</td>
    </tr>

    <tr>
      <td class="delete">**prompt**<span class="type-desc">string</span><br />\<lora:\$sd\_name:\$weight></td>
      <td class="list-col">prompt<span class="type-desc">string</span></td>
      <td class="moved">Moved Inside</td>
    </tr>

    <tr>
      <td />

      <td class="list-col">loras<span class="type-desc">object\[]</span></td>
      <td><span class="moved">Moved Inside</span><br />**Migrate LoRA usage: From **`prompt`** to **`request.loras`** parameter**</td>
    </tr>

    <tr>
      <td />

      <td class="list-sub-col">model\_name<span class="type-desc">string</span></td>
      <td><span class="new-field">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 class="list-sub-col">strength<br /><span class="type-desc mt-1 ml-0">number(float32)</span></td>
      <td><span class="new-field">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 class="delete">**negative\_prompt**<span class="type-desc">string</span></td>
      <td class="list-col">negative\_prompt<br /><span class="type-desc mt-1 ml-0">string</span></td>
      <td class="moved">Moved Inside</td>
    </tr>

    <tr>
      <td class="delete">**sampler\_name**<span class="type-desc">string</span></td>
      <td class="list-col">sampler\_name<span class="type-desc">string</span></td>
      <td class="moved">Moved Inside</td>
    </tr>

    <tr>
      <td class="delete">**batch\_size**<span class="type-desc">integer</span></td>
      <td class="list-col">image\_num<span class="type-desc">integer</span></td>
      <td><span class="moved">Changed</span><br /> `batch_size`**→** `request.image_num`</td>
    </tr>

    <tr>
      <td class="delete">**n\_iter**<span class="type-desc">integer</span></td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="delete">**steps**<span class="type-desc">string</span></td>
      <td class="list-col">steps<span class="type-desc">string</span></td>
      <td class="moved">Moved Inside</td>
    </tr>

    <tr>
      <td class="delete">**cfg\_scale**<span class="type-desc">integer</span></td>
      <td class="list-col">guidance\_scale<br /><span class="type-desc mt-1 ml-0">number(float32)</span></td>
      <td><span class="moved">Changed</span><br /> `cfg_scale`**→** `request.guidance_scale`</td>
    </tr>

    <tr>
      <td class="delete">**seed**<span class="type-desc">integer</span></td>
      <td class="list-col">seed<span class="type-desc">integer</span></td>
      <td class="moved">Moved Inside</td>
    </tr>

    <tr>
      <td class="delete">**height**<span class="type-desc">integer</span></td>
      <td class="list-col">height<span class="type-desc">integer</span></td>
      <td><span class="moved">Moved Inside</span><br />Range Change: \[128, 2048].</td>
    </tr>

    <tr>
      <td class="delete">**width**<span class="type-desc">integer</span></td>
      <td class="list-col">width<span class="type-desc">integer</span></td>
      <td><span class="moved">Moved Inside</span><br />Range Change: \[128, 2048].</td>
    </tr>

    <tr>
      <td class="delete">**model\_name**<span class="type-desc">string</span></td>
      <td class="list-col">model\_name<span class="type-desc">string</span></td>
      <td><span class="moved">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 class="delete">**init\_images**<span class="type-desc">string\[]</span></td>
      <td class="list-col">image\_base64<span class="type-desc">string</span></td>
      <td><span class="moved">Changed</span><br /> `init_images`**→** `request.image_base64`</td>
    </tr>

    <tr>
      <td class="delete">**denoising\_strength**<br /><span class="type-desc mt-1 ml-0">number(float)</span></td>
      <td class="list-col">strength<br /><span class="type-desc mt-1 ml-0">number(float)</span></td>
      <td><span class="moved">Changed</span><br /> `denoising_strength`**→** `request.strength`</td>
    </tr>

    <tr>
      <td class="delete">**restore\_faces**<span class="type-desc">bool</span></td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="delete">**sd\_vae**<span class="type-desc">string</span></td>
      <td class="list-col">sd\_vae<span class="type-desc">string</span></td>
      <td class="moved">Moved Inside</td>
    </tr>

    <tr>
      <td class="delete">**clip\_skip**<span class="type-desc">integer</span></td>
      <td class="list-col">clip\_skip<span class="type-desc">integer</span></td>
      <td class="moved">Moved Inside</td>
    </tr>

    <tr>
      <td class="delete">**mask**<span class="type-desc">string</span></td>

      <td />

      <td><span class="deprecated">Deprecated</span><br />Recommendation: Use V3 Inpainting API</td>
    </tr>

    <tr>
      <td class="delete">**mask\_blur**<span class="type-desc">integer</span></td>

      <td />

      <td><span class="deprecated">Deprecated</span><br />Recommendation: Use V3 Inpainting API</td>
    </tr>

    <tr>
      <td class="delete">**resize\_mode**<span class="type-desc">integer</span></td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="delete">**image\_cfg\_scale**<span class="type-desc">integer</span></td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="delete">**inpainting\_fill**<span class="type-desc">integer</span></td>

      <td />

      <td><span class="deprecated">Deprecated</span><br />Recommendation: Use V3 Inpainting API</td>
    </tr>

    <tr>
      <td class="delete">**inpaint\_full\_res**<span class="type-desc">integer</span></td>

      <td />

      <td><span class="deprecated">Deprecated</span><br />Recommendation: Use V3 Inpainting API</td>
    </tr>

    <tr>
      <td class="delete">**inpaint\_full\_res\_padding**<br /><span class="type-desc mt-1 ml-0">integer</span></td>

      <td />

      <td><span class="deprecated">Deprecated</span><br />Recommendation: Use V3 Inpainting API</td>
    </tr>

    <tr>
      <td class="delete">**inpainting\_mask\_invert**<br /><span class="type-desc mt-1 ml-0">integer</span></td>

      <td />

      <td><span class="deprecated">Deprecated</span><br />Recommendation: Use V3 Inpainting API</td>
    </tr>

    <tr>
      <td class="delete">**initial\_noise\_multiplier**<br /><span class="type-desc mt-1 ml-0">number(float32)</span></td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="delete">**img\_expire\_ttl**<span class="type-desc">integer</span></td>

      <td />

      <td><span class="deprecated">Deprecated</span><br />Default 3600s</td>
    </tr>

    <tr>
      <td class="delete">**sd\_refiner**<span class="type-desc">object</span></td>
      <td class="list-col">refiner<span class="type-desc">object</span></td>
      <td><span class="moved">Changed</span><br /> `sd_refiner`**→** `request.refiner`</td>
    </tr>

    <tr>
      <td class="list-col delete">checkpoint</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="list-col delete">switch\_at<br /><span class="type-desc mt-1 ml-0">number(float32)</span></td>
      <td class="list-sub-col">switch\_at<br /><span class="type-desc mt-1 ml-0">number(float32)</span></td>
      <td class="moved">Moved Inside</td>
    </tr>

    <tr>
      <td />

      <td class="list-sub-col">controlnet<span class="type-desc">object</span></td>
      <td><span class="new-field">New Field</span></td>
    </tr>

    <tr>
      <td class="delete">**controlnet\_units**<span class="type-desc">object\[]</span></td>
      <td class="list-grandson-col">units<span class="type-desc">object\[]</span></td>
      <td><span class="moved">Changed</span><br /> `controlnet_units`**→** `request.controlnet.units`</td>
    </tr>

    <tr>
      <td class="list-col delete">model<span class="type-desc">string</span></td>
      <td class="list-grandson-sub-col ">model\_name<br /><span class="type-desc mt-1 ml-0">string</span></td>
      <td><span class="moved">Changed</span><br /> `controlnet_units.model`**→** <br />`request.controlnet.units.model_name`</td>
    </tr>

    <tr>
      <td class="list-col delete">weight<span class="type-desc">number</span></td>
      <td class="list-grandson-sub-col ">strength<br /><span class="type-desc mt-1 ml-0">number(float32)</span></td>
      <td><span class="moved">Changed</span><br /> `controlnet_units.weight`**→** <br />`request.controlnet.units.strength`</td>
    </tr>

    <tr>
      <td class="list-col delete">input\_image<span class="type-desc">string</span></td>
      <td class="list-grandson-sub-col ">image\_base64<br /><span class="type-desc mt-1 ml-0">string</span></td>
      <td><span class="moved">Changed</span><br /> `controlnet_units.input_image`**→** <br />`request.controlnet.units.image_base64`</td>
    </tr>

    <tr>
      <td class="list-col delete">module<span class="type-desc">string,Enum</span></td>
      <td class="list-grandson-sub-col ">preprocessor<br /><span class="type-desc mt-1 ml-0">string,Enum</span></td>
      <td><span class="moved">Changed</span><br />`controlnet_units.module`**→** <br />`request.controlnet.units.preprocessor`</td>
    </tr>

    <tr>
      <td class="list-col delete">control\_mode</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="list-col delete">mask</td>

      <td />

      <td><span class="deprecated">Deprecated</span><br />Recommendation: Use V3 Inpainting API</td>
    </tr>

    <tr>
      <td class="list-col delete">resize\_mode</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="list-col delete">processor\_res</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="list-col delete">threshold\_a</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="list-col delete">threshold\_b</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="list-col delete">guidance\_start<br /><span class="type-desc mt-1 ml-0">number(float32)</span></td>
      <td class="list-grandson-sub-col">guidance\_start<br /><span class="type-desc mt-1 ml-0">number(float32)</span></td>
      <td class="moved">Moved Inside</td>
    </tr>

    <tr>
      <td class="list-col delete">guidance\_end<br /><span class="type-desc mt-1 ml-0">number(float32)</span></td>
      <td class="list-grandson-sub-col">guidance\_end<br /><span class="type-desc mt-1 ml-0">number(float32)</span></td>
      <td class="moved">Moved Inside</td>
    </tr>

    <tr>
      <td class="list-col delete">pixel\_perfect</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>
  </tbody>
</table>

### Response Parameter Mapping

<table class="table">
  <thead>
    <tr>
      <th>V2</th>
      <th>V3</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="delete">code</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="delete">msg</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="delete">data</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>

    <tr>
      <td class="list-col delete">task\_id</td>
      <td>**task\_id**</td>
      <td><span class="moved">Changed</span><br /> `data.task_id`**→** `task_id`</td>
    </tr>

    <tr>
      <td class="list-col delete">warn</td>

      <td />

      <td class="deprecated">Deprecated</td>
    </tr>
  </tbody>
</table>

### Example

<CardGroup cols={2}>
  <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
    {
      "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 height="404" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/misc_01.png" />
</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 height="500" src="https://next-app-static.s3.ap-southeast-1.amazonaws.com/get-started/misc_02.png" />
</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.


# Novita AI & OWL Integration Guide
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/v3/openai](https://api.novita.ai/v3/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.

  ![Visitthekeymanagementpageandselect Add New Keytogenerateyour AP Ikey Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/-VisitthekeymanagementpageandselectAddNewKeytogenerateyourAPIkey..png)
* 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.

    ![Keepyour AP Ikeysafe 1 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/-KeepyourAPIkeysafe-1.png)

    ![Keepyour AP Ikeysafe 2 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/-KeepyourAPIkeysafe-2.png)

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
cd owl
cp .env_template .env
```

* Start OWL and specify your task by executing:

```bash
python examples/run_novita_ai.py
```

![Step3 Configure OWL Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/Step3-ConfigureOWL.png)

### **Step 4: View Results**

1. **Terminal Output**

* Once launched, OWL will display the execution results directly in the terminal window.

  ![Terminal Output 1 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/TerminalOutput-1.png)

  ![Terminal Output 2 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/TerminalOutput-2.png)

2. **Web Interface**

* For a more intuitive experience, use OWL’s web-based interface. Launch it by running:

```bash
cd owl
python webapp.py
```

![Web Interface 1 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/WebInterface-1.png)

![Web Interface 2 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/WebInterface-2.png)

* 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`.

    ![Stepstousethe Web UI 1 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/-StepstousetheWebUI-1.png)
  * Click `Run` to execute your task.

    ![Stepstousethe Web UI 2 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/-StepstousetheWebUI-2.png)
  * To perform a new task, update the input field and click `Run` again.

    ![Stepstousethe Web UI 3 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/-StepstousetheWebUI-3.png)

    ![Stepstousethe Web UI 4 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/-StepstousetheWebUI-4.png)
  * Results will be displayed in the terminal, or a new file will be generated in the root directory, depending on the task.

    ![Stepstousethe Web UI 5 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/-StepstousetheWebUI-5.png)
  * Alternatively, you can directly input your desired task into the content box and click the `Run` button to execute it.

    ![Stepstousethe Web UI 6 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/-StepstousetheWebUI-6.png)


# Novita AI & Page Assist Integration Guide
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
git clone https://github.com/n4ze3m/page-assist.git
cd page-assist
```

2. Install dependencies using Bun or npm:

```bash
bun install
```

### Step 3: Build Page Assist Extension

* Build the extension for Chrome (default):

```bash
bun run build
```

* For Firefox, use:

```bash
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>
     ![Inyour Page Assist Settings,enter Open Compatible AP Itoaddprovider Jpe](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/InyourPageAssistSettings,enterOpenCompatibleAPItoaddprovider.jpeg)
   </Frame>

   * Choose Novita from the `Custom list`, and use your API key for authentication.

   <Frame>
     ![Choose Novitafromthe Customlist,anduseyour AP Ikeyforauthentication Jpe](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/ChooseNovitafromtheCustomlist,anduseyourAPIkeyforauthentication..jpeg)
   </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>
  ![Chooseyourmodelfromthemodellistprovidedby Novita AI Jpe](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/ChooseyourmodelfromthemodellistprovidedbyNovitaAI..jpeg)
</Frame>

* Interact with your Novita AI model by asking questions or analyzing web content.

<Frame>
  ![Interactwithyour Novita A Imodelbyaskingquestionsoranalyzingwebcontent Jpe](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/InteractwithyourNovitaAImodelbyaskingquestionsoranalyzingwebcontent.jpeg)
</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 height="200" src="https://cf-images.novitai.com/docs/v2/payment_methods_stripe.png/docs" />
</Frame>


# Novita AI & Portkey Integration Guide
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
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
pip install -qU portkey-ai
```

Next, execute the following Python code to send your first request:

```python
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
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>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/portkey-gateway.png)
</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
npm install --save portkey-ai
```

**Python**

```python
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
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
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
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
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.


# 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 src="https://mintlify.s3.us-west-1.amazonaws.com/novitaai/guides/images/sandbox-console-sbx.png" alt="Sandbox Management" width="1200" />
</Frame>

## Template Management

* Display the list of available templates, including official templates provided by Novita official and your [custom templates](/guides/sandbox-e2b-sandbox-template).
* Support searching for a template by ID.
* Support filtering templates by visibility (public, private, or all), vCPUs, and memory.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/novitaai/guides/images/sandbox-console-template.png" alt="Sandbox Management" width="1200" />
</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" target="_blank">billing details</Link> page.
</Tip>

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/novitaai/guides/images/sandbox-console-usage.png" alt="Sandbox Management" width="1200" />
</Frame>


# E2B CLI
Source: https://novita.ai/docs/guides/sandbox-e2b-cli



E2B CLI is a command line tool that allows you to list, kill running <Link href="/guides/sandbox-e2b-sandbox" target="_blank">sandboxes</Link>, and manage <Link href="/guides/sandbox-e2b-sandbox-template" target="_blank">sandbox templates</Link>.

## Installation

**Using Homebrew (on macOS)**

```bash Bash icon="terminal"
brew install e2b
```

**Using NPM**

You can install E2B CLI using the following command:

```bash Bash icon="terminal"
npm i -g @e2b/cli
```

### Beta CLI

The latest beta version of the CLI can be installed from NPM using the following command:

```bash Bash icon="terminal"
npm i -g @e2b/cli@beta
```


# Authentication in CLI
Source: https://novita.ai/docs/guides/sandbox-e2b-cli-auth



Before using the E2B 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" highlight={1}
export E2B_DOMAIN=sandbox.novita.ai
e2b auth login
```


# List sandboxes
Source: https://novita.ai/docs/guides/sandbox-e2b-cli-list-sandboxes



export const E2BCliConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the command-line related example code in this document, please refer to the <Link href="/guides/sandbox-e2b-cli">tutorial</Link> to install the E2B command-line tool and complete <Link href="/guides/sandbox-e2b-cli-auth">authentication</Link>.</Note>;
  }
};

<E2BCliConfigHint />

You can list all running sandboxes using the following command:

```bash Bash icon="terminal" highlight={1}
export E2B_DOMAIN=sandbox.novita.ai
e2b sandbox list
```

## Changes in the Beta CLI

<Note>
  If you're using the [beta version of the CLI](/guides/sandbox-e2b-cli#beta-version), the `sandbox list` command was updated.
</Note>

### List all sandboxes

To list all sandboxes, use the following command:

```bash Bash icon="terminal"
export E2B_DOMAIN=sandbox.novita.ai
e2b sandbox list
```

This will return all sandboxes, both running and paused.

### 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"
export E2B_DOMAIN=sandbox.novita.ai
e2b sandbox list --state running,paused
```

### Filter by metadata

To filter the sandboxes by their metadata, use the `--metadata` flag.

```bash Bash icon="terminal"
export E2B_DOMAIN=sandbox.novita.ai
e2b 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"
export E2B_DOMAIN=sandbox.novita.ai
e2b sandbox list --limit 10
```

By default, the command will return all sandboxes.


# Shutdown running sandboxes
Source: https://novita.ai/docs/guides/sandbox-e2b-cli-shutdown-sandboxes



export const E2BCliConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the command-line related example code in this document, please refer to the <Link href="/guides/sandbox-e2b-cli">tutorial</Link> to install the E2B command-line tool and complete <Link href="/guides/sandbox-e2b-cli-auth">authentication</Link>.</Note>;
  }
};

You can shutdown single or all running sandboxes with the E2B CLI.

<E2BCliConfigHint />

## Shutdown single sandbox

To shutdown a single sandbox, run the following command:

```bash Bash icon="terminal" highlight={1}
export E2B_DOMAIN=sandbox.novita.ai
e2b sandbox kill <sandbox-id>
```

## Shutdown all sandboxes

To shutdown all running sandboxes, run the following command:

```bash Bash icon="terminal"
export E2B_DOMAIN=sandbox.novita.ai
e2b sandbox kill --all
```


# Start sandbox and connect to terminal
Source: https://novita.ai/docs/guides/sandbox-e2b-cli-spawn-sandbox



export const E2BCliConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the command-line related example code in this document, please refer to the <Link href="/guides/sandbox-e2b-cli">tutorial</Link> to install the E2B command-line tool and complete <Link href="/guides/sandbox-e2b-cli-auth">authentication</Link>.</Note>;
  }
};

<E2BCliConfigHint />

With the following command, you can use the E2B command line tool to start a sandbox and connect to the terminal.

```bash Bash icon="terminal" highlight={1}
export E2B_DOMAIN=sandbox.novita.ai
e2b sandbox spawn <template-id>
```


# Running commands in sandbox
Source: https://novita.ai/docs/guides/sandbox-e2b-commands



export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

<SandboxConfigHint />

You can run terminal commands inside the sandbox using the `commands.run()` method.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js"
  import { Sandbox } from '@e2b/code-interpreter'

  const sandbox = await Sandbox.create()

  const result = await sandbox.commands.run('ls -l')
  console.log(result)
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  sandbox = Sandbox()

  result = sandbox.commands.run('ls -l')
  print(result)
  ```
</CodeGroup>


# Running commands in background
Source: https://novita.ai/docs/guides/sandbox-e2b-commands-background



export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

<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"
  import { Sandbox } from '@e2b/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()
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  sandbox = Sandbox()

  # 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()
  ```
</CodeGroup>


# Streaming command output
Source: https://novita.ai/docs/guides/sandbox-e2b-commands-streaming



export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

<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"
  import { Sandbox } from '@e2b/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)
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  sandbox = Sandbox()

  result = sandbox.commands.run('echo hello; sleep 1; echo world', on_stdout=lambda data: print(data), on_stderr=lambda data: print(data))

  print(result)
  ```
</CodeGroup>


# Overview
Source: https://novita.ai/docs/guides/sandbox-e2b-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-e2b-filesystem-read-write)
* [Watch sandbox directory for changes](/guides/sandbox-e2b-filesystem-watch)
* [Upload data to sandbox](/guides/sandbox-e2b-filesystem-upload)
* [Download data from sandbox](/guides/sandbox-e2b-filesystem-download)


# Download data from sandbox
Source: https://novita.ai/docs/guides/sandbox-e2b-filesystem-download



export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

You can download data from the sandbox using the `files.read()` method.

<SandboxConfigHint />

<CodeGroup>
  ```js JavaScript & TypeScript icon="js"
  import fs from 'fs'
  import { Sandbox } from '@e2b/code-interpreter'

  const sandbox = await Sandbox.create()

  // Read file from sandbox
  const content = await sandbox.files.read('/path/in/sandbox')
  // Write file to local filesystem
  fs.writeFileSync('/local/path', content)
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  sandbox = Sandbox()

  # Read file from sandbox
  content = sandbox.files.read('/path/in/sandbox')
  # Write file to local filesystem
  with open('/local/path', 'w') as file:
    file.write(content)
  ```
</CodeGroup>


# Read & write files
Source: https://novita.ai/docs/guides/sandbox-e2b-filesystem-read-write



export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

<SandboxConfigHint />

## Reading files

You can read files from the sandbox filesystem using the `files.read()` method.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js"
  import { Sandbox } from '@e2b/code-interpreter'
  const sandbox = await Sandbox.create()
  const fileContent = await sandbox.files.read('/path/to/file')
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  sandbox = Sandbox()
  file_content = sandbox.files.read('/path/to/file')
  ```
</CodeGroup>

## Writing single files

You can write single files to the sandbox filesystem using the `files.write()` method.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js"
  import { Sandbox } from '@e2b/code-interpreter'
  const sandbox = await Sandbox.create()

  await sandbox.files.write('/path/to/file', 'file content')
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  sandbox = Sandbox()

  await sandbox.files.write('/path/to/file', 'file content')
  ```
</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"
  import { Sandbox } from '@e2b/code-interpreter'
  const sandbox = await Sandbox.create()

  await sandbox.files.write([
      { path: '/path/to/a', data: 'file content' },
      { path: '/another/path/to/b', data: 'file content' }
  ])
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  sandbox = Sandbox()

  await sandbox.files.write([
      { "path": "/path/to/a", "data": "file content" },
      { "path": "another/path/to/b", "data": "file content" }
  ])
  ```
</CodeGroup>


# Upload data to sandbox
Source: https://novita.ai/docs/guides/sandbox-e2b-filesystem-upload



export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

You can upload data to the sandbox using the `files.write()` method.

<SandboxConfigHint />

## Upload single file

<CodeGroup>
  ```js JavaScript & TypeScript icon="js"
  import fs from 'fs'
  import { Sandbox } from '@e2b/code-interpreter'

  const sandbox = await Sandbox.create()

  // Read file from local filesystem
  const content = fs.readFileSync('/local/path')
  // Upload file to sandbox
  await sandbox.files.write('/path/in/sandbox', content)
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  sandbox = Sandbox()

  # Read file from local filesystem
  with open("path/to/local/file", "rb") as file:
    # Upload file to sandbox
    sandbox.files.write("/path/in/sandbox", file)
  ```
</CodeGroup>

## Upload directory / multiple files

<CodeGroup>
  ```js JavaScript & TypeScript icon="js"
  import fs from 'fs'
  import path from 'path'

  import { Sandbox } from '@e2b/code-interpreter'

  const sandbox = await Sandbox.create()

  // Read all files in the directory and store their paths and contents in an array
  const readDirectoryFiles = (directoryPath) => {
    // Read all files in the local directory
    const files = fs.readdirSync(directoryPath);

    // Map files to objects with path and data
    const filesArray = files
      .filter(file => {
        const fullPath = path.join(directoryPath, file);
        // Skip if it's a directory
        return fs.statSync(fullPath).isFile();
      })
      .map(file => {
        const filePath = path.join(directoryPath, file);
      
        // Read the content of each file
        return {
          path: filePath,
          data: fs.readFileSync(filePath, 'utf8')
        };
      });

    return filesArray;
  };

  // Usage example
  const files = readDirectoryContents('/local/dir');
  console.log(files); 
  // Output example:
  // [
  //   { path: '/local/dir/file1.txt', data: 'File 1 contents...' },
  //   { path: '/local/dir/file2.txt', data: 'File 2 contents...' },
  //   ...
  // ]

  await sandbox.files.write(files)
  ```

  ```python Python icon="python"
  import os
  from e2b_code_interpreter import Sandbox

  sandbox = Sandbox()

  def read_directory_files(directory_path):
      files = []
      
      # Iterate through all files in the directory
      for filename in os.listdir(directory_path):
          file_path = os.path.join(directory_path, filename)
          
          # Skip if it's a directory
          if os.path.isfile(file_path):
              # Read file contents in binary mode
              with open(file_path, "rb") as file:
                  files.append({
                      'path': file_path,
                      'data': file.read()
                  })
      
      return files

  files = read_directory_files("/local/dir")
  print(files)

  # Output example:
  # [
  #  {"'path": "/local/dir/file1.txt", "data": "File 1 contents..." },
  #   { "path": "/local/dir/file2.txt", "data": "File 2 contents..." },
  #   ...
  # ]

  sandbox.files.write(files)
  ```
</CodeGroup>


# Watch sandbox directory for changes
Source: https://novita.ai/docs/guides/sandbox-e2b-filesystem-watch



export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

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"
  import { Sandbox, FilesystemEventType } from '@e2b/code-interpreter'

  const sandbox = await Sandbox.create()
  const dirname = '/home/user'

  // Start watching directory for changes
  const handle = await sandbox.files.watchDir(dirname, async (event) => {
    console.log(event)
    if (event.type === FilesystemEventType.WRITE) {
      console.log(`wrote to file ${event.name}`)
    }
  })

  // Trigger file write event
  await sandbox.files.write(`${dirname}/my-file`, 'hello')
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  sandbox = Sandbox()
  dirname = '/home/user'

  # Watch directory for changes
  handle = sandbox.files.watch_dir(dirname)
  # Trigger file write event
  sandbox.files.write(f"{dirname}/my-file", "hello")

  # Retrieve the latest new events since the last `get_new_events()` call
  events = handle.get_new_events()
  for event in events:
    print(event)
    if event.type == FilesystemEventType.Write:
      print(f"wrote to file {event.name}")
  ```
</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"
  import { Sandbox, FilesystemEventType } from '@e2b/code-interpreter'

  const sandbox = await Sandbox.create()
  const dirname = '/home/user'

  // Start watching directory for changes
  const handle = await sandbox.files.watchDir(dirname, async (event) => {
    console.log(event)
    if (event.type === FilesystemEventType.WRITE) {
      console.log(`wrote to file ${event.name}`)
    }
  }, {
    recursive: true
  })

  // Trigger file write event
  await sandbox.files.write(`${dirname}/my-folder/my-file`, 'hello')
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  sandbox = Sandbox()
  dirname = '/home/user'

  # Watch directory for changes
  handle = sandbox.files.watch_dir(dirname, recursive=True)
  # Trigger file write event
  sandbox.files.write(f"{dirname}/my-folder/my-file", "hello")

  # Retrieve the latest new events since the last `get_new_events()` call
  events = handle.get_new_events()
  for event in events:
    print(event)
    if event.type == FilesystemEventType.Write:
      print(f"wrote to file {event.name}")
  ```
</CodeGroup>


# Sandbox Lifecycle
Source: https://novita.ai/docs/guides/sandbox-e2b-sandbox



export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

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"
  import { Sandbox } from '@e2b/code-interpreter'

  // Create sandbox with and keep it running for 60 seconds.
  const sandbox = await Sandbox.create({
    timeoutMs: 60_000, // The units are milliseconds.
  })
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  # Create sandbox with and keep it running for 60 seconds.
  sandbox = Sandbox(
    timeout=60, # The units are seconds.
  )
  ```
</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"
  import { Sandbox } from '@e2b/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)
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  # Create sandbox with and keep it running for 60 seconds.
  sandbox = Sandbox(timeout=60)

  # Change the sandbox timeout to 30 seconds.
  # The new timeout will be 30 seconds from now.
  sandbox.set_timeout(30)
  ```
</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"
  import { Sandbox } from '@e2b/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
  // }
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  # Create sandbox with and keep it running for 60 seconds.
  sandbox = Sandbox(timeout=60)

  # Retrieve sandbox information.
  info = sandbox.get_info()

  print(info)

  # Output example:
  # SandboxInfo(sandbox_id='iibyw7wzt2j8x11awa5ap-82b888ba', template_id='23j9hy90m6r461w7nkrn', name='code-interpreter-v1', metadata={}, started_at=datetime.datetime(2025, 6, 30, 6, 47, 47, 644521, tzinfo=tzutc()), end_at=datetime.datetime(2025, 6, 30, 6, 48, 47, 644521, tzinfo=tzutc()), envd_version='0.2.0', _envd_access_token=<e2b.api.client.types.Unset object at 0x10236bd60>)
  ```
</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"
  import { Sandbox } from '@e2b/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"
  from e2b_code_interpreter import Sandbox

  # Create sandbox with and keep it running for 60 seconds.
  sandbox = Sandbox(timeout=60)

  # Shutdown the sandbox immediately.
  sandbox.kill()
  ```
</CodeGroup>


# Installing beta SDKs
Source: https://novita.ai/docs/guides/sandbox-e2b-sandbox-beta-sdk



To use features like [sandbox persistence](/guides/sandbox-e2b-sandbox-persistence) and [metrics](/guides/sandbox-e2b-sandbox-metrics), you need to install the beta version of the SDKs.

### Code Interpreter SDK

<CodeGroup>
  ```bash JavaScript & TypeScript icon="terminal"
  npm i @e2b/code-interpreter@beta
  ```

  ```bash Python icon="terminal"
  pip install e2b-code-interpreter==1.2.0b5
  ```
</CodeGroup>

### Core SDK

<CodeGroup>
  ```bash JavaScript & TypeScript icon="terminal"
  npm i e2b@beta
  ```

  ```bash Python icon="terminal"
  pip install e2b==1.2.0b6
  ```
</CodeGroup>

### Desktop SDK

<CodeGroup>
  ```bash JavaScript & TypeScript icon="terminal"
  npm i @e2b/desktop@beta
  ```

  ```bash Python icon="terminal"
  pip install e2b-desktop==1.7.1b1
  ```
</CodeGroup>


# Connect to running sandbox
Source: https://novita.ai/docs/guides/sandbox-e2b-sandbox-connect



export const BetaSdkSbListWarning = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Warning>Please note that the methods related to "listing sandboxes" in the <Link href="/guides/sandbox-e2b-sandbox-beta-sdk">beta SDKs</Link> have significant updates. For details, please refer to <Link href="/guides/sandbox-e2b-sandbox-list#changes-in-the-beta-sdks">Changes in the Beta SDKs</Link>.</Warning>;
  }
};

export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

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.

<BetaSdkSbListWarning />

<CodeGroup>
  ```js JavaScript & TypeScript icon="js"
  import { Sandbox } from "@e2b/code-interpreter"

  // Get all running sandboxes
  const runningSandboxes = await Sandbox.list()
  if (runningSandboxes.length === 0) {
    throw new Error("No running sandboxes found")
  }

  // Get the ID of the sandbox you want to connect to
  const sandboxId = runningSandboxes[0].sandboxId
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  # Get all running sandboxes
  running_sandboxes = Sandbox.list()

  # Get the ID of the sandbox you want to connect to
  if len(running_sandboxes) == 0:
    raise Exception("No running sandboxes found")

  # Get the ID of the sandbox you want to connect to
  sandbox_id = running_sandboxes[0].sandbox_id
  ```
</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"
  import { Sandbox } from "@e2b/code-interpreter"

  // Get all running sandboxes
  const runningSandboxes = await Sandbox.list()

  if (runningSandboxes.length === 0) {
    throw new Error("No running sandboxes found")
  }

  // Get the ID of the sandbox you want to connect to
  const sandboxId = runningSandboxes[0].sandboxId

  // Connect to the sandbox
  const sandbox = await Sandbox.connect(sandboxId)
  // Now you can use the sandbox as usual
  // ...

  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  # Get all running sandboxes
  running_sandboxes = Sandbox.list()

  # Get the ID of the sandbox you want to connect to
  if len(running_sandboxes) == 0:
    raise Exception("No running sandboxes found")

  sandbox_id = running_sandboxes[0].sandbox_id

  # Connect to the sandbox
  sandbox = Sandbox.connect(sandbox_id)
  # Now you can use the sandbox as usual
  # ...

  ```
</CodeGroup>


# Environment variables
Source: https://novita.ai/docs/guides/sandbox-e2b-sandbox-environment-variables



export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

This page covers how to set and use environment variables in a sandbox, and default environment variables inside the sandbox.

<SandboxConfigHint />

## Default environment variables

### Knowing if you are inside a sandbox

Sometimes it's useful to know if the code is running inside a sandbox. Upon creating a sandbox, an environment variable `E2B_SANDBOX` is automatically set to `true`.
You can try it out by running the following code in the sandbox:

<CodeGroup>
  ```js JavaScript & TypeScript icon="js"
  import { Sandbox } from '@e2b/code-interpreter'

  const sandbox = await Sandbox.create()
  const result = await sandbox.commands.run('echo $E2B_SANDBOX')

  console.log(result)

  // Output example:
  // { exitCode: 0, error: undefined, stdout: 'true\n', stderr: ' ' }
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  sandbox = Sandbox()
  result = sandbox.commands.run("echo $E2B_SANDBOX")

  print(result)

  # Output example:
  # CommandResult(stderr='', stdout='true\n', exit_code=0, error='')
  ```
</CodeGroup>

***

## 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"
  import { Sandbox } from '@e2b/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: '' }
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  sandbox = Sandbox(
    envs={
      'MY_VAR': 'my_value',
    },
  )

  result = sandbox.commands.run("echo $MY_VAR")

  print(result)

  # Output example:
  # { exitCode: 0, error: undefined, stdout: '123\n', stderr: '' }
  ```
</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"
  import { Sandbox } from '@e2b/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',
    },
  })
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  sandbox = Sandbox()
  result = sandbox.run_code(
      'import os; print(os.environ.get("MY_VAR"))',
      envs={
          'MY_VAR': 'my_value'
      }
  )

  print(result)
  ```
</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"
  import { Sandbox } from '@e2b/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: '' }
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  sandbox = Sandbox()
  result = sandbox.commands.run(
      'echo $MY_VAR',
      envs={
          'MY_VAR': '123'
      }
  )

  print(result)

  # Output example:
  # CommandResult(stderr='', stdout='123\n', exit_code=0, error='')
  ```
</CodeGroup>


# Internet access
Source: https://novita.ai/docs/guides/sandbox-e2b-sandbox-internet-access



export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

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"
  import { Sandbox } from '@e2b/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
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  sandbox = Sandbox()

  # 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
  ```
</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"
  import { Sandbox } from '@e2b/code-interpreter'

  const sandbox = await Sandbox.create()

  // Start a simple HTTP server inside the sandbox.
  const process = 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 process.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>
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  sandbox = Sandbox()

  # Start a simple HTTP server inside the sandbox.
  process = 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.
  process.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>
  ```
</CodeGroup>


# List sandboxes
Source: https://novita.ai/docs/guides/sandbox-e2b-sandbox-list



export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

You can list sandboxes using the `Sandbox.list()` method.

<Warning>
  Please note that methods related to "getting sandbox list" in the [beta SDK](/guides/sandbox-e2b-sandbox-beta-sdk) have significant updates. For details, please refer to [Changes in the Beta SDKs](#changes-in-the-beta-sdks).
</Warning>

<SandboxConfigHint />

<Note>
  Once you have information about running sandbox, you can [connect](/guides/sandbox-e2b-sandbox-connect) to it using the `Sandbox.connect()` method.
</Note>

<CodeGroup>
  ```js JavaScript & TypeScript icon="js"
  import { Sandbox } from '@e2b/code-interpreter'

  // Create a sandbox.
  const sandbox = await Sandbox.create({
    metadata: {
      name: 'My Sandbox',
    },
  })

  // List all running sandboxes.
  const runningSandboxes = await Sandbox.list()
  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)

  // Example output:
  // Running sandbox metadata: { name: 'My Sandbox' }
  // Running sandbox id: iqbeb0ag4drozc5ftytj5-a402f90a
  // Running sandbox started at: 2025-06-30T06:44:31.647Z
  // Running sandbox template id: 23j9hy90m6r461w7nkrn
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  # Create a sandbox.
  sandbox = Sandbox({
    metadata: {
      name: 'My Sandbox',
    },
  })

  # List all running sandboxes.
  running_sandboxes = Sandbox.list()
  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)

  # Example output:
  # Running sandbox metadata: { name: 'My Sandbox' }
  # Running sandbox id: im3mzkz550w1ew803gw0i-82b888ba
  # Running sandbox started at: 2025-06-30T06:44:53.754Z
  # Running sandbox template id: 23j9hy90m6r461w7nkrn
  ```
</CodeGroup>

## Filtering sandboxes

You can filter sandboxes by specifying <Link href="/guides/sandbox-e2b-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"
  import { Sandbox } from '@e2b/code-interpreter'

  // Create sandbox with metadata.
  const sandbox = await Sandbox.create({
    metadata: {
      env: 'dev',
      app: 'my-app',
      userId: '123',
    },
  })

  // List running sandboxes that has `userId` key with value `123` and `env` key with value `dev`.
  const runningSandboxes = await Sandbox.list({
    query: {
      metadata: { userId: '123', env: 'dev' },
    },
  })
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox
  from e2b.sandbox.sandbox_api import SandboxQuery

  # Create sandbox with metadata.
  sandbox = Sandbox(
      metadata={
          "env": "dev",
          "app": "my-app",
          "user_id": "123",
      },
  )

  # List running sandboxes that has `userId` key with value `123` and `env` key with value `dev`.
  running_sandboxes = Sandbox.list(
      query=SandboxQuery(
          metadata={
              "userId": "123",
              "env": "dev",
          }
      ),
  )
  ```
</CodeGroup>

## Changes in the Beta SDKs

<Note>
  If you're using the [beta version of the SDK](/guides/sandbox-e2b-sandbox-beta-sdk), the `Sandbox.list()` method was updated.
</Note>

### 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" 
  import { Sandbox, SandboxInfo } from '@e2b/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()

  // Get the next page of sandboxes
  const nextPage = await paginator.nextItems()
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox, SandboxInfo

  sandbox = Sandbox()

  paginator = Sandbox.list()

  # Get the first page of sandboxes (running and paused)
  firstPage = paginator.next_items()

  # Get the next page of sandboxes
  nextPage = paginator.next_items()
  ```
</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"
  import { Sandbox } from '@e2b/code-interpreter'

  // Create a sandbox.
  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()
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox, SandboxListQuery

  # Create a sandbox with metadata.
  sandbox = Sandbox()

  # List running sandboxes that are running or paused.
  paginator = Sandbox.list(
      query=SandboxListQuery(
          state=['running', 'paused'],
      ),
  )

  # Get the first page of sandboxes (running and paused)
  sandboxes = paginator.next_items()
  ```
</CodeGroup>

Filter sandboxes by the metadata key value pairs specified during Sandbox creation.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js"
  import { Sandbox } from '@e2b/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()
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox, SandboxListQuery

  # Create sandbox with metadata.
  sandbox = Sandbox(
      metadata={
          "env": "dev",
          "app": "my-app",
          "user_id": "123",
      },
  )

  # List running sandboxes that has `userId` key with value `123` and `env` key with value `dev`.
  paginator = Sandbox.list(
      query=SandboxListQuery(
          metadata={
              "userId": "123",
              "env": "dev",
          }
      ),
  )

  # Get the first page of sandboxes (running and paused)
  sandboxes = paginator.next_items()
  ```
</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"
  import { Sandbox } from '@e2b/code-interpreter'

  const paginator = Sandbox.list({
    limit: 1000,
    nextToken: '<base64-encoded-token>',
  })

  // Additional paginator properties
  // Whether there is a next page
  paginator.hasNext

  // Next page token
  paginator.nextToken

  // Fetch the next page
  await paginator.nextItems()
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox, SandboxListQuery

  paginator = Sandbox.list(
      limit=1000,
      next_token='<base64-encoded-token>',
  )

  # Additional paginator properties
  # Whether there is a next page
  paginator.has_next

  # Next page token
  paginator.next_token

  # Fetch the next page
  paginator.next_items()
  ```
</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"
  import { Sandbox } from '@e2b/code-interpreter'

  const paginator = Sandbox.list()

  // Loop through all pages
  const sandboxes: SandboxInfo[] = []
  while (paginator.hasNext) {
    const items = await paginator.nextItems()
    sandboxes.push(...items)
  }
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  paginator = Sandbox.list()

  # Loop through all pages
  sandboxes: list[SandboxInfo] = []
  while paginator.has_next:
      items = paginator.next_items()
      sandboxes.extend(items)
  ```
</CodeGroup>


# Sandbox Metadata
Source: https://novita.ai/docs/guides/sandbox-e2b-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-e2b-sandbox-connect).

You specify metadata when creating a sandbox and can access it later through listing running sandboxes with `Sandbox.list()` method.

<Note>
  If you're using the [beta version of the SDK](/guides/sandbox-e2b-sandbox-beta-sdk), the `Sandbox.list()` method was updated. See [List Sandboxes](/guides/sandbox-e2b-sandbox-list#changes-in-the-beta-sdks) for more information.
</Note>

<CodeGroup>
  ```js JavaScript & TypeScript icon="js"
  import { Sandbox } from '@e2b/code-interpreter'

  // Create sandbox with metadata.
  const sandbox = await Sandbox.create({
    metadata: {
      userId: '123',
    },
  })

  // List running sandboxes and access metadata.
  const runningSandboxes = await Sandbox.list()

  console.log(runningSandboxes[0].metadata)

  // Example output:
  // { userId: '123' }
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  # Create sandbox with metadata.
  sandbox = Sandbox(
    metadata={
      'userId': '123',
    },
  )

  # List running sandboxes and access metadata.
  running_sandboxes = Sandbox.list()

  print(running_sandboxes[0].metadata)

  # Example output:
  # { userId: '123' }
  ```
</CodeGroup>

## Filtering sandboxes by metadata

You can also filter sandboxes by metadata, you can find more about it [here](/guides/sandbox-e2b-sandbox-list#filtering-sandboxes).


# Sandbox Metrics
Source: https://novita.ai/docs/guides/sandbox-e2b-sandbox-metrics



export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

The sandbox metrics allows you to get information about the sandbox's CPU and memory usage.

<SandboxConfigHint />

<Warning>
  The sandbox "Monitoring Metrics" feature is currently in Beta testing. You need to install the [beta version of the SDK](/guides/sandbox-e2b-sandbox-beta-sdk) or [beta version of the CLI](/guides/sandbox-e2b-cli#beta-cli) to use it.
</Warning>

## Installation

To get sandbox metrics, you need to install the beta version of the SDKs and CLI:

* [Installing beta SDKs](/guides/sandbox-e2b-sandbox-beta-sdk)

* [Installing beta CLI](/guides/sandbox-e2b-cli#beta-cli)

## 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"
  import { Sandbox } from '@e2b/code-interpreter'

  const sbx = await Sandbox.create()
  console.log('Sandbox created', sbx.sandboxId)

  const metrics = await sbx.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 sbx.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'
  //   }
  // ]
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox
  import time

  sbx = Sandbox()
  print('Sandbox created', sbx.sandbox_id)

  metrics = sbx.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 = sbx.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)]
  ```
</CodeGroup>

### Getting sandbox metrics using the CLI

```bash Bash icon="terminal"
e2b sandbox metrics <sandbox_id>
```

## Limitations while in beta

* 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.


# Sandbox Persistence
Source: https://novita.ai/docs/guides/sandbox-e2b-sandbox-persistence



export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

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>
  The sandbox persistence feature is currently in Beta testing. You need to install the [Beta version SDK](/guides/sandbox-e2b-sandbox-beta-sdk) to use it.

  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 paused up to 30 days.
  * After 30 days, the data will be deleted and you will not be able to resume the sandbox. Trying to resume sandbox that was deleted or does not exist will result in the `NotFoundError` error in JavaScript SDK and `NotFoundException` exception in Python SDK.
</Warning>

## Pausing sandbox

When you pause a sandbox, both the sandbox's <Link href="/guides/sandbox-e2b-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"
  import { Sandbox } from '@e2b/code-interpreter'
  // or import { Sandbox } from 'e2b'
  // or import { Sandbox } from '@e2b/desktop'

  const sbx = await Sandbox.create()
  console.log('Sandbox created', sbx.sandboxId)

  // Pause the sandbox
  // You can save the sandbox ID in your database
  // to resume the sandbox later
  const sandboxId = await sbx.pause()
  console.log('Sandbox paused', sandboxId)
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox
  # or from e2b import Sandbox
  # or from e2b_desktop import Sandbox

  sbx = Sandbox()
  print('Sandbox created', sbx.sandbox_id)

  # Pause the sandbox
  # You can save the sandbox ID in your database
  # to resume the sandbox later
  sandbox_id = sbx.pause()
  print('Sandbox paused', sandbox_id)
  ```
</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"
  import { Sandbox } from '@e2b/code-interpreter'
  // or import { Sandbox } from 'e2b'
  // or import { Sandbox } from '@e2b/desktop'

  const sbx = await Sandbox.create()
  console.log('Sandbox created', sbx.sandboxId)

  // Pause the sandbox
  // You can save the sandbox ID in your database
  // to resume the sandbox later
  const sandboxId = await sbx.pause()
  console.log('Sandbox paused', sandboxId)

  // Resume the sandbox from the same state
  const sameSbx = await Sandbox.resume(sandboxId)
  console.log('Sandbox resumed', sameSbx.sandboxId)
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox
  # or from e2b import Sandbox
  # or from e2b_desktop import Sandbox

  sbx = Sandbox()
  print('Sandbox created', sbx.sandbox_id)

  # Pause the sandbox
  # You can save the sandbox ID in your database
  # to resume the sandbox later
  sandbox_id = sbx.pause()
  print('Sandbox paused', sandbox_id)

  # Resume the sandbox from the same state
  same_sbx = Sandbox.resume(sandbox_id)
  print('Sandbox resumed', same_sbx.sandbox_id)
  ```
</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-e2b-sandbox-list).

<CodeGroup>
  ```js JavaScript & TypeScript icon="js"
  import { Sandbox, SandboxInfo } from '@e2b/code-interpreter'
  // or import { Sandbox, SandboxInfo } from 'e2b'
  // or import { Sandbox, SandboxInfo } from '@e2b/desktop'

  // List all paused sandboxes
  const paginator = Sandbox.list({ query: { state: ['paused'] } })

  // Get the first page of paused sandboxes
  const sandboxes = await paginator.nextItems()

  // Get all paused sandboxes
  const sandboxes: SandboxInfo[] = []
  while (paginator.hasNext) {
    const items = await paginator.nextItems()
    sandboxes.push(...items)
  }
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox, SandboxInfo, SandboxListQuery
  # or from e2b import Sandbox, SandboxInfo, SandboxListQuery
  # or from e2b_desktop import Sandbox, SandboxInfo, SandboxListQuery

  # List all paused sandboxes
  paginator = Sandbox.list(SandboxListQuery(state=['paused']))

  # Get the first page of paused sandboxes
  sandboxes = paginator.next_items()

  # Get all paused sandboxes
  sandboxes: list[SandboxInfo] = []
  while paginator.has_next:
    items = paginator.next_items()
    sandboxes.extend(items)
  ```
</CodeGroup>

## Removing paused sandboxes

You can remove paused sandboxes by calling the `kill` method on the sandbox instance.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js"
  import { Sandbox } from '@e2b/code-interpreter'
  // or import { Sandbox } from 'e2b'
  // or import { Sandbox } from '@e2b/desktop'

  const sbx = await Sandbox.create()
  console.log('Sandbox created', sbx.sandboxId)

  // Pause the sandbox
  // You can save the sandbox ID in your database
  // to resume the sandbox later
  const sandboxId = await sbx.pause()

  // Remove the sandbox
  await sbx.kill()

  // Remove sandbox by id
  await Sandbox.kill(sandboxId)
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox
  # or from e2b import Sandbox
  # or from e2b_desktop import Sandbox

  sbx = Sandbox()

  # Pause the sandbox
  sandbox_id = sbx.pause()

  # Remove the sandbox
  sbx.kill()

  # Remove sandbox by id
  Sandbox.kill(sandbox_id)
  ```
</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.resume()` method like this:

<CodeGroup>
  ```js JavaScript & TypeScript icon="js"
  import { Sandbox } from '@e2b/code-interpreter'
  // or import { Sandbox } from 'e2b'
  // or import { Sandbox } from '@e2b/desktop'

  const sbx = await Sandbox.resume(sandboxId, { timeoutMs: 60 * 1000 }) // 60 seconds
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox
  # or from e2b import Sandbox
  # or from e2b_desktop import Sandbox

  sbx = Sandbox.resume(sandbox_id, timeout=60) # 60 seconds
  ```
</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.


# Sandbox Templates
Source: https://novita.ai/docs/guides/sandbox-e2b-sandbox-template



export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

export const E2BCliConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the command-line related example code in this document, please refer to the <Link href="/guides/sandbox-e2b-cli">tutorial</Link> to install the E2B command-line tool and complete <Link href="/guides/sandbox-e2b-cli-auth">authentication</Link>.</Note>;
  }
};

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" target="_blank">console</Link>.
</Tip>

<E2BCliConfigHint />

To create a sandbox template, you specify the `e2b.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 E2B CLI](#1-install-e2b-cli)
2. [Initialize sandbox template](#2-initialize-sandbox-template)
3. [Customize `e2b.Dockerfile`](#3-customize-e2b-dockerfile)
4. [Build your sandbox template](#4-build-your-sandbox-template)
5. [Start your custom sandbox](#5-start-your-custom-sandbox)

### 1. Install E2B CLI

Please refer to the <Link href="/guides/sandbox-e2b-cli">tutorial</Link> for installation and complete <Link href="/guides/sandbox-e2b-cli-auth">authentication</Link>.

### 2. Initialize sandbox template

The following command will create a basic `e2b.Dockerfile` in the current directory.

<CodeGroup isTerminalCommand>
  ```bash Bash icon="terminal"
  export E2B_DOMAIN=sandbox.novita.ai
  e2b template init
  ```
</CodeGroup>

### 3. Customize `e2b.Dockerfile`

Now you can customize your sandbox template by editing the `e2b.Dockerfile` file.

<CodeGroup title="e2b.Dockerfile">
  ```dockerfile e2b.Dockerfile icon="docker"
  # Make sure to use this base image
  FROM e2bdev/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 E2B CLI.
What is going to happen is that E2B CLI will call Docker to build the image and then push it to the E2B cloud.
Then we convert the Docker image to a micro VM that can be then launched as a sandbox with our SDK.

<CodeGroup isTerminalCommand>
  ```bash Bash icon="terminal"
  export E2B_DOMAIN=sandbox.novita.ai
  e2b 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"
  import { sandbox } from '@e2b/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 execution = await sandbox.runCode(`
  import cowsay
  cowsay.say('Hello world!')
  `)

  console.log(execution.stdout)
  ```

  ```python Python icon="python"
  from e2b_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(template_id)

  # The template installed cowsay, so we can use it
  execution = sandbox.run_code("""
  import cowsay
  cowsay.say('Hello world!')
  """)

  print(execution.stdout)
  ```
</CodeGroup>

## How it works

Every time you are building a sandbox template, we create a container based on the `e2b.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-e2b-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-e2b-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-e2b-sandbox-template-customize-cpu-ram



export const E2BCliConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the command-line related example code in this document, please refer to the <Link href="/guides/sandbox-e2b-cli">tutorial</Link> to install the E2B command-line tool and complete <Link href="/guides/sandbox-e2b-cli-auth">authentication</Link>.</Note>;
  }
};

You can customize the CPU and RAM of your sandbox template via E2B CLI.

<E2BCliConfigHint />

You need to create a <Link href="/guides/sandbox-e2b-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"
e2b 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 `e2b.toml` file in the same directory where you run the `e2b template build` command.

```toml Toml icon="gear"
template_id = "0r0efkbfwzfp9p7qpc1c"
dockerfile = "e2b.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
```


# Ready Command
Source: https://novita.ai/docs/guides/sandbox-e2b-sandbox-template-ready-cmd



export const E2BCliConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the command-line related example code in this document, please refer to the <Link href="/guides/sandbox-e2b-cli">tutorial</Link> to install the E2B command-line tool and complete <Link href="/guides/sandbox-e2b-cli-auth">authentication</Link>.</Note>;
  }
};

The ready command allows you to specify a command that will determine **template sandbox** readiness before a [snapshot](/guides/sandbox-e2b-sandbox-template#how-it-works) is created.
It is executed in an infinite loop until it returns a successful **exit code 0**.
This way you can control how long should we wait for the [start command](/guides/sandbox-e2b-sandbox-template-start-cmd) or any system state.

<E2BCliConfigHint />

## How to add ready command

When you are building a sandbox template you can specify the ready command by using the `--ready-cmd` option:

```bash Bash icon="terminal"
export E2B_DOMAIN=sandbox.novita.ai
e2b template build --ready-cmd "<your-ready-command>"
```

### Sandbox template config

You can specify the ready command inside the `e2b.toml` in the same directory where you run `e2b template build`.

```toml Toml icon="gear"
template_id = "0r0efkbfwzfp9p7qpc1c"
dockerfile = "e2b.Dockerfile"
template_name = "my-agent-sandbox"
ready_cmd = "<your-ready-command>"
```

## Default values

By default, the ready command is set to `sleep 0`, which means the sandbox template will be ready immediatelly.
If the [start command](/guides/sandbox-e2b-sandbox-template-start-cmd) is defined, the default is set to `sleep 20`, which means that the template sandbox will wait for 20 seconds before taking the snapshot.

## Examples

Here are some examples of the ready command you can use.

### Wait for URL to return 200 status code

```bash Bash icon="terminal"
ready_cmd = 'curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 | grep -q "200"'
```

### Wait for a specific process to start

```bash Bash icon="terminal"
ready_cmd = 'pgrep my-process-name > /dev/null'
```

### Wait for a file to exist

```bash Bash icon="terminal"
ready_cmd = '[ -f /tmp/ready.flag ]'
```


# Start Command
Source: https://novita.ai/docs/guides/sandbox-e2b-sandbox-template-start-cmd



export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

export const E2BCliConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the command-line related example code in this document, please refer to the <Link href="/guides/sandbox-e2b-cli">tutorial</Link> to install the E2B command-line tool and complete <Link href="/guides/sandbox-e2b-cli-auth">authentication</Link>.</Note>;
  }
};

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-e2b-sandbox-template#how-it-works).

<E2BCliConfigHint />

## 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"
export E2B_DOMAIN=sandbox.novita.ai
e2b 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 `e2b.toml` in the same directory where you run `e2b template build`.

```toml Toml icon="gear"
template_id = "0r0efkbfwzfp9p7qpc1c"
dockerfile = "e2b.Dockerfile"
template_name = "my-agent-sandbox"
start_cmd = "<your-start-command>"
```

## Logs

You can retrieve the start command's logs using the SDK during runtime.

<Note>
  These logs are the logs from the start command during the build phase.
</Note>

<SandboxConfigHint />

<CodeGroup title="Check start command logs">
  ```js JavaScript & TypeScript icon="js"
  import { Sandbox } from '@e2b/code-interpreter'

  // Spawn your custom sandbox
  const sandbox = await Sandbox.create({
    id: 'my-agent-sandbox',
    // If you specify onStderr and onStdout handlers when spawning the sandbox
    // you will see logs from the start command.
    onStderr: output => console.log("stderr", output.line),
    onStdout: output => console.log("stdout", output.line),
  })

  // Close sandbox once done
  await sandbox.close()
  ```

  ```python Python icon="python"
  from e2b_code_interpreter import Sandbox

  # Spawn your custom sandbox
  sandbox = Sandbox(
    id="my-agent-sandbox",
    # If you specify on_stderr and on_stdout handlers when spawning the sandbox
    # you will see logs from the start command.
    on_stderr=lambda output: print("stderr", output.line),
    on_stdout=lambda output: print("stdout", output.line),
  )

  # Close sandbox once done
  sandbox.close()
  ```
</CodeGroup>

Or you can use the CLI:

```bash Bash icon="terminal"
export E2B_DOMAIN=sandbox.novita.ai
e2b sandbox logs <sandbox-id>
```


# Learn more
Source: https://novita.ai/docs/guides/sandbox-learn-more



After reading the [quick start guide](/guides/sandbox-your-first-agent-sandbox), you may have a basic understanding of how to create and use Novita Agent Sandbox through the SDK. To unlock more advanced features, you can refer to the [detailed tutorial](/guides/sandbox-e2b-sandbox).

Additionally, you can also manage sandboxes and templates through the [CLI](/guides/sandbox-e2b-cli).


# 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-e2b-sandbox-persistence)**. Can pause the sandbox at any time and resume it when needed later, with filesystem and process state also being restored.
* **[Background execution](/guides/sandbox-e2b-commands-background)**. Supports background task execution, 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.

Or contact our <Link href="https://meet.brevo.com/novita-ai/contact-sales" target="_blank">solution engineers</Link> to learn how to integrate into your business.

## Pricing

Agent Sandbox supports billing for CPU and RAM (memory) by the second, with on-demand usage and flexible billing. Storage and templates are currently free. For details, please refer to [pricing page](/guides/sandbox-pricing).

## 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).


# 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 class="table table-big">
  <thead>
    <tr>
      <th style={{ minWidth: '80px' }}>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-e2b-filesystem" target="_blank">Storage</Link></td>
      <td>Currently free. Each Sandbox is allocated a fixed 20 GB storage space.</td>
    </tr>

    <tr>
      <td><Link href="/guides/sandbox-e2b-sandbox-template" target="_blank">Templates</Link></td>
      <td>Currently free.</td>
    </tr>
  </tbody>
</table>

## Pricing

* **CPU**

<table class="table table-big">
  <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 class="table table-big">
  <thead>
    <tr>
      <th>Memory (MiB)</th>
      <th>Unit Price</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Even value between 128 MiB \~ 8192 MiB</td>
      <td>\$0.0000016/GiB/s</td>
    </tr>

    <tr>
      <td>512 MiB</td>
      <td>\$0.0000008/s</td>
    </tr>

    <tr>
      <td>1 GiB</td>
      <td>\$0.0000016/s</td>
    </tr>

    <tr>
      <td>2 GiB</td>
      <td>\$0.0000032/s</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" target="_blank">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" target="_blank">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" target="_blank">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>50</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" taget="_blank">contact our support team</Link>.


# 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" target="_blank">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" target="_blank">Key Management page</Link>, you can create an API key and save the API key value for use in subsequent steps.

## Install SDK

Since Novita Agent Sandbox service is compatible with the E2B protocol, you can use any SDK that supports the E2B protocol to use Novita Agent Sandbox.

You can install the SDK by executing the following commands.

<CodeGroup isTerminalCommand>
  ```bash JavaScript & TypeScript SDK icon="terminal"
  npm i @e2b/code-interpreter dotenv
  ```

  ```bash Python SDK icon="terminal"
  pip install e2b-code-interpreter python-dotenv
  ```
</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}
E2B_API_KEY=sk_*** # Novita API key obtained from previous steps
E2B_DOMAIN=sandbox.novita.ai # Novita Agent Sandbox service domain
```

Or you can configure the API key and API domain address by setting environment variables in your terminal.

```bash Bash icon="terminal" highlight={2}
export E2B_API_KEY=sk_*** # Novita API key obtained from previous steps
export E2B_DOMAIN=sandbox.novita.ai # Novita Agent Sandbox service domain
```

## 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>
  ```ts index.ts icon="js"
  import 'dotenv/config'
  import { Sandbox } from '@e2b/code-interpreter'

  const sbx = await Sandbox.create()
  const execution = await sbx.runCode('print("hello world")')
  console.log(execution.logs)

  const files = await sbx.files.list('/')
  console.log(files)

  // Close sandbox when no longer needed
  await sbx.kill()
  ```

  ```python main.py icon="python"
  from dotenv import load_dotenv
  load_dotenv()
  from e2b_code_interpreter import Sandbox

  sbx = Sandbox()
  execution = sbx.run_code("print('hello world')")
  print(execution.logs)

  files = sbx.files.list("/")
  print(files)

  # Close sandbox when no longer needed
  sbx.kill()
  ```
</CodeGroup>

Execute the following commands to run the above code.

<CodeGroup isTerminalCommand>
  ```bash index.ts icon="terminal"
  npx tsx ./index.ts
  ```

  ```bash main.py icon="terminal"
  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" target="_blank">Serverless GPUs Console</a>.

<Frame>
  <img height="220" src="https://cf-images.novitai.com/docs/v2/serverless_pricing_1.png/docs" />
</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 height="180" src="https://cf-images.novitai.com/docs/v2/serverless_pricing_2.png/docs" />
</Frame>

* Also, after creating a Serverless Endpoint, the actual pricing can be checked on the Serverless Endpoint management page.

<Frame>
  <img height="260" src="https://cf-images.novitai.com/docs/v2/serverless_pricing_3.png/docs" />
</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 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" target="_blank">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
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" target="_blank">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.


# Novita AI & Skyvern Integration Guide
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
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>![Leveraging Novita AI in Skyvern- edit environment variables](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/LeveragingNovitaAIinSkyvern-editenvironmentvariables.jpeg "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>
  ![Temlib1 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/temlib1.png)
</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>
  ![Temlib2 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/temlib2.png)
</Frame>

Once you click on it, you’ll open the `Create Template` popup.

<Frame>
  ![Temlib3 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/temlib3.png)
</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>
  ![Readmechanchanchan Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/readmechanchanchan.png)
</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>
  ![Temlib5 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/temlib5.png)
</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>
  ![Temlib6 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/temlib6.png)
</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>
  ![Temlib7 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/temlib7.png)
</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>
  ![Temlib8 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/temlib8.png)
</Frame>

***

## Use a template to create an instance

The `Template Library` is integrated into the `Explore` section during instance creation.

<Frame>
  ![Temlib9 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/temlib9.png)
</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>
  ![Temlib10 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/temlib10.png)
</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>
  ![Temlib11 Pn](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/temlib11.png)
</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)


# Novita AI & Verba Integration Guide
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>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/VisittheVerbaWebsite.png)
</Frame>

### Step 2: **Choose Deployment Option**

* Select your preferred deployment method on the homepage to proceed.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/ChooseDeploymentOption.png)
</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>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/ConfigureSettings.png)
</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>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/ImportData.png)
</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>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/novitaai/images/third-party/StartChatting.png)
</Frame>