Volcengine Ark

https://docs.volcengine.com/docs/ark
Admin
Volcengine Ark is a large model service platform by ByteDance's Volcano Engine that provides...
Tokens:741,222
Snippets:3,158
Trust Score:9.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Complete quickstart script with error handling

Source: https://docs.volcengine.com/docs/ark/quick-start-code?lang=zh

This is the complete runnable script that combines the steps from the guide. It sets 'set -euo pipefail' to terminate on any failure, requires the ARK_API_KEY environment variable, and uses the Ark base URL. Save it as quickstart.sh.

```bash
#!/usr/bin/env bash
set -euo pipefail

export ARK_API_KEY="${ARK_API_KEY:?请先 export ARK_API_KEY}"
ARK_BASE_URL="https://ark.cn-beijing.volces.com"
```

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

### Install Ark SDK and Generate Video with Seedance 2.0

Source: https://docs.volcengine.com/docs/ark/seedance-2-0?lang=zh

Install the arkruntime package and use the Ark client to create a video generation task. The example sets the base URL, API key from environment, and sends a request with text prompt, reference images, video, and audio. It enables audio generation, sets aspect ratio to 16:9, duration to 11 seconds, and enables watermark.

```python
python -m pip install --upgrade arkruntime
```

```python
from arkruntime import Ark

client = Ark(
# The base URL for model invocation
base_url='https://ark.cn-beijing.volces.com/api/v3',
# Get API Key：https://ark.volcengine.com/region:cn-beijing/apikey
api_key=os.environ.get("ARK_API_KEY"),
)

if __name__ == "__main__":
print("----- create request -----")
create_result = client.content_generation.tasks.create(
model="doubao-seedance-2-0-260128", # Replace with Model ID
content=[
{
"type": "text",
"text": "全程使用视频1的第一视角构图，全程使用音频1作为背景音乐。第一人称视角果茶宣传广告，seedance牌「苹苹安安」苹果果茶限定款；首帧为图片1，你的手摘下一颗带晨露的阿克苏红苹果，轻脆的苹果碰撞声；2-4 秒：快速切镜，你的手将苹果块投入雪克杯，加入冰块与茶底，用力摇晃，冰块碰撞声与摇晃声卡点轻快鼓点，背景音：「鲜切现摇」；4-6 秒：第一人称成品特写，分层果茶倒入透明杯，你的手轻挤奶盖在顶部铺展，在杯身贴上粉红包标，镜头拉近看奶盖与果茶的分层纹理；6-8 秒：第一人称手持举杯，你将图片2中的果茶举到镜头前（模拟递到观众面前的视角），杯身标签清晰可见，背景音「来一口鲜爽」，尾帧定格为图片2。背景声音统一为女生音色。",
},
{
"type": "image_url",
"image_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"
},
"role": "reference_image",
},
{
"type": "image_url",
"image_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"
},
"role": "reference_image",
},
{
"type": "video_url",
"video_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"
},
"role": "reference_video",
},
{
"type": "audio_url",
"audio_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"
},
"role": "reference_audio",
},
],
generate_audio=True,
ratio="16:9",
duration=11,
watermark=True,
)
print(create_result)
```

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

### Python: Generate images with sequential image generation using Ark SDK

Source: https://docs.volcengine.com/docs/ark/seedream-4-0-5-0?lang=zh

Python example using the arkruntime SDK to generate multiple images sequentially. Requires installing the SDK with 'python -m pip install --upgrade arkruntime'. The API key is read from the ARK_API_KEY environment variable. The example streams responses and handles partial failures, partial successes, and completion events.

