Driving Seedance Prompt Studio from code

Everything the web app does is available over HTTP. The base URL is https://api.skillsafe.ai/v1/app-api, every request carries Authorization: Bearer <token>, and every response is the same envelope.

The `task` field comes first

This app has six lanes behind one endpoint. Every run body must carry a task field naming the lane - it is what the system prompt routes on. Send the wrong one and you get a valid package of the wrong kind; omit it and the model picks the closest lane and tells you which it chose.

One more shape trap: the run body is the input object. Do not wrap it in an {"input": ...} envelope - that returns 200 while hiding task from the model, which is the most confusing way this API can fail.

task Lane Fields Sections returned

plan Video plan idea, seconds, aspect, audience, style, language Summary, Logline, Audience and Platform, Scene Table, Continuity Bible, Production Risks, Next Step

cast Character design plan, cast_notes, style, aspect, language Summary, Cast List, Identity Lock, Wardrobe and Props, Character Sheet Prompt, Continuity Risks, Next Step

board Storyboard package scene, scene_no, seconds, identity, aspect, style, language Summary, Grid Plan, Panel Table, Storyboard Sheet Prompt, Continuity Checklist, Next Step

prompt Seedance 2.0 prompt brief, mode, seconds, assets, aspect, style, audio, negatives, language Summary, Asset Roles, Prompt, Segment Table, Audio Design, Constraint Check, Next Step

extend Long-form segmentation brief, total_seconds, opening, aspect, style, language Summary, Segment Map, Segment Prompts, Splice Points, Constraint Check, Next Step

audit Prompt audit draft, seconds, assets, language Summary, Verdict, Findings, Rewritten Prompt, Constraint Check, Next Step

task	Lane	Fields	Sections returned
`plan`	Video plan	`idea, seconds, aspect, audience, style, language`	Summary, Logline, Audience and Platform, Scene Table, Continuity Bible, Production Risks, Next Step
`cast`	Character design	`plan, cast_notes, style, aspect, language`	Summary, Cast List, Identity Lock, Wardrobe and Props, Character Sheet Prompt, Continuity Risks, Next Step
`board`	Storyboard package	`scene, scene_no, seconds, identity, aspect, style, language`	Summary, Grid Plan, Panel Table, Storyboard Sheet Prompt, Continuity Checklist, Next Step
`prompt`	Seedance 2.0 prompt	`brief, mode, seconds, assets, aspect, style, audio, negatives, language`	Summary, Asset Roles, Prompt, Segment Table, Audio Design, Constraint Check, Next Step
`extend`	Long-form segmentation	`brief, total_seconds, opening, aspect, style, language`	Summary, Segment Map, Segment Prompts, Splice Points, Constraint Check, Next Step
`audit`	Prompt audit	`draft, seconds, assets, language`	Summary, Verdict, Findings, Rewritten Prompt, Constraint Check, Next Step

Only task and the lane's own required field are mandatory: idea for plan, plan for cast, scene for board, brief for prompt, brief and total_seconds for extend, draft for audit. Everything else has a sensible default. seconds, scene_no and total_seconds are numbers, not strings - sending "12" where 12 is expected is the most common 400.

Add $model to any body to choose the model for that run: gpt-5.6-luna, gpt-5.6-terra (the default) or gpt-5.6-sol. Luna caps output at 4,096 tokens and will fail the plan, board and extend lanes rather than shorten them.

The response envelope

Success and failure have the same outer shape, so one check covers both.

{
  "ok": true,
  "data": {
    "...": "the result"
  }
}

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "seconds should be number, got string",
    "details": {}
  }
}

HTTP error.code What it means

400 VALIDATION_ERROR The body was not a JSON object, or a declared field had the wrong type. A number field sent as a string is the usual cause.

401 UNAUTHORIZED No token, or a token that has expired or been revoked. Mint a new one.

402 INSUFFICIENT_CREDITS The balance is below the run's minimum. Call /estimate first and compare hold_credits against /me.

404 NOT_FOUND Wrong path, or a job id that does not belong to this token.

409 CONFLICT An Idempotency-Key replay whose body differs from the original request.

429 RATE_LIMITED Too many requests. Back off; do not tight-loop.

