|Docs

Quick start

Sume exposes a workspace-scoped Public API and an agent-friendly CLI. Both follow the same pattern: authenticate, create or search something in the API-key workspace, then read results through stable job and asset endpoints.

Base URL

https://www.sume.so/api/v1

Use this production base URL unless you are intentionally testing another Sume environment.

1. Authenticate

Create an API key in Sume and keep it server-side.

export SUME_API_KEY="sume_live_..."

Check the account and workspace attached to the key:

curl https://www.sume.so/api/v1/me \
  -H "Authorization: Bearer $SUME_API_KEY"

The API key determines workspace scope. Do not send workspace_id or user_id in request bodies.

2. Check credits

Generation endpoints can spend credits. Check balance and concurrency before creating jobs:

curl https://www.sume.so/api/v1/credits \
  -H "Authorization: Bearer $SUME_API_KEY"

CLI equivalent:

sume credits

3. Create an image job

curl https://www.sume.so/api/v1/images/generations \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Clean skincare product photo on a white bathroom counter.",
    "aspect_ratio": "1:1",
    "image_count": 1
  }'

The response is accepted asynchronously and includes a job id.

{
  "object": "image_generation",
  "job": {
    "id": "job_...",
    "status": "queued"
  }
}

CLI equivalent:

sume images generate \
  --prompt "Clean skincare product photo on a white bathroom counter." \
  --aspect-ratio 1:1 \
  --wait \
  --json

4. Poll status

curl https://www.sume.so/api/v1/jobs/job_123 \
  -H "Authorization: Bearer $SUME_API_KEY"

Common terminal states are completed, failed, canceled, or expired. If the job is still queued, running, or processing, wait and poll again.

CLI equivalent:

sume jobs get job_123 --json

5. Fetch result

curl https://www.sume.so/api/v1/jobs/job_123/result \
  -H "Authorization: Bearer $SUME_API_KEY"

Result payloads may include safe public media URLs and metadata. Avoid logging full URLs if they contain query strings or private tokens.

CLI equivalent:

sume jobs result job_123 --json
sume jobs result job_123 --download ./outputs/

6. Search Asset Library

Asset Library returns indexed scene-level records. Use it to find reusable clips, generated outputs, hooks, CTAs, product demos, and source-video metadata.

curl "https://www.sume.so/api/v1/assets?q=product%20demo%20hook&source_type=generated&limit=5" \
  -H "Authorization: Bearer $SUME_API_KEY"

CLI equivalent:

sume assets search "product demo hook" \
  --source-type generated \
  --limit 5 \
  --json

Next steps