```Python
from arkruntime import Ark
from arkruntime.types.images import SequentialImageGenerationOptionsParam

client = Ark(
    # The base URL for model invocation
    base_url="https://ark.cn-beijing.volces.com/api/v3",
    # Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
    api_key=os.getenv('ARK_API_KEY'),
)

if __name__ == "__main__":
    stream = client.images.generate(
        # Replace with Model ID
        model="doubao-seedream-5-0-lite-260128",
        prompt="参考图1，生成四图片，图中人物分别带着墨镜，骑着摩托，带着帽子，拿着棒棒糖",
        image="https://arkdocs.tos-cn-beijing.volces.com/images/image-generation/seedream4_imageToimages_1.png",
        size="2K",
        sequential_image_generation="auto",
        sequential_image_generation_options=SequentialImageGenerationOptionsParam(max_images=4),
        output_format="png",
        response_format="url",
        stream=True,
        watermark=True
    )
    for event in stream:
        if event is None:
            continue
        if event.type == "image_generation.partial_failed":
            print(f"Stream generate images error: {event.error}")
            if event.error is not None and event.error.code.equal("InternalServiceError"):
                break
        elif event.type == "image_generation.partial_succeeded":
            if event.error is None and event.url:
                print(f"recv.Size: {event.size}, recv.Url: {event.url}")
        elif event.type == "image_generation.completed":
            if event.error is None:
                print("Final completed event:")
                print("recv.Usage:", event.usage)
        elif event.type == "image_generation.partial_image":
            print(f"Partial image index={event.partial_image_index}, size={len(event.b64_json)}")
```

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

### Window truncation with delete interface (Java)

Source: https://docs.volcengine.com/docs/ark/responses-api-text-generation?lang=zh

Java implementation of the window truncation example using the ArkService. It shows the initial setup and the beginning of the conversation creation.

```Java
package com.ark.example;
import com.volcengine.ark.runtime.service.ArkService;
import com.volcengine.ark.runtime.models.responses.*;
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)
```

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

### Image Generation Example (Go)

Source: https://docs.volcengine.com/docs/ark/seedream-4-0-5-0?lang=zh

Demonstrates how to initialize the Ark client and request image generation using the Go SDK.

```go
package main

import (
"context"
"fmt"
"os"

"github.com/volcengine/ark-runtime-go/arkruntime"
model "github.com/volcengine/ark-runtime-go/arkruntime/model/images"
)

func main() {
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
// The base URL for model invocation
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
ctx := context.Background()
outputFormat := model.OutputFormatPNG
var sequentialImageGeneration model.SequentialImageGenerationMode = "auto"
maxImages := 4

generateReq := &model.CreateImageGenerationRequest{
Model: "doubao-seedream-5-0-lite-260128",
Prompt: model.NewOptString("参考这个LOGO，做一套户外运动品牌视觉设计，品牌名称为“GREEN”，包括包装袋、帽子、卡片、挂绳等。绿色视觉主色调，趣味、简约现代风格"),

Image: model.NewOptCreateImageGenerationRequestImage(model.NewStringArrayCreateImageGenerationRequestImage([]string{"https://arkdocs.tos-cn-beijing.volces.com/images/image-generation/seedream4_imageToimages.png"})),

Size: model.NewOptString("2K"),
OutputFormat: model.NewOptOutputFormat(outputFormat),
ResponseFormat: model.NewOptResponseFormat(model.ResponseFormatURL),
Watermark: model.NewOptBool(true),
SequentialImageGeneration: model.NewOptSequentialImageGenerationMode(sequentialImageGeneration),
SequentialImageGenerationOptions: model.NewOptSequentialImageGenerationOptions(model.SequentialImageGenerationOptions{
MaxImages: model.NewOptInt32(int32(maxImages)),
}),
}

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

if resp.Error.IsSet() {
fmt.Printf("API returned error: %s - %s\n", resp.Error.Value.Code, resp.Error.Value.Message)
return
}

// Output the generated image information
fmt.Printf("Generated %d images:\n", len(resp.Data))
for i, image := range resp.Data {
var url string
if image.URL.IsSet() {
url = image.URL.Or("")
} else {
url = "N/A"
}
fmt.Printf("Image %d: Size: %s, URL: %s\n", i+1, image.Size.Or(""), url)
}
}
```

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

### Go Image Generation Example

Source: https://docs.volcengine.com/docs/ark/seedream-4-0-5-0?lang=zh

Demonstrates how to initialize the Ark client and request image generation using the Go SDK.