503 UPSTREAM_UNAVAILABLE The model provider is unavailable. Retry with backoff.

HTTP	error.code	What it means
`400`	`VALIDATION_ERROR`	The body was not a JSON object, or a declared field had the wrong type. A number field sent as a string is the usual cause.
`401`	`UNAUTHORIZED`	No token, or a token that has expired or been revoked. Mint a new one.
`402`	`INSUFFICIENT_CREDITS`	The balance is below the run's minimum. Call /estimate first and compare hold_credits against /me.
`404`	`NOT_FOUND`	Wrong path, or a job id that does not belong to this token.
`409`	`CONFLICT`	An Idempotency-Key replay whose body differs from the original request.
`429`	`RATE_LIMITED`	Too many requests. Back off; do not tight-loop.
`503`	`UPSTREAM_UNAVAILABLE`	The model provider is unavailable. Retry with backoff.

1. Get a token

Open /tokens.html in a browser and copy the token this app already holds - no developer console needed. A guest token is minted automatically and is enough for /me and /estimate; writing a package is metered and needs a personal token, which comes from signing in on that page.

Keep it in an environment variable rather than in source:

export SKILLSAFE_TOKEN="YOUR_TOKEN"

2. Check the session and the balance

GET /me is free. It returns only three fields: subject_type, subject_id and credits. Signed-in means subject_type == "user" - there is no username or email to test.

curl -sS -X GET "https://api.skillsafe.ai/v1/app-api/me" \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN"

import json, urllib.request

TOKEN = "YOUR_TOKEN"   # from /tokens.html
BASE  = "https://api.skillsafe.ai/v1/app-api"

def call(method, path, payload=None, headers=None):
    data = json.dumps(payload).encode() if payload is not None else None
    req = urllib.request.Request(BASE + path, data=data, method=method)
    req.add_header("Authorization", "Bearer " + TOKEN)
    req.add_header("Content-Type", "application/json")
    req.add_header("Accept", "application/json")
    # A plain urllib request with no User-Agent is refused with 403.
    req.add_header("User-Agent", "seedance-prompt-studio-client/1.0")
    for k, v in (headers or {}).items():
        req.add_header(k, v)
    with urllib.request.urlopen(req) as r:
        return json.loads(r.read())

out = call("GET", "/me")
print(json.dumps(out["data"], indent=2))

const TOKEN = "YOUR_TOKEN";   // from /tokens.html
const BASE  = "https://api.skillsafe.ai/v1/app-api";

async function call(method, path, payload) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "Content-Type": "application/json"
    },
    body: payload === undefined ? undefined : JSON.stringify(payload)
  });
  const json = await res.json();
  if (!res.ok || !json.ok) throw new Error(json.error?.message || res.statusText);
  return json.data;
}

const data = await call("GET", "/me");
console.log(data);

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

const base = "https://api.skillsafe.ai/v1/app-api"
const token = "YOUR_TOKEN" // from /tokens.html

func main() {
	req, _ := http.NewRequest("GET", base+"/me", nil)
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

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

public class Main {
    static final String BASE  = "https://api.skillsafe.ai/v1/app-api";
    static final String TOKEN = "YOUR_TOKEN"; // from /tokens.html

    public static void main(String[] args) throws Exception {
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(BASE + "/me"))
            .header("Authorization", "Bearer " + TOKEN)
            .header("Content-Type", "application/json")
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();
        HttpResponse<String> res = HttpClient.newHttpClient()
            .send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(res.body());
    }
}

require 'net/http'
require 'json'
require 'uri'

BASE  = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "YOUR_TOKEN" # from /tokens.html

uri = URI("#{BASE}/me")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{TOKEN}"
req["Content-Type"] = "application/json"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
puts JSON.pretty_generate(JSON.parse(res.body)["data"])

<?php
$base  = "https://api.skillsafe.ai/v1/app-api";
$token = "YOUR_TOKEN"; // from /tokens.html

$opts = ["http" => [
    "method"  => "GET",
    "header"  => "Authorization: Bearer $token\r\nContent-Type: application/json\r\n",
]];
$res  = file_get_contents($base . "/me", false, stream_context_create($opts));
$json = json_decode($res, true);
print_r($json["data"]);

using System.Net.Http;
using System.Text;

