Ultimate offer while subscribed
Docs

Start here

Start a canvas

POST/v1/studio/projects/{project}/canvaseson https://api.auray.ai/v1

Start a canvas in a project: a name, and a canvas document (one empty page when none is sent).

Start a canvas in a project: a name, and a canvas document (one empty page when none is sent). The document is read strictly — anything that does not read is refused canvas_invalid with each problem, past 2 MB of JSON canvas_too_large — and stored with no run on any node: a node's run is only ever what the jobs it started say. A project holds as many canvases as its limits.canvases says: its owner's plan's figure, whoever starts them. Needs the edit_canvas capability in the project. Takes a key holding studio:write — Account offers it unticked — or the desktop's own session key. Spends nothing.

#Authentication

Authorization: Bearer auray_sk_… — studio:write — Account offers it unticked; the desktop's session key holds it.

#Request

#Path parameters

NameTypeRequiredDescription
projectstringyes

#Body

application/json, required.

FieldTypeRequiredDefaultDescription
namestringyes—1 to 80 characters.
docobjectno—A canvas document, version 1: pages (up to 20), each with its viewport, its nodes (up to 1,500 — prompts, generators, uploads and the project's assets, upscalers, editors, notes, stickies, shapes, text, drawn strokes, tables, comment pins, reactions and frames) and the edges wiring an output port into an input port that takes its type. The full shape is published with the Studio's contract; a document that does not read is refused canvas_invalid, naming each problem. A node's run is the server's: anything sent there is ignored.
doc.vintegeryes—One of 1.
doc.pagesobject[]yes—
doc.pages[].idstringyes—
doc.pages[].namestringyes—0 to 80 characters.
doc.pages[].viewportobjectyes—
doc.pages[].viewport.xnumberno—
doc.pages[].viewport.ynumberno—
doc.pages[].viewport.zoomnumberno—0.05 to 4.
doc.pages[].nodesobject[]yes—
doc.pages[].nodes[].idstringyes—
doc.pages[].nodes[].kindstringyes—One of "prompt", "number", "upload", "assets", "image_gen", "video_gen", "audio_gen", "llm", "upscale", "edit", "note", "sticky", "shape", "text", "stroke", "table", "comment_pin", "reaction", "frame".
doc.pages[].nodes[].xnumberyes—
doc.pages[].nodes[].ynumberyes—
doc.pages[].nodes[].wnumberyes—
doc.pages[].nodes[].hnumberyes—
doc.pages[].nodes[].parentstringno—May be null.
doc.pages[].nodes[].zintegerno—
doc.pages[].nodes[].lockedbooleanno—
doc.pages[].nodes[].dataobjectyes—
doc.pages[].nodes[].runobjectno—A node's last run, read off the jobs it started — never written by a request. Null before it ran. May be null.
doc.pages[].edgesobject[]yes—
doc.pages[].edges[].idstringyes—
doc.pages[].edges[].fromobjectyes—
doc.pages[].edges[].toobjectyes—

#Example request

curl -X POST https://api.auray.ai/v1/studio/projects/3f0c8a52-6a1d-4e8b-9c2d-7e5f4a3b2c1d/canvases \
  -H "Authorization: Bearer $AURAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "name": "Storm sequence",
  "doc": {
    "v": 1,
    "pages": [
      {
        "id": "page-1",
        "name": "Page 1",
        "viewport": {
          "x": 0,
          "y": 0,
          "zoom": 1
        },
        "nodes": [
          {
            "id": "prompt-1",
            "kind": "prompt",
            "x": 0,
            "y": 0,
            "w": 280,
            "h": 160,
            "parent": null,
            "z": 0,
            "locked": false,
            "data": {
              "text": "A lighthouse in a storm, seen from the sea."
            },
            "run": null
          },
          {
            "id": "image-1",
            "kind": "image_gen",
            "x": 400,
            "y": 0,
            "w": 300,
            "h": 340,
            "parent": null,
            "z": 0,
            "locked": false,
            "data": {
              "model": null,
              "prompt": "",
              "params": {}
            },
            "run": null
          }
        ],
        "edges": [
          {
            "id": "edge-1",
            "from": {
              "node": "prompt-1",
              "port": "text"
            },
            "to": {
              "node": "image-1",
              "port": "prompt"
            }
          }
        ]
      }
    ]
  }
}'

