One video task contract.

1. Authentication and registration.

Joining the waitlist does not create an account or issue a key. After gateway access is explicitly enabled, POST /v1/register accepts a JSON email field and returns a new key once. An existing email returns 409; recovery is handled through support.

Send Authorization: Bearer YOUR_API_KEY on video requests. Keys are generated with 256 bits of randomness; only a SHA-256 hash is stored. Revoked keys return 401. Keep your key on your server.

2. Submit a video.

Set FRAMECALL_BASE_URL to the service origin after launch. Send POST /v1/videos with JSON fields model, prompt and optional aspect_ratio. A prompt must contain 1–2,500 characters. The aspect ratio is 16:9 (default) or 9:16. Preset durations, audio and resolutions are fixed; unknown fields are rejected.

# Proposed API · early access only
curl "$FRAMECALL_BASE_URL/v1/videos" \
  -H "Authorization: Bearer $FRAMECALL_API_KEY" \
  -H "Idempotency-Key: demo-request-001" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "veo-3-1-fast-hd",
  "prompt": "A ceramic rover crosses a red desert, soft wind and mechanical footsteps.",
  "aspect_ratio": "16:9"
}'

Every new task requires an Idempotency-Key of 8–128 letters, digits, underscores or hyphens. Repeating the same key and body returns the existing task; changing its body returns 409. Never reuse an example key for a new generation.

{
  "id": "YOUR_TASK_ID",
  "model": "veo-3-1-fast-hd",
  "status": "pending",
  "result_urls": []
}

Submission returns 202. Tasks move through submitting → pending → processing → completed or failed. Providers can skip intermediate states. An uncertain submit is marked unknown, is never automatically retried, and requires support to reconcile.

3. Query a task.

curl "$FRAMECALL_BASE_URL/v1/videos/YOUR_TASK_ID" \
  -H "Authorization: Bearer $FRAMECALL_API_KEY"

Query every 5–10 seconds while pending or processing. A completed result includes HTTPS video URLs in result_urls. A failed task has no video URL. Keys can query only their own tasks. Download outputs promptly; long-term file storage is not promised.

4. Errors.

5. Billing and routing boundaries.

No payment, credit grant, top-up or deduction is implemented in this trial. The future policy is pay per successful task and no charge for failed generations. Usage records count completed videos once; they are not invoices.

Same-model upstream route failover is a planned service property. This trial uses a single configured adapter and never retries an ambiguous submission automatically. Failover must be verified before enabling the public gateway.