const string Base  = "https://api.skillsafe.ai/v1/app-api";
const string Token = "YOUR_TOKEN"; // from /tokens.html

var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", $"Bearer {Token}");

var res = await http.SendAsync(new HttpRequestMessage(new HttpMethod("GET"), Base + "/me")
{
    Content = null
});
Console.WriteLine(await res.Content.ReadAsStringAsync());

3. Price the run before making it

POST /estimate costs nothing, creates no job, and returns the worst-case cost. Compare hold_credits against the balance from step 2 before you submit: a 402 after the fact is avoidable. hold_credits is a reservation priced at the full output cap - the actual charge is usually far lower.

It also echoes model, model_alias and markup_bps, which is the authoritative check that a run is bound to the model you think it is. Estimate each lane separately: their prompts and caps differ, so their holds do.

curl -sS -X POST "https://api.skillsafe.ai/v1/app-api/estimate" \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
}'

import json, urllib.request

TOKEN = "YOUR_TOKEN"   # from /tokens.html
BASE  = "https://api.skillsafe.ai/v1/app-api"

def call(method, path, payload=None, headers=None):
    data = json.dumps(payload).encode() if payload is not None else None
    req = urllib.request.Request(BASE + path, data=data, method=method)
    req.add_header("Authorization", "Bearer " + TOKEN)
    req.add_header("Content-Type", "application/json")
    req.add_header("Accept", "application/json")
    # A plain urllib request with no User-Agent is refused with 403.
    req.add_header("User-Agent", "seedance-prompt-studio-client/1.0")
    for k, v in (headers or {}).items():
        req.add_header(k, v)
    with urllib.request.urlopen(req) as r:
        return json.loads(r.read())

payload = {
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
}
out = call("POST", "/estimate", payload)
print(out["data"]["hold_credits"], out["data"]["model"])

const TOKEN = "YOUR_TOKEN";   // from /tokens.html
const BASE  = "https://api.skillsafe.ai/v1/app-api";

async function call(method, path, payload) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "Content-Type": "application/json"
    },
    body: payload === undefined ? undefined : JSON.stringify(payload)
  });
  const json = await res.json();
  if (!res.ok || !json.ok) throw new Error(json.error?.message || res.statusText);
  return json.data;
}

const payload = {
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
};
const data = await call("POST", "/estimate", payload);
console.log(data.hold_credits, data.model, data.model_alias);

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

const base = "https://api.skillsafe.ai/v1/app-api"
const token = "YOUR_TOKEN" // from /tokens.html

func main() {
	payload := []byte(`{
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
}`)
	req, _ := http.NewRequest("POST", base+"/estimate", bytes.NewReader(payload))
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

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

public class Main {
    static final String BASE  = "https://api.skillsafe.ai/v1/app-api";
    static final String TOKEN = "YOUR_TOKEN"; // from /tokens.html

    public static void main(String[] args) throws Exception {
        String payload = """
{
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
}
""";
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(BASE + "/estimate"))
            .header("Authorization", "Bearer " + TOKEN)
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .build();
        HttpResponse<String> res = HttpClient.newHttpClient()
            .send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(res.body());
    }
}

require 'net/http'
require 'json'
require 'uri'

BASE  = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "YOUR_TOKEN" # from /tokens.html

payload = {
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
}

uri = URI("#{BASE}/estimate")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{TOKEN}"
req["Content-Type"] = "application/json"
req.body = JSON.dump(payload)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
puts JSON.pretty_generate(JSON.parse(res.body)["data"])

<?php
$base  = "https://api.skillsafe.ai/v1/app-api";
$token = "YOUR_TOKEN"; // from /tokens.html

$payload = json_encode([
  "task" => "prompt",
  "brief" => "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode" => "omni",
  "seconds" => 12,
  "assets" => "Image 1 => the bottle\nImage 2 => the platform at dusk\nVideo 1 => a push-in to copy",
  "aspect" => "9:16",
  "audio" => "running water, platform announcement bleed, no music",
  "negatives" => "no on-screen text, no logos, no watermark",
  "language" => "en"
]);

$opts = ["http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer $token\r\nContent-Type: application/json\r\n",
    "content" => $payload,
]];
$res  = file_get_contents($base . "/estimate", false, stream_context_create($opts));
$json = json_decode($res, true);
print_r($json["data"]);

