Make your first video

Send a brief, follow the creator’s run and download a result. You can continue editing the same project in Ghostmotion.

1. Save your API key

Create a key and replace the placeholder locally.

export GHOSTMOTION_API_KEY='YOUR_API_KEY'

2. Send your brief

curl --fail-with-body "https://app.ghostmotion.ai/api/v1/videos" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "request_id": "launch-video-001",
  "brief": "Make a 20-second launch video for a collaborative design app. Show the problem, introduce the app, and end with an invitation to try it.",
  "duration_seconds": 20,
  "aspect_ratio": "16:9"
}'

Choose a new request_id for each new video. Reuse the same ID and unchanged body after a timeout so a retry does not create another project.

{
  "project_id": "project-id",
  "run_id": "run-id",
  "project_url": "https://app.ghostmotion.ai/p/project-id",
  "status": "accepted",
  "poll_after_seconds": 15
}

3. Check the run

Save the returned ID as RUN_ID. Wait for poll_after_seconds before checking, and keep following that delay while the status is running.

export RUN_ID='RUN_ID_FROM_RESPONSE'

curl --fail-with-body "https://app.ghostmotion.ai/api/v1/runs/$RUN_ID" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY"

Stop polling at completed, failed, cancelled or interrupted. A completed run can have an empty new_films list. Read reply: the creator may need an answer before it can make the video.

4. Download a video

Each item in new_films has a url, version and expires_at. Use its URL as shown below. Links expire after one hour; fetch the run again for fresh links.

export VIDEO_URL='URL_FROM_NEW_FILMS'
curl --fail --location "$VIDEO_URL" --output video.mp4

The URL authorizes the download; no extra bearer header is required. Follow redirects and keep these URLs private.

Continue the same project

Set PROJECT_ID to the returned project ID. Once the current run has finished, send an edit or answer. This starts a new run and can spend more credits.

export PROJECT_ID='PROJECT_ID_FROM_RESPONSE'

curl --fail-with-body "https://app.ghostmotion.ai/api/v1/projects/$PROJECT_ID/messages" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "request_id": "launch-edit-001",
  "message": "Make the opening faster and add captions."
}'

Poll the new run ID, or open the returned project_url in Ghostmotion. The API reference covers listing projects, stopping runs and adding references.