Quickstart
Create a character, generate an image for it, and poll for the result — using nothing but curl and an API key.
This walkthrough takes you from an API key to a finished image. Every call uses the base URL https://api.someone.app.
Set your API key
Create a key in the Someone app settings, then keep it in an environment variable. Keys look like sk_live_ followed by 64 hex characters and are shown only once.
export SOMEONE_KEY="sk_live_your_key_here"Create a character
A character is generated asynchronously — you get back an id and a status of generating. Every mutation needs a unique Idempotency-Key (any UUID you generate).
curl -X POST https://api.someone.app/v1/characters \
-H "Authorization: Bearer $SOMEONE_KEY" \
-H "Idempotency-Key: 019f6e11-69d4-7a16-8ab8-17e9e14a6821" \
-H "Content-Type: application/json" \
-d '{
"name": "Luna",
"parameters": {
"gender": "female",
"age": "25-34",
"artStyle": "hyper-realistic"
}
}'Save the data.id — that’s your character_id.
Generate an image
Reference the character by id. Use a fresh Idempotency-Key.
curl -X POST https://api.someone.app/v1/generations \
-H "Authorization: Bearer $SOMEONE_KEY" \
-H "Idempotency-Key: 019f6e12-3d8a-74d9-b5ad-18e83ae82432" \
-H "Content-Type: application/json" \
-d '{
"character_id": "CHARACTER_UUID",
"type": "image",
"prompt": "walking through a neon-lit Tokyo street at night",
"options": { "aspect_ratio": "16:9", "hd": true }
}'The response returns 201 with status: "processing" and a generation id.
Poll for the result
Generation is async. Poll the generation every few seconds until status is completed or failed. When it’s done, data.output.url holds the finished image.
curl https://api.someone.app/v1/generations/GENERATION_UUID \
-H "Authorization: Bearer $SOMEONE_KEY"Check your credits
Every generation spends credits. Check your balance any time.
curl https://api.someone.app/v1/account \
-H "Authorization: Bearer $SOMEONE_KEY"