using System.Net.Http;
using System.Text;

const string Base  = "https://api.skillsafe.ai/v1/app-api";
const string Token = "YOUR_TOKEN"; // from /tokens.html

var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", $"Bearer {Token}");

var payload = """
{
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
}
""";
var content = new StringContent(payload, Encoding.UTF8, "application/json");
var res = await http.SendAsync(new HttpRequestMessage(new HttpMethod("POST"), Base + "/estimate")
{
    Content = content
});
Console.WriteLine(await res.Content.ReadAsStringAsync());

4. Write a package

POST /run submits the job. Always send an Idempotency-Key: a network blip that replays the same request must not bill twice. A replay with the same key returns the stored result and is not charged again; a replay with the same key but a different body is a 409.

The response carries output.output (the Markdown package), charged_credits and truncated. If truncated is true the balance sat between min_credits and hold_credits and the output was cut short - render what arrived and say so rather than presenting it as complete.

curl -sS -X POST "https://api.skillsafe.ai/v1/app-api/run" \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
}'

import json, urllib.request

TOKEN = "YOUR_TOKEN"   # from /tokens.html
BASE  = "https://api.skillsafe.ai/v1/app-api"

def call(method, path, payload=None, headers=None):
    data = json.dumps(payload).encode() if payload is not None else None
    req = urllib.request.Request(BASE + path, data=data, method=method)
    req.add_header("Authorization", "Bearer " + TOKEN)
    req.add_header("Content-Type", "application/json")
    req.add_header("Accept", "application/json")
    # A plain urllib request with no User-Agent is refused with 403.
    req.add_header("User-Agent", "seedance-prompt-studio-client/1.0")
    for k, v in (headers or {}).items():
        req.add_header(k, v)
    with urllib.request.urlopen(req) as r:
        return json.loads(r.read())

payload = {
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
}
out = call("POST", "/run", payload)
print(out["data"]["output"]["output"])

const TOKEN = "YOUR_TOKEN";   // from /tokens.html
const BASE  = "https://api.skillsafe.ai/v1/app-api";

async function call(method, path, payload) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "Content-Type": "application/json"
    },
    body: payload === undefined ? undefined : JSON.stringify(payload)
  });
  const json = await res.json();
  if (!res.ok || !json.ok) throw new Error(json.error?.message || res.statusText);
  return json.data;
}

const payload = {
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
};
const data = await call("POST", "/run", payload);
console.log(data.output.output);

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

const base = "https://api.skillsafe.ai/v1/app-api"
const token = "YOUR_TOKEN" // from /tokens.html

func main() {
	payload := []byte(`{
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
}`)
	req, _ := http.NewRequest("POST", base+"/run", bytes.NewReader(payload))
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

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

public class Main {
    static final String BASE  = "https://api.skillsafe.ai/v1/app-api";
    static final String TOKEN = "YOUR_TOKEN"; // from /tokens.html

    public static void main(String[] args) throws Exception {
        String payload = """
{
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
}
""";
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(BASE + "/run"))
            .header("Authorization", "Bearer " + TOKEN)
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .build();
        HttpResponse<String> res = HttpClient.newHttpClient()
            .send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(res.body());
    }
}

require 'net/http'
require 'json'
require 'uri'

BASE  = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "YOUR_TOKEN" # from /tokens.html

payload = {
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
}

uri = URI("#{BASE}/run")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{TOKEN}"
req["Content-Type"] = "application/json"
req.body = JSON.dump(payload)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
puts JSON.pretty_generate(JSON.parse(res.body)["data"])

<?php
$base  = "https://api.skillsafe.ai/v1/app-api";
$token = "YOUR_TOKEN"; // from /tokens.html

$payload = json_encode([
  "task" => "prompt",
  "brief" => "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode" => "omni",
  "seconds" => 12,
  "assets" => "Image 1 => the bottle\nImage 2 => the platform at dusk\nVideo 1 => a push-in to copy",
  "aspect" => "9:16",
  "audio" => "running water, platform announcement bleed, no music",
  "negatives" => "no on-screen text, no logos, no watermark",
  "language" => "en"
]);