```go
package main

import (
"context"
"fmt"
"os"

"github.com/volcengine/ark-runtime-go/arkruntime"
model "github.com/volcengine/ark-runtime-go/arkruntime/model/images"
)

func main() {
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
// The base URL for model invocation
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
ctx := context.Background()
outputFormat := model.OutputFormatPNG
var sequentialImageGeneration model.SequentialImageGenerationMode = "auto"
maxImages := 3

generateReq := &model.CreateImageGenerationRequest{
Model: "doubao-seedream-5-0-lite-260128",
Prompt: model.NewOptString("生成3张女孩和奶牛玩偶在游乐园开心地坐过山车的图片，涵盖早晨、中午、晚上"),

Image: model.NewOptCreateImageGenerationRequestImage(model.NewStringArrayCreateImageGenerationRequestImage([]string{
"https://arkdocs.tos-cn-beijing.volces.com/images/image-generation/seedream4_imagesToimages_1.png",
"https://arkdocs.tos-cn-beijing.volces.com/images/image-generation/seedream4_imagesToimages_2.png",


})),

Size: model.NewOptString("2K"),
OutputFormat: model.NewOptOutputFormat(outputFormat),
ResponseFormat: model.NewOptResponseFormat(model.ResponseFormatURL),
Watermark: model.NewOptBool(true),
SequentialImageGeneration: model.NewOptSequentialImageGenerationMode(sequentialImageGeneration),
SequentialImageGenerationOptions: model.NewOptSequentialImageGenerationOptions(model.SequentialImageGenerationOptions{
MaxImages: model.NewOptInt32(int32(maxImages)),
}),
}

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

if resp.Error.IsSet() {
fmt.Printf("API returned error: %s - %s\n", resp.Error.Value.Code, resp.Error.Value.Message)
return
}

// Output the generated image information
fmt.Printf("Generated %d images:\n", len(resp.Data))
for i, image := range resp.Data {
var url string
if image.URL.IsSet() {
url = image.URL.Or("")
} else {
url = "N/A"
}
fmt.Printf("Image %d: Size: %s, URL: %s\n", i+1, image.Size.Or(""), url)
}
}
```

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

### Python chat completion with arkruntime

Source: https://docs.volcengine.com/docs/ark/context-management?lang=zh

Python example using the arkruntime SDK to create a chat completion. Requires the ARK_API_KEY environment variable and the arkruntime package (install with `python -m pip install --upgrade arkruntime`). The model ID must be replaced with a valid one.

```python
from arkruntime import Ark

# 初始化Ark客户端
client = Ark(
    # The base URL for model invocation
    base_url="https://ark.cn-beijing.volces.com/api/v3",
    # Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
    api_key=os.getenv('ARK_API_KEY'),
)

completion = client.chat.completions.create(
    # Replace with Model ID
    model = "doubao-seed-2-1-pro-260915",
    messages=[
        {"role": "system", "content": "你是 AI 人工智能助手"},
        {"role": "user", "content": "常见的十字花科植物有哪些？"},
    ],
    # 设置模型最大输出长度为 1024 token，您可按需进行调整
    max_tokens=1024,
)
print(completion.choices[0].message.content)
```

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

### Run the complete quickstart script

Source: https://docs.volcengine.com/docs/ark/quick-start-code?lang=zh

This command runs the complete quickstart.sh script. It is used after saving the script and configuring the ARK_API_KEY environment variable.

```bash
bash quickstart.sh
```

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

### Create video generation task with Python SDK

Source: https://docs.volcengine.com/docs/ark/video-generation-tutorial?lang=zh

Python example using the arkruntime SDK to create a video generation task. Requires ARK_API_KEY environment variable and the SDK installed via pip. The model ID must be replaced. This example is for offline inference with service_tier=flex, which is 50% cheaper but requires appropriate timeout settings.

```python
import os
import time
# Install SDK: python -m pip install --upgrade arkruntime
from arkruntime import Ark

# Make sure that you have stored the API Key in the environment variable ARK_API_KEY
# Initialize the Ark client to read your API Key from an environment variable
client = Ark(
# This is the default path. You can configure it based on the service location
base_url="https://ark.cn-beijing.volces.com/api/v3",
# Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
api_key=os.environ.get("ARK_API_KEY"),
)

if __name__ == "__main__":
print("----- create request -----")
create_result = client.content_generation.tasks.create(
model="doubao-seedance-1-0-pro-250528", # Replace with Model ID
content=[
{
```

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

### Create video generation task with Python SDK

Source: https://docs.volcengine.com/docs/ark/seedance-2-5?lang=zh

Uses the arkruntime SDK to create a video generation task. Requires installing the SDK with 'python -m pip install --upgrade arkruntime' and setting the ARK_API_KEY environment variable. The example sets the model, content (text and two images), generate_audio, ratio, and duration, then prints the result.

