### Ark Runtime Tool Call Example (Go)

Source: https://docs.byteplus.com/en/docs/ModelArk/1958524

This example demonstrates how to use the Ark Runtime SDK in Go to make a tool-calling request. It includes setting up the client, defining a tool (get_weather), sending the initial request, simulating tool execution, and then sending a second request with the tool's output to get the final answer.

```APIDOC
## POST /api/v3/responses

### Description
This endpoint allows you to interact with the Ark Runtime model, enabling it to call external tools based on user input and then process the tool's output to generate a final response.

### Method
POST

### Endpoint
/api/v3/responses

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **model** (string) - Required - The name of the model to use (e.g., "seed-1-6-250915").
- **store** (boolean) - Optional - Whether to store the conversation history.
- **input** (object) - Required - The user's input message or a sequence of messages.
  - **listValue** (object) - Represents a list of input items.
    - **listValue** (array) - An array of `InputItem` objects.
      - **easyMessage** (object) - Represents a simple message.
        - **role** (string) - Required - The role of the message sender (e.g., "user").
        - **type** (string) - Required - The type of the item (e.g., "message").
        - **content** (object) - The content of the message.
          - **stringValue** (string) - The text content of the message.
- **tools** (array) - Optional - A list of tools the model can use.
  - **toolFunction** (object) - Defines a function tool.
    - **name** (string) - Required - The name of the function.
    - **type** (string) - Required - The type of the tool (e.g., "function").
    - **description** (string) - Optional - A description of what the function does.
    - **parameters** (object) - The JSON schema defining the function's parameters.
- **previousResponseId** (string) - Optional - The ID of the previous response, used for continuing a conversation.

### Request Example (First Round)
```json
{
  "model": "seed-1-6-250915",
  "store": true,
  "input": {
    "listValue": {
      "listValue": [
        {
          "easyMessage": {
            "role": "user",
            "type": "message",
            "content": {
              "stringValue": "Query the weather in Beijing today"
            }
          }
        }
      ]
    }
  },
  "tools": [
    {
      "toolFunction": {
        "name": "get_weather",
        "type": "function",
        "description": "Query weather (including temperature and weather conditions) based on the city name",
        "parameters": {
          "value": "{\"type\":\"object\",\"properties\":{\"location\":{\"type\":\"string\",\"description\":\"City name, e.g., Beijing, Shanghai (only domestic prefecture-level cities are supported)\"}},\"required\":[\"location\"]}"
        }
      }
    }
  ]
}
```

### Response (First Round - Tool Call)
```json
{
  "id": "resp_id_123",
  "output": [
    {
      "functionToolCall": {
        "callId": "call_id_abc",
        "arguments": "{\"location\": \"Beijing\"}"
      }
    }
  ]
}
```

### Request Example (Second Round - Tool Output)
```json
{
  "model": "seed-1-6-250915",
  "previousResponseId": "resp_id_123",
  "input": {
    "listValue": {
      "listValue": [
        {
          "functionToolCallOutput": {
            "callId": "call_id_abc",
            "output": "{\"city\": \"Beijing\", \"date\": \"2025-10-13\", \"temperature\": \"18~28℃\", \"condition\": \"Sunny to Cloudy\", \"wind\": \"Northeast wind level 2\"}",
            "type": "function_call_output"
          }
        }
      ]
    }
  }
}
```

### Response (Second Round - Final Answer)
```json
{
  "id": "resp_id_456",
  "output": [
    {
      "message": {
        "content": [
          {
            "text": "The weather in Beijing today is Sunny to Cloudy, with temperatures ranging from 18 to 28 degrees Celsius. There is a Northeast wind level 2."
          }
        ]
      }
    }
  ]
}
```

### Error Handling
- **response error**: If the API returns an error during the request.
- **json marshal error**: If there's an issue marshalling the tool output to JSON.
```

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

### Batch Chat Inference - Quick Start

Source: https://docs.byteplus.com/en/docs/ModelArk/1399517

This section provides a quick start guide using a minimized sample code to initiate a batch inference request with the Batch Chat interface.

```APIDOC
## POST /batch_chat/completions

### Description
Initiates a batch inference request using the Batch Chat interface.

### Method
POST

### Endpoint
/batch_chat/completions

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **model** (string) - Required - The batch inference endpoint ID.
- **messages** (array) - Required - A list of message objects, where each object has a 'role' (string) and 'content' (string).

### Request Example
```json
{
  "model": "<MODEL>",
  "messages": [
    {"role": "user", "content": "Hello"}
  ]
}
```

### Response
#### Success Response (200)
- **choices** (array) - Contains the completion choices.
  - **message** (object)
    - **content** (string) - The content of the message.

#### Response Example
```json
{
  "choices": [
    {
      "message": {
        "content": "Hello! How can I help you today?"
      }
    }
  ]
}
```
```

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

### Multi-step Function Calling Example

Source: https://docs.byteplus.com/en/docs/ModelArk/1262342