#Responses

#201 Created

Created.

FieldTypeRequiredDefaultDescription
objectstringyes—One of "canvas".
idstringyes—
project_idstringyes—
namestringyes—0 to 80 characters.
revintegeryes—A save names the rev it was drawn from. 1 to ….
pagesintegeryes—1 to ….
nodesintegeryes—0 to ….
updated_atstringyes—
updated_bynull or objectyes—Who saved it last, while they are a member; null once they left.
docobjectyes—A canvas document, version 1: pages (up to 20), each with its viewport, its nodes (up to 1,500 — prompts, generators, uploads and the project's assets, upscalers, editors, notes, stickies, shapes, text, drawn strokes, tables, comment pins, reactions and frames) and the edges wiring an output port into an input port that takes its type. The full shape is published with the Studio's contract; a document that does not read is refused canvas_invalid, naming each problem. A node's run is the server's: anything sent there is ignored.
doc.vintegeryes—One of 1.
doc.pagesobject[]yes—
doc.pages[].idstringyes—
doc.pages[].namestringyes—0 to 80 characters.
doc.pages[].viewportobjectyes—
doc.pages[].viewport.xnumberno—
doc.pages[].viewport.ynumberno—
doc.pages[].viewport.zoomnumberno—0.05 to 4.
doc.pages[].nodesobject[]yes—
doc.pages[].nodes[].idstringyes—
doc.pages[].nodes[].kindstringyes—One of "prompt", "number", "upload", "assets", "image_gen", "video_gen", "audio_gen", "llm", "upscale", "edit", "note", "sticky", "shape", "text", "stroke", "table", "comment_pin", "reaction", "frame".
doc.pages[].nodes[].xnumberyes—
doc.pages[].nodes[].ynumberyes—
doc.pages[].nodes[].wnumberyes—
doc.pages[].nodes[].hnumberyes—
doc.pages[].nodes[].parentstringno—May be null.
doc.pages[].nodes[].zintegerno—
doc.pages[].nodes[].lockedbooleanno—
doc.pages[].nodes[].dataobjectyes—
doc.pages[].nodes[].runobjectno—A node's last run, read off the jobs it started — never written by a request. Null before it ran. May be null.
doc.pages[].edgesobject[]yes—
doc.pages[].edges[].idstringyes—
doc.pages[].edges[].fromobjectyes—
doc.pages[].edges[].toobjectyes—
bytesintegeryes—The document's size as JSON, which is kept up to 2 MB. 0 to ….
crdtstringyes—The name the canvas's live edits travel under: canvas: and its id.
request_idstringno—Mirrored in the X-Request-Id header.

Headers:

HeaderDescription
RateLimit-LimitBurst capacity.
RateLimit-Remaining
RateLimit-ResetSeconds until refill.
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-ResetUnix seconds. The X- spelling is what client libraries read.
X-Request-Id

#400 Bad Request

#401 Unauthorized

#403 Forbidden

#404 Not Found

#409 Conflict

#413 Payload Too Large

#429 Too Many Requests

#500 Internal Server Error

#503 Service Unavailable

#Status codes

StatusMeaning
201Created.
400Bad Request
401Unauthorized
403Forbidden
404Not Found
409Conflict
413Payload Too Large
429Too Many Requests
500Internal Server Error
503Service Unavailable

Every refusal names its code, and every code is explained at Errors.

Start typing to search every page of the documentation.

Up arrow Down arrow to moveEnter to openEscape to close