Files and Mounts - AI Coding Assistant Lingma: Central de Documentação do Alibaba Cloud

Fluxo de trabalho

Envio do arquivo

POST /files — envie o conteúdo binário e escolha uma finalidade.
Montagem na Session

POST /sessions/{session_id}/resources — anexe o arquivo enviado à Session.
Uso pelo Agent

O Agent lê o conteúdo do arquivo durante a Session e conclui a tarefa.

Envio de um arquivo

POST https://api.qoder.com.cn/api/v1/cloud/files
Content-Type: multipart/form-data

Parâmetros

Campo	Tipo	Obrigatório	Descrição
file	binary	Sim	Conteúdo do arquivo
purpose	string	Sim	Finalidade do arquivo (consulte a tabela)
filename	string	Não	Nome personalizado do arquivo

Valores de finalidade

Valor	Significado	Produtor	Disponível para download
user_upload	Arquivo de entrada enviado pelo usuário	Usuário	Não
tool_output	Arquivo gerado pela execução de uma ferramenta	Agent/ferramenta	Sim
skill_output	Arquivo gerado por uma Skill	Agent/Skill	Sim
session_resource	Arquivo de recurso no escopo da Session	Usuário/sistema	Não
agent_output	Arquivo de saída final do Agent	Agent	Não

Somente arquivos com finalidade tool_output e skill_output podem ser baixados pelo endpoint /content. As demais finalidades destinam-se exclusivamente ao uso interno do Agent.

Exemplo de envio com curl

curl -X POST https://api.qoder.com.cn/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./src/main.py" \
  -F "purpose=user_upload"

Resposta:

{
  "file_id": "file_019e6a18dc0978e9a2104c9b269748ac",
  "filename": "main.py",
  "purpose": "user_upload",
  "size_bytes": 4096,
  "metadata": {},
  "mime_type": "text/plain",
  "status": "ready",
  "created_at": "2026-05-01T10:00:00Z",
  "updated_at": "2026-05-01T10:00:00Z"
}

Envio de vários arquivos:

# Upload one at a time
curl -X POST https://api.qoder.com.cn/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./config.yaml" \
  -F "purpose=user_upload"

curl -X POST https://api.qoder.com.cn/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./requirements.txt" \
  -F "purpose=user_upload"

Montagem em uma Session

Após o envio, monte o arquivo em uma Session usando a API Resources:

POST https://api.qoder.com.cn/api/v1/cloud/sessions/{session_id}/resources

Corpo da requisição — passe uma ou mais entradas em um array resources:

{
  "resources": [
    {
      "type": "file",
      "file_id": "file_abc123"
    }
  ]
}

Exemplo de montagem com curl

curl -X POST https://api.qoder.com.cn/api/v1/cloud/sessions/sess_abc123/resources \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "resources": [
      {"type": "file", "file_id": "file_abc123"}
    ]
  }'

Montagem de vários arquivos em uma única requisição:

curl -X POST https://api.qoder.com.cn/api/v1/cloud/sessions/sess_abc123/resources \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "resources": [
      {"type": "file", "file_id": "file_abc123"},
      {"type": "file", "file_id": "file_def456"},
      {"type": "file", "file_id": "file_ghi789"}
    ]
  }'

Download de um arquivo

Somente arquivos com finalidade tool_output e skill_output podem ser baixados:

curl https://api.qoder.com.cn/api/v1/cloud/files/file_abc123/content \
  -H "Authorization: Bearer $QODER_PAT" \
  -o output.txt

Para outras finalidades, requisições ao endpoint /content retornam 403 Forbidden.

Consulta de metadados do arquivo

curl https://api.qoder.com.cn/api/v1/cloud/files/file_abc123 \
  -H "Authorization: Bearer $QODER_PAT"

Listagem de arquivos

curl "https://api.qoder.com.cn/api/v1/cloud/files?purpose=user_upload" \
  -H "Authorization: Bearer $QODER_PAT"

É possível filtrar os resultados por finalidade.

Exemplo completo de ponta a ponta

# 1. Upload the source file
FILE_ID=$(curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./app.py" \
  -F "purpose=user_upload" | jq -r '.file_id')

echo "Uploaded: $FILE_ID"

# 2. Create a Session
SESSION_ID=$(curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{"agent": "agent_abc123"}' | jq -r '.id')

# 3. Mount the file on the Session
curl -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/$SESSION_ID/resources" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d "{\"resources\": [{\"type\": \"file\", \"file_id\": \"$FILE_ID\"}]}"

# 4. Send a task — the Agent can reference mounted files
curl -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"type": "user.message", "content": [{"type": "text", "text": "Review app.py and fix the bugs."}]}
    ]
  }'

Perguntas frequentes

P: Por quanto tempo os arquivos enviados são retidos? R: Os arquivos compartilham o ciclo de vida do recurso pai (Agent ou Session). Quando a Session é excluída, os arquivos associados também são removidos.

P: Posso anexar arquivos ao criar uma Session? R: Atualmente, esse processo exige duas etapas: envio e, em seguida, montagem. Uma operação combinada poderá ser adicionada futuramente.

P: Por que não consigo baixar arquivos com finalidade user_upload? R: Por motivos de segurança, os envios brutos do usuário são acessíveis apenas internamente pelo Agent. Para exportar resultados, solicite que o Agent gere arquivos com finalidade tool_output ou skill_output.

P: Quais formatos de arquivo são suportados? R: Qualquer arquivo binário é aceito. Arquivos baseados em texto (código, configuração, documentos) oferecem os melhores resultados.