Demonstrates a multi-step process to fulfill a user request involving external function calls. This example shows how to get weather information and send it to a recipient, illustrating a common pattern for complex task execution.

```python
def get_current_weather(location):
    # Function to get weather information for a given location
    pass

def send_message(recipient, message):
    # Function to send a message to a recipient
    pass

# User request: "Check the weather in Beijing and send the result to John Doe."

# Step 1: Get weather information
weather_info = get_current_weather("Beijing")

# Step 2: Send the message
send_message("John Doe", weather_info)

# Step 3: Summarize and return response
```

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

### Generate Images with Go SDK

Source: https://docs.byteplus.com/en/docs/ModelArk/1399008

Provides a Go code example for generating images using the ModelArk SDK. It initializes a client with an API key and base URL, then makes a request to the image generation endpoint.

```go
package main

import (
    "context"
    "fmt"
    "os"
    "strings"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/service/arkruntime"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/service/arkruntime/model"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus"
)

func main() {
    client := arkruntime.NewClientWithApiKey(        
        os.Getenv("ARK_API_KEY"), // Get API Key: https://console.byteplus.com/ark/region:ark+ap-southeast-1/apikey
        arkruntime.WithBaseUrl("https://ark.ap-southeast.bytepluses.com/api/v3"), //The base URL for model invocation
    )    
    ctx := context.Background()

    generateReq := model.GenerateImagesRequest{
       Model:          "seedream-4-5-251128", //Replace with Model ID
       Prompt:         "Vibrant close-up editorial portrait, model with piercing gaze, wearing a sculptural hat, rich color blocking, sharp focus on eyes, shallow depth of field, Vogue magazine cover aesthetic, shot on medium format, dramatic studio lighting.",
       Size:           byteplus.String("2K"),
       ResponseFormat: byteplus.String(model.GenerateImagesResponseFormatURL),
       Watermark:      byteplus.Bool(false),
    }

    imagesResponse, err := client.GenerateImages(ctx, generateReq)
    if err != nil {
       fmt.Printf("generate images error: %v\n", err)
       return
    }

    fmt.Printf("%s\n", *imagesResponse.Data[0].Url)
}
```

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

### Streaming Output with Python SDK

Source: https://docs.byteplus.com/en/docs/ModelArk/1895586

This example demonstrates how to use the Python SDK to upload a video file and then process it using the streaming output feature to get real-time responses.

```APIDOC
## POST /api/v3/responses

### Description
This endpoint allows for real-time, incremental content delivery by streaming responses from the model. It's useful for long-running inference tasks to provide immediate feedback to the user and avoid timeouts.

### Method
POST

### Endpoint
/api/v3/responses

### Parameters
#### Query Parameters
- **stream** (boolean) - Required - Set to `true` to enable streaming.

#### Request Body
- **model** (string) - Required - The ID of the model to use for generation.
- **input** (array) - Required - An array of input messages, which can include text and file references (e.g., video).
  - **role** (string) - Required - The role of the message sender (e.g., "user").
  - **content** (array) - Required - The content of the message.
    - **type** (string) - Required - The type of content (e.g., "input_video", "input_text").
    - **file_id** (string) - Required if type is "input_video" - The ID of the uploaded video file.
    - **text** (string) - Required if type is "input_text" - The text content of the message.
- **caching** (object) - Optional - Caching configuration.
  - **type** (string) - Required - The type of caching (e.g., "enabled").
- **store** (boolean) - Optional - Whether to store the response.

### Request Example
```json
{
  "model": "seed-1-6-250915",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_video",
          "file_id": "file-12345"
        },
        {
          "type": "input_text",
          "text": "Describe the sequence of actions performed by the person in the video and output the results in JSON format. Include start_time, end_time, event, and danger (boolean), and express timestamps in HH:mm:ss format."
        }
      ]
    }
  ],
  "caching": {
    "type": "enabled"
  },
  "store": true,
  "stream": true
}
```

### Response
#### Success Response (200)
Responses are streamed as a sequence of events. The exact structure of each event depends on its type (e.g., `ResponseReasoningSummaryTextDeltaEvent`, `ResponseTextDeltaEvent`, `ResponseCompletedEvent`).

#### Response Example (Event Stream)
```
ResponseTextDeltaEvent(delta='The person in the video')
ResponseTextDeltaEvent(delta=' starts by')
ResponseOutputItemAddedEvent(type='output_text')
ResponseTextDeltaEvent(delta=' picking up')
ResponseTextDeltaEvent(delta=' a red ball.')
ResponseTextDoneEvent()
ResponseCompletedEvent(response=UsageInfo(model='seed-1-6-250915', total_tokens=50, prompt_tokens=20, completion_tokens=30))
```
```

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

### Install Volcano Engine SDK (Go)

Source: https://docs.byteplus.com/en/docs/ModelArk/1465834

Command to install the Volcano Engine Go SDK using the go get command. This makes the SDK available for use in your Go projects.

```shell
go get -u github.com/volcengine/volc-sdk-golang
```

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

