Bytedance

BytePlus Apps Development Guide

This guide covers creating inference.sh apps that use BytePlus ARK SDK for video and image generation.

Overview

BytePlus ModelArk provides access to powerful generative AI models like Seedance for video generation. Apps use the BytePlus Python SDK with an async polling pattern for content generation tasks.

SDK Installation

pip install --upgrade 'byteplus-python-sdk-v2'

Authentication

BytePlus apps require an API key from the BytePlus ModelArk console.

inf.yml Configuration

secrets:
  - key: ARK_API_KEY
    description: BytePlus ModelArk API key
    optional: false

Accessing in Code

import os
from byteplussdkarkruntime import Ark

client = Ark(
    base_url="https://ark.ap-southeast.bytepluses.com/api/v3",
    api_key=os.environ.get("ARK_API_KEY"),
)

Using the Helper Module

symlink the shared helper (byteplus_helper.py) into the app dir and import helper methods for common operations:

from .byteplus_helper import (
    setup_byteplus_client,
    create_content_task,
    poll_task_status,
    download_video,
    build_text_content,
    build_image_content,
)

Content Generation Pattern

BytePlus uses an async task-based pattern:

1. Create Task: Submit content generation request
2. Poll Status: Wait for task completion
3. Download Result: Get the generated content

Example Flow

async def run(self, input_data: AppInput) -> AppOutput:
    # 1. Build content list
    content = [
        build_text_content(
            input_data.prompt,
            duration=input_data.duration,
            camerafixed=input_data.camera_fixed
        ),
    ]

    # Add image if provided (for image-to-video)
    if input_data.image:
        content.append(build_image_content(input_data.image.uri))

    # 2. Create task
    task_id = create_content_task(
        self.client,
        model=self.model_id,
        content=content,
        logger=self.logger
    )

    # 3. Poll for completion
    result = await poll_task_status(
        self.client,
        task_id,
        logger=self.logger,
        cancel_flag_getter=lambda: self.cancel_flag
    )

    # 4. Download and return
    video_url = result.data.video.url  # Adjust based on actual response
    video_path = download_video(video_url, self.logger)

    return AppOutput(video=File(path=video_path))

Cancellation Support

BytePlus tasks can be cancelled. Implement the on_cancel hook:

class App(BaseApp):
    async def setup(self, config):
        self.cancel_flag = False
        self.current_task_id = None

    async def on_cancel(self):
        self.cancel_flag = True
        if self.current_task_id:
            cancel_task(self.client, self.current_task_id, self.logger)
        return True

Available Models

Content Format

Text Prompt with Parameters

Parameters are embedded in the text using --param value syntax:

content = [{
    "type": "text",
    "text": "A drone flying through mountains --duration 5 --camerafixed false"
}]

Common Parameters

Image Content (First Frame)

content = [
    {"type": "text", "text": "prompt --duration 5"},
    {
        "type": "image_url",
        "image_url": {"url": "https://example.com/first_frame.png"}
    }
]

Resource Configuration

BytePlus apps are API-based and don't require GPU:

resources:
    gpu:
        count: 0
        vram: 0
        type: none
    ram: 4  # 4GB is typically sufficient

Output Metadata

Track video generation for usage-based pricing:

from inferencesh import OutputMeta, VideoMeta, VideoResolution

output_meta = OutputMeta(
    outputs=[
        VideoMeta(
            width=1280,
            height=720,
            resolution=VideoResolution.RES_720P,
            seconds=5.0,
            fps=24,
        )
    ]
)

Error Handling

BytePlus tasks can fail. Check the error field:

if result.status == "failed":
    error_msg = getattr(result, 'error', 'Unknown error')
    raise RuntimeError(f"Generation failed: {error_msg}")

API Reference

• BytePlus ModelArk Docs
• Content Generation API
• Task Query API

Example Apps

• seedance-1-5-pro/ - Seedance video generation with image-to-video support