API reference

API reference · API

Keep a project

POST/v1/studio/projectsAPI key

A whole editor document as project, or a new empty one by name and aspect. 409 project_exists when its doc_id is kept already and too_many_projects past the cap; 413 project_too_large. An API key with the chat scope (a write or a spend). Rate limited per key at the key's own requests a minute, in a window of its own. An agent's key is refused (403 policy_violation). Every /v1/studio door is a 404 while video and sound jobs are switched off.

Request body

application/json, required

Request body fields
FieldTypeWhat it is
projectobjectThe editor's own Project document (lib/studio/timeline.ts), held to the same schema: every clip names an asset the document carries, or none for a title.
project.idrequiredstringAt most 100 characters.
project.namerequiredstringAt most 500 characters.
project.aspectrequiredstringOne of "16:9", "9:16", "1:1".
project.budgetMicrosrequirednumber or null
project.assetsrequiredarray of object
project.assets[].idrequiredstringAt most 100 characters.
project.assets[].kindrequiredstringOne of "video", "audio", "image".
project.assets[].namerequiredstringAt most 500 characters.
project.assets[].mimerequiredstringAt most 200 characters.
project.assets[].durationrequirednumberAt least 0.
project.assets[].widthnumber
project.assets[].heightnumber
project.assets[].hasAudioboolean
project.assets[].sourcerequiredstringOne of "import", "generated", "speech", "image", "frame".
project.assets[].modelstringAt most 200 characters.
project.assets[].promptstringAt most 20000 characters.
project.assets[].microsnumberAt least 0.
project.assets[].jobobject
project.assets[].job.idrequiredstringAt most 120 characters.
project.assets[].job.statusrequiredstringOne of "queued", "in_progress", "completed", "failed", "cancelled".
project.assets[].job.progressrequirednumber or null
project.assets[].job.errorstringAt most 2000 characters.
project.assets[].job.expiresAtnumber or null
project.assets[].renderMsnumberAt least 0.
project.assets[].shootoutstringAt most 100 characters.
project.assets[].seedintegerFrom 0 to 2147483647.
project.assets[].variationstringAt most 100 characters.
project.assets[].askedobject
project.assets[].asked.camerarequiredstring or null
project.assets[].asked.pathobject
project.assets[].asked.refsarray of string
project.assets[].asked.endstringAt most 100 characters.
project.assets[].asked.negativestringAt most 2000 characters.
project.assets[].categorystringOne of "Characters", "Locations", "Products".
project.assets[].characterobject
project.assets[].character.idrequiredstring
project.assets[].character.namerequiredstringAt most 80 characters.
project.assets[].storedstring
project.assets[].fromobject
project.assets[].from.assetIdrequiredstringAt most 100 characters.
project.assets[].from.taskrequiredstringOne of "speech", "lipsync", "talking", "edit", "extend", "upscale", "motion", "enlarge", "inpaint".
project.assets[].reverseOfobject
project.assets[].reverseOf.assetIdrequiredstringAt most 100 characters.
project.assets[].reverseOf.fromrequirednumberAt least 0.
project.assets[].reverseOf.torequirednumberAt least 0.
project.assets[].forShotstringAt most 100 characters.
project.assets[].tagsarray of string
project.assets[].beatsobject
project.assets[].beats.bpmrequirednumberFrom 0 to 1000.
project.assets[].beats.atrequiredarray of number
project.assets[].motionobject
project.assets[].motion.fpsrequirednumberAt most 120.
project.assets[].motion.xrequiredarray of number
project.assets[].motion.yrequiredarray of number
project.assets[].draftboolean
project.assets[].rating1 or -1
project.assets[].lastFrameOfstringAt most 100 characters.
project.assets[].createdAtrequirednumber
project.clipsrequiredarray of object
project.clips[].idrequiredstringAt most 100 characters.
project.clips[].trackrequiredstringOne of "title", "overlay", "video", "caption", "voice", "music", "effects".
project.clips[].assetIdrequiredstring or null
project.clips[].startrequirednumberAt least 0.
project.clips[].inrequirednumberAt least 0.
project.clips[].durationrequirednumber
project.clips[].speedrequirednumber
project.clips[].volumerequirednumberAt least 0.
project.clips[].lookstringAt most 100 characters.
project.clips[].panobject
project.clips[].pan.xrequirednumber
project.clips[].pan.yrequirednumber
project.clips[].transitionobject
project.clips[].transition.kindrequiredstringOne of "cut", "crossfade", "dip-black", "dip-white", "whip".
project.clips[].transition.durationrequirednumberAt least 0.
project.clips[].textstringAt most 2000 characters.
project.clips[].stylestringOne of "cinema", "lower-third", "bold", "minimal", "clean", "boxed", "karaoke", "large".
project.clips[].enterstringOne of "none", "fade", "type", "slide".
project.clips[].exitstringOne of "none", "fade", "type", "slide".
project.clips[].placeobject
project.clips[].place.xrequirednumberFrom -1 to 1.
project.clips[].place.yrequirednumberFrom -1 to 1.
project.clips[].place.scalerequirednumberFrom 0.1 to 4.
project.clips[].opacitynumberFrom 0 to 1.
project.clips[].placeKeysarray of object
project.clips[].placeKeys[].srequirednumber
project.clips[].placeKeys[].xrequirednumberFrom -1 to 1.
project.clips[].placeKeys[].yrequirednumberFrom -1 to 1.
project.clips[].placeKeys[].scalerequirednumberFrom 0.1 to 4.
project.clips[].placeKeys[].opacitynumberFrom 0 to 1.
project.clips[].volumeKeysarray of object
project.clips[].volumeKeys[].srequirednumber
project.clips[].volumeKeys[].vrequirednumberFrom 0 to 1.
project.clips[].adjustobject
project.clips[].adjust.exposurenumberFrom -2 to 2.
project.clips[].adjust.contrastnumberFrom 0.5 to 1.5.
project.clips[].adjust.saturationnumberFrom 0 to 2.
project.clips[].ramparray of object
project.clips[].ramp[].urequirednumberFrom 0 to 1.
project.clips[].ramp[].vrequirednumberFrom 0.25 to 4.
project.clips[].panKeysarray of object
project.clips[].panKeys[].srequirednumber
project.clips[].panKeys[].xrequirednumberFrom -1 to 1.
project.clips[].panKeys[].yrequirednumberFrom -1 to 1.
project.clips[].chromaobject
project.clips[].chroma.colorrequiredstring
project.clips[].chroma.tolerancerequirednumberFrom 0 to 1.
project.clips[].chroma.softnessrequirednumberFrom 0 to 1.
project.clips[].chroma.spillrequirednumberFrom 0 to 1.
project.clips[].stabilizenumberFrom 0 to 1.
project.clips[].maskobject
project.clips[].mask.shaperequiredstringOne of "rect", "ellipse".
project.clips[].mask.xrequirednumberFrom 0 to 1.
project.clips[].mask.yrequirednumberFrom 0 to 1.
project.clips[].mask.wrequirednumberFrom 0 to 2.
project.clips[].mask.hrequirednumberFrom 0 to 2.
project.clips[].mask.featherrequirednumberFrom 0 to 1.
project.clips[].mask.invertboolean
project.clips[].blendstringOne of "normal", "screen", "multiply", "overlay", "add".
project.clips[].cellobject