### Perform Multimodal Understanding with Java SDK

Source: https://docs.byteplus.com/en/docs/ModelArk/1399008

This Java code snippet outlines the setup for using the BytePlus Java SDK to perform multimodal understanding. It initializes the ArkService with an API key and base URL, preparing to send requests. The full request construction and execution would follow.

```java
package com.ark.sample;

import com.byteplus.ark.runtime.service.ArkService;
import com.byteplus.ark.runtime.model.responses.request.*;
import com.byteplus.ark.runtime.model.responses.content.*;
import com.byteplus.ark.runtime.model.responses.item.*;
import com.byteplus.ark.runtime.model.responses.response.ResponseObject;
import com.byteplus.ark.runtime.model.responses.constant.ResponsesConstants;

public class demo {
  public static void main(String[] args) {
    String apiKey = System.getenv("ARK_API_KEY");
    // Further initialization and request building would go here.
    // Example: ArkService service = ArkService.newBuilder().apiKey(apiKey).baseUrl("https://ark.ap-southeast-1.byteplus.com/api/v3").build();
  }
}
```

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

### Arkiteck SDK - Weather Example

Source: https://docs.byteplus.com/en/docs/ModelArk/1262342

This example demonstrates how to use the Arkiteck SDK to get current weather information for a specified location. It includes defining a tool function `get_current_weather` and using it within a `Context` for chat completions.

```APIDOC
## Arkiteck SDK - Weather Tool

### Description
This section details how to define and use a Python function as a tool within the Arkiteck SDK to retrieve weather information. The SDK automatically handles the inference and execution of these tools based on user prompts.

### Method
N/A (This is a code example demonstrating SDK usage, not a direct API endpoint call)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```python
from arkitect.core.component.context.context import Context
from enum import Enum
import asyncio
from pydantic import Field

def get_current_weather(
    location: str = Field(description="Location information, e.g., Beijing, Shanghai"),
    unit: str = Field(description="Temperature unit, optional values are Celsius or Fahrenheit")
):
    """
    Get the weather information of the specified location
    """
    return f"{location} today the weather is sunny, temperature 25 {unit}."

async def chat_with_tool():
    ctx = Context(
            model="", # Replace with your model ID.
            tools=[
                get_current_weather
            ],  # Add all your Python methods to the list as tools.
        )
    await ctx.init()
    completion = await ctx.completions.create(
        messages=[
            {"role": "user", "content": "What's the weather like in Beijing and Shanghai today?"}
        ],
        stream=False
    )
    return completion

completion = asyncio.run(chat_with_tool())
print(completion.choices[0].message.content)
```

### Response
#### Success Response (200)
N/A (This is a code example, the output is printed to the console)

#### Response Example
```
Beijing today the weather is sunny, temperature 25 Celsius.
Shanghai today the weather is sunny, temperature 25 Celsius.
```
```

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

### Video Generation API Examples

Source: https://docs.byteplus.com/en/docs/ModelArk/1399008

Examples for generating video content using the ModelArk API. This section provides code snippets in Python, Java, and Go to illustrate how to utilize the video generation functionality based on text and image inputs.

```python
import os
import time
```

```java
import os
import time
```

```go
import os
import time
```

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

### Install and Generate Images with Python SDK

Source: https://docs.byteplus.com/en/docs/ModelArk/1399008

Installs the byteplus-python-sdk-v2 and demonstrates how to generate images using the Ark client. It requires an API key and specifies model parameters like prompt, size, and response format.

```python
pip install byteplus-python-sdk-v2
from byteplussdkarkruntime import Ark 
import os

client = Ark(
    #The base URL for model invocation
    base_url="https://ark.ap-southeast.bytepluses.com/api/v3", 
    # Get API Key: https://console.byteplus.com/ark/region:ark+ap-southeast-1/apikey
    api_key=os.getenv('ARK_API_KEY'), 
)
 
imagesResponse = client.images.generate( 
    #Replace with Model ID
    model="seedream-4-5-251128",
    prompt="Vibrant close-up editorial portrait, model with piercing gaze, wearing a sculptural hat, rich color blocking, sharp focus on eyes, shallow depth of field, Vogue magazine cover aesthetic, shot in medium format, dramatic studio lighting.",
    size="2K",
    response_format="url",
    watermark=False
) 
 
print(imagesResponse.data[0].url)
```

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

### Document Understanding with PDF Upload (Go SDK)

Source: https://docs.byteplus.com/en/docs/ModelArk/1958521

Provides the initial setup for using the Go SDK to interact with the ModelArk API. This snippet shows how to create a client and start a context for uploading a PDF file, with placeholders for error handling and further operations.

```go
package main

import (
    "context"
    "fmt"
    "io"
    "os"
    "time"

    "github.com/byteplus-sdk/byteplus-go-sdk-v2/service/arkruntime"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/service/arkruntime/model/file"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/service/arkruntime/model/responses"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus"
)

func main() {
    client := arkruntime.NewClientWithApiKey(os.Getenv("ARK_API_KEY"))
    ctx := context.Background()

    fmt.Println("----- upload file data -----")
    data, err := os.Open("/Users/doc/demo.pdf")
    if err != nil {

```

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

