ArtCraft API Tutorial: Generate Video with the Omni API

ArtCraft is best known as a desktop studio, but it also has a developer API. The Omni API gives you programmatic access to the same generation models you use in the app, authenticated with an API key instead of a browser session. This guide follows the official Omni API documentation and walks through a complete video generation.

Base URL and authentication

The API lives on the storyteller.ai domain, not getartcraft.com. The official docs call this out explicitly, so it is not a mistake in your setup.

Step 1: Create an API key

1. Open the web app

   Sign in at app.getartcraft.com.

2. Go to Account → Settings → API Keys

   This section only appears if API access is enabled for your account.

3. Create a key and store it safely

   The secret is shown once. Save it in a password manager or your server's secret store, never in source control.

A valid key starts with artcraft_api_ followed by 40 lowercase characters, for 53 characters in total. The API accepts Bearer, Key, or a bare key in the Authorization header; Bearer is recommended.

Step 2: Request a video

Send a POST to /v1/omni_api/generate/video. The example below animates a starting image with Seedance 2.0:

curl -s -X POST https://api.storyteller.ai/v1/omni_api/generate/video \
  -H "Authorization: Bearer $ARTCRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance_2p0",
    "prompt": "A puffin turns its head on a windy cliff edge as morning light catches its beak.",
    "duration_seconds": 6,
    "aspect_ratio": "wide_sixteen_by_nine",
    "idempotency_token": "'"$(uuidgen)"'",
    "start_frame_image_url": "https://example.com/puffin.jpg"
  }'

The response contains a job token you use to fetch the result:

{
  "success": true,
  "inference_job_token": "jinf_xxxxxxxxxxxxxxxxxxxxxxxxx",
  "all_job_tokens": ["jinf_xxxxxxxxxxxxxxxxxxxxxxxxx"]
}

Request fields

Passing reference media by URL

You don't have to upload files first. The server downloads each URL, saves it to your account, and runs the generation with it:

Rules to keep in mind:

• URLs must start with http:// or https:// and be reachable by the server. Up to 10 redirects are followed, so CDN links work.
• File types are detected from the downloaded bytes, not the extension.
• Each URL field has a media-token equivalent (for files already on your account), such as reference_image_media_tokens. You can send one or the other for each input, never both.

Step 3: Poll for the result

Generation is asynchronous. Poll GET /v1/omni_api/job_status/job/{token} until the job finishes. To check many jobs at once, use GET /v1/omni_api/job_status/batch?tokens=…&tokens=….

The job state is at state.status.status:

state.status.progress_percentage gives a rough 0–100 progress value. When the job succeeds, the finished file is at state.maybe_result.media_links.cdn_url. Video jobs also include still and animated preview URLs under media_links.maybe_video_previews.

Complete example in Python

This script submits a video job and polls until it finishes:

import os
import time
import uuid

import requests

BASE_URL = "https://api.storyteller.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['ARTCRAFT_API_KEY']}"}
FAILED = {"complete_failure", "dead", "cancelled_by_user", "cancelled_by_system"}

job = requests.post(
    f"{BASE_URL}/v1/omni_api/generate/video",
    headers=HEADERS,
    json={
        "model": "seedance_2p0",
        "prompt": "A puffin turns its head on a windy cliff edge as morning light catches its beak.",
        "duration_seconds": 6,
        "aspect_ratio": "wide_sixteen_by_nine",
        "idempotency_token": str(uuid.uuid4()),
        "start_frame_image_url": "https://example.com/puffin.jpg",
    },
    timeout=240,
)
job.raise_for_status()
token = job.json()["inference_job_token"]

while True:
    resp = requests.get(f"{BASE_URL}/v1/omni_api/job_status/job/{token}", headers=HEADERS, timeout=30)
    resp.raise_for_status()
    state = resp.json()["state"]
    status = state["status"]["status"]
    print(status, state["status"]["progress_percentage"], "%")
    if status == "complete_success":
        print("Video:", state["maybe_result"]["media_links"]["cdn_url"])
        break
    if status in FAILED:
        raise SystemExit(f"Job ended without a result: {status}")
    time.sleep(5)

Complete example in JavaScript

The same flow in Node.js 18 or newer, which has fetch built in:

import { randomUUID } from "node:crypto";

const BASE_URL = "https://api.storyteller.ai";
const headers = {
  Authorization: `Bearer ${process.env.ARTCRAFT_API_KEY}`,
  "Content-Type": "application/json",
};
const FAILED = new Set(["complete_failure", "dead", "cancelled_by_user", "cancelled_by_system"]);

const job = await fetch(`${BASE_URL}/v1/omni_api/generate/video`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "seedance_2p0",
    prompt: "A puffin turns its head on a windy cliff edge as morning light catches its beak.",
    duration_seconds: 6,
    aspect_ratio: "wide_sixteen_by_nine",
    idempotency_token: randomUUID(),
    reference_image_urls: ["https://example.com/puffin.jpg", "https://example.com/cliff.jpg"],
  }),
}).then((r) => r.json());

while (true) {
  const { state } = await fetch(
    `${BASE_URL}/v1/omni_api/job_status/job/${job.inference_job_token}`,
    { headers },
  ).then((r) => r.json());
  const status = state.status.status;
  if (status === "complete_success") {
    console.log("Video:", state.maybe_result.media_links.cdn_url);
    break;
  }
  if (FAILED.has(status)) throw new Error(`Job ended without a result: ${status}`);
  await new Promise((r) => setTimeout(r, 5000));
}

Generating images

A companion endpoint, POST /v1/omni_api/generate/image, follows the same pattern. It accepts image_urls (or image_media_tokens, but not both) for input images, returns a job token, and uses the same job status endpoint. For image jobs, cdn_url points to the image file, and media_links.maybe_thumbnail_template provides resizable thumbnails.

Errors and troubleshooting

The official documentation in the GitHub repository covers the video endpoints in detail and links to the full API reference for everything else. Model identifiers other than seedance_2p0 are not listed in that guide, so check the full reference before using other models.