Developers

Director API & MCP

One HTTP call turns a brief and some material into a shot-by-shot production plan — as a document a person can read, and as a machine plan with every scene pinned to a second range. Same director as the done-for-you service; you are just calling it yourself.

Three steps

What it costs

Priced by finished-video duration — the length of the film you are making, not how long we spend on it. Upload music and the audio length is measured and used; without music you declare it.

Launch pricing. Questions and failures cost nothing: if the director needs more information, or generation fails, the hold is released in full.

Submit a plan

curl -X POST https://spaceskills.shop/v1/plans \
  -H "Authorization: Bearer $DIRECTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "4-minute MV, a courier riding through the city at night, lonely turning to free",
    "lang": "en",
    "materials": {
      "music": { "name": "song.mp3", "url": "https://example.com/song.mp3" },
      "characters": [{ "name": "courier.jpg", "url": "https://example.com/courier.jpg" }]
    }
  }'

Returns immediately with a plan_id. Generation takes two to four minutes; poll the plan until status leaves running.

curl https://spaceskills.shop/v1/plans/pl_xxx \
  -H "Authorization: Bearer $DIRECTOR_API_KEY"

status is one of running, need_info, succeeded, failed. On succeeded you get the plan document and the machine plan; on need_info you get questions to answer.

Endpoints

Sending material

Everything goes in one JSON body. Files are either inline base64 or an https URL we fetch. Up to 40 MB per file, 120 MB per request, at most 12 characters and 12 stills.

A file is { "name": "hero.jpg", "url": "https://…" } or { "name": "hero.jpg", "data_base64": "…" }. URLs must be https and must not resolve to a private address.

What comes back

Two representations of the same plan. The document is for people; the machine plan is for whatever you feed it into next.

• · Every scene and shot carries start_sec and end_sec. The timeline covers the whole runtime with no gaps and no overlaps — for music, the boundaries are computed from the audio, not written by the model.
• · Characters carry per-interval states, so you know who is in what condition at second 94.
• · Every craft term is an id into the vocabulary, with the definition inlined per plan — no lookup table to maintain on your side.
• · Assets you sent come back with sha256 and the id the plan refers to them by.
• · warnings lists anything the plan itself could not reconcile. It is worth reading before you commit render budget.

{
  "schema": "director.plan/1",
  "media": { "aspect_ratio": "9:16", "fps": 24, "duration_sec": 270.59 },
  "timeline": [
    { "scene": 1, "title": "…", "start_sec": 0, "end_sec": 30,
      "shots": [{ "id": "1a", "intent": "…", "terms": ["push-in"],
                  "start_sec": 0, "end_sec": 15 }] }
  ],
  "characters": [
    { "id": "c1", "name": "…", "asset": "a1",
      "states": [{ "from_sec": 0, "to_sec": 44, "state": "…" }] }
  ],
  "vocabulary": [{ "id": "push-in", "zh": "推镜头", "definition": "…" }],
  "assets": [{ "id": "a1", "file": "courier.jpg", "sha256": "…" }],
  "warnings": []
}

The machine plan declares schema: "director.plan/1". Seconds everywhere, aspect ratio from a fixed enum.

MCP

The same six operations as tools, for clients that speak MCP. Your key goes in the environment; nothing else to configure.

claude mcp add director -e DIRECTOR_API_KEY=sk_live_… -- npx -y @spaceskills/director-mcp

quote_plan · create_plan · get_plan · answer_questions · get_credits · get_vocabulary

When things go wrong

Limits

• · Five generations per 24 hours before you top up, fifty after.
• · One plan generates at a time per account; submissions past that get busy.
• · Five API keys per account. Revoking is immediate.
• · Material is kept for a week after delivery, then deleted.

Questions, or something behaving oddly? Tell us