### Initialize Ark Runtime Client in Go

Source: https://docs.byteplus.com/en/docs/ModelArk/1399008

This Go snippet shows the initialization of the Ark runtime client using an API key. It sets up the client with the base URL for model invocation and retrieves the API key from environment variables. This is the first step before making any requests to the Ark service.

```go
package main

import (
    "context"
    "fmt"
    "os"
    "time"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/service/arkruntime"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/service/arkruntime/model"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus"
)

func main() {
    client := arkruntime.NewClientWithApiKey(        
        os.Getenv("ARK_API_KEY"), // Get API Key：https://console.byteplus.com/ark/region:ark+ap-southeast-1/apikey

```

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

### Basic ModelArk SDK - Chat Completion

Source: https://docs.byteplus.com/en/docs/ModelArk/1262342

This example shows the basic setup for using the ModelArk SDK to perform chat completions. It initializes the client and prepares a list of messages for the conversation.

```APIDOC
## Basic ModelArk SDK - Chat Completion

### Description
This section provides a basic example of initializing the ModelArk SDK client and structuring messages for a chat completion request.

### Method
N/A (This is a code example demonstrating SDK usage, not a direct API endpoint call)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```python
from byteplussdkarkruntime import Ark
from byteplussdkarkruntime.types.chat import ChatCompletion
import json

client = Ark()
messages = [
    {"role": "user", "content": "What's the weather like in Beijing and Shanghai today?"}
]

# To send the request and get a completion, you would typically do:
# completion = client.chat.completions.create(
#     model="your-model-id",
#     messages=messages
# )
# print(completion.choices[0].message.content)
```

### Response
#### Success Response (200)
N/A (This is a code example, the actual response would depend on the model's output)

#### Response Example
```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "your-model-id",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I cannot provide real-time weather information. Please check a weather service."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25
  }
}
```
```

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

### Install and Use Python SDK for Video Understanding

Source: https://docs.byteplus.com/en/docs/ModelArk/1895586

Installs the byteplus-python-sdk-v2 and demonstrates how to use the Ark client to process a video. It sends a video URL and a text prompt to the model, then prints the completion result. Ensure the ARK_API_KEY environment variable is set.

```python
from byteplussdkarkruntime import Ark 
import os

client = Ark(
    #The base URL for model invocation . 
    base_url="https://ark.ap-southeast.bytepluses.com/api/v3", 
    # Get API Key：https://console.byteplus.com/ark/region:ark+ap-southeast-1/apikey
    api_key=os.getenv('ARK_API_KEY'), 
)

completion = client.chat.completions.create(
    #Replace with Model ID . 
    model = "seed-1-6-250915",
    messages=[
        {
            # Set the message role to user
            "role": "user",
            "content": [
                {
                    "type": "video_url",
                    "video_url": {
                        # Replace the link with the actual video URL
                        "url":  "https://ark-doc.tos-ap-southeast-1.bytepluses.com/video_understanding.mp4",
                        "fps": 5, # Extract 5 frames per second for video understanding
                    }
                },
                # Text message content that asks what's in the video
                {"type": "text", "text": "At what time point did the referee appear?"},
            ],
        }
    ],
)

print(completion.choices[0])
```

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

### Text Generation using Java SDK

Source: https://docs.byteplus.com/en/docs/ModelArk/1399008

This Java example demonstrates text generation using the BytePlus Ark SDK. It builds an `ArkService` instance with your API key and base URL. A `CreateResponsesRequest` is constructed with the model and input, and the `createResponse` method is invoked. The result is printed, and the service executor is shut down. Dependencies: `com.byteplus.ark.runtime`.

```java
package com.ark.sample;

import com.byteplus.ark.runtime.service.ArkService;
import com.byteplus.ark.runtime.model.responses.request.*;
import com.byteplus.ark.runtime.model.responses.response.ResponseObject;

public class demo {
    public static void main(String[] args) {
        String apiKey = System.getenv("ARK_API_KEY");
        //The base URL for model invocation
        ArkService arkService = ArkService.builder().apiKey(apiKey).baseUrl("https://ark.ap-southeast.bytepluses.com/api/v3").build();

        CreateResponsesRequest request = CreateResponsesRequest.builder()
                .model("seed-1-6-250915")
                .input(ResponsesInput.builder().stringValue("hello").build()) // Replace with your prompt
                // Manually disable deep thinking: .thinking(ResponsesThinking.builder().type(ResponsesConstants.THINKING_TYPE_DISABLED).build())
                .build();

        ResponseObject resp = arkService.createResponse(request);
        System.out.println(resp);

        arkService.shutdownExecutor();
    }
}
```

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

### Install and Use BytePlus Python SDK for Video Understanding

Source: https://docs.byteplus.com/en/docs/ModelArk/1895586

