Tool Calling

Let a chat application submit video tasks, then poll and download in a background worker.

API Calls in Multiple Languages

See language setup. Set API_KEY and replace model, file URL, and ID placeholders first. Each version displays the raw response to the same request.

These examples submit a task only. Keep the returned id for subsequent queries. This is the generation API call inside the tool handler, not the chat endpoint. See the complete example below for handling chat call IDs.

cURL

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)

JavaScript

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());
    }
}

Integration Steps

1. Run Generate Video Overview with the same API_KEY, VIDEO_MODEL_ID, and model settings.
2. In the complete Chat Tool Calling example, replace the contents of the TOOLS list with this definition.
3. Replace execute with the handler below. Its result reports the current task state, not a completed video.

{"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}}}

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"]}

Replace the inventory question in the Chat example with a video-generation request before running the tool loop.

Retrieve the Video

Save task_id in the overview example's video-task.txt and run that script to poll and download. In production, let a background worker do this and notify the UI only after completion.

Persist the mapping between tool-call ID and task ID. For a repeated call, return the saved task instead of submitting again. If submission times out without an ID, check records before claiming failure or completion.