```python
import os
import time
# Install SDK: python -m pip install --upgrade arkruntime
from arkruntime import Ark

client = Ark(
# The base URL for model invocation
base_url="https://ark.cn-beijing.volces.com/api/v3",
# Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
api_key=os.environ.get("ARK_API_KEY"),
)

if __name__ == "__main__":
print("----- create request -----")
create_result = client.content_generation.tasks.create(
model="doubao-seedance-2-5-260628", # Replace with Model ID
content=[
{
"type": "text",
"text": "草莓夹心饼干缓慢旋转一周，镜头平滑环绕，保持产品居中",
},
{
"type": "image_url",
"image_url": {
"url": "https://arkdocs.tos-cn-beijing.volces.com/images/video-generation/seedance2.5_reference1.png"
},
"role": "first_frame",
},
{
"type": "image_url",
"image_url": {
"url": "https://arkdocs.tos-cn-beijing.volces.com/images/video-generation/seedance2.5_reference1.png"
},
"role": "last_frame",
},
],
generate_audio=True,
ratio="adaptive",
duration=5,
)
print(create_result)
```

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

### Python: Install and use Ark SDK for video understanding

Source: https://docs.volcengine.com/docs/ark/video-understanding?lang=zh

Install the arkruntime package and create a client with the base URL and API key from environment variable. Send a chat completion request with a video URL and a text question, then print the first choice.

```python
python -m pip install --upgrade arkruntime
```

```python
from arkruntime import Ark

client = Ark(
# The base URL for model invocation .
base_url="https://ark.cn-beijing.volces.com/api/v3",
# Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
api_key=os.getenv('ARK_API_KEY'),
)

completion = client.chat.completions.create(
# Replace with Model ID .
model = "doubao-seed-2-1-pro-260915",
messages=[
{
# 消息角色为用户
"role": "user",
"content": [
{
"type": "video_url",
"video_url": {
# 替换链接为实际视频链接
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/video-understanding.mp4",
"fps": 5, # 每秒截取5帧画面，用于视频理解
}
},
# 文本类型的消息内容，询问视频里有什么
{"type": "text", "text": "裁判什么时间点出现的？"},
],
}
],
)

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

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

### Go Image Generation Example

Source: https://docs.volcengine.com/docs/ark/seedream-4-0-5-0?lang=zh

Demonstrates how to initialize the Go client and perform sequential image generation with the Seedream 4.0 model.

```go
package main

import (
"context"
"fmt"
"os"

"github.com/volcengine/ark-runtime-go/arkruntime"
model "github.com/volcengine/ark-runtime-go/arkruntime/model/images"
)

func main() {
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
// The base URL for model invocation .
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
ctx := context.Background()
outputFormat := model.OutputFormatPNG
var (
sequentialImageGeneration model.SequentialImageGenerationMode = "auto"
maxImages = 4
mode model.OptimizePromptMode = model.OptimizePromptModeFast
)

generateReq := &model.CreateImageGenerationRequest{
Model: "doubao-seedream-4-0-250828",
Prompt: model.NewOptString("生成一组共4张连贯插画，核心为同一庭院一角的四季变迁，以统一风格展现四季独特色彩、元素与氛围"),

Size: model.NewOptString("2K"),
OutputFormat: model.NewOptOutputFormat(outputFormat),
ResponseFormat: model.NewOptResponseFormat(model.ResponseFormatURL),
Watermark: model.NewOptBool(true),
SequentialImageGeneration: model.NewOptSequentialImageGenerationMode(sequentialImageGeneration),
SequentialImageGenerationOptions: model.NewOptSequentialImageGenerationOptions(model.SequentialImageGenerationOptions{
MaxImages: model.NewOptInt32(int32(maxImages)),
}),
OptimizePromptOptions: model.NewOptOptimizePromptOptions(model.OptimizePromptOptions{
Mode: model.NewOptOptimizePromptMode(mode),
}),
}

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

if resp.Error.IsSet() {
fmt.Printf("API returned error: %s - %s\n", resp.Error.Value.Code, resp.Error.Value.Message)
return
}

// Output the generated image information
fmt.Printf("Generated %d images:\n", len(resp.Data))
for i, image := range resp.Data {
var url string
if image.URL.IsSet() {
url = image.URL.Or("")
} else {
url = "N/A"
}
fmt.Printf("Image %d: Size: %s, URL: %s\n", i+1, image.Size.Or(""), url)
}
}
```

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

### Query Video Generation Task Status with Java (ArkService)

Source: https://docs.volcengine.com/docs/ark/video-generation-tutorial?lang=zh

Java example using ArkService to get a content generation task. Requires ARK_API_KEY environment variable. Replace <TASK_ID> with your task ID.

```java
package com.ark.sample;