Installs the byteplus-python-sdk-v2 and demonstrates how to use the Ark client to process video content. It requires an API key and specifies a model ID for video understanding. The input includes a video URL and a text prompt.

```python
from byteplussdkarkruntime import Ark 
import os

client = Ark(
    #The base URL for model invocation
    base_url="https://ark.ap-southeast.bytepluses.com/api/v3", 
    # Get API Key：https://console.byteplus.com/ark/region:ark+ap-southeast-1/apikey
    api_key=os.getenv('ARK_API_KEY'), 
)

completion = client.chat.completions.create(
    #Replace with Model ID
    model = "seed-1-6-250915",
    messages=[
        {
            # Set the message role to user
            "role": "user",
            "content": [
                {
                    "type": "video_url",
                    "video_url": {
                        # Replace the link with the actual video URL
                        "url":  "https://ark-doc.tos-ap-southeast-1.bytepluses.com/video_understanding.mp4",
                        "fps": 2, # Extract 2 frames per second for video understanding
                    }
                },
                {"type": "text", "text": "What is in the video?"},
            ],
        }
    ],
)

print(completion.choices[0])
```

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

### Define Role-based System Prompt (Bash Example)

Source: https://docs.byteplus.com/en/docs/ModelArk/1221660

This snippet demonstrates how to structure a system prompt for an AI model using a bash-like format. It outlines key elements such as defining the AI's persona, background, personality traits, language style, and providing supplementary information for dialogue context. This structure helps in guiding the AI's responses.

```bash
You are {a specific person}, called {xxx}, born in {explain background information and context}.
Personality traits:
Language style:
Interpersonal relationships:
Past experiences:
Classic lines or catchphrases:
{Lines 1 (Supplementary information: You can put actions, expressions, tone, psychological activities, and story background in () to provide supplementary information for the dialogue.)}
{Lines 2}
```

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

### Go Signature Generation

Source: https://docs.byteplus.com/en/docs/ModelArk/1465834

This section provides instructions for generating request signatures using the Go SDK, including installation and a code example for preparing a signed request.

```APIDOC
## POST /api/knowledge/collection/search

### Description
This endpoint is used for searching within the knowledge base. It requires a signature generated using the Volcano Engine SDK.

### Method
POST

### Endpoint
/api/knowledge/collection/search

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **body** ([]byte) - Required - The request payload as a byte slice.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **field1** (type) - Description

#### Response Example
```json
{
  "example": "response body"
}
```

### SDK Installation (Go)
```bash
go get -u github.com/volcengine/volc-sdk-golang
```

### Signature Generation (Go)
```go
package main

import (
	"bytes"
	"fmt"
	"net/http"
	"net/url"
	"strings"
	"io/ioutil"
	"github.com/volcengine/volc-sdk-golang/base"
)

const (
	testAk = "***"
	testSk = "***"
)

func PrepareRequest(method string, path string, ak string, sk string, query url.Values, body []byte) *http.Request {
	u := url.URL{
		Scheme: "https",
		Host:   "api-knowledgebase.mlp.cn-hongkong.bytepluses.com",
		Path:   "/api/knowledge/collection/search",
	}
	if query != nil {
		u.RawQuery = query.Encode()
	}
	req, _ := http.NewRequest(strings.ToUpper(method), u.String(), bytes.NewReader(body))
	req.Header.Add("Accept", "application/json")
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Host", "api-knowledgebase.mlp.cn-hongkong.bytepluses.com")

	credential := base.Credentials{
		AccessKeyID:     ak,
		SecretAccessKey: sk,
		Service:         "air",
		Region:          "cn-hongkong",
	}
	req = credential.Sign(req)
	return req
}
```
```

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

### Install and Use ModelArk SDK in Python

Source: https://docs.byteplus.com/en/docs/ModelArk/1362931

Installs the ModelArk Python SDK and demonstrates how to initialize the client with API key and base URL. It then shows how to send a multi-modal message containing an image URL and text to the chat completion API, printing the first choice from the response.

```python
from byteplussdkarkruntime import Ark 
import os

client = Ark(
    # The base URL for model invocation
    base_url="https://ark.ap-southeast.bytepluses.com/api/v3", 
    # Get API Key：https://console.byteplus.com/ark/region:ark+ap-southeast-1/apikey
    api_key=os.getenv('ARK_API_KEY'), 
)

completion = client.chat.completions.create(
    # Replace with Model ID
    model = "seed-1-6-250915",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "image_url","image_url": {"url": "https://ark-doc.tos-ap-southeast-1.bytepluses.com/ModelArk_demo_img_1.jpg"}},
                {"type": "text", "text": "Which model series supports image input?"},
            ],
        }
    ],
)

print(completion.choices[0])
```

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

### Start and Verify Codex CLI Session

Source: https://docs.byteplus.com/en/docs/ModelArk/2188959

Demonstrates how to start a Codex CLI session using a specific profile and verify its status.

