API Reference

Create your first video in three API calls: generate → poll → download.

curl -X POST https://yoh.app/api/v1/stories/generate \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "A dragon teaches a young knight how to fly", "aspectRatio": "16:9" }'

{
  "jobId": "cmnk8wu2q0001q3vpmqv93nmy",
  "status": "queued",
  "pollUrl": "/api/v1/stories/jobs/cmnk8wu2q0001q3vpmqv93nmy"
}

curl https://yoh.app/api/v1/stories/jobs/cmnk8wu2q0001q3vpmqv93nmy \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "status": "completed", "progress": 100,
  "storyId": "cmnk8xxnx000004lbd7siief7",
  "videoUrl": "https://cdn.example.com/video/clip.mp4",
  "error": null
}

All API requests must include your API key in the header using the scheme.

Authorization: Bearer sk_live_YOUR_API_KEY

API keys begin with . You can create and manage keys from the .

Each API key is granted one or more scopes that control which endpoints it can access. Story generation costs credits per job. Credits are refunded if the job fails after all retries.

Submits a prompt and returns a immediately. The video is generated asynchronously. Poll to track progress.

Request body

Response 202 Accepted

{ "jobId": "cmnk8wu2q0001q3vpmqv93nmy", "status": "queued", "pollUrl": "/api/v1/stories/jobs/..." }

Poll this endpoint after calling . The job typically takes 8–15 minutes depending on story length and whether is enabled. Recommend polling every .

Job status lifecycle

Response fields

After a job completes you can fetch all assets generated for the story using the returned by the job. All asset endpoints require the scope.

Each clip is a scene segment with its own AI-generated video, still image, and audio. All URL fields are absolute and publicly accessible.

{
  "data": [{
    "id": "clip_001", "order": 0, "narration": "In the year 2157...",
    "duration": 8,
    "videoUrl": "https://cdn.example.com/generated/video/clip1.mp4",
    "imageUrl": "https://cdn.example.com/generated/image/clip1.jpg",
    "audioUrl": null, "status": "completed"
  }]
}

Uploads and persists a character reference image for a series so the AI uses a consistent face/look across all stories in that series. This operation is — calling it multiple times with the same character name is safe.

API key management endpoints use (logged-in user cookie), not an API key. Use the for a browser-based workflow, or call these endpoints programmatically from your backend with a valid session.

{
  "data": [{
    "id": "key_abc123", "name": "Production",
    "keyPrefix": "sk_live_7WH3",
    "scopes": ["stories:generate", "stories:read", "assets:read"],
    "revokedAt": null, "createdAt": "2026-04-03T10:00:00.000Z"
  }]
}

// Response — full key shown once
{
  "id": "key_abc123",
  "key": "sk_live_...",
  "name": "My integration",
  "keyPrefix": "sk_live_7WH3",
  "scopes": ["stories:generate", "stories:read", "assets:read"]
}

{ "id": "key_abc123", "revoked": true }

All errors return a consistent JSON shape with an object containing a machine-readable .

{ "error": { "code": "insufficient_credits", "message": "...", "status": 402 } }