import com.volcengine.ark.runtime.models.content_generation.*;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.volcengine.ark.runtime.service.ArkService;
import java.util.concurrent.TimeUnit;
import okhttp3.ConnectionPool;
import okhttp3.Dispatcher;


public class Sample {

static String apiKey = System.getenv("ARK_API_KEY");

static ConnectionPool connectionPool = new ConnectionPool(5, 1, TimeUnit.SECONDS);
static Dispatcher dispatcher = new Dispatcher();
static ArkService service =
ArkService.builder()
.dispatcher(dispatcher)
.connectionPool(connectionPool)
.apiKey(apiKey)
.baseUrl("https://ark.cn-beijing.volces.com/api/v3")
.build();

public static void main(String[] args) throws JsonProcessingException {
String taskId = "<TASK_ID>";

String req = taskId;


service.getContentGenerationTask(req).toString();
System.out.println(service.getContentGenerationTask(req));

service.shutdownExecutor();
}
}
```

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

### Query Video Generation Task Status with Go (arkruntime)

Source: https://docs.volcengine.com/docs/ark/video-generation-tutorial?lang=zh

Go example using the arkruntime-go library to get a content generation task. Requires ARK_API_KEY environment variable. Replace <TASK_ID> with your task ID.

```go
package main

import (
"context"
"fmt"
"os"

"github.com/volcengine/ark-runtime-go/arkruntime"
)


func main() {
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
ctx := context.Background()

req := "<TASK_ID>"
resp, err := client.GetContentGenerationTask(ctx, req)
if err != nil {
fmt.Printf("get content generation task error: %v\n", err)
return
}
fmt.Printf("%+v\n", resp)
}
```

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

### Install Ark SDK and Perform Video Understanding

Source: https://docs.volcengine.com/docs/ark/video-understanding?lang=zh

Install the arkruntime package, then create a client with your API key and send a chat completion request with a video URL. The video is sampled at 2 frames per second for understanding. Replace the model ID and video URL with your own.

```python
python -m pip install --upgrade arkruntime
```

```python
from arkruntime import Ark

client = Ark(
# The base URL for model invocation .
base_url="https://ark.cn-beijing.volces.com/api/v3",
# Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
api_key=os.getenv('ARK_API_KEY'),
)