```Shell
codex --profile seed-code
```

```Bash
codex status
```

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

### Install and Initialize BytePlus Python SDK v2

Source: https://docs.byteplus.com/en/docs/ModelArk/1359497

This snippet shows how to install the SDK using pip and initialize the Ark client. It requires setting the base URL for model invocation and obtaining an API key, typically via an environment variable.

```shell
pip install byteplus-python-sdk-v2
```

```python
from byteplussdkarkruntime import Ark 
import os

client = Ark(
    #The base URL for model invocation
    base_url="https://ark.ap-southeast.bytepluses.com/api/v3", 
    # Get API Key：https://console.byteplus.com/ark/region:ark+ap-southeast-1/apikey
    api_key=os.getenv('ARK_API_KEY'), 
)
#Replace with Model ID
ark_model="deepseek-v3-250324"

messages = [
    {"role": "system", "content": "The following is a scene from Journey to the West. Please converse according to the specified role. For each round of dialogue, only reply with the content of the current role; do not add any additional content.\n\nAfter leaving Wuzhuang Guan, Tang Seng and his disciples traveled for more than a month and arrived at the foot of a great mountain. Wukong looked around and saw lofty mountains, steep ridges, overgrown weeds, and extremely dangerous terrain."},
    {"role": "assistant", "content": "Wukong said:"}
]

completion = client.chat.completions.create(
    model=ark_model,
    messages=messages
)
print(messages[-1]['content']+completion.choices[0].message.content)
```

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

### Text Generation using Go SDK

Source: https://docs.byteplus.com/en/docs/ModelArk/1399008

This Go code snippet illustrates text generation with the BytePlus Go SDK. It sets up an Ark runtime client using an API key and base URL. The `CreateResponses` method is called with a request object containing the model and input. Error handling is included, and the response is printed. Dependencies: `github.com/byteplus-sdk/byteplus-go-sdk-v2/service/arkruntime`.

```go
package main

import (
    "context"
    "fmt"
    "os"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/service/arkruntime"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/service/arkruntime/model/responses"
)

func main() {
    client := arkruntime.NewClientWithApiKey(
        // Get API Key：https://console.byteplus.com/ark/region:ark+ap-southeast-1/apikey
        os.Getenv("ARK_API_KEY"),
        arkruntime.WithBaseUrl("https://ark.ap-southeast.bytepluses.com/api/v3"),
    )
    ctx := context.Background()

    resp, err := client.CreateResponses(ctx, &responses.ResponsesRequest{
        Model: "seed-1-6-250915",
        Input: &responses.ResponsesInput{Union: &responses.ResponsesInput_StringValue{StringValue: "hello"}}, // Replace with your prompt
        // Manually disable deep thinking: &responses.ResponsesThinking{Type: responses.ThinkingType_disabled.Enum()}
    })
    if err != nil {
        fmt.Printf("response error: %v\n", err)
        return
    }
    fmt.Println(resp)
}
```

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

### Example Web Search Tool Usage Details

Source: https://docs.byteplus.com/en/docs/ModelArk/1783703

Shows an example of detailed usage statistics for the web search tool, including counts for different search providers or types like toutiao, moji, and search_engine.

```json
{
  "tool_usage_details": {
    "web_search": {
      "toutiao": 1,
      "moji": 1,
      "search_engine": 1
    }
  }
}
```

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

### Video Understanding Request Example

Source: https://docs.byteplus.com/en/docs/ModelArk/1895586

This example demonstrates how to structure a request for video understanding, which is analogous to a multi-image understanding request. It includes text prompts and image URLs sampled at specific time intervals.

```APIDOC
## POST /api/video/understand

### Description
Sends a video for understanding analysis, similar to how multi-image requests are processed. This allows for temporal analysis by providing frames at specific timestamps.

### Method
POST

### Endpoint
`/api/video/understand`

### Parameters
#### Request Body
- **model** (string) - Required - The identifier for the model to use for understanding.
- **messages** (array) - Required - An array of message objects, where each object contains the role and content.
  - **role** (string) - Required - The role of the message sender (e.g., 'user').
  - **content** (array) - Required - An array of content parts, which can be text or image URLs with timestamps.
    - **type** (string) - Required - The type of content ('text' or 'image_url').
    - **text** (string) - Optional - The text content, including temporal information like `[0.0 second]`.
    - **image_url** (object) - Optional - An object containing the URL of the image frame.
      - **url** (string) - Required - The URL of the image frame.

### Request Example
```json
{
    "model": "seed-1-6-250915",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type":"text",
                    "text":"Is this scary?"
                },
                {
                    "type":"text",
                    "text":"[0.0 second]"
                },
                {
                    "type":"image_url",
                    "image_url":{
                        "url":"https://ark-doc.tos-ap-southeast-1.bytepluses.com/80hou@0.jpg"}
                },
                {
                    "type":"text",
                    "text":"[1.0 second]"
                },
                {
                    "type":"image_url",
                    "image_url":{
                        "url":"https://ark-doc.bytepluses.com/80hou@1.jpg"}
                },
                {
                    "type":"text",
                    "text":"[2.0 second]"
                },
                {
                    "type":"image_url",
                    "image_url":{
                        "url":"https://ark-doc.tos-ap-southeast-1.bytepluses.com/80hou@2.jpg"}
                },
                {
                    "type":"text",
                    "text":"[3.0 second]"
                },
                {
                    "type":"image_url",
                    "image_url":{
                        "url":"https://ark-doc.tos-ap-southeast-1.bytepluses.com/80hou@3.jpg"}
                },
                {
                    "type":"text",
                    "text":"[4.0 second]"
                },
                {
                    "type":"image_url",
                    "image_url":{
                        "url":"https://ark-doc.tos-ap-southeast-1.bytepluses.com/80hou@4.jpg"}
                },
                {
                    "type":"text",
                    "text":"[5.0 second]"
                },
                {
                    "type":"image_url",
                    "image_url":{
                        "url":"https://ark-doc.tos-ap-southeast-1.bytepluses.com/80hou@5.jpg"}
                }
            ]
        }
    ]
}
```

### Response
#### Success Response (200)
- **response** (object) - The analysis result from the video understanding model.

#### Response Example
```json
{
  "response": "Analysis results for the video content."
}
```
```

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

