工具呼叫

讓聊天應用程式提交影片任務，再由背景工作查詢及下載。

多語言 API 呼叫

執行方式見多語言範例說明。先設定 API_KEY，並替換模型、檔案網址及 ID 占位值；四種方式會顯示相同請求的原始回應。

這組範例只提交任務，成功回應中的 id 需保留供後續查詢。這是工具處理函式內的生成 API 呼叫，不是聊天端點；聊天回合的關聯 ID 處理見下方完整範例。

cURLPythonJavaScriptJava

bash

curl --fail-with-body --silent --show-error --max-time 180 \
  --request POST \
  --url "https://api.tokatlas.ai/v1/videos" \
  --header "Authorization: Bearer $API_KEY" \
  --form model=YOUR_ENABLED_SORA_MODEL_ID \
  --form 'prompt=A ceramic cup on a table, steam rising, slow camera movement' \
  --form seconds=4 \
  --form size=720x1280

python

import os
import requests

headers = {
    'Authorization': 'Bearer ' + os.environ["API_KEY"],
}
files = {'model': (None, 'YOUR_ENABLED_SORA_MODEL_ID'),
 'prompt': (None, 'A ceramic cup on a table, steam rising, slow camera movement'),
 'seconds': (None, '4'),
 'size': (None, '720x1280')}
response = requests.request(
    'POST', 'https://api.tokatlas.ai/v1/videos', headers=headers,
    files=files,
    timeout=180,
)
response.raise_for_status()
print(response.text)

if (!process.env.API_KEY) throw new Error("Set API_KEY first.");
const form = new FormData();
form.append("model", "YOUR_ENABLED_SORA_MODEL_ID");
form.append("prompt", "A ceramic cup on a table, steam rising, slow camera movement");
form.append("seconds", "4");
form.append("size", "720x1280");
const response = await fetch("https://api.tokatlas.ai/v1/videos", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.API_KEY,
  },
  body: form,
  signal: AbortSignal.timeout(180_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.text());

java

import java.net.URI;
import java.net.http.*;
import java.time.Duration;

public class Example {
    public static void main(String[] args) throws Exception {
        String apiKey = System.getenv("API_KEY");
        if (apiKey == null || apiKey.isBlank()) {
            throw new IllegalArgumentException("Set API_KEY first.");
        }
        String boundary = "TokatlasExampleBoundary";
        String payload =
            "--TokatlasExampleBoundary\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\nYOUR_ENABLED_SORA_MODEL_ID\r\n" +
            "--TokatlasExampleBoundary\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nA ceramic cup on a table, steam rising, slow camera movement\r\n" +
            "--TokatlasExampleBoundary\r\nContent-Disposition: form-data; name=\"seconds\"\r\n\r\n4\r\n" +
            "--TokatlasExampleBoundary\r\nContent-Disposition: form-data; name=\"size\"\r\n\r\n720x1280\r\n" +
            "--TokatlasExampleBoundary--\r\n";
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(30)).build();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.tokatlas.ai/v1/videos"))
            .timeout(Duration.ofSeconds(180))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "multipart/form-data; boundary=" + boundary)
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .build();
        HttpResponse<String> response = client.send(
            request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": "
                + response.body());
        }
        System.out.println(response.body());
    }
}

接入步驟

先跑通影片生成概覽，保留相同的 API_KEY、VIDEO_MODEL_ID 與模型參數。
在 Chat 工具呼叫的完整範例中，以以下定義替換 TOOLS 列表內容。
用下方函式替換 execute。回傳的工具結果表示任務目前狀態，不代表影片已完成。

json

{"type":"function","function":{"name":"submit_video","description":"Submit a video generation task and return its ID.","parameters":{"type":"object","properties":{"prompt":{"type":"string"}},"required":["prompt"],"additionalProperties":false}}}

python

import os
import requests

def execute(name, args):
    if name != "submit_video" or not isinstance(args, dict):
        return {"error": "Invalid tool call"}
    prompt = args.get("prompt")
    if set(args) != {"prompt"} or not isinstance(prompt, str) or not prompt.strip():
        return {"error": "Expected a non-empty prompt"}
    response = requests.post(
        "https://api.tokatlas.ai/v1/videos",
        headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
        files={"model": (None, os.environ["VIDEO_MODEL_ID"]),
               "prompt": (None, prompt), "seconds": (None, "4"),
               "size": (None, "720x1280")},
        timeout=120,
    )
    response.raise_for_status()
    task = response.json()
    return {"task_id": task["id"], "status": task["status"]}

將 Chat 範例中的庫存查詢訊息改為影片生成要求，再執行工具迴圈。

取得影片

記錄 task_id，把它寫入概覽範例的 video-task.txt，執行該腳本即可查詢並下載。正式應用由背景工作接手，完成後再通知前端顯示影片。

保存工具呼叫 ID 與任務 ID 的對應；重複收到同一工具呼叫時傳回已保存的任務，不要再次提交。提交超時而沒有 ID 時先查記錄，不能直接宣稱失敗或完成。

工具呼叫 ​

多語言 API 呼叫 ​

接入步驟 ​

取得影片 ​

工具呼叫

多語言 API 呼叫

接入步驟

取得影片