Example

{
  "project": {
    "id": "string",
    "name": "string",
    "aspect": "16:9",
    "budgetMicros": 0,
    "assets": [
      {
        "id": "string",
        "kind": "video",
        "name": "string",
        "mime": "string",
        "duration": 0,
        "source": "import",
        "model": "antimatter/auto",
        "prompt": "Say hello in five words.",
        "createdAt": 0
      }
    ],
    "clips": [
      {
        "id": "string",
        "track": "title",
        "assetId": "string",
        "start": 0,
        "in": 0,
        "duration": 0,
        "speed": 0,
        "volume": 0
      }
    ],
    "duck": false,
    "characterAssetId": "string",
    "model": "antimatter/auto",
    "createdAt": 0,
    "updatedAt": 0
  },
  "name": "string",
  "aspect": "16:9"
}

Answer 201

The project.

Fields of the 201 answer
FieldTypeWhat it is
idstring
objectstringOne of "studio.project".
doc_idstringThe document's own id (Project.id), unique per owner.
namestring
aspectstringOne of "16:9", "9:16", "1:1".
versionintegerMoves on by one with every write; a write names the version it read.
bytesinteger
org_idinteger or null
created_atinteger
updated_atinteger
projectobjectThe editor's own Project document (lib/studio/timeline.ts), held to the same schema: every clip names an asset the document carries, or none for a title.
project.idrequiredstringAt most 100 characters.
project.namerequiredstringAt most 500 characters.
project.aspectrequiredstringOne of "16:9", "9:16", "1:1".
project.budgetMicrosrequirednumber or null
project.assetsrequiredarray of object
project.assets[].idrequiredstringAt most 100 characters.
project.assets[].kindrequiredstringOne of "video", "audio", "image".
project.assets[].namerequiredstringAt most 500 characters.
project.assets[].mimerequiredstringAt most 200 characters.
project.assets[].durationrequirednumberAt least 0.
project.assets[].widthnumber
project.assets[].heightnumber
project.assets[].hasAudioboolean
project.assets[].sourcerequiredstringOne of "import", "generated", "speech", "image", "frame".
project.assets[].modelstringAt most 200 characters.
project.assets[].promptstringAt most 20000 characters.
project.assets[].microsnumberAt least 0.
project.assets[].jobobject
project.assets[].job.idrequiredstringAt most 120 characters.
project.assets[].job.statusrequiredstringOne of "queued", "in_progress", "completed", "failed", "cancelled".
project.assets[].job.progressrequirednumber or null
project.assets[].job.errorstringAt most 2000 characters.
project.assets[].job.expiresAtnumber or null
project.assets[].renderMsnumberAt least 0.
project.assets[].shootoutstringAt most 100 characters.
project.assets[].seedintegerFrom 0 to 2147483647.
project.assets[].variationstringAt most 100 characters.
project.assets[].askedobject
project.assets[].asked.camerarequiredstring or null
project.assets[].asked.pathobject
project.assets[].asked.refsarray of string
project.assets[].asked.endstringAt most 100 characters.
project.assets[].asked.negativestringAt most 2000 characters.
project.assets[].categorystringOne of "Characters", "Locations", "Products".
project.assets[].characterobject
project.assets[].character.idrequiredstring
project.assets[].character.namerequiredstringAt most 80 characters.
project.assets[].storedstring
project.assets[].fromobject
project.assets[].from.assetIdrequiredstringAt most 100 characters.
project.assets[].from.taskrequiredstringOne of "speech", "lipsync", "talking", "edit", "extend", "upscale", "motion", "enlarge", "inpaint".
project.assets[].reverseOfobject
project.assets[].reverseOf.assetIdrequiredstringAt most 100 characters.
project.assets[].reverseOf.fromrequirednumberAt least 0.
project.assets[].reverseOf.torequirednumberAt least 0.
project.assets[].forShotstringAt most 100 characters.
project.assets[].tagsarray of string
project.assets[].beatsobject
project.assets[].beats.bpmrequirednumberFrom 0 to 1000.
project.assets[].beats.atrequiredarray of number
project.assets[].motionobject
project.assets[].motion.fpsrequirednumberAt most 120.
project.assets[].motion.xrequiredarray of number
project.assets[].motion.yrequiredarray of number
project.assets[].draftboolean
project.assets[].rating1 or -1
project.assets[].lastFrameOfstringAt most 100 characters.
project.assets[].createdAtrequirednumber
project.clipsrequiredarray of object
project.clips[].idrequiredstringAt most 100 characters.
project.clips[].trackrequiredstringOne of "title", "overlay", "video", "caption", "voice", "music", "effects".
project.clips[].assetIdrequiredstring or null
project.clips[].startrequirednumberAt least 0.
project.clips[].inrequirednumberAt least 0.
project.clips[].durationrequirednumber
project.clips[].speedrequirednumber
project.clips[].volumerequirednumberAt least 0.
project.clips[].lookstringAt most 100 characters.
project.clips[].panobject
project.clips[].pan.xrequirednumber
project.clips[].pan.yrequirednumber
project.clips[].transitionobject
project.clips[].transition.kindrequiredstringOne of "cut", "crossfade", "dip-black", "dip-white", "whip".
project.clips[].transition.durationrequirednumberAt least 0.
project.clips[].textstringAt most 2000 characters.
project.clips[].stylestringOne of "cinema", "lower-third", "bold", "minimal", "clean", "boxed", "karaoke", "large".
project.clips[].enterstringOne of "none", "fade", "type", "slide".
project.clips[].exitstringOne of "none", "fade", "type", "slide".
project.clips[].placeobject
project.clips[].place.xrequirednumberFrom -1 to 1.
project.clips[].place.yrequirednumberFrom -1 to 1.
project.clips[].place.scalerequirednumberFrom 0.1 to 4.
project.clips[].opacitynumberFrom 0 to 1.
project.clips[].placeKeysarray of object
project.clips[].placeKeys[].srequirednumber
project.clips[].placeKeys[].xrequirednumberFrom -1 to 1.
project.clips[].placeKeys[].yrequirednumberFrom -1 to 1.
project.clips[].placeKeys[].scalerequirednumberFrom 0.1 to 4.
project.clips[].placeKeys[].opacitynumberFrom 0 to 1.
project.clips[].volumeKeysarray of object
project.clips[].volumeKeys[].srequirednumber
project.clips[].volumeKeys[].vrequirednumberFrom 0 to 1.
project.clips[].adjustobject
project.clips[].adjust.exposurenumberFrom -2 to 2.
project.clips[].adjust.contrastnumberFrom 0.5 to 1.5.
project.clips[].adjust.saturationnumberFrom 0 to 2.
project.clips[].ramparray of object
project.clips[].ramp[].urequirednumberFrom 0 to 1.
project.clips[].ramp[].vrequirednumberFrom 0.25 to 4.
project.clips[].panKeysarray of object
project.clips[].panKeys[].srequirednumber
project.clips[].panKeys[].xrequirednumberFrom -1 to 1.
project.clips[].panKeys[].yrequirednumberFrom -1 to 1.
project.clips[].chromaobject
project.clips[].chroma.colorrequiredstring
project.clips[].chroma.tolerancerequirednumberFrom 0 to 1.
project.clips[].chroma.softnessrequirednumberFrom 0 to 1.
project.clips[].chroma.spillrequirednumberFrom 0 to 1.
project.clips[].stabilizenumberFrom 0 to 1.

Errors

  • 400OpenAI shaped error.
  • 401OpenAI shaped error.
  • 403OpenAI shaped error.
  • 404OpenAI shaped error.
  • 409OpenAI shaped error.
  • 413OpenAI shaped error.
  • 429OpenAI shaped error.

Every error answers in one shape, with its type, code and the field it names. The whole list is in the docs' Errors section.

Antimatter