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.

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.

• 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.
• Every route, with its fields, is in the interactive reference.