Add reference files

Upload files before including them in a creation or edit. Files attached to an assistant’s chat are not automatically available to Ghostmotion. Remote URL references are not supported.

1. Prepare an upload

curl --fail-with-body "https://app.ghostmotion.ai/api/v1/reference-uploads" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "filename": "logo.png",
  "content_type": "image/png"
}'

The response includes upload_id, upload_url, headers, max_bytes and expires_at. The URL expires in one hour.

2. Send the bytes

export UPLOAD_URL='UPLOAD_URL_FROM_RESPONSE'
curl --fail-with-body -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @logo.png

Use the exact content type returned in headers. Send raw bytes, not multipart form data. Keep the complete URL intact; no extra bearer header is required. upload_url is a private Google Cloud Storage upload session, so the file goes straight to storage at any size and storage answers the PUT: 200 or 201 means it has the whole file. Its response body is storage’s own. To get Ghostmotion’s status: "ready" before using the file, call complete_reference_upload; otherwise the file is verified when a creation or edit first uses it.

On a slow or unreliable connection, send Content-Range: bytes start-end/total chunks instead (non-final chunks in multiples of 256 KiB; chunk_bytes is a good size). A 308 reports the persisted Range: resume at its next byte. After an interruption, ask with an empty PUT and Content-Range: bytes */total (or */*). Treat the URL as a secret.

3. Reference the upload

Add this field to a create_video or send_message input, or to the equivalent HTTP request body.

"references": [{ "upload_id": "UPLOAD_ID_FROM_RESPONSE" }]

At most 20 references may be included. Use a completed upload before it expires. Verification, on first use or with complete_reference_upload, does not extend the original expires_at: an upload is usable only until the original expires_at. Each upload is consumed by one request, but retries of that same request ID can reuse it. Upload again to use the same file in a different request.

File sizes

Reference uploads have no file-size cap. The response returns max_bytes: null. size_bytes is optional. An optional sha256 is checked. Files are validated before use; a supported extension alone does not guarantee valid contents.