### Initialize Go Module and Install Go SDK for ModelArk

Source: https://docs.byteplus.com/en/docs/ModelArk/1319854

Initializes a Go module and installs the latest ModelArk Go SDK (v2). This requires Go version 1.18 or later. Replace `<your-project-name>` with your project's actual name.

```Bash
go mod init <your-project-name>
```

```Bash
go get -u github.com/byteplus-sdk/byteplus-go-sdk-v2
```

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

### Install OpenAI Python SDK

Source: https://docs.byteplus.com/en/docs/ModelArk/1399008

Installs the OpenAI Python SDK. This SDK can be used alongside ModelArk, potentially for accessing compatible models or features.

```bash
pip install openai
```

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

### Classify User Reviews with Samples (Plain Text)

Source: https://docs.byteplus.com/en/docs/ModelArk/1221660

This snippet demonstrates how to use a model as a binary text classifier to distinguish between positive and negative user reviews. It provides clear instructions and examples to guide the model's classification. The output is expected to be a simple 'positive review' or 'negative review'.

```plain
Please help me distinguish whether the user input text is a positive review or a negative review according to the following classification method. Please directly output: positive review/negative review.
Please refer to the following examples:
Example 1:
User input: I went to this restaurant last night and their food and service were amazing. I will definitely patronize again.
Output: positive review
Example 2:
User input: I have read this book. Some plots are okay, but the overall plot is dragging and average.
Output: negative review
Example 3:
User input: I watched this movie yesterday. I think it’s okay, but some parts are a bit boring.
Output: negative review
Example 4:
User input: I watched this movie last week. It was a waste of time. The plot was boring and the actors’ performances were not satisfactory. I really regret watching it.
Output: negative review
Please answer the following questions:
User input: I recently dined at this restaurant. It was okay, but not particularly amazing.
Output:
```

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

### Install and Verify Codex CLI

Source: https://docs.byteplus.com/en/docs/ModelArk/2188959

Installs the Codex CLI globally using npm and provides a command to verify the installation by checking the version.

```Bash
npm i -g @openai/codex@<version>
codex --version
```

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

### Use Go SDK for Video Understanding

Source: https://docs.byteplus.com/en/docs/ModelArk/1895586

Demonstrates using the byteplus-go-sdk-v2 to perform video understanding. It initializes an Ark runtime client with an API key and base URL, constructs a request with video URL and text content, and prints the response or error. Requires the ARK_API_KEY environment variable.

```go
package main

import (
    "context"
    "fmt"
    "os"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/service/arkruntime"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/service/arkruntime/model"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus"
)

func main() {
    client := arkruntime.NewClientWithApiKey(
        // Get API Key：https://console.byteplus.com/ark/region:ark+ap-southeast-1/apikey
        os.Getenv("ARK_API_KEY"),
        //The base URL for model invocation
        arkruntime.WithBaseUrl("https://ark.ap-southeast.bytepluses.com/api/v3"),
    )
    // Create a context, typically used to pass request context information such as timeouts and cancellation
    ctx := context.Background()
    // Build the message content
    contentParts := []*model.ChatCompletionMessageContentPart{
        {
            Type: "video_url",
            VideoURL: &model.ChatMessageVideoURL{
                URL: "https://ark-doc.tos-ap-southeast-1.bytepluses.com/video_understanding.mp4",
                FPS: byteplus.Float64(5),
            },
        },
        // Text content
        {
            Type: "text",
            Text: "At what time point did the referee appear?",
        },
    }
    // Build the chat completion request and set the request model and message content
    req := model.CreateChatCompletionRequest{
        //Replace with Model ID
       Model: "seed-1-6-250915",
       Messages: []*model.ChatCompletionMessage{
          {
             // The message role is user
             Role: model.ChatMessageRoleUser,
             Content: &model.ChatCompletionMessageContent{
                ListValue: contentParts, // Use ListValue for multi-type content
             },
          },
       },
       MaxTokens: byteplus.Int(300), // Set the model's maximum output token count
    }

    // Send the chat completion request, store the result in resp, and store any errors in err
    resp, err := client.CreateChatCompletion(ctx, req)
    if err!= nil {
       // If an error occurs, print the error message and terminate the program
       fmt.Printf("standard chat error: %v\n", err)
       return
    }
    // Print the chat completion response
    fmt.Println(*resp.Choices[0].Message.Content.StringValue)
}
```

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

