API quickstart

In the studio, open Settings, API keys and create a key with the personas:read, creatives:read and creatives:write scopes. Copy it: it is shown once. You can give it a monthly credit limit.

Requests made with a key are paid with API credits, bought under Billing on any plan and never expiring. How credits work.

export VIEWGC_KEY=ugc_live_...

List the actors your workspace can use: your own and the shared cast.

curl -s "https://api.viewgc.com/v1/personas?limit=20" \
  -H "Authorization: Bearer $VIEWGC_KEY"

Name the actor and say what the clip is about. The answer is immediate; the video takes a few minutes. Leave out prompt and the actor makes something of their own. Send an Idempotency-Key (one per clip, reused when retrying) so a retry after a dropped connection returns the first answer and is charged once.

curl -s https://api.viewgc.com/v1/studio/generate \
  -H "Authorization: Bearer $VIEWGC_KEY" \
  -H "Idempotency-Key: refill-bottle-clip-1" \
  -H "Content-Type: application/json" \
  -d '{
    "personaId": "<an id from step 2>",
    "prompt": "Why she switched to a refillable bottle for her commute",
    "aspectRatio": "9:16",
    "generationMode": "NATIVE_AUDIO"
  }'
# => { "campaignId": "...", "workflowId": "...", "status_url": "/v1/creatives?campaignId=..." }

• aspectRatio: 9:16, 16:9 or 1:1.
• generationMode: NATIVE_AUDIO, VOICE_OVER or VOICE_LIPSYNC.
• productId (optional): the clip opens on the actor holding one of your products.
• captionsEnabled (optional, off by default): captions burned into the video, timed to what is said.
• language (optional, en by default): what the clip is written and spoken in, for example es, fr or pt-BR. GET /v1/billing/catalog lists them.

Poll the creatives of the session until one is COMPLETED; its videoUrl is the finished, mastered file. A FAILED one carries failureMessage and is refunded automatically.

curl -s "https://api.viewgc.com/v1/creatives?campaignId=<campaignId>" \
  -H "Authorization: Bearer $VIEWGC_KEY"

Rather than polling, register a webhook for creative.completed.

Every key shows what it spent this month (UTC, net of refunds) in Settings, API Keys, where an owner or admin can also set a monthly credit limit on it. A request that would pass the limit is refused with nothing charged; work already started finishes. With the key itself you can read the workspace’s spending:

curl -s "https://api.viewgc.com/v1/billing/usage?days=30" \
  -H "Authorization: Bearer $VIEWGC_KEY"

The answer splits studio credits from API credits, by UTC day and by action, for up to 90 days. Subscribe to billing.api_credits_low to hear when API credits fall to 500.

• 402 INSUFFICIENT_CREDITS: not enough API credits; details says what it costs and what you have.
• 402 SPEND_LIMIT_REACHED: the key reached the monthly limit you set on it.
• 403 FORBIDDEN_SCOPE: the key is missing a scope the route needs.
• 422 CONTENT_REJECTED: the request asks for something the terms do not allow.
• 409 CONFLICT on an Idempotency-Key: the key was used with a different body, or that request is still running. A repeat of a finished request with the same body gets the first answer back instead.
• 429 RATE_LIMITED: slow down; details.retry_after_seconds says how long.
• Every route, with its fields, is in the interactive reference.