$opts = ["http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer $token\r\nContent-Type: application/json\r\n",
    "content" => $payload,
]];
$res  = file_get_contents($base . "/run", false, stream_context_create($opts));
$json = json_decode($res, true);
print_r($json["data"]);

using System.Net.Http;
using System.Text;

const string Base  = "https://api.skillsafe.ai/v1/app-api";
const string Token = "YOUR_TOKEN"; // from /tokens.html

var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", $"Bearer {Token}");

var payload = """
{
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
}
""";
var content = new StringContent(payload, Encoding.UTF8, "application/json");
var res = await http.SendAsync(new HttpRequestMessage(new HttpMethod("POST"), Base + "/run")
{
    Content = content
});
Console.WriteLine(await res.Content.ReadAsStringAsync());

5. Stream a run

POST /run-stream is the same call with a text/event-stream response. Worth knowing before you build on it: from a server or from cURL you get event: delta frames carrying the output token by token; from a browser you get event: tick heartbeats and then one event: done with the whole output. Handle both, and treat ticks as liveness rather than progress.

Frame types are job (the job id), delta ({"text": "..."}), tick ({"t": seconds}), done, and error. An idempotent replay returns plain JSON with no stream at all, so check the content type before you start reading frames.

curl -sS -N -X POST "https://api.skillsafe.ai/v1/app-api/run-stream" \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "Idempotency-Key: seed-$(date +%s)" \
  -d '{
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
}'

import json, urllib.request

TOKEN = "YOUR_TOKEN"
BASE  = "https://api.skillsafe.ai/v1/app-api"

payload = {
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
}

req = urllib.request.Request(BASE + "/run-stream", data=json.dumps(payload).encode(), method="POST")
req.add_header("Authorization", "Bearer " + TOKEN)
req.add_header("Content-Type", "application/json")
req.add_header("Accept", "text/event-stream")
req.add_header("Idempotency-Key", "seed-demo-1")
req.add_header("User-Agent", "seedance-prompt-studio-client/1.0")

event, data = "message", ""
with urllib.request.urlopen(req) as r:
    for raw in r:
        line = raw.decode().rstrip("\n")
        if line.startswith("event:"):
            event = line[6:].strip()
        elif line.startswith("data:"):
            data += line[5:].strip()
        elif line == "":
            if data:
                frame = json.loads(data)
                if event == "delta":
                    print(frame.get("text", ""), end="")
                elif event == "done":
                    print("\n--- charged:", frame.get("charged_credits"))
            event, data = "message", ""

const TOKEN = "YOUR_TOKEN";
const BASE  = "https://api.skillsafe.ai/v1/app-api";

const payload = {
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
};

const res = await fetch(BASE + "/run-stream", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "seed-demo-1"
  },
  body: JSON.stringify(payload)
});

// An idempotent replay comes back as plain JSON with no stream at all.
if (!(res.headers.get("content-type") || "").includes("text/event-stream")) {
  const json = await res.json();
  console.log(json.data.output.output);
} else {
  const reader = res.body.getReader();
  const dec = new TextDecoder();
  let buf = "";
  for (;;) {
    const { done, value } = await reader.read();
    if (done) break;
    buf += dec.decode(value, { stream: true });
    let i;
    while ((i = buf.indexOf("\n\n")) >= 0) {
      const frame = buf.slice(0, i);
      buf = buf.slice(i + 2);
      let name = "message", data = "";
      for (const line of frame.split("\n")) {
        if (line.startsWith("event:")) name = line.slice(6).trim();
        else if (line.startsWith("data:")) data += line.slice(5).trim();
      }
      if (!data) continue;
      const p = JSON.parse(data);
      if (name === "delta") process.stdout.write(p.text || "");
      if (name === "tick") console.error("still writing:", p.t + "s");
      if (name === "done") console.log("\ncharged:", p.charged_credits);
    }
  }
}

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

const base = "https://api.skillsafe.ai/v1/app-api"
const token = "YOUR_TOKEN" // from /tokens.html