### Concurrent Request Example with QPSClimber in Go

Source: https://docs.byteplus.com/en/docs/ModelArk/handle_burst_traffic

Demonstrates how to manage concurrent requests using Go's sync.WaitGroup and the QPSClimber to control the overall rate. This pattern helps in efficiently handling high volumes of requests while respecting rate limits.

```Go
// Concurrent request example 
var wg sync.WaitGroup 
concurrency := 1000 
wg.Add(concurrency) 

for i := 0; i < concurrency; i++ { 
    go func() { 
        defer wg.Done() 
        for total.Add(-1) >= 0 { 
// Business request code 
            req := &model.CreateChatCompletionRequest{...} 
            _, err := qpsClimber.DoRequest(ctx, req) 
// Error handling 
        } 
    }() 
} 
wg.Wait()
```

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

### Example Image Processing Tool Usage Details

Source: https://docs.byteplus.com/en/docs/ModelArk/1783703

Provides an example of the detailed breakdown for image processing tool usage, showing counts for specific operations like zoom, point, and grounding.

```json
{
  "tool_usage_details": {
    "image_process": {
      "zoom": 1,
      "point": 1,
      "grounding": 1
    }
  }
}
```

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

### Use BytePlus Go SDK for Video Understanding

Source: https://docs.byteplus.com/en/docs/ModelArk/1895586

Demonstrates using the BytePlus Go SDK to invoke the Ark runtime for video understanding. It requires an API key and specifies a model ID. The input includes a video URL and a text prompt, with error handling for the API call.

```go
package main

import (
    "context"
    "fmt"
    "os"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/service/arkruntime"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/service/arkruntime/model"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus"
)

func main() {
    client := arkruntime.NewClientWithApiKey(
        // Read ARK_API_KEY from the environment using os.Getenv
        os.Getenv("ARK_API_KEY"),
        //The base URL for model invocation
        arkruntime.WithBaseUrl("https://ark.ap-southeast.bytepluses.com/api/v3"),
    )
    // Create a context, typically used to pass request-scoped data such as timeouts and cancellations
    ctx := context.Background()
    // Build the message content
    contentParts := []*model.ChatCompletionMessageContentPart{
        {
            Type: "video_url",
            VideoURL: &model.ChatMessageVideoURL{
                URL: "https://ark-doc.tos-ap-southeast-1.bytepluses.com/video_understanding.mp4",
                FPS: byteplus.Float64(2),
            },
        },
        // Text content
        {
            Type: "text",
            Text: "What is in the video?",
        },
    }
    // Build the chat completion request and set the model and message content
    req := model.CreateChatCompletionRequest{
        //Replace with Model ID
       Model: "seed-1-6-250915",
       Messages: []*model.ChatCompletionMessage{
          {
             // Set the message role to user
             Role: model.ChatMessageRoleUser,
             Content: &model.ChatCompletionMessageContent{
                ListValue: contentParts, // Use ListValue for multi-type content
             },
          },
       },
       MaxTokens: byteplus.Int(300), // Set the model's maximum output tokens
    }

    // Send the chat completion request; store the result in resp and any error in err
    resp, err := client.CreateChatCompletion(ctx, req)
    if err!= nil {
       // If an error occurs, print the error message and terminate the program
       fmt.Printf("standard chat error: %v\n", err)
       return
    }
    // Print the chat completion response
    fmt.Println(*resp.Choices[0].Message.Content.StringValue)
}
```

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

### Perform Multimodal Understanding with Curl

Source: https://docs.byteplus.com/en/docs/ModelArk/1399008

This example shows how to perform a multimodal understanding request using Curl. It sends a JSON payload containing an image URL and a text query to the BytePlus ModelArk API. Replace $ARK_API_KEY with your actual API key.

```bash
curl https://ark.ap-southeast.bytepluses.com/api/v3/responses -H "Authorization: Bearer $ARK_API_KEY" -H 'Content-Type: application/json' -d '{
    "model": "seed-1-6-250915",
    "input": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_image",
                    "image_url": "https://ark-doc.tos-ap-southeast-1.bytepluses.com/doc_image/ark_demo_img_1.png"
                },
                {
                    "type": "input_text",
                    "text": "Which model series supports input images?"
                }
            ]
        }
    ]
}'
```