This page takes you from nothing to a first image. You need a terminal and one of cURL, Node 20 or later, or Python 3.11 or later.
1. Make a key
- Sign up and confirm your email address.
- Open API keys in the console and choose Create key. Give it a name that says where it will run.
- Copy the key. It is shown once, and Dramatis Studio keeps only a hash of it.
- Put it in your shell. Every sample on this page reads the key from
OPSIS_API_KEY, so no key is ever pasted into code.
export OPSIS_API_KEY="paste the key here" |
An account pays from a prepaid balance. During the beta the operator grants the balance; the Billing page of the console says how to ask for one. A task is refused with 402 insufficient_balance until the account has some.
Keep the key on a server. Keys says why and how.
2. Set up your language
Each sample on this page is shown in cURL, JavaScript and Python. Use the one you like.
- cURL needs nothing installed. Paste the command into your terminal.
- JavaScript is meant to use the TypeScript package. That package is not published yet. The sample is the call it is meant to make: save it as
quickstart.mjsand, once the package exists, run it withnode quickstart.mjs. - Python is meant to use the Python package. That package is not published yet. The sample is the call it is meant to make: save it as
quickstart.pyand, once the package exists, run it withpython3 quickstart.py.
The samples read OPSIS_API_KEY and pass the key in. They do not install a package. Each task creation in the samples carries an idempotency key. The host in the samples, https://api.studio.dramatis.ai, is not open yet.
3. List the models
The model list needs no key. It gives each model's id, its inputs, its limits and its prices.
Request
curl 'https://api.studio.dramatis.ai/v1/models' \
|
-H "Authorization: Bearer $OPSIS_API_KEY" |
Pick one id. It has a slash, such as family/variant. The request on this page uses the first model of the list as it was when this page was built.
4. Create a task
A task is one request for one or more images. POST /v1/tasks takes the model's id as model and its input. It must carry an Idempotency-Key header, which the SDK samples add for you. See Idempotency.
wait asks Dramatis Studio to hold the connection for up to 60 seconds, so a small script can make one call and get the image. If the task is not finished in time, the answer is 202 and you poll.
Request
curl 'https://api.studio.dramatis.ai/v1/tasks?wait=30' \
|
-X POST \
|
-H "Authorization: Bearer $OPSIS_API_KEY" \
|
-H "Content-Type: application/json" \
|
-H "Idempotency-Key: sample-$(date +%s)-$RANDOM" \
|
-d '{
|
"model": "google/gemini-3.1-flash-lite-image",
|
"input": {
|
"prompt": "A woman with silver hair stands on a pier at dusk, soft evening light.",
|
"aspect_ratio": "1:1"
|
}
|
}' |
The answer is the task. A finished one has status set to SUCCEEDED and its images in output.images:
{
|
"id": "task_01k3m8x9q2z4v7n5p6r8s0t1w3",
|
"status": "SUCCEEDED",
|
"model": "family/variant",
|
"output": {
|
"images": [
|
{ "url": "https://…signed link…", "expires_at": "2026-11-02T10:12:31Z", "mime": "image/png", "width": 832, "height": 1216, "bytes": 1483920, "seed": 4217 }
|
]
|
}
|
} |
Keep the task id, not the link. A link works for one hour, and every read of the task gives a fresh one.
5. Poll the task
If the answer was 202, the task has a status that is not final yet. Read it with its id, no faster than every 2 seconds, and back off to 10. It is finished when status is SUCCEEDED or FAILED.
Request
curl 'https://api.studio.dramatis.ai/v1/tasks/task_01k3m8x9q2z4v7n5p6r8s0t1w3' \
|
-H "Authorization: Bearer $OPSIS_API_KEY" |
A FAILED task says why in status_reason and in error.code. Tasks lists the statuses and Errors the codes.
6. Download the image
The link is in output.images[0].url of the task's answer. It is a signed link to storage, so fetching it needs no key. This command reads the task again, which gives a fresh link, takes the link out of the answer with jq and saves the image. Put your task's id where it says TASK_ID.
The host in this command is not open yet.
URL=$(curl -s https://api.studio.dramatis.ai/v1/tasks/TASK_ID \
|
-H "Authorization: Bearer $OPSIS_API_KEY" | jq -r '.output.images[0].url')
|
curl -o image.png "$URL" |
Without jq, copy the value of url from the answer by hand and put it between the quotes of the second command in place of $URL.
That is a first image. Next:
- Send the result to your server as it happens with webhooks, instead of polling.
- Read how retention keeps and deletes results.
- Open the API reference for every field of every call.