func main() {
	payload := []byte(`{
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
}`)
	req, _ := http.NewRequest("POST", base+"/run-stream", bytes.NewReader(payload))
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

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

public class Main {
    static final String BASE  = "https://api.skillsafe.ai/v1/app-api";
    static final String TOKEN = "YOUR_TOKEN"; // from /tokens.html

    public static void main(String[] args) throws Exception {
        String payload = """
{
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
}
""";
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(BASE + "/run-stream"))
            .header("Authorization", "Bearer " + TOKEN)
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .build();
        HttpResponse<String> res = HttpClient.newHttpClient()
            .send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(res.body());
    }
}

require 'net/http'
require 'json'
require 'uri'

BASE  = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "YOUR_TOKEN" # from /tokens.html

payload = {
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
}

uri = URI("#{BASE}/run-stream")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{TOKEN}"
req["Content-Type"] = "application/json"
req.body = JSON.dump(payload)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
puts JSON.pretty_generate(JSON.parse(res.body)["data"])

<?php
$base  = "https://api.skillsafe.ai/v1/app-api";
$token = "YOUR_TOKEN"; // from /tokens.html

$payload = json_encode([
  "task" => "prompt",
  "brief" => "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode" => "omni",
  "seconds" => 12,
  "assets" => "Image 1 => the bottle\nImage 2 => the platform at dusk\nVideo 1 => a push-in to copy",
  "aspect" => "9:16",
  "audio" => "running water, platform announcement bleed, no music",
  "negatives" => "no on-screen text, no logos, no watermark",
  "language" => "en"
]);

$opts = ["http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer $token\r\nContent-Type: application/json\r\n",
    "content" => $payload,
]];
$res  = file_get_contents($base . "/run-stream", false, stream_context_create($opts));
$json = json_decode($res, true);
print_r($json["data"]);

using System.Net.Http;
using System.Text;

const string Base  = "https://api.skillsafe.ai/v1/app-api";
const string Token = "YOUR_TOKEN"; // from /tokens.html

var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", $"Bearer {Token}");

var payload = """
{
  "task": "prompt",
  "brief": "The commuter fills a steel bottle at a tiled wall tap on a station platform at dusk. A train pulls in behind them and the doors open.",
  "mode": "omni",
  "seconds": 12,
  "assets": "Image 1: the bottle\nImage 2: the platform at dusk\nVideo 1: a push-in to copy",
  "aspect": "9:16",
  "audio": "running water, platform announcement bleed, no music",
  "negatives": "no on-screen text, no logos, no watermark",
  "language": "en"
}
""";
var content = new StringContent(payload, Encoding.UTF8, "application/json");
var res = await http.SendAsync(new HttpRequestMessage(new HttpMethod("POST"), Base + "/run-stream")
{
    Content = content
});
Console.WriteLine(await res.Content.ReadAsStringAsync());

6. Read the result

output.output is Markdown in the envelope this app's system prompt guarantees: every section is a level-two heading spelled exactly as listed in the lane table above, in that order; tables are GitHub pipe tables with the declared columns; prompts are in fenced blocks opened with three backticks and the word text; checklists are - [x] lines.

So parsing is a split on /^## / - but do it fence-aware, because a prompt block can legitimately contain a line starting with ##. Count the sections you got against the ones the lane declares: a short list means the run was truncated, not that the contract changed.

def sections(md):
    out, name, buf, fence = {}, None, [], False
    for line in md.split("\n"):
        if line.lstrip().startswith("```"):
            fence = not fence
        if not fence and line.startswith("## "):
            if name:
                out[name] = "\n".join(buf).strip()
            name, buf = line[3:].strip(), []
            continue
        if name:
            buf.append(line)
    if name:
        out[name] = "\n".join(buf).strip()
    return out

The artifact most callers actually want is the fenced block inside ## Prompt (or ## Rewritten Prompt, or each block under ## Segment Prompts). That is the text you paste into Seedance.

Rate limits and good manners

/estimate and /me are free. Call them as much as you like, within reason.
A 429 means back off with a delay, not retry immediately.
Send an Idempotency-Key on every /run. Derive it from a hash of the body plus an attempt counter, so a retry of the same request reuses the key and a deliberate re-run gets a new one.
The free prompt checker in the web app is client-side only and has no endpoint. If you want the same checks in your own pipeline, the rules are the platform's published limits, the @ reference table, and the upstream skills' common-mistakes list - all documented on the home page and in llms.txt.