> ## Documentation Index
> Fetch the complete documentation index at: https://portkey-docs-add-third-party-integration-issues-fixes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# BytePlus ModelArk

> Integrate BytePlus ModelArk models with Portkey's AI Gateway

Portkey provides a robust and secure gateway to integrate various Large Language Models (LLMs) into applications, including [BytePlus ModelArk](https://www.byteplus.com/en/product/modelark) models.

With Portkey, take advantage of features like fast AI gateway access, observability, prompt management, and more, while securely managing API keys through [Model Catalog](/product/model-catalog).

<Note>
  Provider Slug: `byteplus`
</Note>

## Quick Start

Get BytePlus ModelArk working in 3 steps:

<CodeGroup>
  ```python Python icon="python" theme={null}
  from portkey_ai import Portkey

  # 1. Install: pip install portkey-ai
  # 2. Add @byteplus provider in model catalog
  # 3. Use it:

  portkey = Portkey(api_key="PORTKEY_API_KEY")

  response = portkey.chat.completions.create(
      model="@byteplus/ep-m-your-endpoint-id",
      messages=[{"role": "user", "content": "Say this is a test"}]
  )

  print(response.choices[0].message.content)
  ```

  ```js Javascript icon="square-js" theme={null}
  import Portkey from 'portkey-ai'

  // 1. Install: npm install portkey-ai
  // 2. Add @byteplus provider in model catalog
  // 3. Use it:

  const portkey = new Portkey({
      apiKey: "PORTKEY_API_KEY"
  })

  const response = await portkey.chat.completions.create({
      model: "@byteplus/ep-m-your-endpoint-id",
      messages: [{ role: "user", content: "Say this is a test" }]
  })

  console.log(response.choices[0].message.content)
  ```

  ```python OpenAI Py icon="python" theme={null}
  from openai import OpenAI
  from portkey_ai import PORTKEY_GATEWAY_URL

  # 1. Install: pip install openai portkey-ai
  # 2. Add @byteplus provider in model catalog
  # 3. Use it:

  client = OpenAI(
      api_key="PORTKEY_API_KEY",  # Portkey API key
      base_url=PORTKEY_GATEWAY_URL
  )

  response = client.chat.completions.create(
      model="@byteplus/ep-m-your-endpoint-id",
      messages=[{"role": "user", "content": "Say this is a test"}]
  )

  print(response.choices[0].message.content)
  ```

  ```js OpenAI JS icon="square-js" theme={null}
  import OpenAI from "openai"
  import { PORTKEY_GATEWAY_URL } from "portkey-ai"

  // 1. Install: npm install openai portkey-ai
  // 2. Add @byteplus provider in model catalog
  // 3. Use it:

  const client = new OpenAI({
      apiKey: "PORTKEY_API_KEY",  // Portkey API key
      baseURL: PORTKEY_GATEWAY_URL
  })

  const response = await client.chat.completions.create({
      model: "@byteplus/ep-m-your-endpoint-id",
      messages: [{ role: "user", content: "Say this is a test" }]
  })

  console.log(response.choices[0].message.content)
  ```

  ```sh cURL icon="square-terminal" theme={null}
  # 1. Add @byteplus provider in model catalog
  # 2. Use it:

  curl https://api.portkey.ai/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "x-portkey-api-key: $PORTKEY_API_KEY" \
    -d '{
      "model": "@byteplus/ep-m-your-endpoint-id",
      "messages": [
        { "role": "user", "content": "Say this is a test" }
      ]
    }'
  ```
</CodeGroup>

<Note>
  **Tip:** You can also set `provider="@byteplus"` in `Portkey()` and use just `model="ep-m-your-endpoint-id"` in the request.
</Note>

## Add Provider in Model Catalog

1. Go to [**Model Catalog → Add Provider**](https://app.portkey.ai/model-catalog/providers)
2. Select **BytePlus**
3. Choose existing credentials or create new by entering your [BytePlus API key](https://console.byteplus.com/ark/region:ark+ap-southeast-1/apiKey)
4. Name your provider (e.g., `byteplus-prod`)

### Configuration Parameters

| Parameter        | Description                                               | Required                          |
| ---------------- | --------------------------------------------------------- | --------------------------------- |
| `apiKey`         | BytePlus ModelArk API key                                 | Yes                               |
| `byteplusRegion` | Region for API requests (`ap-southeast-1` or `eu-west-1`) | No (defaults to `ap-southeast-1`) |

When using headers directly, pass the region via the `x-portkey-byteplus-region` header.

<Card title="Complete Setup Guide →" href="/product/model-catalog">
  See all setup options, code examples, and detailed instructions
</Card>

***

## Supported Endpoints

| Endpoint              | Support                |
| --------------------- | ---------------------- |
| `/chat/completions`   | Supported              |
| `/embeddings`         | Supported (multimodal) |
| `/images/generations` | Supported              |
| `/responses`          | Supported              |

## Supported Features

| Feature            | Support                            |
| ------------------ | ---------------------------------- |
| Thinking/Reasoning | Supported via `thinking` parameter |
| Streaming          | Supported                          |

***

## Embeddings

Generate multimodal embeddings using BytePlus ModelArk:

<CodeGroup>
  ```python Python theme={null}
  from portkey_ai import Portkey

  portkey = Portkey(api_key="PORTKEY_API_KEY")

  response = portkey.embeddings.create(
      model="@byteplus/ep-m-your-embedding-endpoint",
      input="The quick brown fox jumps over the lazy dog"
  )

  print(response.data[0].embedding[:5])
  ```

  ```js Javascript theme={null}
  import Portkey from 'portkey-ai'

  const portkey = new Portkey({
      apiKey: "PORTKEY_API_KEY"
  })

  const response = await portkey.embeddings.create({
      model: "@byteplus/ep-m-your-embedding-endpoint",
      input: "The quick brown fox jumps over the lazy dog"
  })

  console.log(response.data[0].embedding.slice(0, 5))
  ```

  ```sh cURL theme={null}
  curl https://api.portkey.ai/v1/embeddings \
    -H "Content-Type: application/json" \
    -H "x-portkey-api-key: $PORTKEY_API_KEY" \
    -d '{
      "model": "@byteplus/ep-m-your-embedding-endpoint",
      "input": "The quick brown fox jumps over the lazy dog"
    }'
  ```
</CodeGroup>

***

## Image Generation

Generate images using BytePlus ModelArk image models:

<CodeGroup>
  ```python Python theme={null}
  from portkey_ai import Portkey

  portkey = Portkey(api_key="PORTKEY_API_KEY")

  image = portkey.images.generate(
      model="@byteplus/ep-m-your-image-endpoint",
      prompt="A serene landscape with mountains and a lake at sunset",
      size="1024x1024"
  )

  print(image.data[0].url)
  ```

  ```js Javascript theme={null}
  import Portkey from 'portkey-ai'

  const portkey = new Portkey({
      apiKey: "PORTKEY_API_KEY"
  })

  const image = await portkey.images.generate({
      model: "@byteplus/ep-m-your-image-endpoint",
      prompt: "A serene landscape with mountains and a lake at sunset",
      size: "1024x1024"
  })

  console.log(image.data[0].url)
  ```

  ```sh cURL theme={null}
  curl https://api.portkey.ai/v1/images/generations \
    -H "Content-Type: application/json" \
    -H "x-portkey-api-key: $PORTKEY_API_KEY" \
    -d '{
      "model": "@byteplus/ep-m-your-image-endpoint",
      "prompt": "A serene landscape with mountains and a lake at sunset",
      "size": "1024x1024"
    }'
  ```
</CodeGroup>

### Additional Image Generation Parameters

BytePlus supports additional parameters for image generation:

| Parameter          | Description                                         |
| ------------------ | --------------------------------------------------- |
| `negative_prompt`  | Text describing what to exclude from the image      |
| `guidance_scale`   | How closely to follow the prompt (1-10)             |
| `seed`             | Seed for reproducible generation (-1 to 2147483647) |
| `width` / `height` | Image dimensions                                    |
| `watermark`        | Add watermark to generated images                   |

***

## Responses API

Use the OpenAI Responses API format with BytePlus models:

<CodeGroup>
  ```python Python theme={null}
  from portkey_ai import Portkey

  portkey = Portkey(api_key="PORTKEY_API_KEY")

  response = portkey.responses.create(
      model="@byteplus/ep-m-your-endpoint-id",
      input="Tell me a three sentence bedtime story about a unicorn."
  )

  print(response)
  ```

  ```js Javascript theme={null}
  import Portkey from 'portkey-ai'

  const portkey = new Portkey({
      apiKey: "PORTKEY_API_KEY"
  })

  const response = await portkey.responses.create({
      model: "@byteplus/ep-m-your-endpoint-id",
      input: "Tell me a three sentence bedtime story about a unicorn."
  })

  console.log(response)
  ```

  ```sh cURL theme={null}
  curl https://api.portkey.ai/v1/responses \
    -H "Content-Type: application/json" \
    -H "x-portkey-api-key: $PORTKEY_API_KEY" \
    -d '{
      "model": "@byteplus/ep-m-your-endpoint-id",
      "input": "Tell me a three sentence bedtime story about a unicorn."
    }'
  ```
</CodeGroup>

<Card title="Responses API reference" icon="code" href="/product/ai-gateway/responses-api">
  Full Responses API docs — streaming, tools, instructions, and more
</Card>

***

## Regions

BytePlus ModelArk is available in multiple regions. Configure the region when setting up your provider:

| Region                     | Base URL                                         |
| -------------------------- | ------------------------------------------------ |
| `ap-southeast-1` (default) | `https://ark.ap-southeast.bytepluses.com/api/v3` |
| `eu-west-1`                | `https://ark.eu-west.bytepluses.com/api/v3`      |

***

## Supported Models

BytePlus ModelArk provides access to various foundation models. Use either:

* **Model ID** (preset endpoints): `ep-m-xxx` format
* **Endpoint ID** (custom endpoints): `ep-xxx` format

For the complete list of available models, refer to the [BytePlus ModelArk documentation](https://docs.byteplus.com/en/docs/ModelArk/).

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Add Metadata" icon="tags" href="/product/observability/metadata">
    Add metadata to your BytePlus requests
  </Card>

  <Card title="Gateway Configs" icon="gear" href="/product/ai-gateway/configs">
    Add gateway configs to your BytePlus requests
  </Card>

  <Card title="Tracing" icon="chart-line" href="/product/observability/traces">
    Trace your BytePlus requests
  </Card>

  <Card title="Fallbacks" icon="arrow-rotate-left" href="/product/ai-gateway/fallbacks">
    Setup fallback strategies with BytePlus
  </Card>
</CardGroup>

For complete SDK documentation:

<Card title="SDK Reference" icon="code" href="/api-reference/sdk/list">
  Complete Portkey SDK documentation
</Card>