API reference

Base URL:

https://sogrok.com

Prefix: /api/v1. JSON over HTTPS unless noted. Authorization: Bearer hxsk_....

Create keys on the keys page. The full key is shown once, starts with hxsk_, and is about 37 characters. Send the id from GET /api/v1/models, not the product label. Age confirmation is required before uploads or jobs.

Success returns the business object. Errors are non-2xx with { "error": { "code": "...", "message": "..." } }. Job creation returns 202. Treat only 2xx bodies as success.

params.model must be an id below, or the current id from GET /api/v1/models. Do not send the keys-page label.

Video

Image

Chat

SKU

SKU must match resolution, e.g. 720p → video.std, 4k → video.ultra. The live list is GET /api/v1/models. Price is whatever the quote returns.

Quote and submit the same params object. Unknown fields return unsupported_field.

Aspect ratios

Mode rules

• i2v needs a first frame or reference image.
• v2v needs a reference video.
• A video job with a first frame or still is image-to-video. First frame uses first_frame_upload_id. Reference stills use reference_image_upload_ids. Do not mix the two.
• Grok video accepts 1 still; Grok image accepts 3.
• Seedance 2.5: 30 images, 10 audio/video clips, 50 assets total. 2.0: 9 images, 3 audio/video clips, 15 total.
• Images, video and audio references accept either an upload_id or a public HTTPS URL. Both can be mixed and count toward the same limits. URLs must be directly downloadable, up to 2048 characters; private-network and http addresses are rejected.
• Reference audio is checked for copyright in the output audio; a task may be rejected when the material contains protected music. For reliable results, supply only visual references and let the model generate audio.
• layer is seedream only: one still, billed by returned layers.

List models

GET /api/v1/models

curl https://sogrok.com/api/v1/models \
  -H "Authorization: Bearer hxsk_..."

Returns { "object": "list", "data": [ ... ] }. Each item has id, modes, resolutions, and prices[].

Quote

POST /api/v1/quotes

curl https://sogrok.com/api/v1/quotes \
  -H "Authorization: Bearer hxsk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "video.std",
    "prompt": "slow push down a rainy alley, neon reflections",
    "params": {
      "model": "seedance-2-5",
      "mode": "t2v",
      "resolution": "720p",
      "ratio": "16:9",
      "duration": 5
    }
  }'

Success fields: quote_id, price_usd, expires_at, estimated_time_seconds, params. Requote if prompt, SKU, or params change.

Create a job

POST /api/v1/jobs → 202

curl https://sogrok.com/api/v1/jobs \
  -H "Authorization: Bearer hxsk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "PASTE_QUOTE_ID",
    "sku": "video.std",
    "prompt": "slow push down a rainy alley, neon reflections",
    "params": {
      "model": "seedance-2-5",
      "mode": "t2v",
      "resolution": "720p",
      "ratio": "16:9",
      "duration": 5
    }
  }'

{
  "job_id": "2f50c75e-...",
  "status": "queued",
  "quoted_price_usd": 0.45,
  "created_at": "2026-09-09T08:00:00.000Z",
  "queue": { "position": 1, "limit": 20 }
}

Creation holds the quoted amount. Do not resubmit the same quote before you know the job status.

Poll a job

GET /api/v1/jobs/:id

curl https://sogrok.com/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer hxsk_..."

Poll until succeeded / failed / rejected. Success includes result.url and usage. Image and video files use the site media URL; add ?thumb=1 for a poster. Chat text is in result.text. usage is { input_tokens, output_tokens, total_tokens } and is 0 until reported.

{
  "job_id": "2f50c75e-...",
  "sku": "video.std",
  "model": "seedance-2-5",
  "status": "succeeded",
  "quoted_price_usd": 0.45,
  "usage": {
    "input_tokens": 0,
    "output_tokens": 40594,
    "total_tokens": 40594
  },
  "result": { "url": "https://sogrok.com/api/v1/jobs/JOB_ID/media" }
}

curl "https://sogrok.com/api/v1/jobs/JOB_ID/media?thumb=1" \
  -H "Authorization: Bearer hxsk_..." \
  -o thumb.webp

History

curl "https://sogrok.com/api/v1/jobs?job_id=2f50" \
  -H "Authorization: Bearer hxsk_..."

Max 20 rows. Filter by full or partial job id.

Upload a reference

POST /api/v1/uploads, multipart/form-data.

curl https://sogrok.com/api/v1/uploads \
  -H "Authorization: Bearer hxsk_..." \
  -F slot=first \
  -F [email protected]

Write the returned upload_id to first_frame_upload_id or reference_image_upload_ids. 10 uploads per user per minute.

Audio references (audio slot) are capped at 15 seconds per clip; longer uploads are rejected (400 audio_too_long).

{
  "sku": "video.std",
  "prompt": "the subject walks toward camera, outfit unchanged",
  "params": {
    "model": "seedance-2-5",
    "mode": "i2v",
    "resolution": "720p",
    "ratio": "9:16",
    "duration": 5,
    "first_frame_upload_id": "UPLOAD_ID"
  }
}

Wallet

curl https://sogrok.com/api/v1/wallet \
  -H "Authorization: Bearer hxsk_..."

Watch available_usd and frozen_usd. The quoted amount freezes on create and moves after settle or refund.

For clients that cannot quote then submit. Path is /v1/videos, not /api/v1. Same auth. The server fills SKU from resolution, quotes, and holds the balance. Use the full API for everything else.

curl https://sogrok.com/v1/videos \
  -H "Authorization: Bearer hxsk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "prompt": "slow push down a rainy alley, neon reflections",
    "duration": 10,
    "resolution": "720p",
    "ratio": "16:9",
    "referenceImages": ["https://example.com/img.jpg"]
  }'

status is queued / processing / succeeded / failed. The success url expires; download promptly. Local files still need /api/v1/uploads. Insufficient balance returns 400 and creates no job.

1. Create a key and allow the models you need.
2. GET /api/v1/models to confirm id, modes, resolution, and SKU.
3. Upload references if required, keep upload_id.
4. POST /api/v1/quotes for quote_id and price_usd.
5. Submit the same prompt, SKU, and params to POST /api/v1/jobs.
6. Poll GET /api/v1/jobs/:id until succeeded, failed, or rejected.
7. Download result.url. Use ?thumb=1 for posters.

JOB_ID='...'
while true; do
  STATUS=$(curl -sS "https://sogrok.com/api/v1/jobs/$JOB_ID" \
    -H "Authorization: Bearer hxsk_..." \
    | jq -r '.status')
  echo "status=$STATUS"
  case "$STATUS" in
    succeeded|failed|rejected) break ;;
  esac
  sleep 3
done

Moderation rejects are not billed. If submit times out, the hold stays — poll the job instead of resubmitting the same quote.