completion = client.chat.completions.create(
# Replace with Model ID .
model = "doubao-seed-2-1-pro-260915",
messages=[
{
# 消息角色为用户
"role": "user",
"content": [
{
"type": "video_url",
"video_url": {
# 替换链接为实际视频链接
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/ark_vlm_video_input.mp4",
"fps": 2, # 每秒截取2帧画面，用于视频理解
}
},

```

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

### Query Video Generation Task Status with Python (arkruntime)

Source: https://docs.volcengine.com/docs/ark/video-generation-tutorial?lang=zh

Python example using the arkruntime library to get a content generation task. Requires ARK_API_KEY environment variable. Replace <TASK_ID> with your task ID.

```python
import os
from arkruntime import Ark

# Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
client = Ark(
api_key=os.environ.get("ARK_API_KEY"),
base_url="https://ark.cn-beijing.volces.com/api/v3",
)

if __name__ == "__main__":
resp = client.content_generation.tasks.get(
task_id="<TASK_ID>",
)
print(resp)
```

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

### Upload video and chat completion using Go

Source: https://docs.volcengine.com/docs/ark/video-understanding?lang=zh

Go example using the ark-runtime-go library to upload a video file with preprocessing configs, wait for processing, and create a chat completion with video and text content.

```go
package main

import (
"context"
"fmt"
"os"

"github.com/volcengine/ark-runtime-go/arkruntime"
"github.com/volcengine/ark-runtime-go/arkruntime/model/chat"
"github.com/volcengine/ark-runtime-go/arkruntime/model/file"
)

func main() {
ctx := context.Background()
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
filePath := os.Getenv("FILE_PATH")
if filePath == "" {
filePath = "/Users/doc/demo.mp4"
}
data, err := os.Open(filePath)
if err != nil {
panic(err)
}
defer data.Close()

uploaded, err := client.UploadFile(ctx, &file.FileCreateRequest{
Purpose: file.PurposeUserData,
PreprocessConfigs: file.NewOptPreprocessConfigs(file.PreprocessConfigs{
Video: file.NewOptVideo(file.Video{
Model: file.NewOptString("doubao-seed-2-1-pro-260915"),
Fps: file.NewOptFloat64(0.3),
}),
}),
}, data)
if err != nil {
panic(err)
}
uploaded, err = client.WaitForFileProcessing(
ctx,
uploaded.ID,
arkruntime.WaitForFileProcessingOptions{},
)
if err != nil || uploaded.Status != file.StatusActive {
panic(fmt.Sprintf("file processing failed: %v, status=%s", err, uploaded.Status))
}

media := chat.ChatCompletionContentPart{OneOf: chat.NewChatCompletionContentPartVideoChatCompletionContentPartSum(chat.ChatCompletionContentPartVideo{Type: chat.ChatCompletionContentPartVideoTypeVideoURL, VideoURL: chat.ChatCompletionContentPartVideoVideoUrl{FileID: chat.NewOptString(uploaded.ID)}})}
text := chat.ChatCompletionContentPart{OneOf: chat.NewChatCompletionContentPartTextChatCompletionContentPartSum(
chat.ChatCompletionContentPartText{Type: chat.ChatCompletionContentPartTextTypeText, Text: "请你描述下视频中的人物的一系列动作，以 JSON 格式输出开始时间（start_time）、结束时间（end_time）、事件（event）、是否危险（danger），请使用 HH:mm:ss 表示时间戳。"},
)}
message := chat.ChatCompletionRequestMessage{OneOf: chat.NewChatCompletionRequestUserMessageChatCompletionRequestMessageSum(
chat.ChatCompletionRequestUserMessage{
Role: chat.ChatCompletionRequestUserMessageRoleUser,
Content: chat.NewOptNilChatCompletionMessageContent(chat.NewChatCompletionContentPartArrayChatCompletionMessageContent(
[]chat.ChatCompletionContentPart{media, text},
)),
},
)}
modelID := os.Getenv("MODEL_ID")
if modelID == "" {
modelID = "doubao-seed-2-1-pro-260915"
}
response, err := client.CreateChatCompletion(ctx, &chat.ChatCompletionRequest{
Model: modelID,
Messages: []chat.ChatCompletionRequestMessage{message},
})
if err != nil {
panic(err)
}
fmt.Printf("id=%s\n%s\n", response.ID, response.Choices[0].Message.Content)
}
```

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

### Python: Get Content Generation Task

Source: https://docs.volcengine.com/docs/ark/video-generation-tutorial?lang=zh

This Python example retrieves a single content generation task by its task ID. It requires the ARK_API_KEY environment variable and uses the Ark client with the base URL 'https://ark.cn-beijing.volces.com/api/v3'.

```Python
import os
from arkruntime import Ark

client = Ark(
    api_key=os.environ.get("ARK_API_KEY"),
    base_url="https://ark.cn-beijing.volces.com/api/v3",
)

if __name__ == "__main__":
    resp = client.content_generation.tasks.get(
        task_id="<TASK_ID>",
    )
    print(resp)
```

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

### Create and poll video generation task in Go

Source: https://docs.volcengine.com/docs/ark/seedance-2-0?lang=zh

A complete example showing how to initialize the Ark client, create a video generation task with a prompt and reference image, and poll the task status until completion.

```go
package main

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

"github.com/volcengine/ark-runtime-go/arkruntime"
model "github.com/volcengine/ark-runtime-go/arkruntime/model/contentgeneration"
)

func main() {
// Initialize Ark client
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
// The base URL for model invocation
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
ctx := context.Background()

// Model ID
modelID := "doubao-seedance-2-0-260128"
// Text prompt
prompt := "生成一段15秒的越野摩托竞技广告感短片。参考图片作为中段飞跃高潮的参考。" +
"镜头逻辑依次为：1）中景跟拍，车手从远处沿土坡高速逼近跳台；" +
"2）超近低机位后轮飞砂特写，轮胎抓地甩出大量泥土和砂石；" +
"3）中近景展示骑手控车、手部发力、悬挂压缩与机械震动；" +
"4）侧向英雄中景拍车手冲坡腾空飞跃，画面状态接近图一，泥土在逆光中大面积飞散；" +
"5）腾空近景帅气细节，突出头盔护目镜、手部控把、轮胎悬空或车身侧面局部；" +
"6）中景跟拍落地，悬挂压缩回弹，随后继续沿土坡赛道高速冲刺收尾。" +
"全片同一名骑手、同一辆车、同一条赛道，镜头景别和角度区分清楚，不重复，动作连贯,画面有真实越野跟拍抖动感、速度感、扬土感和夕阳逆光竞技氛围。"

// Example resource URLs
refImage := "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_4k.png"

// Output video parameters
generateAudio := true
videoResolution := "4k"
videoRatio := "adaptive"
videoDuration := int64(15)
showWatermark := true

// 1. Create video generation task
fmt.Println("----- create request -----")
createReq := &model.CreateContentGenerationTaskRequest{
Model: modelID,
GenerateAudio: model.NewOptBool(generateAudio),
Resolution: model.NewOptString(videoResolution),
Ratio: model.NewOptString(videoRatio),
Duration: model.NewOptInt64(videoDuration),
Watermark: model.NewOptBool(showWatermark),
Content: []model.ContentItem{
{
Type: model.ContentTypeText,
Text: model.NewOptString(prompt),
},
{
Type: model.ContentTypeImageURL,
ImageURL: model.NewOptImageURL(model.ImageURL{
URL: refImage,
}),
Role: model.NewOptString("reference_image"),
},
},
}

createResp, err := client.CreateContentGenerationTask(ctx, createReq)
if err != nil {
fmt.Printf("create content generation error: %v\n", err)
return
}

taskID := createResp.ID
fmt.Printf("Task Created with ID: %s\n", taskID)

// 2. Poll task status
pollTaskStatus(ctx, client, taskID)
}

// poll task status
func pollTaskStatus(ctx context.Context, client *arkruntime.Client, taskID string) {
fmt.Println("----- polling task status -----")
for {
getReq := taskID
getResp, err := client.GetContentGenerationTask(ctx, getReq)
if err != nil {
fmt.Printf("get content generation task error: %v\n", err)
return
}

status := getResp.Status
if status == "succeeded" {
fmt.Println("----- task succeeded -----")
fmt.Printf("Task ID: %s \n", getResp.ID)
fmt.Printf("Model: %s \n", getResp.Model)
fmt.Printf("Video URL: %s \n", getResp.Content.Or(model.TaskContent{}).VideoURL.Or(""))
fmt.Printf("Completion Tokens: %d \n", getResp.Usage.Or(model.TaskUsage{}).CompletionTokens)
fmt.Printf("Created At: %d, Updated At: %d\n", getResp.CreatedAt.Or(0), getResp.UpdatedAt.Or(0))
return
} else if status == "failed" {
fmt.Println("----- task failed -----")
if getResp.Error.IsSet() {
fmt.Printf("Error Code: %s, Message: %s\n", getResp.Error.Value.Code, getResp.Error.Value.Message)
}
return
} else {
fmt.Printf("Current status: %s, Retrying in 10 seconds... \n", status)
time.Sleep(10 * time.Second)
}
}
}
```

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

### Generate Images with Go SDK

Source: https://docs.volcengine.com/docs/ark/seedream-4-0-5-0?lang=zh

Example of using the Go SDK to initialize the client and generate images.

```go
package main

import (
"context"
"fmt"
"os"

"github.com/volcengine/ark-runtime-go/arkruntime"
model "github.com/volcengine/ark-runtime-go/arkruntime/model/images"
)

func main() {
client := arkruntime.NewClientWithApiKey(
// Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
os.Getenv("ARK_API_KEY"),
// The base URL for model invocation
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
ctx := context.Background()
outputFormat := model.OutputFormatPNG


generateReq := &model.CreateImageGenerationRequest{
Model: "doubao-seedream-5-0-lite-260128", // Replace with Model ID
Prompt: model.NewOptString("充满活力的特写编辑肖像，模特眼神犀利，头戴雕塑感帽子，色彩拼接丰富，眼部焦点锐利，景深较浅，具有Vogue杂志封面的美学风格，采用中画幅拍摄，工作室灯光效果强烈。"),

Size: model.NewOptString("2K"),
OutputFormat: model.NewOptOutputFormat(outputFormat),
ResponseFormat: model.NewOptResponseFormat(model.ResponseFormatURL),
Watermark: model.NewOptBool(true),
}

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.Or(""))
}
```

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

### Go: Video understanding with ark-runtime-go

Source: https://docs.volcengine.com/docs/ark/video-understanding?lang=zh

Create a client with API key and base URL, build a chat completion request with video and text content parts, and print the response. The example sets MaxTokens to 300.

```go
package main

import (
"context"
"fmt"
"os"
"github.com/volcengine/ark-runtime-go/arkruntime"
"github.com/volcengine/ark-runtime-go/arkruntime/model/chat"
)

func main() {
client := arkruntime.NewClientWithApiKey(
// Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
os.Getenv("ARK_API_KEY"),
// The base URL for model invocation .
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
// 创建一个上下文，通常用于传递请求的上下文信息，如超时、取消等
ctx := context.Background()
// 构建消息内容
contentParts := []chat.ChatCompletionContentPart{
chat.ChatCompletionContentPart{OneOf: chat.NewChatCompletionContentPartVideoChatCompletionContentPartSum(chat.ChatCompletionContentPartVideo{Type: chat.ChatCompletionContentPartVideoTypeVideoURL, VideoURL: chat.ChatCompletionContentPartVideoVideoUrl{URL: chat.NewOptString("https://ark-project.tos-cn-beijing.volces.com/doc_video/video-understanding.mp4"), Fps: chat.NewOptFloat64(5)}})},
chat.ChatCompletionContentPart{OneOf: chat.NewChatCompletionContentPartTextChatCompletionContentPartSum(chat.ChatCompletionContentPartText{Type: chat.ChatCompletionContentPartTextTypeText, Text: "裁判什么时间点出现的？"})},
}
// 构建聊天完成请求，设置请求的模型和消息内容
req := &chat.ChatCompletionRequest{
// Replace with Model ID
Model: "doubao-seed-2-1-pro-260915",
Messages: []chat.ChatCompletionRequestMessage{
chat.ChatCompletionRequestMessage{OneOf: chat.NewChatCompletionRequestUserMessageChatCompletionRequestMessageSum(chat.ChatCompletionRequestUserMessage{Role: chat.ChatCompletionRequestUserMessageRoleUser, Content: chat.NewOptNilChatCompletionMessageContent(chat.NewChatCompletionContentPartArrayChatCompletionMessageContent(contentParts))})},
},
MaxTokens: chat.NewOptInt32(int32(300)), // 设置模型输出最大 token 数
}

// 发送聊天完成请求，并将结果存储在 resp 中，将可能出现的错误存储在 err 中
resp, err := client.CreateChatCompletion(ctx, req)
if err!= nil {
// 若出现错误，打印错误信息并终止程序
fmt.Printf("standard chat error: %v\n", err)
return
}
// 打印聊天完成请求的响应结果
fmt.Println(resp.Choices[0].Message.Content)
}
```

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

### Python: Install arkruntime and create chat completion with JSON output

Source: https://docs.volcengine.com/docs/ark/structured-output-beta?lang=zh

Install the arkruntime SDK via pip, then create a chat completion request. The example sets the base URL to 'https://ark.cn-beijing.volces.com/api/v3', retrieves the API key from the environment variable 'ARK_API_KEY', and uses the model 'doubao-seed-2-1-pro-260915'. It requests JSON output via 'response_format' and disables deep thinking with 'thinking={"type": "disabled"}'.

```bash
pip install arkruntime
```

```python
from arkruntime import Ark

client = Ark(
    # The base URL for model invocation
    base_url="https://ark.cn-beijing.volces.com/api/v3",
    # Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
    api_key=os.getenv('ARK_API_KEY'),
)

completion = client.chat.completions.create(
    # Replace with Model ID
    model = "doubao-seed-2-1-pro-260915",
    messages=[
        {"role": "user", "content": "常见的十字花科植物有哪些？json输出"}
    ],
    response_format={"type":"json_object"},
    thinking={"type": "disabled"},# 不使用深度思考能力
)

# 打印原始响应内容
print(completion.choices[0].message.content)
```
Tokens:
Raw