How Get3W Works

Get3W is a unified API in front of many upstream model providers. You call one endpoint with a model slug; Get3W picks a provider, runs the job, stores the output, and returns URLs.

Your app → Get3W API → task queue → worker → model provider → object storage → outputs

Model Slugs

Every model is addressed by a three-part slug:

{provider_id}/{model_id}/{run_type}

For example google/nano-banana-pro/text-to-image. The slug is also the submit path:

POST /v1/google/nano-banana-pro/text-to-image

See What are Models for the full list of providers and run types.

Run Types

The run_type segment declares what kind of job you are running:

Group	Run types
Image	text-to-image, image-to-image, text-to-panorama, image-to-panorama
Video	text-to-video, first-to-video, first-last-to-video, reference-to-video, video-to-video, digital-human
Audio	text-to-speech, text-to-music, speech-to-text
3D	text-to-3d, image-to-3d
Chat	chat (OpenAI-compatible, see below)

Channels

Many models expose a channel in the request body to choose a service tier. The common set is economy, stable, and official; some model families use their own values such as turbo, balanced, quality, standard, pro, fast, or human.

The channel affects pricing, queue routing, and which upstream providers are eligible. If you omit it, Get3W fills in that model's default.

Request Flow

1. Submit

POST /v1/{provider_id}/{model_id}/{run_type}

Optional query parameters:

Parameter	Effect
sync	Wait for completion and return the full result in the same response
webhook	Callback URL to receive the result when the task finishes
prefix	Custom storage prefix for output files, e.g. myfolder1/myfolder2

Before anything is queued, the API server:

1. Authenticates the Authorization: Bearer API key
2. Validates the provider and resolves the effective channel
3. Screens the prompt against the content blacklist (403 if blocked)
4. Prices the request and checks your balance (402 if insufficient)

2. Queue and Execute

Accepted tasks are pushed onto a Celery queue with a 30-minute expiry and returned to you immediately:

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "created",
  "estimated_duration": 52
}

estimated_duration is in seconds, derived from the median runtime of recent completed tasks for that model and channel.

A worker then picks up the task, calls the upstream provider, downloads the result, writes it to object storage, and settles the charge against your balance.

3. Retrieve

Poll the request until it reaches a terminal state:

GET /v1/requests/{request_id}

While the task is still running, the response is {"id": ..., "status": "processing"} with a Retry-After: 3 header. Once terminal, you get the full result:

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "model": "google/nano-banana-pro/text-to-image",
  "status": "completed",
  "code": 0,
  "outputs": ["https://storage.example.com/output.png"],
  "timings": {
    "queue_wait": 427,
    "celery_init": 2054,
    "api_call": 23068,
    "save": 1902,
    "run_overhead": 679,
    "total": 28131
  },
  "error": null,
  "created_at": "2026-03-28T07:50:42"
}

All timings are in milliseconds. api_call is time spent at the upstream provider; save is time spent persisting outputs.

Task Statuses

Status	Meaning
created	Accepted and queued
processing	A worker is running the task
completed	Finished; outputs holds the result URLs
failed	Finished with an error; see code and error

completed and failed are terminal — stop polling once you see them. See Error Codes for the code values.

Provider Routing and Reliability

A single model slug can be backed by several upstream platforms. Get3W fails over between them automatically rather than pinning one:

• Configured order — Each model and channel has an ordered list of eligible platforms, maintained by Get3W.
• Multi-round retry — A failed attempt falls through to the next platform in that order. The list is retried for up to 2 rounds, with a backoff between rounds starting at 10 seconds.
• Fast-fail on user errors — Failures that are your input's fault, such as content moderation or an invalid parameter, abort immediately instead of being retried against other platforms. Retrying them would cost time without changing the outcome.

Success rate and latency per platform are recorded continuously and inform how Get3W orders that list, but ordering is applied from configuration rather than recomputed per request.

Because retries happen inside a single task, your request ID stays the same throughout. You only see failed when every eligible platform has been exhausted, or when the failure was non-retryable.

Geographic Routing

Get3W runs two clusters, one in Guangzhou and one in Silicon Valley. Tasks are queued to the cluster closest to the model's primary upstream platform, so China-hosted providers run on the CN workers and overseas providers run on the US workers. When a task on a CN worker needs to reach an overseas provider, that call is offloaded to the US cluster instead of crossing the border directly.

This is transparent to you — the API host and request format are identical either way.

Call Modes

Mode	How	Guide
Sync	?sync=true on submit	Get Started with API
Async	Submit, then poll /v1/requests	Async Mode
Webhook	?webhook=<your-url> on submit	Webhook Mode

Webhook delivery is retried up to 3 times with exponential backoff if your endpoint does not return a 2xx. The result also remains available via polling, so a missed webhook is never a lost result.

Chat Models

Chat models use the OpenAI-compatible surface instead of the submit endpoint:

POST /v1/chat/completions

Point any OpenAI client at https://api.get3w.com/v1 with your Get3W API key and pass a chat model slug in the model field. Chat requests are synchronous and support streaming.

Content Lifecycle

1. Created — Request validated, priced, and queued
2. Processing — A worker runs the task against an upstream provider
3. Completed — Outputs written to object storage and exposed as URLs
4. Expiring — Output files are retained for the current and previous calendar month; task records are kept 7 days
5. Deleted — Expired files and records are removed by a cleanup routine

Because retention is measured in whole calendar months, a file's actual lifetime depends on when in the month it was created — treat the previous month's boundary as the deadline, not a fixed number of days.

Download anything you need to keep. If you configure your own cloud storage on your API key, outputs are written there instead and retention is yours to control.

Balance and Account Level

Check your balance and tier at any time:

GET /v1/balance

{
  "balance": 42.5,
  "currency": "USD",
  "account_level": "Silver"
}

Tiers are based on cumulative top-up and never decrease. See What are Account Tiers.

Next Steps

• What are Models
• What are Tasks
• Get Started with API